Skip to main content

Fun-ASR-Realtime Java SDK

Este tópico descreve os parâmetros e as interfaces do Java SDK para reconhecimento de fala em tempo real com Fun-ASR-Realtime.

Pré-requisitos

O service está ativado e você Obtain an API key. Para evitar riscos de segurança causados por vazamento de código, Configure API key as an environment variable em vez de codificá-la diretamente no código-fonte.

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.
import com.alibaba.dashscope.audio.asr.recognition.Recognition;
import com.alibaba.dashscope.audio.asr.recognition.RecognitionParam;
import com.alibaba.dashscope.utils.Constants;

import java.io.File;

public class Main {
    public static void main(String[] args) {
        // The following is the configuration for the Singapore region. When calling, replace "{WorkspaceId}" with your real workspace ID. Configurations differ by region.
        Constants.baseWebsocketApiUrl = "wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference";
        // Create a Recognition instance
        Recognition recognizer = new Recognition();
        // Create RecognitionParam
        RecognitionParam param =
                RecognitionParam.builder()
                        .model("fun-asr-realtime")
                        // The API Key differs between the Singapore and Beijing regions. Get an API Key: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
                        // If you have not configured the environment variable, replace the following line with your Model Studio API Key: .apiKey("sk-xxx")
                        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                        .format("wav")
                        .sampleRate(16000)
                        //.parameter("language_hints", new String[]{"zh"})
                        .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 after the task is complete
            recognizer.getDuplexApi().close(1000, "bye");
        }
        System.out.println(
                "[Metric] requestId: "
                        + recognizer.getLastRequestId()
                        + ", first package delay ms: "
                        + recognizer.getFirstPackageDelay()
                        + ", last package delay ms: "
                        + recognizer.getLastPackageDelay());
        System.exit(0);
    }
}

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.
RecognitionParam param = RecognitionParam.builder()
  .model("fun-asr-realtime")
  .format("pcm")
  .sampleRate(16000)
  //.parameter("language_hints", new String[]{"zh"})
  .build();
ParâmetroTipoObrigatórioDescrição
modelStringSimO nome do modelo.
sampleRateIntegerSimTaxa de amostragem, em Hz.Valores válidos: modelos de 8 kHz suportam apenas 8000 Hz; demais modelos aceitam qualquer taxa.
formatStringSimFormato de áudio.Valores válidos:
  • pcm
  • wav
  • mp3
  • opus
  • speex
  • aac
  • amr
opus/speex: Devem usar encapsulamento Ogg.wav: Deve usar codificação PCM.amr: Apenas o tipo AMR-NB é suportado.
vocabularyIdStringNãoID 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.
max_sentence_silenceIntegerNãoLimiar 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: 1300.Valores válidos: [200, 6000].Defina max_sentence_silence pelo método parameter ou parameters da instância RecognitionParam:
RecognitionParam param = RecognitionParam.builder()
 .model("fun-asr-realtime")
 .format("pcm")
 .sampleRate(16000)
 .parameter("max_sentence_silence", 800)
 .build();
multi_threshold_mode_enabledbooleanNãoAtiva 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:
RecognitionParam param = RecognitionParam.builder()
 .model("fun-asr-realtime")
 .format("pcm")
 .sampleRate(16000)
 .parameter("multi_threshold_mode_enabled", true)
 .build();
punctuation_prediction_enabledbooleanNãoDefine se a pontuação deve ser adicionada automaticamente aos resultados:
  • true (padrão): sim. Este valor não pode ser alterado.
Defina punctuation_prediction_enabled pelo método parameter ou parameters da instância RecognitionParam:
RecognitionParam param = RecognitionParam.builder()
 .model("fun-asr-realtime")
 .format("pcm")
 .sampleRate(16000)
 .parameter("punctuation_prediction_enabled", false)
 .build();
