Alibaba Cloud Model Studio:Qwen-ASR-Realtime Java SDK - API reference

Use o DashScope Java SDK para chamar o Qwen-ASR-Realtime.

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

Pré-requisitos

• DashScope SDK 2.22.5 ou posterior (Instalar o SDK)
• Obter uma chave de API
• Compreender o fluxo de interação entre cliente e servidor

Modos de interação

O Qwen-ASR-Realtime oferece dois modos para determinar quando processar o áudio:

Para obter detalhes sobre cada modo, consulte Modo VAD e Modo manual.

Parâmetros da solicitação

Parâmetros de conexão (OmniRealtimeParam)

Defina esses parâmetros com os métodos encadeados da classe OmniRealtimeParam.

OmniRealtimeParam param = OmniRealtimeParam.builder()
        .model("qwen3-asr-flash-realtime")
        // Endpoint for the Singapore region.
        // The following configuration is for the Singapore region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration varies by region.
        .url("wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime")
        // The API keys for the Singapore and Beijing regions are different.
        // To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
        // If you have not configured an environment variable, replace the following line with .apikey("sk-xxx").
        .apikey(System.getenv("DASHSCOPE_API_KEY"))
        .build();

Configuração da sessão (OmniRealtimeConfig)

Defina esses parâmetros com os métodos encadeados da classe OmniRealtimeConfig.

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âmetros de transcrição (OmniRealtimeTranscriptionParam)

Defina esses parâmetros com os métodos setter da classe OmniRealtimeTranscriptionParam.

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

Interfaces principais

OmniRealtimeConversation

Importação: com.alibaba.dashscope.audio.omni.OmniRealtimeConversation

Esta classe gerencia o ciclo de vida do WebSocket: conexão ao servidor, envio de áudio e encerramento da sessão.

Crie uma conversa

OmniRealtimeConversation conversation =
        new OmniRealtimeConversation(param, callback);

Cria uma nova instância de conversa com os parâmetros de conexão e o manipulador de callback especificados.

Conectar-se ao servidor

conversation.connect();

Abre uma conexão WebSocket. O servidor responde com os eventos session.created e session.updated.

Gera exceção: NoApiKeyException, InterruptedException.

Configure a sessão

conversation.updateSession(config);

Atualiza a configuração da sessão após estabelecer a conexão. O servidor responde com um evento session.updated. Se não for chamado, o servidor usa as configurações padrão.

Enviar dados de áudio

conversation.appendAudio(audioBase64);

Adiciona um segmento de áudio codificado em Base64 ao buffer de áudio no lado do servidor.

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

Confirmar o buffer de áudio

conversation.commit();

Envia o áudio armazenado em buffer para reconhecimento. O servidor responde com um evento input_audio_buffer.committed.

Este método está disponível apenas no modo manual ( enableTurnDetection=false ). Ocorre um erro se o buffer de áudio estiver vazio.

Encerrar a sessão

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

Notifica o servidor para concluir o processamento de qualquer áudio restante e encerrar a sessão. O servidor responde com um evento session.finished.

Quando chamar:

• Modo VAD: Após terminar de enviar áudio.
• Modo manual: Após chamar commit().

Cancele uma resposta

conversation.cancelResponse();

Cancela a resposta em andamento. Se não houver resposta para cancelar, o servidor retornará um erro.

Fechar a conexão

conversation.close();

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

Obter IDs de sessão e resposta

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

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

OmniRealtimeCallback

Importação: com.alibaba.dashscope.audio.omni.OmniRealtimeCallback

Herde esta classe e implemente os métodos de callback para lidar com eventos do servidor.