Este documento descreve como usar o SDK Java do DashScope para chamar o modelo de tradução de áudio e vídeo em tempo real (Qwen-LiveTranslate-Realtime).
Para a conexão e a autenticação, consulte Acesso por WebSocket; para os campos de eventos e exemplos JSON, consulte eventos do cliente e eventos do servidor.
Pré-requisitos
- Instale o SDK e verifique se a versão do DashScope SDK é 2.22.5 ou posterior.
- Obtenha e configure uma chave de API.
- Conheça a tradução de fala/áudio e vídeo em tempo real - Qwen.
ImportanteO Alibaba Cloud Model Studio lançou domínios dedicados por workspace para as regiões China (Pequim) e Singapura, que oferecem desempenho superior e maior estabilidade para solicitações de inferência. Recomendamos migrar para os novos domínios:
- China (Pequim): migre de
wss://dashscope.aliyuncs.comparawss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com - Singapura: migre de
wss://dashscope-intl.aliyuncs.comparawss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
Entre eles, {WorkspaceId} é o ID do seu workspace, que você pode visualizar na página Detalhes do workspace no console do Alibaba Cloud Model Studio. Os domínios existentes permanecem disponíveis.
Início rápido
O exemplo a seguir mostra como gravar áudio de um microfone em tempo real e realizar a tradução.
Código de exemplo de tradução em tempo real por microfone
wss://WorkspaceId.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtimewss://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtimeimport com.alibaba.dashscope.audio.omni.*;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.google.gson.JsonObject;
import javax.sound.sampled.*;
import java.util.*;
import java.util.concurrent.atomic.AtomicBoolean;
/**
* 实时音视频翻译模型麦克风示例
*/
public class Main {
private static final int INPUT_CHUNK_SIZE = 3200; // 100ms 的 16kHz 16bit 单声道音频
private static final int OUTPUT_CHUNK_SIZE = 4800; // 100ms 的 24kHz 16bit 单声道音频
private static final AtomicBoolean running = new AtomicBoolean(true);
private static SourceDataLine speaker; // 扬声器
public static void main(String[] args) throws InterruptedException {
String apiKey = System.getenv("DASHSCOPE_API_KEY");
if (apiKey == null || apiKey.isEmpty()) {
System.err.println("请设置环境变量 DASHSCOPE_API_KEY");
System.exit(1);
}
// 创建连接参数
OmniRealtimeParam param = OmniRealtimeParam.builder()
.model("qwen3.5-livetranslate-flash-realtime")
.url("wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime")
.apikey(apiKey)
.build();
// 创建回调处理
OmniRealtimeCallback callback = new OmniRealtimeCallback() {
@Override
public void onOpen() {
System.out.println("[连接已建立]");
}
@Override
public void onEvent(JsonObject message) {
String type = message.get("type").getAsString();
switch (type) {
case "input_audio_buffer.speech_started":
System.out.println("====== 检测到语音输入 ======");
break;
case "input_audio_buffer.speech_stopped":
System.out.println("====== 语音输入结束 ======");
break;
case "conversation.item.input_audio_transcription.completed":
String originalText = message.get("transcript").getAsString();
System.out.println("[原文] " + originalText);
break;
case "response.audio_transcript.done":
String translatedText = message.get("transcript").getAsString();
System.out.println("[翻译结果] " + translatedText);
break;
case "response.audio.delta":
// 解码并播放翻译后的音频
String audioB64 = message.get("delta").getAsString();
byte[] audioBytes = Base64.getDecoder().decode(audioB64);
if (speaker != null) {
speaker.write(audioBytes, 0, audioBytes.length);
}
break;
case "error":
JsonObject error = message.get("error").getAsJsonObject();
System.err.println("[错误] " + error.get("message").getAsString());
break;
}
}
@Override
public void onClose(int code, String reason) {
System.out.println("[连接已关闭] code: " + code + ", reason: " + reason);
}
};
// 创建会话
OmniRealtimeConversation conversation = new OmniRealtimeConversation(param, callback);
try {
// 初始化扬声器(用于播放翻译后的语音)
AudioFormat speakerFormat = new AudioFormat(24000, 16, 1, true, false);
DataLine.Info speakerInfo = new DataLine.Info(SourceDataLine.class, speakerFormat);
speaker = (SourceDataLine) AudioSystem.getLine(speakerInfo);
speaker.open(speakerFormat, OUTPUT_CHUNK_SIZE * 4);
speaker.start();
// 初始化麦克风(用于采集语音输入)
AudioFormat micFormat = new AudioFormat(16000, 16, 1, true, false);
DataLine.Info micInfo = new DataLine.Info(TargetDataLine.class, micFormat);
if (!AudioSystem.isLineSupported(micInfo)) {
System.err.println("麦克风不可用");
System.exit(1);
}
TargetDataLine microphone = (TargetDataLine) AudioSystem.getLine(micInfo);
microphone.open(micFormat);
microphone.start();
// 连接服务端
conversation.connect();
// 配置翻译参数
Map<String, Object> phrases = new HashMap<>();
phrases.put("人工智能", "Artificial Intelligence");
phrases.put("机器学习", "Machine Learning");
OmniRealtimeConfig config = OmniRealtimeConfig.builder()
.modalities(Arrays.asList(OmniRealtimeModality.AUDIO, OmniRealtimeModality.TEXT))
.voice("Tina")
.inputAudioFormat(OmniRealtimeAudioFormat.PCM_16000HZ_MONO_16BIT)
.outputAudioFormat(OmniRealtimeAudioFormat.PCM_24000HZ_MONO_16BIT)
.InputAudioTranscription("qwen3-asr-flash-realtime")
.translationConfig(OmniRealtimeTranslationParam.builder()
.language("en")
.corpus(OmniRealtimeTranslationParam.Corpus.builder()
.phrases(phrases)
.build())
.build())
.build();
conversation.updateSession(config);
// 注册退出信号处理
Runtime.getRuntime().addShutdownHook(new Thread(() -> {
System.out.println("\n[正在退出...]");
running.set(false);
microphone.stop();
microphone.close();
speaker.stop();
speaker.close();
try {
conversation.endSession();
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
}
conversation.close(1000, "用户停止");
}));
System.out.println("[开始实时翻译] 请对着麦克风说话,按 Ctrl+C 退出");
// 持续采集麦克风音频并发送
byte[] buffer = new byte[INPUT_CHUNK_SIZE];
while (running.get()) {
int bytesRead = microphone.read(buffer, 0, buffer.length);
if (bytesRead > 0) {
conversation.appendAudio(Base64.getEncoder().encodeToString(buffer));
}
}
} catch (NoApiKeyException e) {
System.err.println("API Key 错误: " + e.getMessage());
} catch (Exception e) {
System.err.println("发生异常: " + e.getMessage());
e.printStackTrace();
}
}
}
Parâmetros da solicitação
-
Os parâmetros a seguir são definidos por meio dos métodos encadeados de
OmniRealtimeParam.Clique para visualizar o código de exemplo
OmniRealtimeParam param = OmniRealtimeParam.builder() .model("qwen3.5-livetranslate-flash-realtime") // 以下为新加坡地域URL,调用时请将{WorkspaceId}替换为真实的业务空间ID,各地域的URL不同。 .url("wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime") // 各地域的API Key不同。获取API Key:https://www.alibabacloud.com/help/model-studio/get-api-key // 若没有配置环境变量,请用百炼API Key将下行替换为:.apikey("sk-xxx") .apikey(System.getenv("DASHSCOPE_API_KEY")) .build();Parâmetro Tipo Obrigatório Descrição modelStringSim
O nome do modelo a ser usado. Recomendamos
qwen3.5-livetranslate-flash-realtime.urlStringSim
URL do serviço de tradução em tempo real:
- China (Pequim):
wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime - Singapura:
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime
Ao chamar, substitua
{WorkspaceId}pelo seu ID do workspace real.apikeyStringNão
Define a chave de API.
- China (Pequim):
-
Os parâmetros a seguir são definidos por meio dos métodos encadeados de
OmniRealtimeConfig.Clique para visualizar o código de exemplo
// 设置翻译热词 Map<String, Object> phrases = new HashMap<>(); phrases.put("人工智能", "Artificial Intelligence"); phrases.put("机器学习", "Machine Learning"); OmniRealtimeConfig config = OmniRealtimeConfig.builder() .modalities(Arrays.asList(OmniRealtimeModality.AUDIO, OmniRealtimeModality.TEXT)) .voice("Tina") .inputAudioFormat(OmniRealtimeAudioFormat.PCM_16000HZ_MONO_16BIT) .outputAudioFormat(OmniRealtimeAudioFormat.PCM_24000HZ_MONO_16BIT) .InputAudioTranscription("qwen3-asr-flash-realtime") .translationConfig(OmniRealtimeTranslationParam.builder() .language("en") .corpus(OmniRealtimeTranslationParam.Corpus.builder() .phrases(phrases) .build()) .build()) .build(); conversation.updateSession(config);Parâmetro
Tipo
Obrigatório
Descrição
modalitiesList<OmniRealtimeModality>Não
As modalidades de saída do modelo.
Valor padrão:
[OmniRealtimeModality.AUDIO, OmniRealtimeModality.TEXT].Faixa de valores:
[OmniRealtimeModality.TEXT]: saída apenas em texto[OmniRealtimeModality.AUDIO, OmniRealtimeModality.TEXT]: saída em texto e áudio
voiceStringSim
A voz do áudio gerado.
Valor padrão:
A voz padrão do Qwen3.5-LiveTranslate-Flash-Realtime é:
Tina
Valores opcionais: consulte Vozes compatíveis.
inputAudioFormatOmniRealtimeAudioFormatNão
Formato do áudio de entrada.
Valor padrão:
OmniRealtimeAudioFormat.PCM_16000HZ_MONO_16BIT.outputAudioFormatOmniRealtimeAudioFormatNão
Formato do áudio de saída.
Valor padrão:
OmniRealtimeAudioFormat.PCM_24000HZ_MONO_16BIT.InputAudioTranscriptionStringNão
O modelo de transcrição do áudio de entrada. Você deve definir este parâmetro se precisar exibir a transcrição da fala original.
Valor opcional:
qwen3-asr-flash-realtime.translationConfigOmniRealtimeTranslationParamNão
Configuração relacionada à tradução.
enableTurnDetectionbooleanNão
Se deve ativar o VAD (Detecção de Atividade de Voz).
Valor padrão:
true, ou seja, o modo VAD está ativado. O servidor detecta automaticamente o início e o fim da fala e aciona a tradução automaticamente.Defina como
falsepara alternar para o modo Manual, no qual o cliente envia o áudio manualmente por meio do métodocommit(). Para descrições detalhadas dos parâmetros, consulte objeto turn_detection (Opcional) A configuração de VAD (Detecção de Atividade de Voz), usada para controlar como o início e o fim da fala são detectados: definido como um objeto de configuração (padrão): o modo VAD é ativado. O servidor detecta automaticamente o início e o fim da fala, confirma automaticamente o buffer de áudio e aciona respostas de tradução. O cliente não precisa enviar o evento input_audio_buffer.commit. Definido como null: o modo Manual é ativado. O cliente confirma manualmente o buffer de áudio por meio do evento input_audio_buffer.commit, e o servidor começa automaticamente a gerar respostas de tradução ao recebê-lo. Propriedades type string (Opcional) O tipo de VAD, fixado como server_vad. threshold float (Opcional) A sensibilidade de detecção do VAD. Um valor menor facilita o reconhecimento de sons fracos (incluindo ruído de fundo) como fala; um valor maior exige uma fala mais clara e mais alta para acionar a detecção. Faixa de valores: [-1.0, 1.0], valor padrão 0.2. silence_duration_ms integer (Opcional) A duração mínima de silêncio (em milissegundos) que deve ser mantida após o fim da fala. Após essa duração, a fala é considerada encerrada, e o servidor confirma automaticamente o buffer de áudio e aciona uma resposta de tradução. Faixa de valores: [200, 6000], valor padrão 1000..Parâmetros estendidos da sessão
Alguns parâmetros da sessão não têm métodos de configuração correspondentes no SDK. Você pode passá-los por meio de
OmniRealtimeConfig.builder().parameters(Map). As chaves do Map são gravadas diretamente emsession. Por exemplo, para ativar a clonagem de voz em tempo real, primeiro construa os seguintes parâmetros:Map<String, Object> options = new HashMap<>(); options.put("frequency", "once"); Map<String, Object> parameters = new HashMap<>(); parameters.put("enable_voice_clone", true); parameters.put("voice_clone_options", options);Na cadeia do construtor da configuração existente, defina a voz como
.voice("default")e adicione.parameters(parameters). Mantenha as configurações originais de idioma e áudio e chameconversation.updateSession(config)após a construção. Para o pareamento entre frequência de clonagem e voz, consulte Clonagem de voz. -
Os parâmetros a seguir são definidos por meio dos métodos encadeados de OmniRealtimeTranslationParam.
Clique para visualizar o código de exemplo
// 设置翻译热词 Map<String, Object> phrases = new HashMap<>(); phrases.put("人工智能", "Artificial Intelligence"); // 源语言词: 目标语言翻译 phrases.put("机器学习", "Machine Learning"); OmniRealtimeTranslationParam translationParam = OmniRealtimeTranslationParam.builder() .language("en") // 翻译目标语言代码 .corpus(OmniRealtimeTranslationParam.Corpus.builder() .phrases(phrases) .build()) .build();Parâmetro
Tipo
Obrigatório
Descrição
languageStringNão
O código do idioma de destino da tradução.
Valor padrão:
en.Valores opcionais: consulte Idiomas compatíveis.
corpusOmniRealtimeTranslationParam.CorpusNão
A configuração de hotwords, usada para melhorar a precisão da tradução de termos específicos.
corpus.phrasesMap<String, Object>Não
A tabela de mapeamento de hotwords. A chave é um termo no idioma de origem, e o valor é a tradução correspondente no idioma de destino.
Exemplo:
{"artificial intelligence": "Artificial Intelligence"}
Referência da API
Classe OmniRealtimeConversation
OmniRealtimeConversation é importado por meio de import com.alibaba.dashscope.audio.omni.OmniRealtimeConversation;.
| Assinatura do método | Eventos de resposta do servidor (entregues por callbacks) | Descrição |
|---|---|---|
| Nenhum | Construtor. |
|
| Estabelece a conexão com o servidor. |
|
| Usado para atualizar a configuração da sessão. Recomenda-se chamar este método primeiro para aplicar as configurações após o estabelecimento da conexão. Se este método não for chamado, o sistema usará a configuração padrão. Apenas os parâmetros envolvidos em |
| Nenhum | Anexa blocos de dados de áudio codificados em Base64 ao buffer de áudio de entrada na nuvem. O servidor detecta automaticamente o início e o fim da fala e aciona a tradução. |
|
| No modo Manual, confirma o áudio anexado anteriormente ao buffer na nuvem por meio do método |
|
| Limpa os dados de áudio no buffer na nuvem atual que ainda não foram confirmados. |
|
| Notifica o servidor para encerrar a sessão. Após receber a notificação de encerramento da sessão, o servidor concluirá a tradução final da fala. |
| Nenhum | Interrompe a tarefa e fecha a conexão. |
| Nenhum | Obtém o session_id da tarefa atual. |
| Nenhum | Obtém o response_id da resposta mais recente. |
| Nenhum | Obtém a latência do primeiro texto da resposta mais recente (em milissegundos). |
| Nenhum | Obtém a latência do primeiro áudio da resposta mais recente (em milissegundos). |
Interface de callback (OmniRealtimeCallback)
O servidor retorna os eventos de resposta e os dados ao cliente por meio de callbacks.
Estenda esta classe e implemente os métodos correspondentes para tratar os eventos do servidor.
Importe-a por meio de import com.alibaba.dashscope.audio.omni.OmniRealtimeCallback;.
| Assinatura do método | Parâmetro | Descrição |
|---|---|---|
| Nenhum | Acionado quando a conexão WebSocket é estabelecida com sucesso. |
| message: Eventos do servidor | Acionado quando um evento do servidor é recebido. |
| code: Código de status reason: Informações de log registradas quando a conexão WebSocket é encerrada | Acionado quando a conexão WebSocket é encerrada. |