Tradução de apoio para consulta. Código e identificadores técnicos preservados. Consultar referência original ↗

Qwen-ASR SDK Java em tempo real

Qwen Integração Java ASR

Guia do usuário: Para obter a visão geral do modelo, recursos e código de exemplo completo, consulte Reconhecimento de fala em tempo real.

Modos de interação

Qwen-ASR-Realtime suporta dois modos:

Modo	`enableTurnDetection`	Como funciona
Modo VAD (padrão)	`true`	O servidor detecta limites de fala com VAD e confirma o buffer de áudio para reconhecimento.
Modo manual	`false`	Você controla quando enviar o áudio ligando para `commit()`.

Para obter detalhes, consulte Modo VAD e Modo manual.

Parâmetros de solicitação

Parâmetros de conexão (OmniRealtimeParam)

Definir com OmniRealtimeParam métodos encadeados.

Clique para ver o código de amostra.

OmniRealtimeParam param = OmniRealtimeParam.builder()
  .model("qwen3-asr-flash-realtime")
  .url("wss://maas.qwencloudapi.com/api-ws/v1/realtime")
  // If you have not configured an environment variable, replace the following line with .apikey("sk-xxx").
  .apikey(System.getenv("DASHSCOPE_API_KEY"))
  .build();

Parâmetro	Tipo	Obrigatório	Descrição
`model`	`String`	Sim	Nome do modelo. Exemplo: `qwen3-asr-flash-realtime`.
`url`	`String`	Sim	Ponto final do serviço: `wss://maas.qwencloudapi.com/api-ws/v1/realtime`.
`apikey`	`String`	Não	Chave de API.

Configuração de sessão (OmniRealtimeConfig)

Definir com OmniRealtimeConfig métodos encadeados.

Clique para ver o código de amostra.

OmniRealtimeTranscriptionParam transcriptionParam = new OmniRealtimeTranscriptionParam();
transcriptionParam.setLanguage("zh");
transcriptionParam.setInputSampleRate(16000);
transcriptionParam.setInputAudioFormat("pcm");

OmniRealtimeConfig config = OmniRealtimeConfig.builder()
  .modalities(Collections.singletonList(OmniRealtimeModality.TEXT))
  .enableTurnDetection(true)
  .turnDetectionType("server_vad")
  .turnDetectionThreshold(0.0f)
  .turnDetectionSilenceDurationMs(400)
  .transcriptionConfig(transcriptionParam)
  .build();

Parâmetro	Tipo	Obrigatório	Descrição
`modalities`	`List<OmniRealtimeModality>`	Sim	Modalidade de saída. Corrigido para `[OmniRealtimeModality.TEXT]`.
`enableTurnDetection`	`boolean`	Não	Ativa o VAD do lado do servidor. Quando desativado, ligue `commit()` para acionar o reconhecimento manualmente. Padrão: `true`.
`turnDetectionType`	`String`	Não	Tipo VAD. Corrigido para `server_vad`.
`turnDetectionThreshold`	`float`	Não	Limite de VAD. Recomendado: `0.0`. Padrão: `0.2`. Intervalo válido: `[-1, 1]`. Valores mais baixos aumentam a sensibilidade, mas correm o risco de tratar o ruído de fundo como fala. Valores mais altos reduzem a sensibilidade, o que é adequado para ambientes ruidosos.
`turnDetectionSilenceDurationMs`	`int`	Não	Limite de silêncio do VAD em milissegundos. O silêncio além desta duração marca o fim de uma declaração. Recomendado: `400`. Padrão: `800`. Intervalo válido: `[200, 6000]`. Valores mais baixos (como 300 ms) aceleram a resposta, mas podem dividir-se em pausas normais. Valores mais altos (como 1.200 ms) lidam melhor com pausas longas, mas adicionam latência.
`transcriptionConfig`	`OmniRealtimeTranscriptionParam`	Não	Configurações de reconhecimento de fala. Consulte Parâmetros de transcrição.

Parâmetros de transcrição (OmniRealtimeTranscriptionParam)

Definir com OmniRealtimeTranscriptionParam métodos setter.

Clique para ver o código de amostra.

OmniRealtimeTranscriptionParam transcriptionParam = new OmniRealtimeTranscriptionParam();
transcriptionParam.setLanguage("zh");
transcriptionParam.setInputSampleRate(16000);
transcriptionParam.setInputAudioFormat("pcm");

