Melhore o reconhecimento de nomes de pessoas, produtos e termos especializados com palavras-chave (instantâneas ou pré-compiladas) e aprimoramento de contexto.
Escolher um método de otimização
Nomes de pessoas, produtos e termos especializados podem ter pronúncia semelhante à de palavras comuns, resultando em homófonos ou grafias incorretas na transcrição. Palavras-chave e aprimoramento de contexto fornecem grafias corretas ou informações relevantes para ajudar o modelo a melhorar o reconhecimento.
Escolha conforme as informações que o aplicativo já possui: use palavras-chave para uma lista de termos definida, ou contexto para conversas ou descrições de negócios existentes. Para palavras-chave, escolha o modo instantâneo ou pré-compilado conforme a necessidade de reutilizar a lista em várias solicitações. Confira os Modelos e regiões compatíveis antes de usar.
| Método | Quando usar | Como usar |
|---|---|---|
| Palavras-chave instantâneas | Os nomes e termos mudam a cada solicitação, ou há poucos termos temporários, sem necessidade de armazenar e gerenciar uma lista. | Envie um objeto “termo: peso” em cada solicitação de reconhecimento. O aplicativo fornece as grafias corretas e pode ajustar a preferência do modelo por cada termo por meio de seu peso. |
| Palavras-chave pré-compiladas | Já existe um glossário de negócios, ou o mesmo conjunto de termos é usado repetidamente e precisa de manutenção centralizada. | Crie uma lista com termos, pesos e idiomas opcionais e referencie seu ID durante o reconhecimento. Atualize a lista quando o glossário mudar, sem reenviar todas as entradas a cada solicitação. |
| Aprimoramento de contexto | O aplicativo já armazena conversas recentes, descrições de negócios ou textos especializados que podem ajudar no reconhecimento. | Envie o texto relevante como mensagens de contexto junto com o áudio. Não é necessário extrair termos nem atribuir pesos individuais. Inclua a grafia correta dos termos desejados. Uma lista de termos definida também pode ser usada como palavras-chave para corrigir o mesmo tipo de erro. |
Usar palavras-chave
Antes de executar os exemplos, baixe o áudio de exemplo e prepare uma chave de API no console do Model Studio. Texto do áudio: “Please send the quarterly project report to Kelyra before Friday.”
Palavras-chave instantâneas
Palavras-chave instantâneas são adequadas para termos que mudam a cada solicitação. Defina parameters.vocabulary como um objeto JSON cujas chaves são os textos das palavras-chave (string) e cujos valores são os pesos (integer). Não é necessário criar uma lista antes.
-
Reconhecer o áudio sem palavras-chave
Sem palavras-chave, o nome deste exemplo não é reconhecido com precisão. A solicitação a seguir retorna o resultado sem configuração.
cURL
-
Adicionar palavras-chave instantâneas à solicitação
Adicione “Kelyra” à mesma solicitação com peso 4. Mantenha as demais entradas inalteradas. Para intervalos e ajustes de peso, consulte Ajustar os pesos das palavras-chave.
cURL
| Configuração | Exemplo de transcrição |
|---|---|
| Sem configuração | Please send the quarterly project report to Kellira before Friday. |
| Com configuração | Please send the quarterly project report to Kelyra before Friday. |
Palavras-chave pré-compiladas
As palavras-chave pré-compiladas são adequadas para vocabulários de negócios reutilizados em várias solicitações. Crie uma lista antecipadamente e passe vocabulary_id durante o reconhecimento, sem reenviar todas as entradas.
Ao criar a lista, envie as entradas como um array JSON. Cada elemento contém os seguintes campos:
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
text | string | Sim | Uma palavra real em um idioma compatível com o modelo. Para os limites de tamanho, consulte Regras do texto das palavras-chave. |
weight | integer | Sim | Use 1 a 5 para palavras-chave comuns, começando em 4. Alguns modelos também aceitam o peso 50 para super palavras-chave. Consulte Ajustar os pesos das palavras-chave. |
lang | string | Não | Código que determina o idioma de aplicação da entrada. Pode ser omitido se o idioma for desconhecido. Para a relação com language_hints, consulte Organizar e manter vocabulários. |
O gerenciamento de palavras-chave e o reconhecimento de fala devem usar a mesma conta. Caso contrário, o reconhecimento não pode acessar o vocabulário.
- HTTP / cURL
- SDK
-
Criar uma lista de palavras-chave
Este exemplo usa
qwen-audio-3.1-asr-flashe especifica o modelo de destino portarget_model. Salveoutput.vocabulary_idda resposta.cURL -
Verificar se a lista está pronta
Substitua
<vocabulary_id>pelo ID retornado na criação e consulte a lista. Prossiga com o reconhecimento quandooutput.statusforOK.cURL -
Referenciar a lista no reconhecimento
Referencie a lista por
parameters.vocabulary_idna solicitação de reconhecimento, sem reenviar as entradas.cURL -
Reutilizar ou excluir a lista
As solicitações seguintes podem continuar usando o mesmo ID. Execute a solicitação de exclusão abaixo somente quando a lista não for mais necessária, para liberar sua cota.
cURL
Usar o aprimoramento de contexto
O aprimoramento de contexto pode usar diretamente o histórico de conversas ou textos especializados existentes. As palavras-chave exigem termos e pesos, enquanto o contexto é enviado como mensagens de texto, sem dividir os materiais de negócios em entradas individuais. Os dois métodos podem melhorar o reconhecimento de nomes próprios. Escolha conforme as informações disponíveis no aplicativo.
Preparar o contexto
Para o áudio de exemplo, mensagens existentes que contenham o nome do destinatário “Kelyra” podem fornecer sua grafia correta. Duas fontes comuns de contexto são apresentadas a seguir.
- Contexto de negócios ou texto especializado
- Histórico de conversas
Use o texto relevante de uma descrição de projeto ou material especializado existente em uma mensagem com
role=user e type=input_text. Não é necessário inventar uma conversa nem adicionar uma resposta. Envie o seguinte array como contexto:A mensagem
assistant é opcional. Organize o histórico por turno, com cada mensagem user antes da mensagem assistant correspondente. Para os limites de tamanho do texto e de turnos retidos, consulte Limites de uso.Configurar e chamar o serviço
Reconheça o mesmo áudio com o contexto preparado. Escolha um exemplo de chamada conforme a família de modelos.
- Qwen-Audio-ASR
- Qwen-Audio-ASR-Message / Qwen-Audio-ASR-Streaming
- Qwen-Audio-ASR-Filetrans
Este exemplo usa
qwen-audio-3.1-asr-flash. Coloque as mensagens de contexto em ordem em input.messages, seguidas da mensagem de áudio atual contendo input_audio.cURL
| Configuração | Exemplo de transcrição |
|---|---|
| Sem configuração | Please send the quarterly project report to Kellira before Friday. |
| Com configuração | Please send the quarterly project report to Kelyra before Friday. |
Ajustar e solucionar problemas de reconhecimento
Compare o mesmo áudio antes e depois da configuração e ajuste entradas, pesos ou contexto. A orientação de palavras-chave vale para ambos os métodos.
Ajustar os pesos das palavras-chave
Os pesos de palavras-chave comuns variam de 1 a 5. Comece com weight=4. Pesos maiores favorecem a palavra, mas valores excessivos podem substituir incorretamente palavras de som semelhante.
| Peso | Preferência | Quando usar |
|---|---|---|
| 1–2 | Leve | Termo com som parecido com uma palavra comum, para evitar correção excessiva |
| 3–4 | Moderada | Configuração inicial recomendada para a maioria dos cenários |
| 5 | Forte | Termos frequentes no áudio e raramente confundidos com outras palavras |
weight=50 nos dois métodos para melhorar a recuperação dos termos-alvo. Cada vocabulário ou solicitação pode conter no máximo 50 super palavras-chave.
Organizar e manter vocabulários
- Agrupar por cenário: Crie listas pré-compiladas separadas para diferentes cenários de negócios, como terminologia médica e nomes de produtos, para reduzir entradas não relacionadas.
-
Distinguir o idioma da entrada do idioma do áudio: um vocabulário pré-compilado pode misturar idiomas, identificados por
lang. O parâmetro de reconhecimentolanguage_hintsdeclara o idioma do áudio. Quando definido, apenas palavras-chave no idioma correspondente têm efeito; os demais idiomas são ignorados. - Manter regularmente: Atualize as entradas conforme as necessidades de negócios e exclua listas não utilizadas para liberar a cota.
Aguarde pelo menos 5 minutos entre atualizações de uma lista de palavras-chave; caso contrário, as palavras-chave atualizadas podem não entrar em vigor.
Investigar a qualidade do reconhecimento
Primeiro, identifique se o problema é uma configuração sem efeito, uma preferência excessiva por palavras-chave ou um áudio difícil de reconhecer. Depois, verifique os itens correspondentes.
| Sintoma | Verificações e ações |
|---|---|
| As palavras-chave não são reconhecidas como esperado | Confira primeiro os Modelos e regiões compatíveis. As palavras-chave instantâneas devem estar em parameters.vocabulary. Para as pré-compiladas, confira a conta, vocabulary_id, status=OK e se o target_model da lista corresponde ao modelo de reconhecimento.Aumente o peso da palavra-chave dentro do intervalo compatível e compare os resultados do mesmo áudio para verificar se o peso era muito baixo. |
| Outras palavras são substituídas incorretamente por palavras-chave | Reduza o peso dentro do intervalo compatível e remova termos não relacionados ao cenário. Confira se lang corresponde ao language_hints da API de reconhecimento e se as entradas pertencem ao idioma desejado. |
| O contexto não melhora os termos desejados | Confira as grafias corretas, as funções, os tipos e a ordem das mensagens, além do campo de entrada exigido pela API. O texto além dos limites de tamanho ou de turnos pode ser truncado ou descartado. Consulte Limites de uso. |
| Muitas palavras comuns também estão incorretas | Confira se o formato e a taxa de amostragem do áudio atendem aos requisitos do modelo e reduza o ruído de fundo. Para áudio em um único idioma, declare o idioma por language_hints na API de reconhecimento. Para seleção de modelos e requisitos de áudio, consulte Visão geral do reconhecimento de fala. |
Modelos e regiões compatíveis
- Palavras-chave pré-compiladas
- Palavras-chave instantâneas
- Aprimoramento de contexto
- Singapura
- China (Pequim)
As palavras-chave são aceitas somente no workspace principal, não em sub-workspaces.
- Qwen-Audio-ASR: qwen-audio-3.1-asr-flash, qwen-audio-3.0-asr-flash
- Qwen-Audio-ASR-Streaming: qwen-audio-3.1-asr-flash-streaming, qwen-audio-3.0-asr-flash-streaming
- Qwen-Audio-ASR-Filetrans: qwen-audio-3.1-asr-flash-filetrans, qwen-audio-3.0-asr-flash-filetrans
- Qwen-Audio-ASR-Message: qwen-audio-3.1-asr-flash-message
- Fun-ASR-Realtime: fun-asr-realtime
- Fun-ASR-Flash: fun-asr-flash-2026-06-15
- Fun-ASR: fun-asr
Limites de uso
- Limites de palavras-chave
- Regras do texto das palavras-chave
- Limites de contexto
| Limite | Descrição |
|---|---|
| Número de listas de palavras-chave | Até 50 vocabulários pré-compilados por conta, compartilhados entre todos os modelos. Cada um possui um vocabulary_id. |
| Palavras-chave | Séries Qwen-Audio-ASR-Message, Qwen-Audio-ASR-Streaming, Qwen-Audio-ASR-Filetrans e Qwen-Audio-ASR: até 2000.Modelos de versão principal das séries Fun-ASR-Realtime, Fun-ASR-Flash e Fun-ASR: até 2000. Outros modelos dessas séries e a série Paraformer: até 500.A contagem é por vocabulário para palavras-chave pré-compiladas e por solicitação para as instantâneas. |
| Super palavras-chave | No máximo 50 entradas podem ter peso 50. |
Nas séries Qwen-Audio-ASR-Message, Qwen-Audio-ASR-Streaming, Qwen-Audio-ASR-Filetrans e Qwen-Audio-ASR, o serviço mescla as palavras-chave pré-compiladas e instantâneas quando ambas são configuradas. Se o conjunto mesclado ultrapassar 2000 palavras-chave, o serviço seleciona 2000 aleatoriamente.
Cobrança dos recursos
Os recursos de palavras-chave instantâneas e pré-compiladas são gratuitos. Para os custos de chamada de modelos com palavras-chave ou aprimoramento de contexto, consulte as regras de cobrança.
APIs relacionadas
- Para criar, consultar, atualizar e excluir listas de palavras-chave, consulte API de gerenciamento de palavras-chave.
- SDKs de gerenciamento de palavras-chave: SDK Java e SDK Python.
- APIs de chamada de modelos: Eventos do cliente Qwen-Audio-ASR-Message, Eventos do cliente Qwen-Audio-ASR-Streaming, Qwen-Audio-ASR-Filetrans HTTP API e Qwen-Audio-ASR HTTP API.