Improve recognition accuracy

​

Overview

​

Precompiled hotwords vs. instant hotwords vs. context enhancement

​

Prerequisites

• An API key is Obtain an API key and configured as an environment variable.
• To call the service through the DashScope SDK, install the latest SDK.

​

Precompiled hotwords

​

Supported models and regions

​

Quick start

​

Workflow

1. Create a hotword list. Call the create-hotword-list API. You must specify target_model (targetModel in Java) to indicate which speech recognition model the list belongs to. If you already have a hotword list (which you can check through the list-all-hotword-lists API), skip this step.
2. Call the speech recognition API and pass the hotword list ID. The model used for recognition must match the target_model (targetModel in Java) specified when the list was created. Otherwise, the hotwords don't take effect.

​

Sample code

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

# The API Key differs between the Beijing and Singapore regions. Get an API Key: https://www.alibabacloud.com/help/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 Singapore region. When calling, replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

# The following is the configuration for the Singapore region. When calling, replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
dashscope.base_websocket_api_url = 'wss://{WorkspaceId}.ap-southeast-1.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)

​

Hotword format

[
    {"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"}
]

​

Instant hotwords

​

Supported models and regions

​

Quick start

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

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

​

Hotword tuning and rules

​

Hotword text rules

• 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

​

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).

​

Hotword limits and billing

​

Context enhancement

​

Supported models and regions

​

Quick start

• 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.

{
    "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"
                        }
                    ]
                }
            ]
        }
    }
}

​

Example

​

API reference

• Precompiled hotword API reference
• Real-time speech recognition - Qwen-Audio-ASR-Streaming/Fun-ASR-Realtime API reference
• Real-time speech recognition - Qwen-ASR API reference
• Real-time speech recognition - Paraformer API reference
• Non-real-time speech recognition - Qwen-Audio-ASR-Filetrans/Fun-ASR API reference
• Non-real-time speech recognition - Qwen-Audio-ASR/Fun-ASR-Flash API reference
• Non-real-time speech recognition - Qwen-ASR API reference
• Non-real-time speech recognition - Paraformer API reference

​

FAQ

​

Q: Recognition doesn't improve after setting hotwords?

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?

• 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.

​

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

• 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.