Skip to main content

Qwen-Audio-ASR / Fun-ASR Python SDK

通过 WebSocket 使用 DashScope Python SDK 调用 Qwen-Audio-ASR / Fun-ASR。

Streaming、Message 和 Fun-ASR-Realtime 均使用 client.audio.asr。用 recognize_file 识别本地文件,或用 recognize 创建双向流式识别会话。

前提条件

接口地址

SDK的实时识别走WebSocket接口,端点由Client的workspace与region自动决定(包含WorkspaceId)。如需切换到其他地域,构造Client时设置对应地域的region即可。
  • 华北2(北京)
  • 新加坡
wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference调用时请将{WorkspaceId}替换为真实的Workspace ID。
阿里云百炼为华北2(北京)、新加坡地域推出了业务空间专属域名,能够为推理请求提供卓越的性能和更高的稳定性,建议迁移至新域名:
  • 华北2(北京)地域:从 dashscope.aliyuncs.com 迁移至 {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • 新加坡地域:从 dashscope-intl.aliyuncs.com 迁移至 {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

快速开始

示例使用 Qwen-Audio-ASR-Streaming。调用同组其他模型时,替换 model,并按对应模型的要求设置采样率。
模型示例中的 model 值
Qwen-Audio-ASR-Streamingqwen-audio-3.1-asr-flash-streaming。下方麦克风示例使用 qwen-audio-3.0-asr-flash-streaming。
Qwen-Audio-ASR-Messageqwen-audio-3.1-asr-flash-message,采样率仅支持 16000 Hz。
Fun-ASR-Realtimefun-asr-realtime。
核心资源(client.audio.asr)提供了非流式调用和双向流式调用等接口。请根据实际需求选择合适的调用方式:
  • 非流式调用(recognize_file):针对本地文件进行识别,SDK自动分块发送音频并驱动到任务结束。适合处理录制好的音频。
  • 双向流式调用(recognize会话):可直接对音频流进行识别,并实时输出结果。音频流可以来自外部设备(如麦克风)或从本地文件读取。适合需要即时反馈的场景。
  • 非流式调用
  • 双向流式调用
提交单个语音实时转写任务,通过传入本地文件的方式同步阻塞地拿到转写结果。调用核心资源(client.audio.asr)的recognize_file方法绑定请求参数并传入本地文件路径,迭代服务端事件获取识别结果。
import os
import dashscope

# 新加坡和北京地域的API Key不同。获取API Key:https://help.aliyun.com/zh/model-studio/get-api-key
# 若没有配置环境变量,请用百炼API Key将下行替换为:api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.environ.get('DASHSCOPE_API_KEY'),
    # 以下为华北2(北京)地域的配置,调用时请将"{WorkspaceId}"替换为真实的业务空间ID,各地域的配置不同。
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

# 识别本地语音文件:recognize_file自动分块发送音频并驱动到任务结束
for event in client.audio.asr.recognize_file(
        '{YOUR_AUDIO_FILE}',
        model='qwen-audio-3.1-asr-flash-streaming',
        format='wav',
        sample_rate=16000):
    payload = event.get('payload') or {}
    sentence = (payload.get('output') or {}).get('sentence') or {}
    if sentence.get('text') and not sentence.get('heartbeat'):
        print('识别结果:', sentence['text'])

请求参数

Qwen-Audio-ASR-Streaming

调用示例见本组的快速开始。返回字段见Streaming 与 Fun-ASR 的响应结果。 请求参数通过核心资源(client.audio.asr)的recognize/recognize_file方法进行设置:model、format、sample_rate、vocabulary_id可直接传入。通过 parameters 字典传入 language_hints。
参数类型是否必须说明
modelstr是模型名称。
sample_rateint是采样率(Hz),支持任意采样率。
formatstr是音频格式。取值范围:
  • pcm
  • wav
  • mp3
  • opus
  • speex
  • aac
  • amr
opus/speex:必须使用Ogg封装;wav:必须为PCM编码;amr:仅支持AMR-NB类型。
keep_dialectbool否仅 qwen-audio-3.1-asr-flash-streaming 支持。默认 false,将方言转写为普通话;设为 true 时保留方言表达。通过 parameters 字典传入。完整参数说明请参见客户端事件。
vad_modelstr否仅 qwen-audio-3.1-asr-flash-streaming 支持。可选 near_meeting_16k(近场)或 far_field_meeting_16k(远场,默认值)。通过 parameters 字典传入。完整参数说明请参见客户端事件。
vocabulary_idstr否预编译热词列表 ID。需预先调用创建热词列表接口生成,识别时传入该 ID 即可使用列表中的热词。适用于词汇已知且相对稳定、需要跨请求复用同一词表的场景。使用方法请参见预编译热词。
vocabularydict否即时热词。以键值对形式传入,键为热词文本(string),值为热词权重(integer),无需预先创建热词列表。权重取值范围为 [1, 5] 或 50:取 [1, 5] 时值越大模型越倾向输出该词;取 50 时为超级热词,召回率大幅提升,但超级热词数量最多不超过 50 个。适用于临时性、会话级别的热词优化。与预编译热词同时配置时,系统会合并两类热词;合并后超过 2000 个时,随机选择 2000 个使用。使用方法请参见即时热词。示例:
import os
import dashscope

client = dashscope.Client(api_key=os.getenv("DASHSCOPE_API_KEY"))

# 即时热词通过parameters传入
vocab = {"张三": 5, "李四": 5}
recognition = client.audio.asr.recognize(
    model='qwen-audio-3.1-asr-flash-streaming',
    format='wav',
    sample_rate=16000,
    parameters={"vocabulary": vocab},
)
max_sentence_silenceint否VAD 断句静音阈值(ms)。当一段语音后的静音时长超过该阈值时,系统会判定该句子已结束。默认值:800。取值范围:[200, 6000]。
multi_threshold_mode_enabledbool否是否启用多阈值模式。启用后可防止 VAD 断句切割过长。默认值:False。
punctuation_prediction_enabledbool否设置是否在识别结果中自动添加标点:
  • True(默认):是,不支持修改。
heartbeatbool否是否启用心跳包。默认值:False。
  • True:在持续发送静音音频的情况下,可保持与服务端的连接不中断。
  • False(默认):即使持续发送静音音频,连接也将在一定时间后因超时而断开。
静音音频指的是在音频文件或数据流中没有声音信号的内容。静音音频可以通过多种方法生成,例如使用音频编辑软件如Audacity或Adobe Audition,或者通过命令行工具如FFmpeg。使用该字段时,SDK版本不能低于2.0.1。
language_hintslist[str]否待识别音频语种。无默认值,不设置时模型自动识别。最多支持设置 4 个值,超出时仅前 4 个生效。
  • zh: 中文
  • en: 英文
  • ja: 日语
  • ko:韩语
  • vi:越南语
  • th:泰语
  • id:印尼语
  • ms:马来语
  • tl:菲律宾语
  • hi:印地语
  • ar:阿拉伯语
  • fr:法语
  • de:德语
  • es:西班牙语
  • pt:葡萄牙语
  • ru:俄语
  • it:意大利语
  • nl:荷兰语
  • sv:瑞典语
  • da:丹麦语
  • fi:芬兰语
  • no:挪威语
  • el:希腊语
  • pl:波兰语
  • cs:捷克语
  • hu:匈牙利语
  • ro:罗马尼亚语
  • bg:保加利亚语
  • hr:克罗地亚语
  • sk:斯洛伐克语
speech_noise_thresholdfloat否语音与噪音的判定阈值,用于调整语音活动检测(VAD)的灵敏度。取值范围:[-1.0, 1.0]。取值说明:
  • 取值越接近 -1:降低噪音判定阈值,噪音被识别为语音的概率增大,可能导致更多噪音被转写
  • 取值越接近 +1:提高噪音判定阈值,语音被误判为噪音的概率增大,可能导致部分语音被过滤
此参数为高级配置参数,调整可能显著影响识别效果,建议:
  • 调整前充分测试验证效果
  • 根据实际音频环境小幅度调整(建议步长 0.1)
special_word_filterstr否指定在语音识别过程中需要处理的敏感词,并支持对不同敏感词设置不同的处理方式。详情请参见敏感词过滤。
使用 recognize 创建识别会话时,通过 input 传入上下文。
参数类型是否必须说明
inputdict否输入对象,用于传入对话上下文(context)。上下文用于辅助识别、提升专有词汇的识别准确率。使用方法详见提升识别准确率。dict 中需包含 context 键,值为消息列表(list[dict]),每条消息包含以下字段:
  • role(str,必选):消息角色。user 表示前几轮用户语音的识别结果或领域相关的词表;assistant 表示前几轮大语言模型的回复内容。
  • content(list[dict],必选):消息内容列表。每个元素包含 type(str,role 为 user 时填 input_text,role 为 assistant 时填 text)和 text(str,文本内容)。
上下文消息(input_text 和 text 类型)各最多 5 条,超出时保留最近的 5 条。每轮上下文文本总长度不超过 400 个字符,超出部分从末尾截断。
携带上下文时,context 中的消息顺序有要求:上下文消息必须按对话轮次排列,每轮中 user(input_text 类型)必须在对应的 assistant(text 类型)之前。
使用该字段时,SDK版本不能低于2.0.1。
# 构建 input 传入数据
input_context = {
    "context": [
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "你好啊"
                }
            ]
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "你好啊,我是通义千问,有什么可以帮助你的?"
                }
            ]
        }
    ]
}

