Improve recognition accuracy

Precompiled hotwords vs. instant hotwords vs. context enhancement

Custom hotwords come in two forms: precompiled hotwords and instant hotwords. The following table compares the three approaches, which apply to different models and APIs:

Supported models and regions

Quick start

import dashscope
from dashscope.audio.asr import *
import os

# The API Key differs between the Beijing and Singapore regions. Get an API Key: https://help.aliyun.com/zh/model-studio/get-api-key
# If the environment variable is not configured, replace the line below with: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

# The following is the configuration for the China (Beijing) region. When calling, replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
dashscope.base_http_api_url = 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1'

# The following is the configuration for the China (Beijing) region. When calling, replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
dashscope.base_websocket_api_url = 'wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference'

prefix = 'testpfx'
target_model = "qwen-audio-3.0-asr-flash-streaming"

my_vocabulary = [
    {"text": "Speech Lab", "weight": 4}
]

service = VocabularyService()
vocabulary_id = service.create_vocabulary(
      prefix=prefix,
      target_model=target_model,
      vocabulary=my_vocabulary)

try:
    if service.query_vocabulary(vocabulary_id)['status'] == 'OK':
        recognition = Recognition(model=target_model,
                              format='wav',
                              sample_rate=16000,
                              callback=None)
        result = recognition.call('{YOUR_AUDIO_FILE}', phrase_id=vocabulary_id)
        print(result.output)
finally:
    # Delete the hotword list regardless of whether recognition succeeds, to avoid consuming quota
    service.delete_vocabulary(vocabulary_id)

import com.alibaba.dashscope.audio.asr.recognition.Recognition;
import com.alibaba.dashscope.audio.asr.recognition.RecognitionParam;
import com.alibaba.dashscope.audio.asr.vocabulary.Vocabulary;
import com.alibaba.dashscope.audio.asr.vocabulary.VocabularyService;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import com.google.gson.JsonArray;
import com.google.gson.JsonObject;

import java.io.File;
import java.util.ArrayList;
import java.util.List;

public class Main {
    // The API Key differs between the Beijing and Singapore regions. Get an API Key: https://help.aliyun.com/zh/model-studio/get-api-key
    // If the environment variable is not configured, replace the line below with: public static String apiKey = "sk-xxx"
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void main(String[] args) throws NoApiKeyException, InputRequiredException {
        // The following is the configuration for the China (Beijing) region. When calling, replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";
        // The following is the configuration for the China (Beijing) region. When calling, replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
        Constants.baseWebsocketApiUrl = "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference";

        String targetModel = "qwen-audio-3.0-asr-flash-streaming";

        JsonArray vocabularyJson = new JsonArray();
        List<Hotword> wordList = new ArrayList<>();
        wordList.add(new Hotword("Speech Lab", 4));

        for (Hotword word : wordList) {
            JsonObject jsonObject = new JsonObject();
            jsonObject.addProperty("text", word.text);
            jsonObject.addProperty("weight", word.weight);
            vocabularyJson.add(jsonObject);
        }

        VocabularyService service = new VocabularyService(apiKey);
        Vocabulary vocabulary = service.createVocabulary(targetModel, "testpfx", vocabularyJson);

        try {
            if ("OK".equals(service.queryVocabulary(vocabulary.getVocabularyId()).getStatus())) {
                Recognition recognizer = new Recognition();
                RecognitionParam param =
                        RecognitionParam.builder()
                                .model(targetModel)
                                .apiKey(apiKey)
                                .format("wav")
                                .sampleRate(16000)
                                .vocabularyId(vocabulary.getVocabularyId())
                                .build();

                try {
                    System.out.println("Recognition result: " + recognizer.call(param, new File("{YOUR_AUDIO_FILE}")));
                } catch (Exception e) {
                    e.printStackTrace();
                } finally {
                    // Close the WebSocket connection
                    recognizer.getDuplexApi().close(1000, "bye");
                }
            }
        } finally {
            // Delete the hotword list regardless of whether recognition succeeds, to avoid consuming quota
            service.deleteVocabulary(vocabulary.getVocabularyId());
        }
        System.exit(0);
    }
}

class Hotword {
    String text;
    int weight;

    public Hotword(String text, int weight) {
        this.text = text;
        this.weight = weight;
    }
}

Hotword format

Submit hotwords as a JSON array, where each element defines a single hotword and its attributes.

Example: Improve the recognition accuracy of movie titles.

