本文档介绍如何使用 DashScope Python SDK 调用实时语音识别(Qwen-ASR-Realtime)模型。
前提条件
- 安装SDK,确保DashScope SDK版本不低于2.0.1。
- 获取与配置 API Key。
- 了解WebSocket API。
快速开始
your_audio_file.pcm(PCM16、16 kHz、单声道)。如仅有 MP3/WAV 等格式,可使用 ffmpeg 转换:请求参数
-
以下参数通过
client.audio.realtime.connect方法设置。点击查看示例代码
参数
类型
是否必须
说明
modelstr是
指定要使用的模型名称。
ws_urlstr否
完整WebSocket端点,未指定时按
Client的workspace与region自动选择端点:华北2(北京)地域:
wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime。调用时请将{WorkspaceId}替换为真实的Workspace ID。新加坡地域:
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime。调用时请将{WorkspaceId}替换为真实的业务空间ID。
-
以下参数通过
RealtimeSession的update_session方法设置。点击查看示例代码
参数
类型
是否必须
说明
output_modalitiesList[str]是
模型输出模态,固定为
["text"]。enable_turn_detectionbool否
是否开启服务端语音活动检测(VAD)。关闭后,需手动调用
commit()方法触发识别。默认值:
True。取值范围:
True:开启False:关闭
turn_detection_typestr否
服务端VAD类型,固定为
server_vad。turn_detection_thresholdfloat否
VAD检测阈值。推荐将该值设为
0.0。默认值:
0.5。取值范围:
[-1, 1]。较低的阈值会提高 VAD 的灵敏度,可能将背景噪音误判为语音。较高的阈值则降低灵敏度,有助于在嘈杂环境中减少误触发。
turn_detection_silence_duration_msint否
VAD断句检测阈值(ms)。静音持续时长超过该阈值将被认为是语句结束。推荐将该值设为
400。默认值:
800。取值范围:
[200, 6000]。较低的值(如 300ms)可使模型更快响应,但可能导致在自然停顿处发生不合理的断句。较高的值(如 1200ms)可更好地处理长句内的停顿,但会增加整体响应延迟。
transcription_paramsdict否
语音识别相关配置。
-
以下参数通过
update_session的transcription_params字典设置。点击查看示例代码
参数
类型
是否必须
说明
languagestr否
音频源语言。
zh:中文(普通话、四川话、闽南语、吴语)
yue:粤语
en:英文
ja:日语
de:德语
ko:韩语
ru:俄语
fr:法语
pt:葡萄牙语
ar:阿拉伯语
it:意大利语
es:西班牙语
hi:印地语
id:印尼语
th:泰语
tr:土耳其语
uk:乌克兰语
vi:越南语
cs:捷克语
da:丹麦语
fil:菲律宾语
fi:芬兰语
is:冰岛语
ms:马来语
no:挪威语
pl:波兰语
sv:瑞典语
sample_rateint否
音频采样率(Hz)。支持
16000和8000。默认值:
16000。设置为
8000时,服务端会先升采样到16000Hz再进行识别,可能引入微小延迟。建议仅在源音频为8000Hz(如电话线路)时使用。input_audio_formatstr否
音频格式。支持
pcm和opus。默认值:
pcm。
接口参考
RealtimeSession(client.audio.realtime.connect)
实时识别会话通过client.audio.realtime.connect(model=...)创建:进入with上下文(或调用会话的connect()方法)后建立连接。
| 方法签名 | 服务端响应事件(通过events()下发) | 说明 |
|---|---|---|
session.created会话已创建session.updated 会话配置已更新 | 和服务端创建连接。进入with上下文时自动调用,勿先connect()再进入同一会话的with。 | |
session.updated会话配置已更新 | 用于更新会话配置,建议在连接建立后首先调用该方法进行设置。若未调用该方法,系统将使用默认配置。只需关注请求参数中的涉及到的参数。 | |
| 无 | 将音频数据片段追加到云端输入音频缓冲区。str视为已编码的Base64,bytes会自动Base64编码。 | |
input_audio_buffer.committed服务端收到提交的音频 | 提交之前通过append添加到云端缓冲区的音视频,如果输入的音频缓冲区为空将产生错误。禁用场景:请求参数enable_turn_detection设为True时。 | |
session.finished服务端完成语音识别,结束会话 | 通知服务端结束会话,服务端收到会话结束通知后将完成最后的语音识别。调用时机:
| |
| 无 | 终止任务,并关闭连接(幂等,不发送session.finish)。 | |
| 无 | 获取当前任务的session_id、最近一次response的response_id(属性)。 |
事件迭代(events())
服务端会通过事件的方式,将服务端响应事件和数据返回给客户端。您需要在接收线程中迭代会话的events(),按event["type"]分发处理(完整事件列表参见服务端事件)。
| 方法签名 | 参数 | 说明 |
|---|---|---|
| event:服务端事件 | 连续读取并逐个产出服务端事件(dict)。连接关闭或收到session.finished后迭代结束。 | |
| 无 | 阻塞读取单条服务端事件,不自动循环;无事件(连接关闭)时返回None。 |