通过 WebSocket 使用 DashScope Python SDK 调用 Qwen-LiveTranslate-Realtime。
前提条件
- 安装SDK,确保DashScope SDK版本不低于2.0.1。
- 获取与配置 API Key。
快速开始
以下示例展示如何从麦克风实时录音并进行翻译。
麦克风实时翻译示例代码
麦克风实时翻译示例代码
请求参数
-
以下参数通过
client.audio.realtime的connect方法设置。服务端事件不再通过回调接收:在接收线程中迭代会话的events()处理(见事件迭代(events()))。点击查看示例代码
参数 类型 是否必须 说明 modelstr是 指定要使用的模型名称,推荐使用 qwen3.5-livetranslate-flash-realtime。ws_urlstr否 会话端点。缺省时由Client构造参数 workspace/region自动推导实时翻译服务地址(华北2(北京):wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime;新加坡:wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime)。指定ws_url时,将域名替换为业务空间对应的 API Host,保留协议和路径。 -
以下参数通过会话的
update_session方法设置。点击查看示例代码
参数
类型
是否必须
说明
output_modalitiesList[str]否
模型输出模态。
默认值:
["text", "audio"]。取值范围:
["text"]:仅输出文本["text", "audio"]:输出文本和音频
voicestr是
生成音频的音色。
默认值:
Qwen3.5-LiveTranslate-Flash-Realtime默认音色为:
Tina
可选值:参见支持的音色。
input_audio_transcription_modelstr否
将
input_audio_transcription_model设为qwen3-asr-flash-realtime,服务端将返回源语言语音识别结果。translation_paramsDict否
翻译相关配置。
enable_turn_detectionbool否
是否启用 VAD(语音活动检测)。
默认值:
True,即启用 VAD 模式,服务端自动检测语音起止并自动触发翻译。 -
以下参数通过
update_session方法的translation_params字典设置。点击查看示例代码
参数
类型
是否必须
说明
languagestr否
翻译目标语言代码。
默认值:
en。可选值:参见支持的语种。
corpusdict否
热词配置,用于提升特定词汇的翻译准确性。
corpus.phrasesdict否
热词映射表。key 为源语言词汇,value 为目标语言对应翻译。
示例:
{'人工智能': 'Artificial Intelligence'}
接口参考
会话(RealtimeSession)
实时翻译会话通过client.audio.realtime.connect(model=...)创建,进入with上下文时自动建立连接(也可调用会话的connect()方法手动建立)。
| 方法签名 | 服务端响应事件(通过events()迭代下发) | 说明 |
|---|---|---|
服务端事件会话已创建服务端事件 会话配置已更新 | 和服务端创建连接。进入with上下文时自动调用。 | |
服务端事件会话已更新 | 用于更新会话配置,建议在连接建立后首先调用该方法进行设置。若未调用该方法,系统将使用默认配置。只需关注会话update_session方法涉及的参数。 | |
session.finished服务端完成语音翻译,结束会话 | 通知服务端结束会话,服务端收到会话结束通知后将完成最后的语音翻译。 | |
| 无 | 将音频数据片段追加到云端输入音频缓冲区,支持Base64字符串或原始bytes(自动编码)。服务端会自动检测语音起止并触发翻译。 | |
input_audio_buffer.committed输入音频缓冲区已提交 | Manual 模式下,提交之前通过append_audio方法追加到云端缓冲区的音频,服务端收到后自动开始生成翻译响应。VAD 模式下无需调用此方法,服务端会自动提交。 | |
input_audio_buffer.cleared输入音频缓冲区已清空 | 清空当前云端缓冲区中尚未提交的音频数据。 | |
| 无 | 终止任务,并关闭连接。退出with上下文时自动调用。 | |
| 无 | 获取当前任务的session_id(从session.created事件读取)。 | |
| 无 | 获取最近一次response的response_id(从response.created事件读取)。 |
事件迭代(events())
服务端会通过事件的方式,将服务端响应事件和数据返回给客户端。在接收线程中迭代会话的events()处理服务端事件,session.finished事件后迭代结束。
error事件会以DashScopeError异常抛出,可在接收线程中使用try/except捕获。
捕获异常后如何继续接收事件
捕获 DashScopeError 后,原来的 events() 迭代已经结束。仅在外层使用 try/except 捕获异常,不会让它自动继续接收事件。
如果 WebSocket 连接仍可用,修正请求后重新调用 events(),或用 recv_event() 逐条接收。连接已关闭时,先重新建连并配置会话,再开始接收。
排查错误原因时,可从异常的 body 读取服务端返回的原始错误事件。
| 方法签名 | 参数 | 说明 |
|---|---|---|
| event:服务端事件 | 迭代接收服务端事件(dict),session.finished事件后迭代结束。请由一个接收线程持续消费,不要并发创建多个读取者。 | |
| event:服务端事件 | 读取一条服务端事件,正常关闭后返回None。 |