[
    {"text": "Warriors of the Rainbow: Seediq Bale", "weight": 4, "lang": "en"},
    {"text": "Seediq Bale", "weight": 4, "lang": "en"},
    {"text": "Goodbye Mr. Loser", "weight": 4, "lang": "en"},
    {"text": "Never Say Die", "weight": 4, "lang": "en"},
    {"text": "Confucius Family", "weight": 4, "lang": "en"},
    {"text": "Confucius' Family", "weight": 4, "lang": "en"}
]

Field descriptions:

Supported models and regions

Quick start

Pass vocabulary in the parameters of the recognition request. No hotword list is required. For detailed usage of each API, see the API reference under Speech-to-text.

Example (non-real-time speech recognition):

curl --location --request POST 'https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
     --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
     --header "Content-Type: application/json" \
     --header "X-DashScope-SSE: disable" \
     --data '{
    "model": "qwen-audio-3.0-asr-flash",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_audio",
                        "input_audio": {
                            "data": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav"
                        }
                    }
                ]
            }
        ]
    },
    "parameters": {
        "format": "wav",
        "sample_rate": "16000",
        "vocabulary": {"John": 5, "Jane": 5}
    }
}'

Hotword format

Pass instant hotwords as a JSON object (key-value pairs): the key is the hotword text (string), and the value is the hotword weight (integer). For hotword text rules, see Hotword text rules.

Example:

{"Michael": 5, "Jennifer": 5, "Speech Lab": 50}

The weight ranges over [1, 5] or 50: values in [1, 5] define regular hotwords, where a higher value means a stronger preference; 50 defines a super hotword, which greatly improves recall. You can have at most 50 super hotwords. For weight tuning, see Adjust hotword weights.

Hotword text rules

A hotword must be an actual word. The following length limits apply:

• With non-ASCII characters: The total character count (the sum of non-ASCII characters such as Chinese characters, Japanese kana, Korean hangul, and Cyrillic letters, plus any ASCII characters) must not exceed 15.

  Examples:

  • ✅ "厄洛替尼盐酸盐" (7 characters)

  • ✅ "EGFR抑制剂" (7 characters, where EGFR counts as 4 ASCII characters)

  • ✅ "こんにちは" (5 characters)

  • ✅ "Фенибут Белфарм" (15 characters, including the space in the middle)

  • ❌ "Клофелин Белмедпрепараты" (24 characters)

• With ASCII characters only: After splitting on spaces, the number of segments must not exceed 7.

  Examples:

  • ✅ "Exothermic reaction" → 2 segments

  • ✅ "Human immunodeficiency virus type 1" → 5 segments

  • ❌ "The effect of temperature variations on enzyme activity in biochemical reactions" → 11 segments

Adjust hotword weights

The weight controls how strongly the model prefers a hotword. Setting it appropriately improves the recognition accuracy of target words while avoiding misrecognition.

Start testing at weight=4 and adjust based on the results.

**Super hotwords (weight=50)**: Both precompiled and instant hotwords support super hotwords, but only the Qwen-Audio-3.0-ASR-Flash-Streaming, Qwen-Audio-3.0-ASR-Flash-Filetrans, and Qwen-Audio-3.0-ASR-Flash model series do. A weight of 50 greatly improves recall. You can have at most 50 super hotwords.

Design recommendations

• Group by scenario: Organize hotwords separately for different business scenarios (for example, one group for medical terms and another for product names) to simplify maintenance and reuse. For precompiled hotwords, create a separate hotword list for each scenario.

• Mix languages (precompiled hotwords): A single hotword list can mix hotwords in different languages, distinguished by the lang field. When you specify language_hints during recognition, only hotwords in that language take effect.

• Clean up regularly (precompiled hotwords): Delete hotword lists you no longer use to free up your quota (up to 10 per account).

Supported models and regions

Quick start

Context enhancement requires no precreated resources. Pass the context parameters directly in the recognition request:

• Non-real-time speech recognition: Pass context messages in input.messages of the HTTP request, placed before the audio message.

• Real-time speech recognition: Pass context messages in input.context of the WebSocket run-task event. To update the context while the task runs, send a continue-task event. The DashScope SDK wraps this protocol, so you can pass the context directly through a parameter.

Use cases: Passing conversation history or domain terms as context significantly improves the transcription accuracy of proper nouns such as people's names, place names, and product terms. The context can be a multi-turn conversation history (the recognition results and model replies from previous turns) or simply a set of domain terms or a word list.

