本文介绍Paraformer实时语音识别Python SDK的参数和接口细节。
用户指南: 关于模型介绍和选型建议,请参见实时语音识别。
模型体验: 仅 paraformer-realtime-v2、paraformer-realtime-8k-v2 支持,可前往千问云体验。
paraformer-realtime-v2 支持的中文方言:上海话、吴语、闽南语、东北话、甘肃话、贵州话、河南话、湖北话、湖南话、江西话、宁夏话、山西话、陕西话、山东话、四川话、天津话、云南话、粤语。
Paraformer Python SDK 提供非流式调用和双向流式调用两种接口。请根据实际需求选择合适的调用方式:
提交单个语音实时转写任务,通过传入本地文件的方式同步阻塞地拿到转写结果。
实例化 Recognition类 绑定请求参数,调用
提交单个语音实时转写任务,通过实现回调接口的方式流式输出实时识别结果。
步骤:
在Python中,由于存在全局解释器锁,同一时刻只有一个线程可以执行Python代码(虽然某些性能导向的库可能会去除此限制)。如果您想更好地利用多核心计算机的计算资源,推荐使用 multiprocessing 或 concurrent.futures.ProcessPoolExecutor。多线程在较高并发下会显著增加SDK调用延迟。
请求参数通过 Recognition类 的构造方法(
在双向流式调用中,通过实现
如遇报错问题,请参见错误信息进行排查。
若问题仍未解决,请加入开发者群反馈遇到的问题,并提供Request ID,以便进一步排查问题。
更多示例,请参见 GitHub。
前提条件
-
已开通服务并获取API Key。请配置API Key到环境变量,而非硬编码在代码中,防范因代码泄露导致的安全风险。
当您需要为第三方应用或用户提供临时访问权限,或者希望严格控制敏感数据访问、删除等高风险操作时,建议使用临时鉴权Token。与长期有效的 API Key 相比,临时鉴权 Token 具备时效性短(60秒)、安全性高的特点,适用于临时调用场景,能有效降低API Key泄露的风险。使用方式:在代码中,将原本用于鉴权的 API Key 替换为获取到的临时鉴权 Token 即可。
- 安装最新版DashScope SDK。
模型列表
| paraformer-realtime-v2(推荐) | paraformer-realtime-8k-v2(推荐) | paraformer-realtime-v1 | paraformer-realtime-8k-v1 | |
|---|---|---|---|---|
| 适用场景 | 直播、会议等场景 | 电话客服、语音信箱等 8kHz 音频的识别场景 | 直播、会议等场景 | 电话客服、语音信箱等 8kHz 音频的识别场景 |
| 采样率 | 任意 | 8kHz | 16kHz | 8kHz |
| 语种 | 中文(含普通话及方言)、英文、日语、韩语、德语、法语、俄语 | 中文 | 中文 | 中文 |
| 标点符号预测 | 默认支持,无需配置 | 默认支持,无需配置 | 默认支持,无需配置 | 默认支持,无需配置 |
| 逆文本正则化(ITN) | 默认支持,无需配置 | 默认支持,无需配置 | 默认支持,无需配置 | 默认支持,无需配置 |
| 定制热词 | 支持(通过 vocabulary_id,参见定制热词) | 支持(通过 vocabulary_id,参见定制热词) | 支持(通过 phrase_id,参见Paraformer语音识别热词定制与管理) | 支持(通过 phrase_id,参见Paraformer语音识别热词定制与管理) |
| 指定待识别语种 | 支持(通过 language_hints 参数指定) | 不支持 | 不支持 | 不支持 |
| 情感识别 | 不支持 | 支持(须关闭语义断句,通过 emo_tag 和 emo_confidence 字段获取) | 不支持 | 不支持 |
快速开始
Paraformer Python SDK 提供非流式调用和双向流式调用两种接口。请根据实际需求选择合适的调用方式:
- 非流式调用: 针对本地文件进行识别,并一次性返回完整的处理结果。适合处理录制好的音频。
- 双向流式调用: 可直接对音频流进行识别,并实时输出结果。音频流可以来自外部设备(如麦克风)或从本地文件读取。适合需要即时反馈的场景。
非流式调用
提交单个语音实时转写任务,通过传入本地文件的方式同步阻塞地拿到转写结果。
实例化 Recognition类 绑定请求参数,调用 call 进行识别并最终获取识别结果(RecognitionResult)。
示例中用到的音频为:asr_example.wav。
双向流式调用
提交单个语音实时转写任务,通过实现回调接口的方式流式输出实时识别结果。
步骤:
-
启动流式语音识别 — 实例化 Recognition类 绑定请求参数和回调接口(RecognitionCallback),调用
start方法启动流式语音识别。 -
流式传输 — 循环调用 Recognition类 的
send_audio_frame方法,将从本地文件或设备(如麦克风)读取的二进制音频流分段发送至服务端。在发送音频数据的过程中,服务端会通过回调接口(RecognitionCallback)的on_event方法,将识别结果实时返回给客户端。建议每次发送的音频时长约为100毫秒,数据大小保持在1KB至16KB之间。 -
结束处理 — 调用 Recognition类 的
stop方法结束语音识别。该方法会阻塞当前线程,直到回调接口(RecognitionCallback)的on_complete或者on_error回调触发后才会释放线程阻塞。
并发调用
在Python中,由于存在全局解释器锁,同一时刻只有一个线程可以执行Python代码(虽然某些性能导向的库可能会去除此限制)。如果您想更好地利用多核心计算机的计算资源,推荐使用 multiprocessing 或 concurrent.futures.ProcessPoolExecutor。多线程在较高并发下会显著增加SDK调用延迟。
请求参数
请求参数通过 Recognition类 的构造方法(__init__)进行设置。
| 参数 | 类型 | 默认值 | 是否必须 | 说明 |
|---|---|---|---|---|
model | str | - | 是 | 用于实时语音识别的模型(参见模型列表)。 |
sample_rate | int | - | 是 | 设置待识别音频采样率(单位Hz)。因模型而异:paraformer-realtime-v2 支持任意采样率;paraformer-realtime-v1 仅支持16000Hz;paraformer-realtime-8k-v2 和 paraformer-realtime-8k-v1 仅支持8000Hz。 |
format | str | - | 是 | 设置待识别音频格式。支持:pcm、wav、mp3、opus、speex、aac、amr。注意:opus/speex 必须使用Ogg封装;wav 必须为PCM编码;amr 仅支持AMR-NB类型。 |
vocabulary_id | str | - | 否 | 热词ID,适用于 paraformer-realtime-v2 和 paraformer-realtime-8k-v2(参见定制热词)。 |
phrase_id | str | - | 否 | 热词ID,适用于 paraformer-realtime-v1 和 paraformer-realtime-8k-v1(参见Paraformer语音识别热词定制与管理)。 |
disfluency_removal_enabled | bool | False | 否 | 是否过滤语气词(如"嗯"、"啊"等)。 |
language_hints | list[str] | ["zh","en"] | 否 | 语言代码列表,指定待识别语种,仅 paraformer-realtime-v2 支持。 |
semantic_punctuation_enabled | bool | False | 否 | 是否开启语义断句。仅 paraformer-realtime-v2 及以上版本支持。 |
max_sentence_silence | int | 800 | 否 | VAD断句静音阈值(单位ms),范围200-6000。仅 paraformer-realtime-v2 及以上版本且使用VAD断句时有效。 |
multi_threshold_mode_enabled | bool | False | 否 | 是否启用多阈值模式,防止VAD断句将过长的句子切断。仅 paraformer-realtime-v2 及以上版本且使用VAD断句时有效。 |
punctuation_prediction_enabled | bool | True | 否 | 是否自动添加标点符号。仅 paraformer-realtime-v2 及以上版本支持。 |
heartbeat | bool | False | 否 | 是否开启长连接保持。仅 paraformer-realtime-v2 及以上版本支持,需SDK版本≥1.23.1。 |
inverse_text_normalization_enabled | bool | True | 否 | 是否开启逆文本正则化(ITN)。仅 paraformer-realtime-v2 及以上版本支持。 |
callback | RecognitionCallback | - | 否 | 回调接口,用于双向流式调用(参见回调接口(RecognitionCallback))。 |
关键接口
Recognition类
| 方法签名 | 说明 |
|---|---|
call(self, file: str, phrase_id: str = None, **kwargs) -> RecognitionResult | 非流式调用:传入本地音频文件路径,同步阻塞地返回完整识别结果。 |
start(self, phrase_id: str = None, **kwargs) | 启动双向流式语音识别。 |
send_audio_frame(self, buffer: bytes) | 向服务端发送音频二进制数据帧(双向流式调用)。 |
stop(self) | 结束语音识别,阻塞直到 on_complete 或 on_error 回调触发。 |
get_last_request_id(self) | 获取最近一次请求的 Request ID。 |
get_first_package_delay(self) | 获取首包延迟(ms)。 |
get_last_package_delay(self) | 获取尾包延迟(ms)。 |
回调接口 RecognitionCallback
在双向流式调用中,通过实现 RecognitionCallback 接口来接收实时识别结果。
| 方法签名 | 说明 |
|---|---|
on_open(self) -> None | 连接建立时触发。 |
on_event(self, result: RecognitionResult) -> None | 收到识别结果时触发,实时返回当前识别状态。 |
on_complete(self) -> None | 识别完成时触发。 |
on_error(self, result: RecognitionResult) -> None | 发生错误时触发。 |
on_close(self) -> None | 连接关闭时触发。 |
识别结果 RecognitionResult
RecognitionResult
| 方法签名 | 说明 |
|---|---|
get_sentence(self) -> Union[Dict[str, Any], List[Any]] | 获取当前识别结果,返回单个句子字典或句子列表。 |
get_request_id(self) -> str | 获取当前识别结果对应的 Request ID。 |
@staticmethod is_sentence_end(sentence: Dict[str, Any]) -> bool | 判断当前句子是否已结束(句子结束标志)。 |
单句信息 Sentence
| 字段 | 类型 | 说明 |
|---|---|---|
begin_time | int | 句子起始时间(ms)。 |
end_time | int | 句子结束时间(ms)。 |
text | str | 识别文本。 |
words | list[Word] | 词级别识别结果(参见词信息 Word)。 |
emo_tag | str | 情感标签(仅 paraformer-realtime-8k-v2 且句子结束时返回),取值:positive、negative、neutral。 |
emo_confidence | float | 情感置信度(范围 0.0–1.0)。 |
词信息 Word
| 字段 | 类型 | 说明 |
|---|---|---|
begin_time | int | 词起始时间(ms)。 |
end_time | int | 词结束时间(ms)。 |
text | str | 词文本。 |
punctuation | str | 词后跟随的标点符号。 |
错误码
如遇报错问题,请参见错误信息进行排查。
若问题仍未解决,请加入开发者群反馈遇到的问题,并提供Request ID,以便进一步排查问题。
更多示例
更多示例,请参见 GitHub。
常见问题
功能特性
Q:在长时间静默的情况下,如何保持与服务端长连接?
Q:在长时间静默的情况下,如何保持与服务端长连接?
将请求参数
heartbeat 设置为 true,并持续向服务端发送静音音频。静音音频指的是在音频文件或数据流中没有声音信号的内容。静音音频可以通过多种方法生成,例如使用音频编辑软件如 Audacity 或 Adobe Audition,或者通过命令行工具如 FFmpeg。Q:如何将音频格式转换为满足要求的格式?
Q:如何将音频格式转换为满足要求的格式?
可使用 FFmpeg工具,更多用法请参见FFmpeg官网。
Q:是否支持查看每句话对应的时间范围?
Q:是否支持查看每句话对应的时间范围?
支持。语音识别结果中会包含每句话的开始时间戳和结束时间戳,可通过它们确定每句话的时间范围。详见单句信息(Sentence)中的
begin_time 和 end_time 字段。Q:如何识别本地文件(录音文件)?
Q:如何识别本地文件(录音文件)?
识别本地文件有两种方式:
-
直接传入本地文件路径: 此种方式在最终识别结束后获取完整识别结果,不适合即时反馈的场景。参见非流式调用,在 Recognition类 的
call方法中传入文件路径对录音文件直接进行识别。 -
将本地文件转成二进制流进行识别: 此种方式一边识别文件一边流式获取识别结果,适合即时反馈的场景。参见双向流式调用,通过 Recognition类 的
send_audio_frame方法向服务端发送二进制流对其进行识别。
故障排查
Q:无法识别语音(无识别结果)是什么原因?
Q:无法识别语音(无识别结果)是什么原因?
-
请检查请求参数中的音频格式(
format)和采样率(sample_rate)设置是否正确且符合参数约束。以下为常见错误示例:- 音频文件扩展名为 .wav,但实际为 MP3 格式,而请求参数
format设置为mp3(参数设置错误)。 - 音频采样率为 3600Hz,但请求参数
sample_rate设置为 48000(参数设置错误)。
- 音频文件扩展名为 .wav,但实际为 MP3 格式,而请求参数
-
使用
paraformer-realtime-v2模型时,请检查language_hints设置的语言是否与音频实际语言一致。例如:音频实际为中文,但language_hints设置为en(英文)。 - 若以上检查均无问题,可通过定制热词提升对特定词语的识别效果。
Paraformer 实时语音识别 WebSocket API
通过 WebSocket 连接使用 Paraformer 实时语音识别服务的完整 API 参考。

