本文档介绍如何使用 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 转换:Python
请求参数
- 以下参数通过
client.audio.realtime.connect方法设置。
点击查看示例代码
点击查看示例代码
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
model | str | 是 | 指定要使用的模型名称。 |
ws_url | str | 否 | 完整WebSocket端点,未指定时由 SDK 推导,服务端点为 wss://maas.qianwenaiapi.com/api-ws/v1/realtime。 |
- 以下参数通过
RealtimeSession的update_session方法设置。
点击查看示例代码
点击查看示例代码
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
output_modalities | List[str] | 是 | 模型输出模态,固定为["text"]。 |
enable_turn_detection | bool | 否 | 是否开启服务端语音活动检测(VAD)。关闭后,需手动调用commit()方法触发识别。默认值: True。取值范围:
|
turn_detection_type | str | 否 | 服务端VAD类型,固定为 server_vad。 |
turn_detection_threshold | float | 否 | VAD检测阈值。推荐将该值设为0.0。默认值: 0.5。取值范围: [-1, 1]。较低的阈值会提高 VAD 的灵敏度,可能将背景噪音误判为语音。较高的阈值则降低灵敏度,有助于在嘈杂环境中减少误触发。 |
turn_detection_silence_duration_ms | int | 否 | VAD断句检测阈值(ms)。静音持续时长超过该阈值将被认为是语句结束。推荐将该值设为400。默认值: 800。取值范围: [200, 6000]。较低的值(如 300ms)可使模型更快响应,但可能导致在自然停顿处发生不合理的断句。较高的值(如 1200ms)可更好地处理长句内的停顿,但会增加整体响应延迟。 |
transcription_params | dict | 否 | 语音识别相关配置。 |
- 以下参数通过
update_session的transcription_params字典设置。
点击查看示例代码
点击查看示例代码
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
language | str | 否 | 音频源语言。
|
sample_rate | int | 否 | 音频采样率(Hz)。支持16000和8000。默认值: 16000。设置为 8000 时,服务端会先升采样到16000Hz再进行识别,可能引入微小延迟。建议仅在源音频为8000Hz(如电话线路)时使用。 |
input_audio_format | str | 否 | 音频格式。支持pcm和opus。默认值: pcm。 |
关键接口
RealtimeSession(client.audio.realtime.connect)
实时识别会话通过client.audio.realtime.connect(model=...)创建:进入with上下文(或调用会话的connect()方法)后建立连接。
| 方法签名 | 服务端响应事件(通过events()下发) | 说明 |
|---|---|---|
| 示例 1 请参见表格下方 | session.created > 会话已创建 session.updated > 会话配置已更新 | 和服务端创建连接。进入with上下文时自动调用,勿先connect()再进入同一会话的with。 |
| 示例 2 请参见表格下方 | session.updated > 会话配置已更新 | 用于更新会话配置,建议在连接建立后首先调用该方法进行设置。若未调用该方法,系统将使用默认配置。只需关注请求参数中的涉及到的参数。 |
| 示例 3 请参见表格下方 | 无 | 将音频数据片段追加到云端输入音频缓冲区。str视为已编码的Base64,bytes会自动Base64编码。 |
| 示例 4 请参见表格下方 | input_audio_buffer.committed > 服务端收到提交的音频 | 提交之前通过append_audio添加到云端缓冲区的音视频,如果输入的音频缓冲区为空将产生错误。 禁用场景:请求参数enable_turn_detection设为True时。 |
| 示例 5 请参见表格下方 | session.finished > 服务端完成语音识别,结束会话 | 通知服务端结束会话,服务端收到会话结束通知后将完成最后的语音识别。 调用时机:
|
| 示例 6 请参见表格下方 | 无 | 终止任务,并关闭连接(幂等,不发送session.finish)。 |
| 示例 7 请参见表格下方 | 服务端事件 > 事件类型位于event["type"] | 连续读取服务端事件。收到session.finished后产出该事件并结束迭代;请由一个接收线程持续消费,不要并发创建多个读取者。 |
| 示例 8 请参见表格下方 | 无 | 获取当前任务的session_id、最近一次response的response_id(属性)。 |
事件迭代(events())
服务端会通过事件的方式,将服务端响应事件和数据返回给客户端。您需要在接收线程中迭代会话的events(),按event["type"]分发处理(完整事件列表参见服务端事件)。
| 方法签名 | 参数 | 说明 |
|---|---|---|
| 示例 1 请参见表格下方 | event:服务端事件 | 连续读取并逐个产出服务端事件(dict)。连接关闭或收到session.finished后迭代结束。 |
| 示例 2 请参见表格下方 | 无 | 阻塞读取单条服务端事件,不自动循环;无事件(连接关闭)时返回None。 |