{
    "model": "qwen-audio-3.0-asr-flash",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_text",
                        "text": "Recognition result of the user's speech in the previous turn"
                    }
                ]
            },
            {
                "role": "assistant",
                "content": [
                    {
                        "type": "text",
                        "text": "Response content of the large model in the previous turn"
                    }
                ]
            },
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_audio",
                        "input_audio": {
                            "data": "URL or Base64 of the audio to be recognized in the current turn"
                        }
                    }
                ]
            }
        ]
    },
    "parameters": {}
}

{
    "header": {
        "action": "run-task",
        "task_id": "2bf83b9a-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "streaming": "duplex"
    },
    "payload": {
        "task_group": "audio",
        "task": "asr",
        "function": "recognition",
        "model": "qwen-audio-3.0-asr-flash-streaming",
        "parameters": {
            "format": "pcm",
            "sample_rate": 16000
        },
        "input": {
            "context": [
                {
                    "role": "user",
                    "content": [
                        {
                            "type": "input_text",
                            "text": "Recognition result of the user's speech in the previous turn"
                        }
                    ]
                },
                {
                    "role": "assistant",
                    "content": [
                        {
                            "type": "text",
                            "text": "Response content of the large model in the previous turn"
                        }
                    ]
                }
            ]
        }
    }
}

from dashscope.audio.asr import Recognition

recognition = Recognition(
    model='qwen-audio-3.0-asr-flash-streaming',
    format='wav',
    sample_rate=16000,
    callback=None)

context = {
    "context": [
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Recognition result of the user's speech in the previous turn"
                }
            ]
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "Response content of the large model in the previous turn"
                }
            ]
        }
    ]
}

result = recognition.call('audio.wav', raw_input=context)
print(result.output)

Map<String, Object> userContent = new HashMap<>();
userContent.put("type", "input_text");
userContent.put("text", "Recognition result of the user's speech in the previous turn");

Map<String, Object> assistantContent = new HashMap<>();
assistantContent.put("type", "text");
assistantContent.put("text", "Response content of the large model in the previous turn");

Map<String, Object> userMessage = new HashMap<>();
userMessage.put("role", "user");
userMessage.put("content", Arrays.asList(userContent));

Map<String, Object> assistantMessage = new HashMap<>();
assistantMessage.put("role", "assistant");
assistantMessage.put("content", Arrays.asList(assistantContent));

Map<String, Object> input = new HashMap<>();
input.put("context", Arrays.asList(userMessage, assistantMessage));

RecognitionParam param = RecognitionParam.builder()
        .model("qwen-audio-3.0-asr-flash-streaming")
        .format("wav")
        .sampleRate(16000)
        .input(input)
        .build();

Recognition recognizer = new Recognition();
System.out.println(recognizer.call(param, new File("audio.wav")));
recognizer.getDuplexApi().close(1000, "bye");

Example

The text field of the context accepts a flexible format—a word list, a natural-language paragraph, or a mix of both—and is highly tolerant of irrelevant text.

The correct recognition result for an audio clip should be "How many of the insider jargon terms in the investment banking world do you know? First, the nine major foreign investment banks—Bulge Bracket, BB ...".

To achieve this enhancement, add a word list or natural-language paragraph that includes specialized terms such as "Bulge Bracket" to the text field of the context.

Q: Recognition doesn't improve after setting hotwords?

Check the following in order:

1. Model match (precompiled hotwords): The target_model specified when you created the hotword list must match the model used by the speech recognition API. When the two don't match, the API doesn't return an error and recognition still returns results, but the hotwords don't take effect. When the results miss the expected hotwords, check this first.

2. Model support

3. Weight: Raise the weight from 4 to 5 and observe the effect. If similar-sounding words are misrecognized as the hotword, revert to 4.

4. Hotword list status (precompiled hotwords): Use the query API to confirm that status is OK.

Q: Are precompiled hotwords used the same way in real-time and non-real-time speech recognition?

They are created the same way but called differently:

• Real-time speech recognition: Pass vocabulary_id in the Recognition or WebSocket connection parameters.

• Audio file transcription: Pass vocabulary_id in the Transcription request parameters.

In both cases, the target_model must match the speech recognition model you actually call. Instant hotwords require no list and no target_model; just pass vocabulary key-value pairs in the request parameters.

Q: Besides hotwords and context enhancement, what other ways can improve recognition accuracy?

You can also optimize in the following ways:

• Audio quality: Match the sample rate to the model's requirement (16 kHz or 8 kHz) and reduce background noise.

• Choose the right model: Different scenarios call for different models. For details, see the Speech-to-text selection guide.

• Specify the language: Declare the audio language through language_hints to improve accuracy in single-language scenarios.