前提条件
- 已开通服务并获取与配置 API Key。请配置API Key到环境变量,而非硬编码在代码中,防范因代码泄露导致的安全风险。
- 安装最新版DashScope SDK。
接口地址 — Qwen-Audio-ASR-Streaming / Fun-ASR-Realtime
SDK的实时识别走WebSocket接口,端点由Client的workspace与region自动决定(包含WorkspaceId)。如需切换到其他地域,构造Client时设置对应地域的region即可。
- 新加坡
- 华北2(北京)
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference调用时请将{WorkspaceId}替换为真实的Workspace ID。接口地址 — Qwen-Audio-ASR-Message
SDK的实时识别走WebSocket接口,端点由Client的workspace与region自动决定(包含WorkspaceId)。如需切换到其他地域,构造Client时设置对应地域的region即可。
- 新加坡
- 华北2(北京)
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference调用时请将{WorkspaceId}替换为真实的Workspace ID。快速开始
以下调用示例可共用。按下表替换示例中的模型 ID。
| 模型 | 示例中的模型 ID |
|---|---|
| Qwen-Audio-ASR-Streaming | qwen-audio-3.1-asr-flash-streaming麦克风示例使用 qwen-audio-3.0-asr-flash-streaming。 |
| Qwen-Audio-ASR-Message | qwen-audio-3.1-asr-flash-message采样率仅支持 16000 Hz。 |
| Fun-ASR-Realtime | fun-asr-realtime |
client.audio.asr)提供了非流式调用和双向流式调用等接口。请根据实际需求选择合适的调用方式:
- 非流式调用(
recognize_file):针对本地文件进行识别,SDK自动分块发送音频并驱动到任务结束。适合处理录制好的音频。 - 双向流式调用(
recognize会话):可直接对音频流进行识别,并实时输出结果。音频流可以来自外部设备(如麦克风)或从本地文件读取。适合需要即时反馈的场景。
- 非流式调用
- 双向流式调用
提交单个语音实时转写任务,通过传入本地文件的方式同步阻塞地拿到转写结果。调用核心资源(
client.audio.asr)的recognize_file方法绑定请求参数并传入本地文件路径,迭代服务端事件获取识别结果。请求参数
Qwen-Audio-ASR-Streaming
共享说明
请参见新版 Qwen-Audio-ASR-Streaming Python SDK。
请求参数通过核心资源(client.audio.asr)的recognize/recognize_file方法进行设置:model、format、sample_rate、vocabulary_id为具名参数,其余参数(如language_hints)通过parameters字典传入。
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
model | str | 是 | 模型名称。 |
sample_rate | int | 是 | 采样率(Hz),支持任意采样率。 |
format | str | 是 | 音频格式。取值范围:
|
keep_dialect | bool | 否 | 仅 qwen-audio-3.1-asr-flash-streaming 支持。默认 false,将方言转写为普通话;设为 true 时保留方言表达。作为同名关键字参数传入。完整参数说明请参见客户端事件。 |
vad_model | str | 否 | 仅 qwen-audio-3.1-asr-flash-streaming 支持。可选 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)。当一段语音后的静音时长超过该阈值时,系统会判定该句子已结束。默认值:800。取值范围:[200, 6000]。 |
multi_threshold_mode_enabled | bool | 否 | 是否启用多阈值模式。启用后可防止 VAD 断句切割过长。默认值:False。 |
punctuation_prediction_enabled | bool | 否 | 设置是否在识别结果中自动添加标点:
|
heartbeat | bool | 否 | 是否启用心跳包。默认值:False。
|
language_hints | list[str] | 否 | 待识别音频语种。无默认值,不设置时模型自动识别。最多支持设置 4 个值,超出时仅前 4 个生效。
点击查看支持的语言代码
|
speech_noise_threshold | float | 否 | 语音与噪音的判定阈值,用于调整语音活动检测(VAD)的灵敏度。取值范围:[-1.0, 1.0]。取值说明:
|
special_word_filter | str | 否 | 指定在语音识别过程中需要处理的敏感词,并支持对不同敏感词设置不同的处理方式。详情请参见敏感词过滤。 |
recognize/recognize_file方法的input关键字参数传入。
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
input | dict | 否 | 输入对象,用于传入对话上下文(context)。上下文用于辅助识别、提升专有词汇的识别准确率。使用方法详见快速开始。dict 中需包含 context 键,值为消息列表(list[dict]),每条消息包含以下字段:
使用该字段时,SDK版本不能低于2.0.1。 |
Qwen-Audio-ASR-Message
共享说明
请参见新版 Qwen-Audio-ASR-Message Python SDK。
请求参数通过核心资源(client.audio.asr)的recognize/recognize_file方法进行设置:model、format、sample_rate、vocabulary_id为具名参数,其余参数(如language_hints)通过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 时返回流式中间结果。作为同名关键字参数传入。 |
keep_dialect | bool | 否 | 默认 false,将方言转写为普通话;设为 true 时保留方言表达。作为同名关键字参数传入。完整参数说明请参见客户端事件。仅在最终结果(sentence_end=true)生效,中间结果(sentence_end=false)不支持。 |
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 个使用。使用方法请参见即时热词。示例: |
language_hints | list[str] | 否 | 待识别音频语种。无默认值,不设置时模型自动识别。最多支持设置 4 个值,超出时仅前 4 个生效。
点击查看支持的语言代码
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/recognize_file方法的input关键字参数传入。
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
input | dict | 否 | 输入对象,用于传入对话上下文(context)。上下文用于辅助识别、提升专有词汇的识别准确率。使用方法详见快速开始。 dict 中需包含context 键,值为消息列表(list[dict]),每条消息包含以下字段:
该字段自 SDK 1.25.23 引入,2.0.1 及以上版本已包含。 |
Fun-ASR-Realtime
共享说明
请参见新版 Fun-ASR-Realtime Python SDK。
请求参数通过核心资源(client.audio.asr)的recognize/recognize_file方法进行设置:model、format、sample_rate、vocabulary_id为具名参数,其余参数(如max_sentence_silence、language_hints)通过parameters字典传入。
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
model | str | 是 | 模型名称。 |
sample_rate | int | 是 | 采样率(Hz)。取值范围:8k模型仅支持 8000 Hz,其他模型支持任意采样率。 |
format | str | 是 | 音频格式。取值范围:
|
vocabulary_id | str | 否 | 预编译热词列表 ID。需预先调用创建热词列表接口生成,识别时传入该 ID 即可使用列表中的热词。适用于词汇已知且相对稳定、需要跨请求复用同一词表的场景。使用方法请参见预编译热词。 |
max_sentence_silence | int | 否 | VAD 断句静音阈值(ms)。当一段语音后的静音时长超过该阈值时,系统会判定该句子已结束。默认值:1300。取值范围:[200, 6000]。 |
multi_threshold_mode_enabled | bool | 否 | 是否启用多阈值模式。启用后可防止 VAD 断句切割过长。默认值:False。 |
punctuation_prediction_enabled | bool | 否 | 设置是否在识别结果中自动添加标点:
|
heartbeat | bool | 否 | 是否启用心跳包。默认值:False。
|
language_hints | list[str] | 否 | 待识别音频语种。无默认值,不设置时模型自动识别。仅支持设置 1 个值,设置多个时仅第一个生效。
点击查看支持的语言代码
|
speech_noise_threshold | float | 否 | 语音与噪音的判定阈值,用于调整语音活动检测(VAD)的灵敏度。取值范围:[-1.0, 1.0]。取值说明:
|
special_word_filter | str | 否 | 指定在语音识别过程中需要处理的敏感词,并支持对不同敏感词设置不同的处理方式。详情请参见敏感词过滤。 |
recognize/recognize_file方法的input关键字参数传入。
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
input | dict | 否 | 输入对象,用于传入对话上下文(context)。上下文用于辅助识别、提升专有词汇的识别准确率。使用方法详见提升识别准确率。dict 中需包含 context 键,值为消息列表(list[dict]),每条消息包含以下字段:
使用该字段时,SDK版本不能低于2.0.1。 |
接口参考
Qwen-Audio-ASR-Streaming / Fun-ASR-Realtime
识别结果(RecognitionResult)
RecognitionResult代表会话results()迭代产出的一次识别结果帧(双向流式调用与非流式调用均可使用;events()产出的是原始事件dict,如需该类型化视图请改用results())。
| 成员方法 | 方法签名 | 说明 |
|---|---|---|
get_sentence | 获取当前识别的句子及时间戳信息,此方法返回类型为Dict[str, Any](单句信息)。详情请参见单句信息(Sentence)。 | |
request_id | 当前事件对应的请求request_id。 | |
is_sentence_end | 判断当前句子是否已经结束。该方法通过检查 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 | 标点。 |
Qwen-Audio-ASR-Streaming
关键接口
核心资源(client.audio.asr)
实时语音识别能力挂载在client.audio.asr资源上:recognize创建双向流式识别会话(Recognition),recognize_file对本地文件一次性识别。
| 成员方法 | 方法签名 | 说明 |
|---|---|---|
| recognize | 创建双向流式识别会话,进入with上下文时自动调用start建立连接并发送任务。发送音频与消费事件需并发进行(配合send_audio_frame、events()/results()和stop使用)。 | |
| recognize_file | 基于本地文件的非流式调用:自动分块发送音频并驱动到任务结束,逐个产出服务端事件。该方法要求所识别文件具有可读权限。 | |
start | 开始语音识别:建立连接、发送任务并等待task-started。进入with上下文时自动调用,启动成功后才能发送音频。 | |
send_audio_frame | 推送音频。每次推送的音频流不宜过大或过小,建议每包音频时长为100ms左右,大小在1KB~16KB之间。识别结果通过事件迭代(events()/results())获取。 | |
stop | 停止语音识别:只通知服务端输入结束,接收线程需继续消费events()直到task-finished事件。 | |
| events / results | 迭代服务端事件:events()产出原始事件dict(识别文本位于payload.output.sentence);results()只产出识别结果帧,返回识别结果(RecognitionResult)类型化对象(心跳帧已过滤)。 | |
| close | 关闭识别会话。退出with上下文时自动调用。 | |
| request_id / first_package_delay / last_package_delay / last_response | 获取request_id、首包延迟(从发送第一包音频到收到首包识别结果延迟)和尾包延迟(发送stop指令到最后一包识别结果下发耗时),在任务完成后使用;last_response为最近一次成功读取的原始报文,可用于获取task-failed报错。会话关闭后仍可读取。 |
事件迭代(events()/results())
双向流式调用时,服务端会通过事件的方式,将关键流程信息和数据返回给客户端。您需要在接收线程中迭代会话的events()(原始事件dict)或results()(类型化识别结果帧),处理服务端返回的信息或者数据。
| 事件/迭代方法 | 产出内容 | 返回值 | 描述 |
|---|---|---|---|
task-started事件 | 无 | 由start()内部读取,启动返回时保存在last_response中,不会由events()再次产出。 | |
event:服务端事件dict | 迭代器 | 当服务有回复时产出事件。识别结果位于payload.output.sentence,可能为心跳或空文本事件,应用可按需忽略。请由一个接收线程持续消费,不要并发创建多个读取者。 | |
result:识别结果(RecognitionResult) | 迭代器 | 只产出识别结果帧(心跳帧已过滤),全部识别结果返回后迭代结束。 | |
DashScopeError异常 | 无 | 发生异常时在发送/接收线程中抛出,可使用try/except捕获。 | |
task-finished事件 | 无 | 当服务已经完成全部识别后由events()产出,随后迭代结束;发送stop()后仍须读取此事件。 |
响应结果
Qwen-Audio-ASR-Message
关键接口
核心资源(client.audio.asr)
实时语音识别能力挂载在client.audio.asr资源上:recognize创建双向流式识别会话(Recognition),recognize_file对本地文件一次性识别。
| 成员方法 | 方法签名 | 说明 |
|---|---|---|
recognize | 创建双向流式识别会话,进入with上下文时自动调用start建立连接并发送任务。发送音频与消费事件需并发进行(配合send_audio_frame、events()/results()和stop使用)。 | |
recognize_file | 基于本地文件的非流式调用:自动分块发送音频并驱动到任务结束,逐个产出服务端事件。该方法要求所识别文件具有可读权限。 | |
start | 开始语音识别:建立连接、发送任务并等待task-started。进入with上下文时自动调用,启动成功后才能发送音频。 | |
send_audio_frame | 推送音频。每次推送的音频流不宜过大或过小,建议每包音频时长为100ms左右,大小在1KB~16KB之间。 识别结果通过事件迭代(events()/results())获取。 | |
stop | 停止语音识别:只通知服务端输入结束,接收线程需继续消费events()直到task-finished事件。 | |
events / results | 迭代服务端事件:events()产出原始事件dict(识别文本位于payload.output.sentence);results()只产出识别结果帧,返回识别结果(RecognitionResult)类型化对象(心跳帧已过滤)。 | |
close | 关闭识别会话。退出with上下文时自动调用。 | |
request_id / first_package_delay / last_package_delay / last_response | 获取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()(类型化识别结果帧),处理服务端返回的信息或者数据。
| 事件/迭代方法 | 产出内容 | 返回值 | 描述 |
|---|---|---|---|
task-started事件 | 无 | 由start()内部读取,启动返回时保存在last_response中,不会由events()再次产出。 | |
event:服务端事件dict | 迭代器 | 当服务有回复时产出事件。识别结果位于payload.output.sentence,可能为心跳或空文本事件,应用可按需忽略。请由一个接收线程持续消费,不要并发创建多个读取者。 | |
result:识别结果(RecognitionResult) | 迭代器 | 只产出识别结果帧(心跳帧已过滤),全部识别结果返回后迭代结束。 | |
DashScopeError异常 | 无 | 发生异常时在发送/接收线程中抛出,可使用try/except捕获。 | |
task-finished事件 | 无 | 当服务已经完成全部识别后由events()产出,随后迭代结束;发送stop()后仍须读取此事件。 |
响应结果
识别结果(RecognitionResult)
RecognitionResult代表会话results()迭代产出的一次识别结果帧(双向流式调用与非流式调用均可使用;events()产出的是原始事件dict,如需该类型化视图请改用results())。
| 成员方法 | 方法签名 | 说明 |
|---|---|---|
get_sentence | 获取当前识别的句子及时间戳信息,此方法返回类型为Dict[str, Any](单句信息)。 详情请参见单句信息(Sentence)。 | |
request_id | 当前事件对应的请求request_id。 | |
is_sentence_end | 判断当前句子是否已经结束。该方法通过检查 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 | 标点。 |
Fun-ASR-Realtime
关键接口
核心资源(client.audio.asr)
实时语音识别能力挂载在client.audio.asr资源上:recognize创建双向流式识别会话(Recognition),recognize_file对本地文件一次性识别。
| 成员方法 | 方法签名 | 说明 |
|---|---|---|
| recognize | 创建双向流式识别会话,进入with上下文时自动调用start建立连接并发送任务。发送音频与消费事件需并发进行(配合send_audio_frame、events()/results()和stop使用)。 | |
| recognize_file | 基于本地文件的非流式调用:自动分块发送音频并驱动到任务结束,逐个产出服务端事件。该方法要求所识别文件具有可读权限。 | |
| start | 开始语音识别:建立连接、发送任务并等待task-started。进入with上下文时自动调用,启动成功后才能发送音频。 | |
| send_audio_frame | 推送音频。每次推送的音频流不宜过大或过小,建议每包音频时长为100ms左右,大小在1KB~16KB之间。识别结果通过events()/results()迭代获取。 | |
| stop | 停止语音识别:只通知服务端输入结束,接收线程需继续消费events()直到task-finished事件。 | |
| events / results | 迭代服务端事件:events()产出原始事件dict(识别文本位于payload.output.sentence);results()只产出识别结果帧,返回识别结果(RecognitionResult)类型化对象(心跳帧已过滤)。 | |
| close | 关闭识别会话。退出with上下文时自动调用。 | |
| request_id / first_package_delay / last_package_delay / last_response | 获取request_id、首包延迟(从发送第一包音频到收到首包识别结果延迟)和尾包延迟(发送stop指令到最后一包识别结果下发耗时),在任务完成后使用;last_response为最近一次成功读取的原始报文,可用于获取task-failed报错。会话关闭后仍可读取。 |
事件迭代(events()/results())
双向流式调用时,服务端会通过事件的方式,将关键流程信息和数据返回给客户端。您需要在接收线程中迭代会话的events()(原始事件dict)或results()(类型化识别结果帧),处理服务端返回的信息或者数据。
| 事件/迭代方法 | 产出内容 | 返回值 | 描述 |
|---|---|---|---|
task-started事件 | 无 | 由start()内部读取,启动返回时保存在last_response中,不会由events()再次产出。 | |
event:服务端事件dict | 迭代器 | 当服务有回复时产出事件。识别结果位于payload.output.sentence,可能为心跳或空文本事件,应用可按需忽略。请由一个接收线程持续消费,不要并发创建多个读取者。 | |
result:识别结果(RecognitionResult) | 迭代器 | 只产出识别结果帧(心跳帧已过滤),全部识别结果返回后迭代结束。 | |
DashScopeError异常 | 无 | 发生异常时在发送/接收线程中抛出,可使用try/except捕获。 | |
task-finished事件 | 无 | 当服务已经完成全部识别后由events()产出,随后迭代结束;发送stop()后仍须读取此事件。 |