本文介绍Qwen-Audio-3.1-ASR-Flash-Message实时语音识别Python SDK的参数和接口细节。
前提条件
- 已开通服务并获取与配置 API Key。请配置API Key到环境变量,而非硬编码在代码中,防范因代码泄露导致的安全风险。
- 安装最新版DashScope SDK。
快速开始
Recognition类提供了非流式调用和双向流式调用等接口。请根据实际需求选择合适的调用方式:
- 非流式调用:针对本地文件进行识别,并一次性返回完整的处理结果。适合处理录制好的音频。
- 双向流式调用:可直接对音频流进行识别,并实时输出结果。音频流可以来自外部设备(如麦克风)或从本地文件读取。适合需要即时反馈的场景。
- 非流式调用
- 双向流式调用
提交单个语音实时转写任务,通过传入本地文件的方式同步阻塞地拿到转写结果。实例化Recognition类绑定请求参数,调用
call进行识别/翻译并最终获取识别结果(RecognitionResult)。接口地址
SDK的接口地址需在初始化前设置为下方地址(包含WorkspaceId)。如需切换到其他地域,请修改 dashscope.base_websocket_api_url为对应地域的URL。
- 华北2(北京)
- 新加坡
wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference调用时请将{WorkspaceId}替换为真实的Workspace ID。请求参数
请求参数通过Recognition类的构造方法(init)进行设置。
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
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 时返回流式中间结果。作为同名关键字参数传入。 |
keep_dialect | bool | 否 | 默认 false,将方言转写为普通话;设为 true 时保留方言表达。作为同名关键字参数传入。完整参数说明请参见客户端事件。 |
vad_model | str | 否 | 可选 near_meeting_16k(近场)或 far_field_meeting_16k(远场,默认值)。作为同名关键字参数传入。完整参数说明请参见客户端事件。 |
vocabulary_id | str | 否 | 预编译热词列表 ID。 需预先调用创建热词列表接口生成,识别时传入该 ID 即可使用列表中的热词。适用于词汇已知且相对稳定、需要跨请求复用同一词表的场景。使用方法请参见预编译热词。 |
vocabulary | dict | 否 | 即时热词。 以键值对形式传入,键为热词文本(string),值为热词权重(integer),无需预先创建热词列表。权重取值范围为 [1, 5] 或 50:取 [1, 5] 时值越大模型越倾向输出该词;取 50 时为超级热词,召回率大幅提升,但超级热词数量最多不超过 50 个。适用于临时性、会话级别的热词优化。与预编译热词同时配置时,系统会合并两类热词;合并后超过 2000 个时,随机选择 2000 个使用。使用方法请参见即时热词。示例: |
max_sentence_silence | int | 否 | VAD 断句静音阈值(ms)。当一段语音后的静音时长超过该阈值时,系统会判定该句子已结束。 默认值:1300。取值范围:[200, 6000]。 |
heartbeat | bool | 否 | 是否启用心跳包。 默认值:False。
|
speech_noise_threshold | float | 否 | 语音与噪音的判定阈值,用于调整语音活动检测(VAD)的灵敏度。 取值范围:[-1.0, 1.0]。取值说明:
|
callback | RecognitionCallback | 否 | 回调接口(RecognitionCallback)。 |
Recognition实例的call或start方法的关键字参数传入。
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
raw_input | dict | 否 | 输入对象,用于传入对话上下文(context)。上下文用于辅助识别、提升专有词汇的识别准确率。使用方法详见提升识别准确率。 dict 中需包含context 键,值为消息列表(list[dict]),每条消息包含以下字段:
使用该字段时,SDK版本不能低于1.25.23。 |
关键接口
Recognition类
Recognition通过from dashscope.audio.asr import *方式引入。
| 成员方法 | 方法签名 | 说明 |
|---|---|---|
call | 基于本地文件的非流式调用,该方法会阻塞当前线程直到全部音频读完,该方法要求所识别文件具有可读权限。 识别结果以RecognitionResult类型数据返回。 | |
start | 开始语音识别。 基于回调形式的流式实时识别,该方法不会阻塞当前线程。需要配合send_audio_frame和stop使用。 | |
send_audio_frame | 推送音频。每次推送的音频流不宜过大或过小,建议每包音频时长为100ms左右,大小在1KB~16KB之间。 识别结果通过回调接口(RecognitionCallback)的on_event方法获取。 | |
stop | 停止语音识别,阻塞到服务将收到的音频都识别后结束任务。 | |
get_last_request_id | 获取request_id,在构造函数调用(创建对象)后可以使用。 | |
get_first_package_delay | 获取首包延迟,从发送第一包音频到收到首包识别结果延迟,在任务完成后使用。 | |
get_last_package_delay | 获得尾包延迟,发送stop指令到最后一包识别结果下发耗时,在任务完成后使用。 | |
get_response | 获取最后一次报文,可以用于获取task-failed报错。 |
更新对话上下文
调用 update_context 在识别任务运行过程中更新对话上下文,用于辅助后续音频的识别。该方法要求 DashScope Python SDK 1.27.5 及以上版本。
- 调用时机:调用
start启动流式识别后、调用stop前。 - 参数:
payload_input为字典,传入continue-task事件的payload.input对象,包含context字段,不要额外包装payload或input层级。 - 支持范围与参数约束:请参见 continue-task。
recognition 实例。
回调接口(RecognitionCallback)
双向流式调用时,服务端会通过回调的方式,将关键流程信息和数据返回给客户端。您需要实现回调方法,处理服务端返回的信息或者数据。
| 方法 | 参数 | 返回值 | 描述 |
|---|---|---|---|
| 无 | 无 | 当和服务端建立连接完成后,该方法立刻被回调。 | |
result:识别结果(RecognitionResult) | 无 | 当服务有回复时会被回调。 | |
| 无 | 无 | 当所有识别结果全部返回后进行回调。 | |
result:识别结果(RecognitionResult) | 无 | 发生异常时该方法被回调。 | |
| 无 | 无 | 当服务已经关闭连接后进行回调。 |
响应结果
识别结果(RecognitionResult)
RecognitionResult代表双向流式调用中一次实时识别或非流式调用的识别结果。
| 成员方法 | 方法签名 | 说明 |
|---|---|---|
get_sentence | 获取当前识别的句子及时间戳信息。回调中返回的是单句信息,所以此方法返回类型为Dict[str, Any]。 详情请参见单句信息(Sentence)。 | |
get_request_id | 获取请求的request_id。 | |
is_sentence_end | 判断给定句子是否已经结束。该方法通过检查 sentence 中 end_time 字段是否为 None 来判定——end_time 不为 None 时表示句子已结束。调用方式为 RecognitionResult.is_sentence_end(sentence),其中 sentence 为 get_sentence() 返回的单句信息 dict,而非 Sentence 实例的布尔字段。 |
单句信息(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:如何识别本地文件(录音文件)?
识别本地文件有两种方式:
-
直接传入本地文件路径:此种方式在最终识别结束后获取完整识别结果,不适合即时反馈的场景。
参见非流式调用,在Recognition类的
call方法中传入文件路径对录音文件直接进行识别。 -
将本地文件转成二进制流进行识别:此种方式一边识别文件一边流式获取识别结果,适合即时反馈的场景。
参见双向流式调用,通过Recognition类的
send_audio_frame方法向服务端发送二进制流对其进行识别。
故障排查
Q:无法识别语音(无识别结果)是什么原因?
-
请检查请求参数中的音频格式(
format)和采样率(sampleRate/sample_rate)设置是否正确且符合参数约束。以下为常见错误示例:- 音频文件扩展名为 .wav,但实际为 MP3 格式,而请求参数
format设置为 wav(参数设置错误)。 - 音频采样率为 3600Hz,但请求参数
sampleRate/sample_rate设置为 48000(参数设置错误)。
- 音频文件扩展名为 .wav,但实际为 MP3 格式,而请求参数
- 若以上检查均无问题,可通过定制热词提升对特定词语的识别效果。