本文介绍Qwen-Audio-3.1-ASR-Flash-Message实时语音识别Python SDK的参数和接口细节。
前提条件
- 已开通服务并获取与配置 API Key。请配置API Key到环境变量,而非硬编码在代码中,防范因代码泄露导致的安全风险。
- 安装最新版DashScope SDK。
快速开始
核心资源(client.audio.asr)提供了非流式调用和双向流式调用等接口。请根据实际需求选择合适的调用方式:
- 非流式调用(
recognize_file):针对本地文件进行识别,SDK自动分块发送音频并驱动到任务结束。适合处理录制好的音频。 - 双向流式调用(
recognize会话):可直接对音频流进行识别,并实时输出结果。音频流可以来自外部设备(如麦克风)或从本地文件读取。适合需要即时反馈的场景。
- 非流式调用
- 双向流式调用
提交单个语音实时转写任务,通过传入本地文件的方式同步阻塞地拿到转写结果。调用核心资源(
client.audio.asr)的recognize_file方法绑定请求参数并传入本地文件路径,迭代服务端事件获取识别结果。接口地址
SDK 的接口地址通过调用时的 ws_url 参数指定为下方地址(未指定时由 SDK 推导默认端点)。
wss://maas.qianwenaiapi.com/api-ws/v1/inference
请求参数
请求参数通过核心资源(client.audio.asr)的recognize/recognize_file方法进行设置:model、format、sample_rate、vocabulary_id、disfluency_removal_enabled为具名参数,其余参数(如language_hints、keep_dialect)通过parameters字典传入。
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
model | str | 是 | 模型名,设置为 qwen-audio-3.1-asr-flash-message。 |
sample_rate | int | 是 | 采样率(Hz)。 仅支持 16000 Hz。 |
format | str | 是 | 音频格式。 取值范围:
|
disfluency_removal_enabled | bool | 否 | 是否过滤语气词并对输出结果进行润色,默认值为 false。设置为 true 时启用。作为同名关键字参数传入。 |
intermediate_result_enabled | bool | 否 | 是否返回流式中间结果,默认值为 false。设置为 true 时返回流式中间结果。通过parameters字典传入。 |
keep_dialect | bool | 否 | 默认 false,将方言转写为普通话;设为 true 时保留方言表达。通过parameters字典传入。完整参数说明请参见客户端事件。仅在最终结果(sentence_end=true)生效,中间结果(sentence_end=false)不支持。 |
vad_model | str | 否 | 可选 near_meeting_16k(近场)或 far_field_meeting_16k(远场,默认值)。通过parameters字典传入。完整参数说明请参见客户端事件。 |
vocabulary_id | str | 否 | 预编译热词列表 ID。 需预先调用创建热词列表接口生成,识别时传入该 ID 即可使用列表中的热词。 适用于词汇已知且相对稳定、需要跨请求复用同一词表的场景。 使用方法请参见预编译热词。 |
vocabulary | dict | 否 | 即时热词。 以键值对形式传入,键为热词文本( string),值为热词权重(integer),无需预先创建热词列表。权重取值范围为 [1, 5] 或 50:取 [1, 5] 时值越大模型越倾向输出该词;取 50 时为超级热词,召回率大幅提升,但超级热词数量最多不超过 50 个。 适用于临时性、会话级别的热词优化。 与预编译热词同时配置时,系统会合并两类热词;合并后超过 2000 个时,随机选择 2000 个使用。通过parameters字典传入。使用方法请参见即时热词。 示例: 示例 1 请参见表格下方 |
language_hints | list[str] | 否 | 待识别音频语种。无默认值,不设置时模型自动识别。最多支持设置 4 个值,超出时仅前 4 个生效。通过parameters字典传入。仅在最终结果(sentence_end=true)生效,中间结果(sentence_end=false)不支持。
|
max_sentence_silence | int | 否 | VAD 断句静音阈值(ms)。当一段语音后的静音时长超过该阈值时,系统会判定该句子已结束。 默认值:800。 取值范围:[200, 6000]。 |
heartbeat | bool | 否 | 是否启用心跳包。 默认值:False。
|
speech_noise_threshold | float | 否 | 语音与噪音的判定阈值,用于调整语音活动检测(VAD)的灵敏度。 取值范围:[-1.0, 1.0]。 取值说明:
|
recognize方法的input关键字参数传入。
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
input | dict | 否 | 输入对象,用于传入对话上下文(context)。上下文用于辅助识别、提升专有词汇的识别准确率。使用方法详见提升识别准确率。 dict 中需包含 context 键,值为消息列表(list[dict]),每条消息包含以下字段:
input_text 和 text 类型)各最多 5 条,超出时保留最近的 5 条。每轮上下文文本总长度不超过 400 个字符,超出部分从末尾截断。 提示: 携带上下文时,context 中的消息顺序有要求:上下文消息必须按对话轮次排列,每轮中 user(input_text 类型)必须在对应的 assistant(text 类型)之前。 说明: 该字段自 SDK 1.25.23 引入,2.0.1 及以上版本已包含。 示例 1 请参见表格下方 |
关键接口
核心资源(client.audio.asr)
实时语音识别能力挂载在client.audio.asr资源上:recognize创建双向流式识别会话(Recognition),recognize_file对本地文件一次性识别。
| 成员方法 | 方法签名 | 说明 |
|---|---|---|
recognize | 示例 1 请参见表格下方 | 创建双向流式识别会话,进入with上下文时自动调用start建立连接并发送任务。发送音频与消费事件需并发进行(配合 send_audio_frame、events()/results()和stop使用)。 |
recognize_file | 示例 2 请参见表格下方 | 基于本地文件的非流式调用:自动分块发送音频并驱动到任务结束,逐个产出服务端事件。该方法要求所识别文件具有可读权限。 |
start | 示例 3 请参见表格下方 | 开始语音识别:建立连接、发送任务并等待task-started。进入with上下文时自动调用,启动成功后才能发送音频。 |
send_audio_frame | 示例 4 请参见表格下方 | 推送音频。每次推送的音频流不宜过大或过小,建议每包音频时长为100ms左右,大小在1KB~16KB之间。 识别结果通过事件迭代( events()/results())获取。 |
stop | 示例 5 请参见表格下方 | 停止语音识别:只通知服务端输入结束,接收线程需继续消费events()直到task-finished事件。 |
events / results | 示例 6 请参见表格下方 | 迭代服务端事件:events()产出原始事件dict(识别文本位于payload.output.sentence);results()只产出识别结果帧,返回识别结果(RecognitionResult)类型化对象(心跳帧已过滤)。 |
close | 示例 7 请参见表格下方 | 关闭识别会话。退出with上下文时自动调用。 |
request_id / first_package_delay / last_package_delay / last_response | 示例 8 请参见表格下方 | 获取request_id、首包延迟(从发送第一包音频到收到首包识别结果延迟)和尾包延迟(发送stop指令到最后一包识别结果下发耗时),在任务完成后使用;last_response为最近一次成功读取的原始报文,可用于获取task-failed报错。会话关闭后仍可读取。 |
更新对话上下文
调用 update_context 在识别任务运行过程中更新对话上下文,用于辅助后续音频的识别。该方法要求 DashScope Python SDK 2.0.1 及以上版本。
- **调用时机:**进入
with上下文(自动调用start)启动流式识别后、调用stop前。 - 参数:
context为字典,传入continue-task事件的payload.input对象,包含context字段,不要额外包装payload或input层级。 - **支持范围与参数约束:**请参见 continue-task。
recognition 实例。
事件迭代(events()/results())
双向流式调用时,服务端会通过事件的方式,将关键流程信息和数据返回给客户端。您需要在接收线程中迭代会话的events()(原始事件dict)或results()(类型化识别结果帧),处理服务端返回的信息或者数据。
| 事件/迭代方法 | 产出内容 | 描述 |
|---|---|---|
| 示例 1 请参见表格下方 | task-started事件 | 由start()内部读取,启动返回时保存在last_response中,不会由events()再次产出。 |
| 示例 2 请参见表格下方 | event:服务端事件dict | 当服务有回复时产出事件。识别结果位于payload.output.sentence,可能为心跳或空文本事件,应用可按需忽略。请由一个接收线程持续消费,不要并发创建多个读取者。 |
| 示例 3 请参见表格下方 | result:识别结果(RecognitionResult) | 只产出识别结果帧(心跳帧已过滤),全部识别结果返回后迭代结束。 |
| 示例 4 请参见表格下方 | DashScopeError异常 | 发生异常时在发送/接收线程中抛出,可使用try/except捕获。 |
| 示例 5 请参见表格下方 | task-finished事件 | 当服务已经完成全部识别后由events()产出,随后迭代结束;发送stop()后仍须读取此事件。 |
响应结果
识别结果(RecognitionResult)
RecognitionResult代表会话results()迭代产出的一次识别结果帧(双向流式调用与非流式调用均可使用;events()产出的是原始事件dict,如需该类型化视图请改用results())。
| 成员方法 | 方法签名 | 说明 |
|---|---|---|
get_sentence | 示例 1 请参见表格下方 | 获取当前识别的句子及时间戳信息,此方法返回类型为Dict[str, Any](单句信息)。 详情请参见单句信息(Sentence)。 |
request_id | 示例 2 请参见表格下方 | 当前事件对应的请求request_id。 |
is_sentence_end | 示例 3 请参见表格下方 | 判断当前句子是否已经结束。该方法通过检查 get_sentence() 返回的单句信息中 end_time 字段是否为 None 来判定——end_time 不为 None 时表示句子已结束。 |
单句信息(Sentence)
Sentence类成员如下:
| 参数 | 类型 | 说明 |
|---|---|---|
begin_time | int | 句子开始时间,单位为ms。 |
end_time | int | 句子结束时间,单位为ms。 |
text | str | 识别文本。 |
words | 字时间戳信息(Word)的list集合 | 字时间戳信息。 |
字时间戳信息(Word)
Word类成员如下:
| 参数 | 类型 | 说明 |
|---|---|---|
begin_time | int | 字开始时间,单位为ms。 |
end_time | int | 字结束时间,单位为ms。 |
text | str | 字。 |
punctuation | str | 标点。 |
错误码
如遇报错问题,请参见错误码进行排查。
若问题仍未解决,可加入语音 SDK 示例仓库中列出的开发者群反馈问题,并提供Request ID,以便进一步排查问题。
常见问题
功能特性
Q:在长时间静默的情况下,如何保持与服务端长连接?
将请求参数heartbeat设置为true,并持续向服务端发送静音音频。
静音音频指的是在音频文件或数据流中没有声音信号的内容。静音音频可以通过多种方法生成,例如使用音频编辑软件如Audacity或Adobe Audition,或者通过命令行工具如FFmpeg。
Q:如何将音频格式转换为满足要求的格式?
可使用FFmpeg工具,更多用法请参见FFmpeg官网。
Q:如何识别本地文件(录音文件)?
识别本地文件有两种方式:
-
直接传入本地文件路径:此种方式在最终识别结束后获取完整识别结果,不适合即时反馈的场景。
参见非流式调用,调用核心资源(
client.audio.asr)的recognize_file方法传入文件路径对录音文件直接进行识别。 -
将本地文件转成二进制流进行识别:此种方式一边识别文件一边流式获取识别结果,适合即时反馈的场景。
参见双向流式调用,通过识别会话的
send_audio_frame方法向服务端发送二进制流对其进行识别。
故障排查
Q:无法识别语音(无识别结果)是什么原因?
-
请检查请求参数中的音频格式(
format)和采样率(sampleRate/sample_rate)设置是否正确且符合参数约束。以下为常见错误示例:- 音频文件扩展名为 .wav,但实际为 MP3 格式,而请求参数
format设置为 wav(参数设置错误)。 - 音频采样率为 3600Hz,但请求参数
sampleRate/sample_rate设置为 48000(参数设置错误)。
- 音频文件扩展名为 .wav,但实际为 MP3 格式,而请求参数
- 若以上检查均无问题,可通过定制热词提升对特定词语的识别效果。