# 创建识别会话时通过 input 参数传入
recognition = client.audio.asr.recognize(
    model='qwen-audio-3.1-asr-flash-streaming',
    format='wav',
    sample_rate=16000,
    input=input_context,
)

Qwen-Audio-ASR-Message

调用示例见本组的快速开始。 请求参数通过核心资源(client.audio.asr)的recognize/recognize_file方法进行设置:model、format、sample_rate、vocabulary_id可直接传入。通过 parameters 字典传入 language_hints。
参数类型是否必须说明
modelstr是模型名,设置为 qwen-audio-3.1-asr-flash-message。
sample_rateint是

采样率(Hz)。

仅支持 16000 Hz。
formatstr是

音频格式。

取值范围:
  • pcm
  • wav
  • mp3
  • opus
  • speex
  • aac
  • amr
opus/speex:必须使用Ogg封装;wav:必须为PCM编码;amr:仅支持AMR-NB类型。
disfluency_removal_enabledbool否是否过滤语气词并对输出结果进行润色,默认值为 false。设置为 true 时启用。作为同名关键字参数传入。
intermediate_result_enabledbool否是否返回流式中间结果,默认值为 false。设置为 true 时返回流式中间结果。通过 parameters 字典传入。
keep_dialectbool否默认 false,将方言转写为普通话;设为 true 时保留方言表达。通过 parameters 字典传入。完整参数说明请参见客户端事件。仅在最终结果(sentence_end=true)生效,中间结果(sentence_end=false)不支持。
vad_modelstr否可选 near_meeting_16k(近场)或 far_field_meeting_16k(远场,默认值)。通过 parameters 字典传入。完整参数说明请参见客户端事件。
vocabulary_idstr否

