Improve recognition accuracy

​

Visão geral

​

Hotwords pré-compiladas vs. hotwords instantâneas vs. aprimoramento de contexto

​

Pré-requisitos

• Obtain an API key e configured as an environment variable.
• Para chamar o service por meio do DashScope SDK, install the latest SDK.

​

Hotwords pré-compiladas

​

Modelos e regiões suportados

​

Início rápido

​

Fluxo de trabalho

1. Crie uma lista de hotwords. Chame a API create-hotword-list. Especifique target_model (targetModel em Java) para indicar a qual modelo de reconhecimento de fala a lista pertence. Se você já tiver uma lista de hotwords (verificável por meio da API list-all-hotword-lists), pule esta etapa.
2. Chame a API de reconhecimento de fala e passe o ID da lista de hotwords. O modelo usado para reconhecimento deve corresponder ao target_model (targetModel em Java) especificado na criação da lista. Caso contrário, as hotwords não terão efeito.

​

Código de exemplo

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}', vocabulary_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)

​

Formato das hotwords

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

​

Hotwords instantâneas

​

Modelos e regiões suportados

​

Início rápido

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}
    }
}'

​

Formato das hotwords

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

​

Ajuste e regras de hotwords

​

Regras de texto das hotwords

• Com caracteres não ASCII: A contagem total de caracteres (a soma de caracteres não ASCII, como caracteres chineses, kana japonês, hangul coreano e letras cirílicas, mais quaisquer caracteres ASCII) não deve exceder 15. Exemplos:
  • ✅ "厄洛替尼盐酸盐" (7 caracteres)
  • ✅ "EGFR抑制剂" (7 caracteres, onde EGFR conta como 4 caracteres ASCII)
  • ✅ "こんにちは" (5 caracteres)
  • ✅ "Фенибут Белфарм" (15 caracteres, incluindo o espaço no meio)
  • ❌ "Клофелин Белмедпрепараты" (24 caracteres)
• Apenas com caracteres ASCII: Após dividir por espaços, o número de segmentos não deve exceder 7. Exemplos:
  • ✅ "Exothermic reaction" → 2 segmentos
  • ✅ "Human immunodeficiency virus type 1" → 5 segmentos
  • ❌ "The effect of temperature variations on enzyme activity in biochemical reactions" → 11 segmentos

​

Ajustar pesos das hotwords

​

Recomendações de design

• Agrupe por cenário: Organize as hotwords separadamente para diferentes cenários de negócios (por exemplo, um grupo para termos médicos e outro para nomes de product) para simplificar a manutenção e a reutilização. Para hotwords pré-compiladas, crie uma lista distinta para cada cenário.
• Misture idiomas (hotwords pré-compiladas): Uma única lista de hotwords pode conter termos em diferentes idiomas, diferenciados pelo campo lang. Ao especifique language_hints durante o reconhecimento, apenas as hotwords naquele idioma entrarão em vigor.
• Faça limpezas regulares (hotwords pré-compiladas): Exclua listas de hotwords que não são mais usadas para liberar sua cota (até 10 por conta).

​

Limites e faturamento de hotwords

​

Aprimoramento de contexto

​

Modelos e regiões suportados

​

Início rápido

• Reconhecimento de fala não em tempo real: Passe mensagens de contexto em input.messages da requisição http, posicionadas antes da mensagem de áudio.
• Reconhecimento de fala em tempo real: Passe mensagens de contexto em input.context do evento WebSocket run-task. Para atualize o contexto enquanto a tarefa está em execução, envie um evento continue-task. O DashScope SDK encapsula esse protocolo, permitindo que você passe o contexto diretamente por meio de um parâmetro.

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

​

Exemplo

​

Referência da API

• 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

​

P: O reconhecimento não melhora após defina hotwords?

1. Correspondência de modelo (hotwords pré-compiladas): O target_model especificado na criação da lista de hotwords deve corresponder ao modelo usado pela API de reconhecimento de fala. Quando não há correspondência, a API não retorna erro e o reconhecimento ainda produz resultados, mas as hotwords não têm efeito. Se os resultados não incluírem as hotwords esperadas, verifique este item primeiro.
2. Suporte do modelo
3. Peso: Aumente o peso de 4 para 5 e observe o efeito. Se palavras com sonoridade semelhante forem reconhecidas incorretamente como a hotword, reverta para 4.
4. Status da lista de hotwords (hotwords pré-compiladas): Use a API de consulta para confirme se o status é OK.

​

P: As hotwords pré-compiladas são usadas da mesma forma no reconhecimento de fala em tempo real e não em tempo real?

• Reconhecimento de fala em tempo real: Passe vocabulary_id nos parâmetros de conexão do Recognition ou WebSocket.
• Transcrição de arquivos de áudio: Passe vocabulary_id nos parâmetros da requisição de Transcription.

​

P: Além de hotwords e aprimoramento de contexto, quais outras formas podem melhorar a precisão do reconhecimento?

• Qualidade do áudio: Alinhe a taxa de amostragem à exigência do modelo (16 kHz ou 8 kHz) e reduza o ruído de fundo.
• Escolha o modelo certo: Diferentes cenários exigem modelos diferentes. Para detalhes, consulte o guia de seleção Speech-to-text.
• Especifique o idioma: Declare o idioma do áudio por meio de language_hints para melhorar a precisão em cenários de idioma único.