heartbeatbooleanNãoAtiva pacotes de heartbeat.Valor padrão: false.
  • true: Mantém a conexão com o servidor ativa mesmo durante envio contínuo de áudio silencioso.
  • false (padrão): Mesmo com envio contínuo de áudio silencioso, a conexão expira e fecha após determinado período.
Áudio silencioso refere-se a conteúdo sem sinal sonoro em um arquivo ou fluxo de dados. É possível gerá-lo de várias formas, usando softwares de edição como Audacity ou Adobe Audition, ou ferramentas de linha de comando como FFmpeg.
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:
RecognitionParam param = RecognitionParam.builder()
 .model("fun-asr-realtime")
 .format("pcm")
 .sampleRate(16000)
 .parameter("heartbeat", true)
 .build();
language_hintsString[]NãoIdioma do áudio a ser reconhecido. Não há valor padrão; se omitido, o modelo detecta o idioma automaticamente.Você pode definir 1 valor. Se definir mais, somente o primeiro terá efeito.
  • fun-asr-realtime:
    • zh: Chinês
    • en: Inglês
    • ja: Japonês
    • ko: Coreano
    • vi: Vietnamita
    • th: Tailandês
    • id: Indonésio
    • ms: Malaio
    • tl: Filipino
    • hi: Hindi
    • ar: Árabe
    • fr: Francês
    • de: Alemão
    • es: Espanhol
    • pt: Português
    • ru: Russo
    • it: Italiano
    • nl: Holandês
    • sv: Sueco
    • da: Dinamarquês
    • fi: Finlandês
    • no: Norueguês
    • el: Grego
    • pl: Polonês
    • cs: Tcheco
    • hu: Húngaro
    • ro: Romeno
    • bg: Búlgaro
    • hr: Croata
    • sk: Eslovaco
  • fun-asr-realtime-2026-02-28:
    • zh: Chinês
    • en: Inglês
    • ja: Japonês
  • fun-asr-flash-8k-realtime, fun-asr-flash-8k-realtime-2026-01-28:
    • zh: Chinês
Defina language_hints pelo método parameter ou parameters da instância RecognitionParam:
RecognitionParam param = RecognitionParam.builder()
 .model("fun-asr-realtime")
 .format("pcm")
 .sampleRate(16000)
 .parameter("language_hints", new String[]{"zh"})
 .build();
speech_noise_thresholdfloatNãoLimiar 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:
  • Quanto mais próximo de -1: O limiar de ruído diminui, aumentando a probabilidade de ruído ser reconhecido como fala, o que pode resultar em transcrição de mais ruído.
  • Quanto mais próximo de +1: O limiar de ruído aumenta, elevando a chance de fala ser confundida com ruído, o que pode filtrar parte da fala.
Trata-se de um parâmetro avançado. Ajustá-lo pode impactar significativamente os resultados. Recomendações:
  • Teste e valide minuciosamente os resultados antes de ajustar.
  • Faça ajustes incrementais conforme o ambiente de áudio real (recomenda-se passo de 0,1).
Defina speech_noise_threshold pelo método parameter ou parameters da instância RecognitionParam:
RecognitionParam param = RecognitionParam.builder()
 .model("fun-asr-realtime")
 .format("pcm")
 .sampleRate(16000)
 .parameter("speech_noise_threshold", -0.5)
 .build();
special_word_filterStringNãoEspecifica 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:
// 1. Build the outermost object
JSONObject root = new JSONObject();
root.put("system_reserved_filter", true);

// 2. Build the "remove completely from results" configuration
JSONObject root1 = new JSONObject();
JSONArray array1 = new JSONArray();
array1.put("start");
array1.put("proceed");
root1.put("word_list", array1);

// 3. Build the "replace with equal-length *" configuration
JSONObject root2 = new JSONObject();
JSONArray array2 = new JSONArray();
array2.put("test");
root2.put("word_list", array2);

// 4. Assemble
root.put("filter_with_empty", root1);
root.put("filter_with_signed", root2);