预编译热词列表 ID。

需预先调用创建热词列表接口生成,识别时传入该 ID 即可使用列表中的热词。适用于词汇已知且相对稳定、需要跨请求复用同一词表的场景。使用方法请参见预编译热词。
vocabularydict否

即时热词。

以键值对形式传入,键为热词文本(string),值为热词权重(integer),无需预先创建热词列表。权重取值范围为 [1, 5] 或 50:取 [1, 5] 时值越大模型越倾向输出该词;取 50 时为超级热词,召回率大幅提升,但超级热词数量最多不超过 50 个。适用于临时性、会话级别的热词优化。与预编译热词同时配置时,系统会合并两类热词;合并后超过 2000 个时,随机选择 2000 个使用。使用方法请参见即时热词。示例:
import os
import dashscope

client = dashscope.Client(api_key=os.getenv("DASHSCOPE_API_KEY"))

# 即时热词通过parameters传入
vocab = {"张三": 5, "李四": 5}
recognition = client.audio.asr.recognize(
    model='qwen-audio-3.1-asr-flash-message',
    format='wav',
    sample_rate=16000,
    parameters={"vocabulary": vocab},
)
language_hintslist[str]否待识别音频语种。无默认值,不设置时模型自动识别。最多支持设置 4 个值,超出时仅前 4 个生效。
  • zh: 中文
  • en: 英文
  • ja: 日语
  • ko:韩语
  • vi:越南语
  • th:泰语
  • id:印尼语
  • ms:马来语
  • tl:菲律宾语
  • hi:印地语
  • ar:阿拉伯语
  • fr:法语
  • de:德语
  • es:西班牙语
  • pt:葡萄牙语
  • ru:俄语
  • it:意大利语
  • nl:荷兰语
  • sv:瑞典语
  • da:丹麦语
  • fi:芬兰语
  • no:挪威语
  • el:希腊语
  • pl:波兰语
  • cs:捷克语
  • hu:匈牙利语
  • ro:罗马尼亚语
  • bg:保加利亚语
  • hr:克罗地亚语
  • sk:斯洛伐克语
