Este tópico descreve os parâmetros e as interfaces do Java SDK para reconhecimento de fala em tempo real com Qwen-Audio-3.0-ASR-Flash-Streaming/Fun-ASR-Realtime.
Guia do usuário: Para uma introdução aos modelos e orientações sobre seleção, consulte Speech-to-text.
A The Recognition class fornece interfaces para chamadas síncronas e de streaming bidirecional. Escolha a abordagem adequada às suas necessidades:
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
Envie uma única tarefa de reconhecimento de fala em tempo real e transmita os resultados implementando uma interface de callback.
Envie uma única tarefa de reconhecimento de fala em tempo real e transmita os resultados implementando um fluxo de trabalho (Flowable).
Flowable é um framework open-source para gerenciamento de fluxos de trabalho e processos de negócios, licenciado sob Apache 2.0. Para saber como usar o Flowable, consulte Detalhes da API Flowable.
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 Optimize Paraformer real-time speech recognition for high concurrency.
Use os métodos encadeados de
Importe
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
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.
Defina o parâmetro
Use a ferramenta FFmpeg. Para mais usos, consulte o site oficial do FFmpeg.
Há duas maneiras de reconhecer um arquivo local:
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
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.
Clique para visualizar o exemplo completo
Clique para visualizar o exemplo completo
Chamada de streaming bidirecional: baseada em callback
Envie uma única tarefa de reconhecimento de fala em tempo real e transmita os resultados implementando uma interface de callback.
-
Inicie o reconhecimento de fala em streaming
Instancie The Recognition class e chame o método
callpara vincular os Request parameters e a The callback interface (ResultCallback) e iniciar o reconhecimento. -
Transmita o áudio
Chame o método
sendAudioFrameda The Recognition class em loop para enviar o fluxo de áudio binário ao servidor em segmentos. Leia o áudio de um arquivo local ou de um dispositivo, como um microfone. Enquanto os dados de áudio são enviados, o servidor retorna resultados de reconhecimento ao cliente em tempo real pelo métodoonEventda The callback interface (ResultCallback). Envie cerca de 100 ms de áudio por quadro, mantendo cada payload entre 1 KB e 16 KB. -
Encerre o processo
Chame o método
stopda The Recognition class para encerrar o reconhecimento de fala. Esse método bloqueia a thread atual até que o callbackonCompleteouonErrorda The callback interface (ResultCallback) seja acionado, liberando a thread.
Clique para visualizar o exemplo completo
Clique para visualizar o exemplo completo
Chamada de streaming bidirecional: baseada em Flowable
Envie uma única tarefa de reconhecimento de fala em tempo real e transmita os resultados implementando um fluxo de trabalho (Flowable).
Flowable é um framework open-source para gerenciamento de fluxos de trabalho e processos de negócios, licenciado sob Apache 2.0. Para saber como usar o Flowable, consulte Detalhes da API Flowable.
Clique para visualizar o exemplo completo
Clique para visualizar o exemplo completo
Chame o método
streamCall da The Recognition class diretamente para iniciar o reconhecimento.O método streamCall retorna uma instância Flowable<RecognitionResult>. Use métodos da instância Flowable, como blockingForEach ou subscribe, para processar os resultados. Cada resultado vem encapsulado em um objeto RecognitionResult.O método streamCall aceita dois parâmetros:- Instância
RecognitionParam(Request parameters): use-a para definir modelo, taxa de amostragem, formato de áudio e outros parâmetros necessários ao reconhecimento. - Instância
Flowable<ByteBuffer>: crie uma instância do tipoFlowable<ByteBuffer>e implemente nela a lógica de análise do fluxo de áudio.
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 Optimize Paraformer real-time speech recognition for high concurrency.
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.
Clique para visualizar o exemplo
Clique para visualizar o exemplo
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| model | String | Sim | Nome do modelo. As séries Qwen-Audio-3.0-ASR-Flash-Streaming e Fun-ASR-Realtime são suportadas. Para mais detalhes, consulte Supported models and regions. |
| sampleRate | Integer | Sim | Taxa de amostragem, em Hz.Valores válidos: modelos de 8 kHz suportam apenas 8000 Hz; demais modelos aceitam qualquer taxa. |
| format | String | Sim | Formato de áudio.Valores válidos:
|
| 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: |
| semantic_punctuation_enabled | boolean | Não | Ativa a segmentação semântica.Valor padrão: false.
Defina semantic_punctuation_enabled 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. Quando semantic_punctuation_enabled é true, este parâmetro deixa de ser critério para retornar sentence_end, mas valores muito baixos podem afetar o desempenho do reconhecimento.Valor padrão: 1300.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:
Defina 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.Defina 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.Para a série Qwen-Audio-3.0-ASR-Flash-Streaming, é possível definir até 4 valores; caso defina mais, apenas os 4 primeiros terão efeito. Para a série Fun-ASR-Realtime, apenas 1 valor é aceito; se houver vários, somente o primeiro será considerado.
Clique para visualizar os códigos de idioma suportados
Defina 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:
Defina 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.Defina 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.
Exemplo
Exemplo
| 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.