Qwen-Audio-3.0-ASR-Flash-Streaming/Fun-ASR-Realtime 实时语音识别 Python SDK
使用指南: 模型选择请参见实时语音识别。
Recognition 类支持非流式和双向流式两种调用方式。
提交单个音频文件的语音识别任务,阻塞等待直到返回结果。
实例化 Recognition 类,设置请求参数,调用
提交语音识别任务,通过回调接收结果。
在 Recognition 类的构造函数(
即时热词示例:
敏感词过滤可对识别结果中的敏感词执行替换或移除,适用于客服质检、内容合规、字幕审核等场景。仅 Fun-ASR 支持,最多支持设置 32 个敏感词。未传入
以下参数通过
通过
在双向流式调用中,服务端通过回调返回数据。实现回调接口以处理响应。
快速开始
Recognition 类支持非流式和双向流式两种调用方式。
- 非流式调用: 识别本地文件,一次性返回完整结果。
- 双向流式调用: 识别音频流并实时返回结果。音频流可来自麦克风或本地文件。
非流式调用
提交单个音频文件的语音识别任务,阻塞等待直到返回结果。
实例化 Recognition 类,设置请求参数,调用 call 获取识别结果 (RecognitionResult)。
点击查看完整示例
点击查看完整示例
双向流式调用
提交语音识别任务,通过回调接收结果。
1
启动流式识别
实例化 Recognition 类,配置请求参数和回调接口 (RecognitionCallback),调用
start。2
发送音频
反复调用
send_audio_frame 发送来自本地文件或设备(如麦克风)的二进制音频数据。服务端通过 on_event 回调实时返回结果。每段音频约 100 ms,大小 1-16 KB。3
停止识别
调用
stop 结束识别。该方法会阻塞等待,直到触发 on_complete 或 on_error。点击查看完整示例
点击查看完整示例
- 识别麦克风语音
- 识别本地音频文件
请求参数
在 Recognition 类的构造函数(__init__)中设置请求参数。
| 参数 | 类型 | 默认值 | 是否必选 | 说明 |
|---|---|---|---|---|
| model | str | - | 是 | 用于实时语音识别的支持的模型。 |
| sample_rate | int | - | 是 | 音频采样率,单位 Hz。8k 模型仅支持 8000 Hz,其他模型支持任意采样率。 |
| format | str | - | 是 | 音频格式:pcm、wav、mp3、opus、speex、aac、amr。 注意: opus/speex 必须使用 Ogg 封装。wav 必须使用 PCM 编码。amr 仅支持 AMR-NB。 |
| vocabulary_id | str | - | 否 | 热词表 ID,用于热词定制。参见自定义热词。 |
| vocabulary | dict | - | 否 | 即时热词。以键值对形式传入,键为热词文本(string),值为热词权重(integer),无需预先创建热词列表。权重取值范围为 [1, 5] 或 50:取 [1, 5] 时值越大模型越倾向输出该词;取 50 时为超级热词,召回率大幅提升,但超级热词数量最多不超过 50 个。适用于临时性、会话级别的热词优化。与预编译热词同时配置时,仅即时热词生效。使用方法请参见即时热词。仅 qwen-audio-3.0-asr-flash-streaming 支持。 |
| semantic_punctuation_enabled | bool | False | 否 | 是否启用语义标点。
|
| max_sentence_silence | int | 1300 | 否 | VAD 断句静音阈值,单位 ms。静音超过该值则断句。当 semantic_punctuation_enabled 为 true 时,该参数不作为返回 sentence_end 的判定依据,但设置过低可能影响识别效果。取值范围:[200, 6000]。 |
| multi_threshold_mode_enabled | bool | False | 否 | 防止 VAD 产生过长的分段。仅在 semantic_punctuation_enabled 为 false 时生效。 |
| punctuation_prediction_enabled | bool | True | 否 | 自动为识别结果添加标点。此参数固定为 true,无法通过 SDK 覆盖;识别结果始终包含自动标点。 |
| heartbeat | bool | False | 否 | 保持服务端持久连接:
|
| language_hints | list[str] | ["zh", "en"] | 否 | 识别的语言代码。不设置时自动检测。支持的语言代码:
|
| speech_noise_threshold | float | - | 否 | 语音噪声检测阈值,用于调节 VAD 灵敏度。范围:[-1.0, 1.0]。
|
| special_word_filter | str | - | 否 | 敏感词过滤配置,仅 Fun-ASR 支持。最多支持设置 32 个敏感词。参见敏感词过滤。 |
| callback | RecognitionCallback | - | 否 | RecognitionCallback 回调接口。 |
敏感词过滤
敏感词过滤可对识别结果中的敏感词执行替换或移除,适用于客服质检、内容合规、字幕审核等场景。仅 Fun-ASR 支持,最多支持设置 32 个敏感词。未传入 special_word_filter 参数时,不会对敏感词进行过滤。
special_word_filter 为 JSON 字符串,包含三个子字段:
filter_with_signed.word_list:字符串数组,列出需要被替换为等长*的敏感词。例如["测试"],"帮我测试一下"会变成"帮我**一下"。filter_with_empty.word_list:字符串数组,列出需要从结果中完全移除的敏感词。例如["开始"],"比赛这就要开始了吗"会变成"比赛这就要了吗"。system_reserved_filter:布尔值,默认false。是否启用敏感词过滤功能。
运行时参数
以下参数通过 Recognition 实例的 call 或 start 方法的关键字参数传入。
| 参数 | 类型 | 默认值 | 是否必选 | 说明 |
|---|---|---|---|---|
| raw_input | dict | - | 否 | 输入对象,用于传入对话上下文(context)。上下文用于辅助识别、提升专有词汇的识别准确率。使用方法详见提升识别准确率。仅 fun-asr-realtime 和 fun-asr-realtime-2025-11-07 模型支持。 |
- 上下文消息(
input_text和text类型)各最多 5 条,超出时保留最近的 5 条。 - 每轮上下文文本总长度不超过 400 个字符,超出部分从末尾截断。
- 上下文消息必须按对话轮次排列,每轮中
user(input_text类型)必须在对应的assistant(text类型)之前。
使用
raw_input 参数时,SDK 版本不能低于 1.25.23。raw_input 通过 Recognition 实例的 start 或 call 方法传入:
核心接口
Recognition 类
通过 from dashscope.audio.asr import * 导入。
| 成员方法 | 方法签名 | 说明 |
|---|---|---|
| call | def call(self, file: str, phrase_id: str = None, **kwargs) -> RecognitionResult | 对本地文件执行非流式识别。阻塞等待处理完成后返回 RecognitionResult。 |
| start | def start(self, phrase_id: str = None, **kwargs) | 启动流式识别,非阻塞。需配合 send_audio_frame 和 stop 使用。 |
| send_audio_frame | def send_audio_frame(self, buffer: bytes) | 发送一个音频帧(每包约 100 ms,1-16 KB)。通过 RecognitionCallback 的 on_event 回调获取结果。 |
| stop | def stop(self) | 停止识别。阻塞等待直到所有音频处理完成。 |
| get_last_request_id | def get_last_request_id(self) | 返回请求 ID。Recognition 对象创建后即可调用。 |
| get_first_package_delay | def get_first_package_delay(self) | 返回首包延迟(从发送第一个音频包到收到第一个结果的时间)。任务完成后可用。 |
| get_last_package_delay | def get_last_package_delay(self) | 返回尾包延迟(从调用 stop 到收到最终结果的时间)。任务完成后可用。 |
回调接口 (RecognitionCallback)
在双向流式调用中,服务端通过回调返回数据。实现回调接口以处理响应。
点击查看示例
点击查看示例
| 方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
def on_open(self) -> None | 无 | 无 | 建立服务端连接时调用。 |
def on_event(self, result: RecognitionResult) -> None | result:RecognitionResult | 无 | 返回识别结果时调用。 |
def on_complete(self) -> None | 无 | 无 | 所有结果返回后调用。 |
def on_error(self, result: RecognitionResult) -> None | result:RecognitionResult | 无 | 发生错误时调用。 |
def on_close(self) -> None | 无 | 无 | 连接关闭时调用。 |
响应
识别结果 (RecognitionResult)
RecognitionResult 表示流式调用或非流式调用的识别结果。
| 成员方法 | 方法签名 | 说明 |
|---|---|---|
| get_sentence | def get_sentence(self) -> Union[Dict[str, Any], List[Any]] | 返回当前识别的句子及时间戳。在回调中返回单个句子,类型为 Dict[str, Any]。参见句子信息。 |
| get_request_id | def get_request_id(self) -> str | 返回请求 ID。 |
| get_usage | def get_usage(self, sentence: Dict[str, Any]) -> Dict | 返回该句子的用量信息。 |
| is_sentence_end | @staticmethod def is_sentence_end(sentence: Dict[str, Any]) -> bool | 判断句子是否结束。 |
句子信息 (Sentence)
| 参数 | 类型 | 说明 |
|---|---|---|
| begin_time | int | 句子开始时间,单位 ms。 |
| end_time | int | 句子结束时间,单位 ms。 |
| text | str | 识别文本。 |
| words | Word 对象列表 | 词级时间戳信息。 |
词级时间戳信息 (Word)
| 参数 | 类型 | 说明 |
|---|---|---|
| begin_time | int | 词的开始时间,单位 ms。 |
| end_time | int | 词的结束时间,单位 ms。 |
| text | str | 词文本。 |
| punctuation | str | 标点符号。 |