通过 parameters 字典传入,例如 parameters={"language_hints": ["zh"]}。仅在最终结果(sentence_end=true)生效,中间结果(sentence_end=false)不支持。
max_sentence_silenceint否

VAD 断句静音阈值(ms)。当一段语音后的静音时长超过该阈值时,系统会判定该句子已结束。

默认值:800。取值范围:[200, 6000]。
heartbeatbool否

是否启用心跳包。

默认值:False。
  • True:在持续发送静音音频的情况下,可保持与服务端的连接不中断。
  • False(默认):即使持续发送静音音频,连接也将在一定时间后因超时而断开。
静音音频指的是在音频文件或数据流中没有声音信号的内容。静音音频可以通过多种方法生成,例如使用音频编辑软件如Audacity或Adobe Audition,或者通过命令行工具如FFmpeg。该字段自 SDK 1.23.1 引入,2.0.1 及以上版本已包含。
speech_noise_thresholdfloat否

语音与噪音的判定阈值,用于调整语音活动检测(VAD)的灵敏度。

取值范围:[-1.0, 1.0]。取值说明:
  • 取值越接近 -1:降低噪音判定阈值,噪音被识别为语音的概率增大,可能导致更多噪音被转写
  • 取值越接近 +1:提高噪音判定阈值,语音被误判为噪音的概率增大,可能导致部分语音被过滤
此参数为高级配置参数,调整可能显著影响识别效果,建议:
  • 调整前充分测试验证效果
  • 根据实际音频环境小幅度调整(建议步长 0.1)
使用 recognize 创建识别会话时,通过 input 传入上下文。
参数类型是否必须说明
inputdict否

输入对象,用于传入对话上下文(context)。上下文用于辅助识别、提升专有词汇的识别准确率。使用方法详见提升识别准确率。

dict 中需包含 context 键,值为消息列表(list[dict]),每条消息包含以下字段:
  • role(str,必选):消息角色。user 表示前几轮用户语音的识别结果或领域相关的词表;assistant 表示前几轮大语言模型的回复内容。
  • content(list[dict],必选):消息内容列表。每个元素包含 type(str,role 为 user 时填 input_text,role 为 assistant 时填 text)和 text(str,文本内容)。
上下文消息(input_text 和 text 类型)各最多 5 条,超出时保留最近的 5 条。每轮上下文文本总长度不超过 400 个字符,超出部分从末尾截断。
携带上下文时,context 中的消息顺序有要求:上下文消息必须按对话轮次排列,每轮中 user(input_text 类型)必须在对应的 assistant(text 类型)之前。
该字段自 SDK 1.25.23 引入,2.0.1 及以上版本已包含。
# 构建 input 传入数据
input_context = {
    "context": [
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "你好啊"
                }
            ]
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "你好啊,我是通义千问,有什么可以帮助你的?"
                }
            ]
        }
    ]
}

# 创建识别会话时通过 input 参数传入
recognition = client.audio.asr.recognize(
    model='qwen-audio-3.1-asr-flash-message',
    format='wav',
    sample_rate=16000,
    input=input_context,
)

Fun-ASR-Realtime

调用示例见本组的快速开始。返回字段见Streaming 与 Fun-ASR 的响应结果。 请求参数通过核心资源(client.audio.asr)的recognize/recognize_file方法进行设置:model、format、sample_rate、vocabulary_id可直接传入。通过 parameters 字典传入 max_sentence_silence 和 language_hints。
参数类型是否必须说明
modelstr是模型名称。
sample_rateint是采样率(Hz)。取值范围:8k模型仅支持 8000 Hz,其他模型支持任意采样率。
formatstr是音频格式。取值范围:
  • pcm
  • wav
  • mp3
  • opus
  • speex
  • aac
  • amr