RecognitionParam param = RecognitionParam.builder()
 .model("fun-asr-realtime")
 .format("pcm")
 .sampleRate(16000)
 .parameter("special_word_filter", root.toString())
 .build();
inputMap<String, Object>NãoObjeto 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.
Apenas os modelos fun-asr-realtime suportam o parâmetro de contexto.
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:
  • role (String, obrigatório): função da mensagem. user indica resultado de reconhecimento de fala do usuário em rodadas anteriores ou lista de palavras específicas de domínio. assistant indica respostas do modelo de linguagem grande em rodadas anteriores.
  • content (List<Map>, obrigatório): lista de conteúdo da mensagem. Cada elemento contém type (String; defina como input_text quando role é user e como text quando role é assistant) e text (String, conteúdo textual).
Limites: mensagens de contexto dos tipos input_text e text limitam-se a 5 cada; ao exceder, mantém-se as 5 mais recentes. O comprimento total do texto por rodada não pode ultrapassar 400 caracteres, truncando-se o excesso a partir do final.
Ao passar contexto, as mensagens em context devem seguir ordem específica: organize-as por rodada de conversa e, dentro de cada rodada, a mensagem user (tipo input_text) deve preceder a mensagem assistant correspondente (tipo text).
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:
// 1. Build the input struct
          Map<String, Object> userContent = new HashMap<>();
          userContent.put("type", "input_text");
          userContent.put("text", "Hello there");

          Map<String, Object> assistantContent = new HashMap<>();
          assistantContent.put("type", "text");
          assistantContent.put("text", "Hello, I am Qwen. How can I help you?");

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

          // 2. Pass it in through the input method
          RecognitionParam param = RecognitionParam.builder()
           .model("fun-asr-realtime")
           .format("pcm")
           .sampleRate(16000)
           .input(input)
           .build();
apiKeyStringNãoSua 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étodoParâmetroValor de retornoDescrição
public void call(RecognitionParam param, final ResultCallback<RecognitionResult> callback)
  • param: Request parameters
  • callback: The callback interface (ResultCallback)
NenhumReconhecimento em tempo real via streaming baseado em callback. Não bloqueia a thread atual.
public String call(RecognitionParam param, File file)
  • param: Request parameters
  • file: Arquivo de áudio a ser reconhecido.
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.
public Flowable<RecognitionResult> streamCall(RecognitionParam param, Flowable<ByteBuffer> audioFrame)
  • param: Request parameters
  • audioFrame: Instância Flowable<ByteBuffer>.
Flowable<RecognitionResult>Reconhecimento em tempo real via streaming baseado em Flowable.
public void sendAudioFrame(ByteBuffer audioFrame)
  • audioFrame: Fluxo de áudio binário do tipo ByteBuffer.
NenhumEnvia á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).
public void stop()
NenhumNenhumInterrompe o reconhecimento em tempo real.Bloqueia a thread atual até que o callback ResultCallback invoque onComplete ou onError.
boolean getDuplexApi().close(int code, String reason)
code: Código de fechamento WebSocket.reason: Motivo do fechamento.Para orientações sobre esses parâmetros, consulte The WebSocket Protocol.trueSempre 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.
public String getLastRequestId()
NenhumrequestIdObté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.
public long getFirstPackageDelay()
NenhumLatê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.
public long getLastPackageDelay()
NenhumLatê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.
ResultCallback<RecognitionResult> callback = new ResultCallback<RecognitionResult>() {
    @Override
    public void onEvent(RecognitionResult result) {
        System.out.println("RequestId: " + result.getRequestId());
        // Add your logic to process the speech recognition result here.
    }

    @Override
    public void onComplete() {
        System.out.println("Task complete");
    }

    @Override
    public void onError(Exception e) {
        System.out.println("Task failed: " + e.getMessage());
    }
};
Interface/MétodoParâmetroValor de retornoDescrição
public void onEvent(RecognitionResult result)
result: Real-time recognition result (RecognitionResult)NenhumInvocado quando o servidor envia resposta.
public void onComplete()
NenhumNenhumInvocado após a conclusão da tarefa.
public void onError(Exception e)
e: Informações da exceção.NenhumInvocado 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étodoParâmetroValor de retornoDescrição
public String getRequestId()
NenhumrequestIdObtém o requestId.
public boolean isSentenceEnd()
NenhumIndica se uma frase completa foi formada, ou seja, se houve detecção de limite de frase.Determina se a frase terminou.
public Sentence getSentence()
NenhumSentence information (Sentence)Obtém informações da frase, incluindo timestamps e texto.