Parâmetro	Tipo	Obrigatório	Descrição
`language`	`String`	Não	Idioma de origem do áudio. Valores suportados: `zh` (chinês - mandarim, sichuanês, minnan e wu), `yue` (Cantonês), `en` (Inglês), `ja` (japonês), `de` (Alemão), `ko` (coreano), `ru` (Russo), `fr` (francês), `pt` (português), `ar` (Árabe), `it` (italiano), `es` (Espanhol), `hi` (hindi), `id` (indonésio), `th` (tailandês), `tr` (Turco), `uk` (ucraniano), `vi` (vietnamita), `cs` (Tcheco), `da` (dinamarquês), `fil` (Filipino), `fi` (finlandês), `is` (islandês), `ms` (malaio), `no` (norueguês), `pl` (polonês), `sv` (sueco).
`inputSampleRate`	`int`	Não	Taxa de amostragem de áudio em Hz. Suportado: `16000`, `8000`. Padrão: `16000`. Configuração `8000` aciona o aumento da resolução do lado do servidor para 16.000 Hz, o que pode adicionar um pequeno atraso. Usar `8000` somente para fonte de áudio de 8.000 Hz (como linhas telefônicas).
`inputAudioFormat`	`String`	Não	Formato de áudio. Suportado: `pcm`, `opus`. Padrão: `pcm`.
`corpusText`	`String`	Não	Contexto (texto de fundo, vocabulários de entidades, informações de referência) para personalizar o reconhecimento. Limite: 10.000 tokens. Consulte Viés de contexto.

Interfaces principais

OmniRealtimeConversation

Importar: com.alibaba.dashscope.audio.omni.OmniRealtimeConversation

Gerencia o ciclo de vida do WebSocket: conectar, enviar áudio e encerrar a sessão.

Crie uma conversa

OmniRealtimeConversation conversation =
  new OmniRealtimeConversation(param, callback);

Cria uma conversa com os parâmetros de conexão e o manipulador de retorno de chamada especificados.

Conecte-se ao servidor

conversation.connect();

Abre uma conexão WebSocket. O servidor envia session.created e session.atualizado eventos.

Lança: NoApiKeyException, InterruptedException.

Configurar a sessão

conversation.updateSession(config);

Atualiza a configuração da sessão após a conexão. O servidor envia um session.updated evento. Se não for chamado, o servidor usará os padrões.

Enviar dados de áudio

conversation.appendAudio(audioBase64);

Acrescenta áudio codificado em Base64 ao buffer de áudio do lado do servidor.

Modo VAD (enableTurnDetection=true): O servidor detecta limites de fala e decide quando processar o buffer.
Modo manual (enableTurnDetection=false): O áudio se acumula até você ligar commit(). Cada evento pode conter até 15 MiB de dados de áudio.

Confirme o buffer de áudio

conversation.commit();

Envia áudio em buffer para reconhecimento. O servidor envia um input_audio_buffer.committed evento.

Disponível apenas no modo manual (enableTurnDetection=false). Retorna um erro se o buffer de áudio estiver vazio.

Terminar a sessão

conversation.endSession();  // synchronous
// or
conversation.endSessionAsync();  // asynchronous

Informa ao servidor para terminar o processamento do áudio restante e encerrar a sessão. O servidor envia um session.finished evento.

Quando ligar:

Modo VAD: Depois de terminar de enviar o áudio.
Modo manual: depois de ligar commit().

Feche a conexão

conversation.close();

Interrompe a tarefa e fecha a conexão WebSocket imediatamente.

Obtenha IDs de sessão e resposta

String sessionId = conversation.getSessionId();
String responseId = conversation.getResponseId();

getSessionId() retorna o ID da sessão para a tarefa atual.
getResponseId() retorna o ID de resposta da resposta mais recente do servidor.

OmniRealtimeCallback

Importar: com.alibaba.dashscope.audio.omni.OmniRealtimeCallback

Implemente esta classe para lidar com eventos do servidor.

Método	Parâmetros	Acionado quando
`onOpen()`	Nenhum	Conexão WebSocket estabelecida.
`onEvent(JsonObject message)`	`message`: Um evento do servidor como JSON. Tipos comuns: `session.created`, `session.updated`, `input_audio_buffer.committed`, `conversation.item.input_audio_transcription.completed`, `session.finished`.	Um evento do servidor é recebido. Analise o `type` campo para determinar o tipo de evento.
`onClose(int code, String reason)`	`code`: Código de status. `reason`: Motivo próximo.	Conexão WebSocket fechada.