opus/speex:必须使用Ogg封装;wav:必须为PCM编码;amr:仅支持AMR-NB类型。
vocabulary_idstr否预编译热词列表 ID。需预先调用创建热词列表接口生成,识别时传入该 ID 即可使用列表中的热词。适用于词汇已知且相对稳定、需要跨请求复用同一词表的场景。使用方法请参见预编译热词。
max_sentence_silenceint否VAD 断句静音阈值(ms)。当一段语音后的静音时长超过该阈值时,系统会判定该句子已结束。默认值:1300。取值范围:[200, 6000]。
multi_threshold_mode_enabledbool否是否启用多阈值模式。启用后可防止 VAD 断句切割过长。默认值:False。
punctuation_prediction_enabledbool否设置是否在识别结果中自动添加标点:
  • True(默认):是,不支持修改。
heartbeatbool否是否启用心跳包。默认值:False。
  • True:在持续发送静音音频的情况下,可保持与服务端的连接不中断。
  • False(默认):即使持续发送静音音频,连接也将在一定时间后因超时而断开。
静音音频指的是在音频文件或数据流中没有声音信号的内容。静音音频可以通过多种方法生成,例如使用音频编辑软件如Audacity或Adobe Audition,或者通过命令行工具如FFmpeg。使用该字段时,SDK版本不能低于2.0.1。
language_hintslist[str]否待识别音频语种。无默认值,不设置时模型自动识别。仅支持设置 1 个值,设置多个时仅第一个生效。
  • fun-asr-realtime:
    • zh: 中文
    • en: 英文
    • ja: 日语
    • ko:韩语
    • vi:越南语
    • th:泰语
    • id:印尼语
    • ms:马来语
    • tl:菲律宾语
    • hi:印地语
    • ar:阿拉伯语
    • fr:法语
    • de:德语
    • es:西班牙语
    • pt:葡萄牙语
    • ru:俄语
    • it:意大利语
    • nl:荷兰语
    • sv:瑞典语
    • da:丹麦语
    • fi:芬兰语
    • no:挪威语
    • el:希腊语
    • pl:波兰语
    • cs:捷克语
    • hu:匈牙利语
    • ro:罗马尼亚语
    • bg:保加利亚语
    • hr:克罗地亚语
    • sk:斯洛伐克语
  • fun-asr-realtime-2026-02-28:
    • zh: 中文
    • en: 英文
    • ja: 日语
  • fun-asr-flash-8k-realtime、fun-asr-flash-8k-realtime-2026-01-28:
    • zh: 中文
speech_noise_thresholdfloat否语音与噪音的判定阈值,用于调整语音活动检测(VAD)的灵敏度。取值范围:[-1.0, 1.0]。取值说明:
  • 取值越接近 -1:降低噪音判定阈值,噪音被识别为语音的概率增大,可能导致更多噪音被转写
  • 取值越接近 +1:提高噪音判定阈值,语音被误判为噪音的概率增大,可能导致部分语音被过滤
此参数为高级配置参数,调整可能显著影响识别效果,建议:
  • 调整前充分测试验证效果
  • 根据实际音频环境小幅度调整(建议步长 0.1)
special_word_filterstr否指定在语音识别过程中需要处理的敏感词,并支持对不同敏感词设置不同的处理方式。详情请参见敏感词过滤。
使用 recognize 创建识别会话时,通过 input 传入上下文。
参数类型是否必须说明
inputdict否输入对象,用于传入对话上下文(context)。上下文用于辅助识别、提升专有词汇的识别准确率。使用方法详见提升识别准确率。
仅 fun-asr-realtime 模型支持 context 参数。
dict 中需包含 context 键,值为消息列表(list[dict]),每条消息包含以下字段:
  • role(str,必选):消息角色。user 表示前几轮用户语音的识别结果或领域相关的词表;assistant 表示前几轮大语言模型的回复内容。
  • content(list[dict],必选):消息内容列表。每个元素包含 type(str,role 为 user 时填 input_text,role 为 assistant 时填 text)和 text(str,文本内容)。
