本文档介绍如何使用 DashScope Python SDK 调用实时音视频翻译(Qwen-LiveTranslate-Realtime)模型。
前提条件
- 安装SDK,确保DashScope SDK版本不低于2.0.1。
- 获取与配置 API Key。
请求参数
- 以下参数通过
client.audio.realtime的connect方法设置。服务端事件不再通过回调接收:在接收线程中迭代会话的events()处理(见事件迭代(events()))。
点击查看示例代码
点击查看示例代码
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
model | str | 是 | 指定要使用的模型名称,推荐使用qwen3.5-livetranslate-flash-realtime。 |
ws_url | str | 否 | 会话端点。不传时由 SDK 推导,服务端点为 wss://maas.qianwenaiapi.com/api-ws/v1/realtime。 |
- 以下参数通过会话的
update_session方法设置。
点击查看示例代码
点击查看示例代码
output_modalities | List[str] | 否 | 模型输出模态。默认值:
["text", "audio"]。取值范围:
["text"]:仅输出文本["text", "audio"]:输出文本和音频
voice | str | 是 | 生成音频的音色。默认值:
Tina。可选值:参见支持的音色。 |
| input_audio_transcription_model | str | 否 | 将input_audio_transcription_model设为qwen3-asr-flash-realtime,服务端将返回源语言语音识别结果。 |
| translation_params | Dict | 否 | 翻译相关配置。 |
| enable_turn_detection | bool | 否 | 是否启用 VAD(语音活动检测)。默认值:
True,即启用 VAD 模式,服务端自动检测语音起止并自动触发翻译。设为
False可切换为 Manual 模式,由客户端通过commit方法手动提交音频。详细参数说明参见turn_detection object (可选) 语音活动检测(VAD,Voice Activity Detection)配置,用于控制语音起止的检测方式: 设为配置对象(默认值):启用 VAD 模式。服务端自动检测语音起止,自动提交音频缓冲区并触发翻译响应,客户端无需发送input_audio_buffer.commit事件。 设为null:启用 Manual 模式。由客户端通过input_audio_buffer.commit事件手动提交音频缓冲区,服务端收到后自动开始生成翻译响应。 属性 type string (可选) VAD 类型,固定为server_vad。 threshold float (可选) VAD 检测灵敏度。值越低,越容易将微弱声音(包括背景噪音)识别为语音;值越高,需要更清晰、音量更大的语音才能触发。 取值范围:[-1.0, 1.0],默认值为 0.2。 silence_duration_ms integer (可选) 语音结束后需保持静音的最短时长(毫秒)。超过该时长后判定语音结束,服务端自动提交音频缓冲区并触发翻译响应。 取值范围:[200, 6000],默认值为 1000。。 |
- 以下参数通过
update_session方法的translation_params字典设置。
点击查看示例代码
点击查看示例代码
language | str | 否 | 翻译目标语言代码。默认值:
en。可选值:参见支持的语种。 | |
corpus | dict | 否 | 热词配置,用于提升特定词汇的翻译准确性。 |
| corpus.phrases | dict | 否 | 热词映射表。key 为源语言词汇,value 为目标语言对应翻译。示例:
{'人工智能': 'Artificial Intelligence'} |
关键接口
会话(RealtimeSession)
实时翻译会话通过client.audio.realtime.connect(model=...)创建,进入with上下文时自动建立连接(也可调用会话的connect()方法手动建立)。
| 方法签名 | 服务端响应事件(通过events()迭代下发) | 说明 |
|---|---|---|
| 示例 1 请参见表格下方 | 服务端事件 > 会话已创建 服务端事件 > 会话配置已更新 | 和服务端创建连接。进入with上下文时自动调用。 |
| 示例 2 请参见表格下方 | 服务端事件 > 会话已更新 | 用于更新会话配置,建议在连接建立后首先调用该方法进行设置。若未调用该方法,系统将使用默认配置。只需关注会话update_session方法涉及的参数。 |
| 示例 3 请参见表格下方 | session.finished > 服务端完成语音翻译,结束会话 | 通知服务端结束会话,服务端收到会话结束通知后将完成最后的语音翻译。 |
| 示例 4 请参见表格下方 | 无 | 将音频数据片段追加到云端输入音频缓冲区,支持Base64字符串或原始bytes(自动编码)。服务端会自动检测语音起止并触发翻译。 |
| 示例 5 请参见表格下方 | input_audio_buffer.committed > 输入音频缓冲区已提交 | Manual 模式下,提交之前通过append_audio方法追加到云端缓冲区的音频,服务端收到后自动开始生成翻译响应。VAD 模式下无需调用此方法,服务端会自动提交。 |
| 示例 6 请参见表格下方 | input_audio_buffer.cleared > 输入音频缓冲区已清空 | 清空当前云端缓冲区中尚未提交的音频数据。 |
| 示例 7 请参见表格下方 | 无 | 终止任务,并关闭连接。退出with上下文时自动调用。 |
| 示例 8 请参见表格下方 | 无 | 获取当前任务的session_id(从session.created事件读取)。 |
| 示例 9 请参见表格下方 | 无 | 获取最近一次response的response_id(从response.created事件读取)。 |
事件迭代(events())
服务端会通过事件的方式,将服务端响应事件和数据返回给客户端。在接收线程中迭代会话的events()处理服务端事件,session.finished事件后迭代结束。
error事件会以DashScopeError异常抛出,可在接收线程中使用try/except捕获。
捕获异常后如何继续接收事件
捕获 DashScopeError 后,原来的 events() 迭代已经结束。仅在外层使用 try/except 捕获异常,不会让它自动继续接收事件。
如果 WebSocket 连接仍可用,修正请求后重新调用 events(),或用 recv_event() 逐条接收。连接已关闭时,先重新建连并配置会话,再开始接收。
排查错误原因时,可从异常的 body 读取服务端返回的原始错误事件。
示例 1(方法签名):
完整示例
以下示例展示如何从麦克风实时录音并进行翻译。
麦克风实时翻译示例代码
麦克风实时翻译示例代码