Este tópico descreve os parâmetros e as interfaces do Java SDK para reconhecimento de fala em tempo real com Qwen-Audio-ASR-Streaming.
Pré-requisitos
Início rápido
A The Recognition class fornece interfaces para chamadas síncronas e de streaming bidirecional. Escolha a abordagem adequada às suas necessidades:
- Chamada síncrona: reconhece um arquivo local e retorna o resultado completo de uma só vez. Ideal para processar áudio pré-gravado.
- Chamada de streaming bidirecional: reconhece um fluxo de áudio diretamente e retorna resultados em tempo real. O fluxo pode vir de um dispositivo externo, como um microfone, ou ser lido de um arquivo local. Indicada para cenários que exigem feedback imediato.
- Chamada síncrona
- Chamada de streaming bidirecional: baseada em callback
- Chamada de streaming bidirecional: baseada em Flowable
Envie uma única tarefa de reconhecimento de fala em tempo real e obtenha o resultado sincronamente passando um arquivo local. A chamada bloqueia a execução até o retorno do resultado.Instancie The Recognition class e chame o método
call para vincular os Request parameters e o arquivo a ser reconhecido. O método executa o reconhecimento e retorna o resultado final.Chamadas de alta concorrência
O DashScope Java SDK utiliza o pool de conexões do OkHttp3 para reduzir a sobrecarga de estabelecimento repetido de conexões. Para mais detalhes, consulte Melhores práticas para alta concorrência.
Parâmetros de solicitação
Use os métodos encadeados de RecognitionParam para configurar modelo, taxa de amostragem, formato de áudio e outros parâmetros. Passe o objeto configurado para o método call/streamCall da The Recognition class.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
model | String | Sim | O nome do modelo. |
sampleRate | Integer | Sim | A taxa de amostragem em Hz. Qualquer taxa é compatível. |
format | String | Sim | Formato de áudio.Valores válidos:
|
keep_dialect | boolean | Não | Aplica-se apenas a qwen-audio-3.1-asr-flash-streaming.false, que transcreve dialetos em chinês padrão. Defina como true para preservar expressões dialetais. Defina com .parameter("keep_dialect", value). |
vad_model | String | Não | Aplica-se apenas a qwen-audio-3.1-asr-flash-streaming.near_meeting_16k (campo próximo) ou far_field_meeting_16k (campo distante, padrão). Defina com .parameter("vad_model", value). |
vocabularyId | String | Não | ID de uma lista de palavras-chave pré-compilada.Gere esse ID antecipadamente chamando a API de criação de lista de palavras-chave. Passe o ID durante o reconhecimento para usar as palavras-chave da lista.Adequado para cenários com vocabulário conhecido e relativamente estável, nos quais é necessário reutilizar a mesma lista entre solicitações.Para detalhes de uso, consulte Precompiled hotwords. |
vocabulary | Map<String, Integer> | Não | Palavras-chave instantâneas.Passadas como pares chave-valor, onde a chave é o texto da palavra-chave (string) e o valor é o peso (integer). Não é necessário criar uma lista antecipadamente. O peso varia de [1, 5] ou é definido como 50: valores em [1, 5] aumentam a probabilidade de o modelo gerar a palavra conforme o valor cresce; o valor 50 designa uma super palavra-chave, que melhora significativamente a recuperação, mas o número de super palavras-chave não pode exceder 50.Adequado para otimização temporária de palavras-chave no nível de sessão.Quando configurado junto com palavras-chave pré-compiladas, apenas as instantâneas têm efeito. Para detalhes de uso, consulte Instant hotwords.Defina vocabulary pelo método parameter ou parameters da instância RecognitionParam: |
max_sentence_silence | Integer | Não | Limiar de silêncio VAD para segmentação, em ms. Se o silêncio após um segmento de fala superar esse limiar, o sistema considera a frase encerrada.Valor padrão: 800.Valores válidos: [200, 6000].Defina max_sentence_silence pelo método parameter ou parameters da instância RecognitionParam: |
multi_threshold_mode_enabled | boolean | Não | Ativa o modo de múltiplos limiares. Quando ativado, evita que segmentos VAD fiquem excessivamente longos.Valor padrão: false.Defina multi_threshold_mode_enabled pelo método parameter ou parameters da instância RecognitionParam: |
punctuation_prediction_enabled | boolean | Não | Define se a pontuação deve ser adicionada automaticamente aos resultados:
punctuation_prediction_enabled pelo método parameter ou parameters da instância RecognitionParam: |
heartbeat | boolean | Não | Ativa pacotes de heartbeat.Valor padrão: false.
Para usar este campo, a versão do SDK deve ser 2.19.1 ou posterior. heartbeat pelo método parameter ou parameters da instância RecognitionParam: |
language_hints | String[] | Não | Idioma do áudio a ser reconhecido. Não há valor padrão; se omitido, o modelo detecta o idioma automaticamente.Você pode definir até 4 valores. Se definir mais, somente os 4 primeiros terão efeito.
Clique para visualizar os códigos de idioma suportados
language_hints pelo método parameter ou parameters da instância RecognitionParam: |
speech_noise_threshold | float | Não | Limiar para distinguir fala de ruído, usado para ajustar a sensibilidade da Detecção de Atividade de Voz (VAD).Valores válidos: [-1,0, 1,0].Descrições dos valores:
speech_noise_threshold pelo método parameter ou parameters da instância RecognitionParam: |
special_word_filter | String | Não | Especifica palavras sensíveis a serem processadas durante o reconhecimento, permitindo definir métodos distintos para cada palavra. Para mais detalhes, consulte Sensitive word filtering.Defina special_word_filter pelo método parameter ou parameters da instância RecognitionParam: |
input | Map<String, Object> | Não | Objeto de entrada que fornece o contexto da conversa. O contexto auxilia no reconhecimento e melhora a precisão de termos específicos. Para uso, consulte Quick start.O Map deve conter a chave context, cujo valor é um array de mensagens do tipo List<Map<String, Object>>. Cada mensagem contém os seguintes campos:
Para usar este campo, a versão do SDK deve ser 2.22.23 ou posterior. input pelo método input da instância RecognitionParam: |
apiKey | String | Não | Sua chave de API. |
Interfaces principais
Classe Recognition
Importe Recognition com import com.alibaba.dashscope.audio.asr.recognition.Recognition;. Suas interfaces principais são:
| Interface/Método | Parâmetro | Valor de retorno | Descrição |
|---|---|---|---|
| Nenhum | Reconhecimento em tempo real via streaming baseado em callback. Não bloqueia a thread atual. | |
| Resultado do reconhecimento. | Reconhecimento não streaming de arquivo local. Bloqueia a thread atual até concluir a leitura completa do arquivo, que deve ser legível. | |
| Flowable<RecognitionResult> | Reconhecimento em tempo real via streaming baseado em Flowable. | |
| Nenhum | Envia áudio. Mantenha cada bloco enviado com tamanho razoável. Recomenda-se cerca de 100 ms de áudio por bloco, entre 1 KB e 16 KB.Os resultados chegam pelo método onEvent da The callback interface (ResultCallback). | |
Nenhum | Nenhum | Interrompe o reconhecimento em tempo real.Bloqueia a thread atual até que o callback ResultCallback invoque onComplete ou onError. | |
| code: Código de fechamento WebSocket.reason: Motivo do fechamento.Para orientações sobre esses parâmetros, consulte The WebSocket Protocol. | true | Sempre feche a conexão WebSocket ao término da tarefa, haja ou não exceção, para evitar vazamentos. Para reutilizar conexões visando eficiência, consulte Optimize Paraformer real-time speech recognition for high concurrency. | |
Nenhum | requestId | Obtém o requestId da tarefa atual. Disponível após iniciar nova tarefa com call ou streamingCall.Disponível apenas no SDK versão 2.18.0 ou posterior. | |
Nenhum | Latência do primeiro pacote. | Obtém a latência do primeiro pacote, ou seja, o atraso entre o envio do primeiro pacote de áudio e o recebimento do primeiro resultado. Use após concluir a tarefa. Disponível apenas no SDK versão 2.18.0 ou posterior. | |
Nenhum | Latência do último pacote. | Obtém a latência do último pacote, ou seja, o tempo entre o envio do comando stop e o recebimento do resultado final. Use após concluir a tarefa.Disponível apenas no SDK versão 2.18.0 ou posterior. |
Interface de callback (ResultCallback)
Durante bidirectional streaming calls, o servidor retorna informações-chave e dados ao cliente via callbacks. Implemente os métodos de callback para tratar essas informações.
Estenda a classe abstrata ResultCallback para implementar os métodos. Ao estendê-la, defina o tipo genérico como RecognitionResult. RecognitionResult encapsula a estrutura de dados retornada pelo servidor.
Como o Java suporta reutilização de conexão, não há onClose nem onOpen.
| Interface/Método | Parâmetro | Valor de retorno | Descrição |
|---|---|---|---|
result: Real-time recognition result (RecognitionResult) | Nenhum | Invocado quando o servidor envia resposta. | |
Nenhum | Nenhum | Invocado após a conclusão da tarefa. | |
e: Informações da exceção. | Nenhum | Invocado quando ocorre exceção. |
Resposta
Resultado de reconhecimento em tempo real (RecognitionResult)
RecognitionResult representa o resultado de um único reconhecimento em tempo real.
| Interface/Método | Parâmetro | Valor de retorno | Descrição |
|---|---|---|---|
Nenhum | requestId | Obtém o requestId. | |
Nenhum | Indica se uma frase completa foi formada, ou seja, se houve detecção de limite de frase. | Determina se a frase terminou. | |
Nenhum | Sentence information (Sentence) | Obtém informações da frase, incluindo timestamps e texto. |
Informações da frase (Sentence)
| Interface/Método | Parâmetro | Valor de retorno | Descrição |
|---|---|---|---|
Nenhum | Tempo inicial da frase, em ms. | Retorna o tempo inicial da frase. | |
Nenhum | Tempo final da frase, em ms. | Retorna o tempo final da frase. | |
Nenhum | Texto reconhecido. | Retorna o texto reconhecido. | |
Nenhum | Lista de objetos Word-level timestamp information (Word). | Retorna timestamps no nível de palavra. |
Timestamps no nível de palavra (Word)
| Interface/Método | Parâmetro | Valor de retorno | Descrição |
|---|---|---|---|
Nenhum | Tempo inicial da palavra, em ms. | Retorna o tempo inicial da palavra. | |
Nenhum | Tempo final da palavra, em ms. | Retorna o tempo final da palavra. | |
Nenhum | Palavra. | Retorna a palavra reconhecida. | |
Nenhum | Pontuação. | Retorna a pontuação. |
Códigos de erro
Em caso de erros, consulte Error codes para solução de problemas.
Se o problema persistir, junte-se à comunidade de desenvolvedores para relatá-lo e forneça o Request ID para investigação.
FAQ
Recursos
P: Como manter a conexão com o servidor ativa durante longos períodos de silêncio?
Defina o parâmetro heartbeat como true e continue enviando áudio silencioso ao servidor.
Áudio silencioso é aquele sem sinal sonoro no arquivo ou fluxo de dados. Gere-o de várias formas, por exemplo, com softwares de edição como Audacity ou Adobe Audition, ou ferramentas de linha de comando como FFmpeg.
P: Como converter áudio para um formato suportado?
Use a ferramenta FFmpeg. Para mais usos, consulte o site oficial do FFmpeg.
P: Como reconhecer um arquivo local (gravação)?
Há duas maneiras de reconhecer um arquivo local:
-
Passe o caminho do arquivo local diretamente: essa abordagem retorna o resultado completo apenas ao fim do reconhecimento, não sendo adequada para cenários que exigem feedback imediato.
Consulte Synchronous call e passe o caminho ao método
callda The Recognition class para reconhecer a gravação diretamente. -
Converta o arquivo local em fluxo binário: essa abordagem reconhece o arquivo e transmite resultados simultaneamente, adequada para cenários que exigem feedback imediato.
- Consulte Bidirectional streaming call: callback-based e envie o fluxo binário ao servidor pelo método
sendAudioFrameda The Recognition class. - Consulte Bidirectional streaming call: Flowable-based e envie o fluxo binário ao servidor pelo método
streamCallda The Recognition class.
- Consulte Bidirectional streaming call: callback-based e envie o fluxo binário ao servidor pelo método
Solução de problemas
P: Por que a fala não é reconhecida (sem resultado)?
-
Verifique se o formato de áudio (
format) e a taxa de amostragem (sampleRate/sample_rate) nos parâmetros estão corretos e atendem às restrições. Erros comuns incluem:- Arquivo com extensão .wav, mas formato MP3, enquanto o parâmetro
formatestá definido como mp3 (configuração incorreta). - Taxa de amostragem do áudio é 3600 Hz, mas o parâmetro
sampleRate/sample_rateestá definido como 48000 (configuração incorreta).
- Arquivo com extensão .wav, mas formato MP3, enquanto o parâmetro
-
Verifique se o idioma definido em
language_hintscorresponde ao idioma real do áudio. Por exemplo, áudio em chinês, maslanguage_hintsdefinido comoen(inglês). - Se nenhuma verificação acima revelar o problema, configure palavras-chave personalizadas para melhorar o reconhecimento de termos específicos.