上下文消息(input_text 和 text 类型)各最多 5 条,超出时保留最近的 5 条。每轮上下文文本总长度不超过 400 个字符,超出部分从末尾截断。
携带上下文时,context 中的消息顺序有要求:上下文消息必须按对话轮次排列,每轮中 user(input_text 类型)必须在对应的 assistant(text 类型)之前。
使用该字段时,SDK版本不能低于2.0.1。
# 构建 input 传入数据
input_context = {
    "context": [
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "你好啊"
                }
            ]
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "你好啊,我是通义千问,有什么可以帮助你的?"
                }
            ]
        }
    ]
}

# 创建识别会话时通过 input 参数传入
recognition = client.audio.asr.recognize(
    model='fun-asr-realtime',
    format='wav',
    sample_rate=16000,
    input=input_context,
)

接口参考

核心资源(client.audio.asr)

实时语音识别能力挂载在client.audio.asr资源上:recognize创建双向流式识别会话(Recognition),recognize_file对本地文件一次性识别。
成员方法方法签名说明
recognize
def recognize(self,
              *,
              model: str,
              format: str = "pcm",
              sample_rate: int = 16000,
              vocabulary_id: str = None,
              disfluency_removal_enabled: bool = None,
              diarization_enabled: bool = None,
              parameters: Dict = None,
              input: Dict = None,
              phrase_id: str = None,
              ...) -> Recognition
创建双向流式识别会话,进入with上下文时自动调用start建立连接并发送任务。发送音频与消费事件需并发进行(配合send_audio_frame、events()/results()和stop使用)。
recognize_file
def recognize_file(self,
                   path: str,
                   *,
                   model: str,
                   format: str = "pcm",
                   sample_rate: int = 16000,
                   ...) -> Iterator[Dict]
基于本地文件的非流式调用:自动分块发送音频并驱动到任务结束,逐个产出服务端事件。该方法要求所识别文件具有可读权限。
start
def start(self)
开始语音识别:建立连接、发送任务并等待task-started。进入with上下文时自动调用,启动成功后才能发送音频。
send_audio_frame
def send_audio_frame(self, buffer: bytes)
推送音频。每次推送的音频流不宜过大或过小,建议每包音频时长为100ms左右,大小在1KB~16KB之间。识别结果通过事件迭代(events()/results())获取。
stop
def stop(self)
停止语音识别:只通知服务端输入结束,接收线程需继续消费events()直到task-finished事件。
events / results
def events(self) -> Iterator[Dict]
def results(self) -> Iterator[RecognitionResult]
迭代服务端事件:events()产出原始事件dict(识别文本位于payload.output.sentence);results()只产出识别结果帧,返回识别结果(RecognitionResult)类型化对象(心跳帧已过滤)。
close
def close(self)
关闭识别会话。退出with上下文时自动调用。
request_id / first_package_delay / last_package_delay / last_response
rec.request_id
rec.first_package_delay
rec.last_package_delay
rec.last_response
获取request_id、首包延迟(从发送第一包音频到收到首包识别结果延迟)和尾包延迟(发送stop指令到最后一包识别结果下发耗时),在任务完成后使用;last_response为最近一次成功读取的原始报文,可用于获取task-failed报错。会话关闭后仍可读取。

事件迭代(events()/results())

双向流式调用时,服务端会通过事件的方式,将关键流程信息和数据返回给客户端。您需要在接收线程中迭代会话的events()(原始事件dict)或results()(类型化识别结果帧),处理服务端返回的信息或者数据。
# 迭代原始事件:识别文本位于 payload.output.sentence
def receive_events(rec):
    for event in rec.events():
        payload = event.get('payload') or {}
        sentence = (payload.get('output') or {}).get('sentence') or {}
        if sentence.get('text') and not sentence.get('heartbeat'):
            print('识别文本:', sentence['text'])


# 或只迭代识别结果帧(返回 RecognitionResult,心跳帧已过滤)
def receive_results(rec):
    for result in rec.results():
        sentence = result.get_sentence()
        if sentence and 'text' in sentence:
            print('识别文本:', sentence['text'])
事件/迭代方法产出内容返回值描述
event["header"]["event"] == "task-started"
task-started事件无由start()内部读取,启动返回时保存在last_response中,不会由events()再次产出。
def events(self) -> Iterator[Dict]
event:服务端事件dict迭代器当服务有回复时产出事件。识别结果位于payload.output.sentence,可能为心跳或空文本事件,应用可按需忽略。请由一个接收线程持续消费,不要并发创建多个读取者。
def results(self) -> Iterator[RecognitionResult]
result:识别结果(RecognitionResult)迭代器只产出识别结果帧(心跳帧已过滤),全部识别结果返回后迭代结束。
try:
    ...
