Alibaba Cloud Model Studio:Improve recognition accuracy

O reconhecimento de fala do Model Studio oferece três formas de aumentar a precisão no reconhecimento de termos especializados, nomes de product e outros vocabulários específicos de domínio: hotwords pré-compiladas, hotwords instantâneas e aprimoramento de contexto. Este tópico descreve o escopo e o uso de cada abordagem.

Visão geral

Alguns termos de negócios, como nomes de product, substantivos próprios e jargões do setor, estão ausentes do vocabulário geral do modelo e, por isso, têm menor precisão no reconhecimento. O reconhecimento de fala do Model Studio fornece três maneiras de melhorar o reconhecimento desses termos: hotwords pré-compiladas, hotwords instantâneas e aprimoramento de contexto.

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

As hotwords personalizadas existem em duas formas: pré-compiladas e instantâneas. A tabela a seguir compara as três abordagens, aplicáveis a diferentes modelos e API:

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

Crie uma lista de hotwords antecipadamente, obtenha o ID dessa lista e passe-o durante o reconhecimento. Essa abordagem é adequada para cenários em que o vocabulário é conhecido e relativamente estável, e você precisa reutilizar a mesma lista de palavras em várias requisições, como nomes de product ou termos médicos.

Modelos e regiões suportados

Início rápido

Fluxo de trabalho

Primeiro crie uma lista de hotwords e depois referencie o ID dela durante o reconhecimento de fala:

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

Exemplo de ponta a ponta: crie uma lista de hotwords, execute o reconhecimento de fala e exclua a lista.

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)

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://www.alibabacloud.com/help/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 Singapore region. When calling, replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
        Constants.baseHttpApiUrl = "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.
        Constants.baseWebsocketApiUrl = "wss://{WorkspaceId}.ap-southeast-1.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;
    }
}

Formato das hotwords

Envie as hotwords como um array JSON, em que cada elemento define uma única hotword e seus atributos.

Exemplo: Melhorar a precisão do reconhecimento de títulos de filmes.

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

Descrição dos campos:

Hotwords instantâneas

As hotwords instantâneas são passadas como pares chave-valor vocabulary diretamente na requisição de reconhecimento. Elas funcionam essencialmente como um conjunto de hotwords ponderadas, idêntico à lista de palavras usada pelas hotwords pré-compiladas, exceto pelo fato de serem enviadas diretamente na requisição, sem necessidade de uma lista pré-criada. Isso é ideal para ajustes temporários de hotwords no nível da sessão.

Modelos e regiões suportados

Início rápido

Passe vocabulary nos parameters da requisição de reconhecimento. Nenhuma lista de hotwords é necessária. Para uso detalhado de cada API, consulte a referência da API em Speech-to-text.

Exemplo (reconhecimento de fala não em tempo real):

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

O exemplo usa o endpoint do DashScope para a região China (Beijing). Você também pode substituí-lo pelo endpoint específico do seu workspace, como https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com, utilizado nos exemplos de hotwords pré-compiladas. Nenhuma outra alteração na requisição é necessária.

Formato das hotwords

Envie as hotwords instantâneas como um objeto JSON (pares chave-valor): a chave é o texto da hotword (string) e o valor é o peso da hotword (integer). Para regras de texto das hotwords, consulte Hotword text rules.

Exemplo:

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

O peso varia no intervalo [1, 5] ou 50: valores em [1, 5] definem hotwords regulares, onde um valor maior indica uma preferência mais forte; 50 define uma super hotword, que melhora significativamente o recall. Você pode ter no máximo 50 super hotwords. Para ajuste de pesos, consulte Adjust hotword weights.

Ajuste e regras de hotwords

As seguintes regras de texto e dicas de ajuste de hotwords aplicam-se tanto a hotwords pré-compiladas quanto a instantâneas.

Regras de texto das hotwords

Uma hotword deve ser uma palavra real. Aplicam-se os seguintes limites de comprimento:

• 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

O peso controla a intensidade com que o modelo prefere uma hotword. Defini-lo adequadamente melhora a precisão do reconhecimento das palavras-alvo, evitando erros de reconhecimento.

Comece os testes com weight=4 e ajuste conforme os resultados.

Super hotwords (weight=50): Tanto hotwords pré-compiladas quanto instantâneas suportam super hotwords, mas apenas as séries de modelos Qwen-Audio-3.0-ASR-Flash-Streaming, Qwen-Audio-3.0-ASR-Flash-Filetrans e Qwen-Audio-3.0-ASR-Flash oferecem esse recurso. Um peso de 50 melhora significativamente o recall. Você pode ter no máximo 50 super 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

O aprimoramento de contexto não exige recursos pré-criados. Passe os parâmetros de contexto diretamente na requisição de reconhecimento:

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

Casos de uso: Passar o histórico da conversa ou termos de domínio como contexto melhora significativamente a precisão da transcrição de substantivos próprios, como nomes de pessoas, lugares e termos de product. O contexto pode ser um histórico de conversa com múltiplos turnos (os resultados de reconhecimento e respostas do modelo de turnos anteriores) ou simplesmente um conjunto de termos de domínio ou uma lista de palavras.

{
    "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");

Exemplo

O campo text do contexto aceita um formato flexível — uma lista de palavras, um parágrafo em linguagem natural ou uma combinação de ambos — e é altamente tolerante a textos irrelevantes.

O resultado correto de reconhecimento para um trecho de áudio deveria ser "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 ...".

Para obter esse aprimoramento, adicione uma lista de palavras ou um parágrafo em linguagem natural que inclua termos especializados, como "Bulge Bracket", ao campo text do contexto.

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?

Verifique os itens a seguir nesta ordem:

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?

Elas são criadas da mesma maneira, mas chamadas de forma diferente:

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

Em ambos os casos, o target_model deve corresponder ao modelo de reconhecimento de fala realmente chamado. Hotwords instantâneas não exigem lista nem target_model; basta passar pares chave-valor vocabulary nos parâmetros da requisição. Para as séries de modelos Qwen-Audio-3.0-ASR-Flash-Streaming, Qwen-Audio-3.0-ASR-Flash-Filetrans e Qwen-Audio-3.0-ASR-Flash, que suportam hotwords instantâneas, o sistema mescla hotwords pré-compiladas e instantâneas quando ambas estão configuradas. Se o conjunto mesclado contiver mais de 2.000 hotwords, o sistema selecionará aleatoriamente 2.000 para uso.

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

Você também pode otimizar das seguintes maneiras:

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