实时语音识别 Python SDK
使用指南: 模型选择请参见实时语音识别。
Recognition 类支持非流式和双向流式两种调用方式。
提交单个音频文件的语音识别任务,阻塞等待直到返回结果。
实例化 Recognition 类,设置请求参数,调用
提交语音识别任务,通过回调接收结果。
在 Recognition 类的构造函数(
通过
在双向流式调用中,服务端通过回调返回数据。实现回调接口以处理响应。
快速开始
Recognition 类支持非流式和双向流式两种调用方式。
- 非流式调用: 识别本地文件,一次性返回完整结果。
- 双向流式调用: 识别音频流并实时返回结果。音频流可来自麦克风或本地文件。
非流式调用
提交单个音频文件的语音识别任务,阻塞等待直到返回结果。
实例化 Recognition 类,设置请求参数,调用 call 获取识别结果 (RecognitionResult)。
点击查看完整示例
点击查看完整示例
示例使用的音频文件:asr_example.wav。
双向流式调用
提交语音识别任务,通过回调接收结果。
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。支持 16000 Hz。 |
| format | str | - | 是 | 音频格式:pcm、wav、mp3、opus、speex、aac、amr。 注意: opus/speex 必须使用 Ogg 封装。wav 必须使用 PCM 编码。amr 仅支持 AMR-NB。 |
| vocabulary_id | str | - | 否 | 热词表 ID,用于热词定制。参见自定义热词。 |
| semantic_punctuation_enabled | bool | False | 否 | 是否启用语义标点。
|
| max_sentence_silence | int | 1300 | 否 | VAD 断句的静音阈值,单位 ms。静音超过该值则断句。范围:200-6000 ms。仅在 semantic_punctuation_enabled 为 false 时生效。 |
| 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]。
|
| callback | RecognitionCallback | - | 否 | RecognitionCallback 回调接口。 |
核心接口
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 | 标点符号。 |