except DashScopeError as e:
    print(e.code, e.message, e.request_id)
DashScopeError异常无发生异常时在发送/接收线程中抛出,可使用try/except捕获。
event["header"]["event"] == "task-finished"
task-finished事件无当服务已经完成全部识别后由events()产出,随后迭代结束;发送stop()后仍须读取此事件。

Streaming 与 Fun-ASR 的响应结果

识别结果(RecognitionResult)

RecognitionResult代表会话results()迭代产出的一次识别结果帧(双向流式调用与非流式调用均可使用;events()产出的是原始事件dict,如需该类型化视图请改用results())。
成员方法方法签名说明
get_sentence
def get_sentence(self) -> Union[Dict[str, Any], List[Any]]
获取当前识别的句子及时间戳信息,此方法返回类型为Dict[str, Any](单句信息)。详情请参见单句信息(Sentence)。
request_id
result.request_id
当前事件对应的请求request_id。
is_sentence_end
def is_sentence_end(self) -> bool
判断当前句子是否已经结束。该方法通过检查 get_sentence() 返回的单句信息中 end_time 字段是否为 None 来判定——end_time 不为 None 时表示句子已结束。

单句信息(Sentence)

Sentence类成员如下:
参数类型说明
begin_timeint句子开始时间,单位为ms。
end_timeint句子结束时间,单位为ms。
textstr识别文本。
words字时间戳信息(Word)的list集合字时间戳信息。

字时间戳信息(Word)

Word类成员如下:
参数类型说明
begin_timeint字开始时间,单位为ms。
end_timeint字结束时间,单位为ms。
textstr字。
punctuationstr标点。

Qwen-Audio-ASR-Message

更新对话上下文

调用 update_context 在识别任务运行过程中更新对话上下文,用于辅助后续音频的识别。该方法要求 DashScope Python SDK 2.0.1 及以上版本。
def update_context(self, context: dict)
  • 调用时机:进入with上下文(自动调用start)启动流式识别后、调用 stop 前。
  • 参数:context 为字典,传入 continue-task 事件的 payload.input 对象,包含 context 字段,不要额外包装 payload 或 input 层级。
  • 支持范围与参数约束:请参见 continue-task。
以下示例复用已启动的 recognition 实例。
payload_input = {
    "context": [
        {
            "role": "user",
            "content": [{"type": "input_text", "text": "你好啊"}]
        },
        {
            "role": "assistant",
            "content": [{"type": "text", "text": "你好啊,我是通义千问,有什么可以帮助你的?"}]
        }
    ]
}
recognition.update_context(context=payload_input)

响应结果

识别结果(RecognitionResult)
RecognitionResult代表会话results()迭代产出的一次识别结果帧(双向流式调用与非流式调用均可使用;events()产出的是原始事件dict,如需该类型化视图请改用results())。
成员方法方法签名说明
get_sentence
def get_sentence(self) -> Union[Dict[str, Any], List[Any]]

获取当前识别的句子及时间戳信息,此方法返回类型为Dict[str, Any](单句信息)。

详情请参见单句信息(Sentence)。
request_id
result.request_id
当前事件对应的请求request_id。
is_sentence_end
def is_sentence_end(self) -> bool
判断当前句子是否已经结束。该方法通过检查 get_sentence() 返回的单句信息中 end_time 字段是否为 None 来判定——end_time 不为 None 时表示句子已结束。
单句信息(Sentence)
Sentence类成员如下:
参数类型说明
begin_timeint句子开始时间,单位为ms。
end_timeint句子结束时间,单位为ms。
textstr识别文本。
words字时间戳信息(Word)的list集合字时间戳信息。
字时间戳信息(Word)
Word类成员如下:
参数类型说明
begin_timeint字开始时间,单位为ms。
end_timeint字结束时间,单位为ms。
textstr字。
punctuationstr标点。

错误码

如遇报错问题,请参见错误码进行排查。 若问题仍未解决,可加入语音 SDK 示例仓库中列出的开发者群反馈问题,并提供Request ID,以便进一步排查问题。