Informações da frase (Sentence)

Interface/MétodoParâmetroValor de retornoDescrição
public Long getBeginTime()
NenhumTempo inicial da frase, em ms.Retorna o tempo inicial da frase.
public Long getEndTime()
NenhumTempo final da frase, em ms.Retorna o tempo final da frase.
public String getText()
NenhumTexto reconhecido.Retorna o texto reconhecido.
public List<Word> getWords()
NenhumLista de objetos Word-level timestamp information (Word).Retorna timestamps no nível de palavra.

Timestamps no nível de palavra (Word)

Interface/MétodoParâmetroValor de retornoDescrição
public long getBeginTime()
NenhumTempo inicial da palavra, em ms.Retorna o tempo inicial da palavra.
public long getEndTime()
NenhumTempo final da palavra, em ms.Retorna o tempo final da palavra.
public String getText()
NenhumPalavra.Retorna a palavra reconhecida.
public String getPunctuation()
NenhumPontuaçã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.
# Basic conversion command (universal template)
# -i, purpose: input file path, example values: audio.wav
# -c:a, purpose: audio encoder, example values: aac, libmp3lame, pcm_s16le
# -b:a, purpose: bitrate (audio quality control), example values: 192k, 320k
# -ar, purpose: sample rate, example values: 44100 (CD), 48000, 16000
# -ac, purpose: number of channels, example values: 1 (mono), 2 (stereo)
# -y, purpose: overwrite an existing file (no value needed)
ffmpeg -i input_audio.ext -c:a encoder_name -b:a bitrate -ar sample_rate -ac channels output.ext

# Example: WAV -> MP3 (preserve original quality)
ffmpeg -i input.wav -c:a libmp3lame -q:a 0 output.mp3
# Example: MP3 -> WAV (16-bit PCM standard format)
ffmpeg -i input.mp3 -c:a pcm_s16le -ar 44100 -ac 2 output.wav
# Example: M4A -> AAC (extract/convert Apple audio)
ffmpeg -i input.m4a -c:a copy output.aac  # Extract directly without re-encoding
ffmpeg -i input.m4a -c:a aac -b:a 256k output.aac  # Re-encode for higher quality
# Example: FLAC lossless -> Opus (high compression)
ffmpeg -i input.flac -c:a libopus -b:a 128k -vbr on output.opus

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 call da 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 sendAudioFrame da The Recognition class.
    • Consulte Bidirectional streaming call: Flowable-based e envie o fluxo binário ao servidor pelo método streamCall da The Recognition class.

Solução de problemas

P: Por que a fala não é reconhecida (sem resultado)?

  1. 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 format está definido como mp3 (configuração incorreta).
    • Taxa de amostragem do áudio é 3600 Hz, mas o parâmetro sampleRate/sample_rate está definido como 48000 (configuração incorreta).
    Use a ferramenta ffprobe para obter informações sobre contêiner, codec, taxa de amostragem, canais e outros dados do áudio:
ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 input.xxx
  1. Verifique se o idioma definido em language_hints corresponde ao idioma real do áudio. Por exemplo, áudio em chinês, mas language_hints definido como en (inglês).
  2. Se nenhuma verificação acima revelar o problema, configure palavras-chave personalizadas para melhorar o reconhecimento de termos específicos.