本文介绍Paraformer实时语音识别Python SDK的参数和接口细节。
前提条件
模型列表
| paraformer-realtime-v2 | paraformer-realtime-8k-v2 | |
|---|---|---|
| 适用场景 | 直播、会议等场景 | 电话客服、语音信箱等 8kHz 音频的识别场景 |
| 采样率 | 任意 | 8kHz |
| 语种 | 中文(包含中文普通话和各种方言)、英文、日语、韩语、德语、法语、俄语支持的中文方言:上海话、吴语、闽南语、东北话、甘肃话、贵州话、河南话、湖北话、湖南话、江西话、宁夏话、山西话、陕西话、山东话、四川话、天津话、云南话、粤语 | 中文 |
| 标点符号预测 | 默认支持,无需配置 | 默认支持,无需配置 |
| 逆文本正则化(ITN) | 默认支持,无需配置 | 默认支持,无需配置 |
| 定制热词 | 参见定制热词 | 参见定制热词 |
| 指定待识别语种 | 通过language_hints参数指定 | 不支持 |
| 情感识别 | 不支持 |
点击查看使用方式 情感识别遵循如下约束:
emo_tag和emo_confidence字段分别获取当前句子的情感和情感置信度。 |
快速开始
核心资源(client.audio.asr)提供了非流式调用和双向流式调用接口。请根据实际需求选择合适的调用方式:
- 非流式调用(
recognize_file):针对本地文件进行识别,SDK自动分块发送音频并驱动到任务结束。适合处理录制好的音频。 - 双向流式调用:可直接对音频流进行识别,并实时输出结果。音频流可以来自外部设备(如麦克风)或从本地文件读取。适合需要即时反馈的场景。
非流式调用
提交单个语音实时转写任务,通过传入本地文件的方式同步阻塞地拿到转写结果。
client.audio.asr)的recognize_file方法绑定请求参数并传入本地文件路径,迭代服务端事件获取识别结果(RecognitionResult)。
点击查看完整示例
点击查看完整示例
recognize_file逐个产出服务端事件(Dict[str, Any]):事件类型位于event['header']['event'],识别文本位于event['payload']['output']['sentence'](sentence_end为true表示该句已结束,begin_time / end_time为时间戳、words为字时间戳等字段见单句信息(Sentence))。心跳与空文本事件仍会产出,可按需忽略。双向流式会话中除events()外,还可通过results()只迭代识别结果帧(返回类型化的识别结果(RecognitionResult),心跳帧已过滤),详见get_sentence方法说明。双向流式调用
提交单个语音实时转写任务,通过迭代事件的方式流式输出实时识别结果。
-
启动流式语音识别
调用核心资源(
client.audio.asr)的recognize方法创建识别会话并绑定请求参数,进入with上下文(自动调用start方法建立连接并发送任务)启动流式语音识别。 -
流式传输
循环调用会话的
send_audio_frame方法,将从本地文件或设备(如麦克风)读取的二进制音频流分段发送至服务端。发送与接收需并发进行:接收线程通过事件迭代(events()/results())迭代服务端事件,将识别结果实时返回给客户端。 建议每次发送的音频时长约为100毫秒,数据大小保持在1KB至16KB之间。 -
结束处理
调用会话的
stop方法结束语音识别。 该方法只通知服务端输入结束;接收线程需继续消费events()直到task-finished事件以获得最后的识别结果和统计信息。ws层的错误会以DashScopeError异常抛出,可在发送/接收处使用try/except捕获。
点击查看完整示例
点击查看完整示例
并发调用
在Python中,由于存在全局解释器锁,同一时刻只有一个线程可以执行Python代码(虽然某些性能导向的库可能会去除此限制)。如果您想更好地利用多核心计算机的计算资源,推荐您使用multiprocessing或concurrent.futures.ProcessPoolExecutor。 多线程在较高并发下会显著增加SDK调用延迟。
请求参数
请求参数通过核心资源(client.audio.asr)的recognize/recognize_file方法进行设置:model、format、sample_rate、vocabulary_id、disfluency_removal_enabled为具名参数,其余参数(如language_hints、semantic_punctuation_enabled)通过parameters字典传入。
参数 | 类型 | 默认值 | 是否必须 | 说明 |
|---|---|---|---|---|
model | str | - | 是 | 用于实时语音识别的模型(参见模型列表)。 |
sample_rate | int | - | 是 | 设置待识别音频采样率(单位Hz)。 因模型而异:
|
format | str | - | 是 | 设置待识别音频格式。 支持的音频格式:pcm、wav、mp3、opus、speex、aac、amr。 opus/speex:必须使用Ogg封装; wav:必须为PCM编码; amr:仅支持AMR-NB类型。 |
vocabulary_id | str | - | 否 | 设置热词ID,若未设置则不生效。v2及更高版本模型设置热词ID时使用该字段。 在本次语音识别中,将应用与该热词ID对应的热词信息。具体使用方法请参见定制热词。 |
disfluency_removal_enabled | bool | False | 否 | 设置是否过滤语气词:
|
language_hints | list[str] | ["zh", "en"] | 否 | 设置待识别语言代码。如果无法提前确定语种,可不设置,模型会自动识别语种。 目前支持的语言代码:
该参数仅对支持多语言的模型生效(参见模型列表)。 |
semantic_punctuation_enabled | bool | False | 否 | 设置是否开启语义断句,默认关闭。
语义断句准确性更高,适合会议转写场景;VAD(Voice Activity Detection,语音活动检测)断句延迟较低,适合交互场景。 通过调整 该参数仅在模型为v2及更高版本时生效。 |
max_sentence_silence | int | 800 | 否 | 设置VAD(Voice Activity Detection,语音活动检测)断句的静音时长阈值(单位为ms)。 当一段语音后的静音时长超过该阈值时,系统会判定该句子已结束。 参数范围为200ms至6000ms,默认值为800ms。 该参数仅在 |
multi_threshold_mode_enabled | bool | False | 否 | 该开关打开时(true)可以防止VAD断句切割过长。默认关闭。 该参数仅在 |
punctuation_prediction_enabled | bool | True | 否 | 设置是否在识别结果中自动添加标点:
该参数仅在模型为v2及更高版本时生效。 |
heartbeat | bool | False | 否 | 当需要与服务端保持长连接时,可通过该开关进行控制:
该参数仅在模型为v2及更高版本时生效。 该字段自 SDK 1.23.1 引入,2.0.1 及以上版本已包含。 |
inverse_text_normalization_enabled | bool | True | 否 | 设置是否开启ITN(Inverse Text Normalization,逆文本正则化)。 默认开启(true)。开启后,中文数字将转换为阿拉伯数字。 该参数仅在模型为v2及更高版本时生效。 |
接口参考
核心资源(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 | 获取request_id、首包延迟(从发送第一包音频到收到首包识别结果延迟)和尾包延迟(发送stop指令到最后一包识别结果下发耗时)。在任务完成后使用,会话关闭后仍可读取。 |
事件迭代(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 | 判断当前句子是否已经结束(句子携带end_time时为True)。 |
单句信息(Sentence)
Sentence类成员如下:
参数 | 类型 | 说明 |
|---|---|---|
begin_time | int | 句子开始时间,单位为ms。 |
end_time | int | 句子结束时间,单位为ms。 |
text | str | 识别文本。 |
words | 字时间戳信息(Word)的list集合 | 字时间戳信息。 |
emo_tag | str | 当前句子的情感:
情感识别遵循如下约束:
|
emo_confidence | float | 当前句子识别情感的置信度,取值范围:[0.0,1.0]。值越大表示置信度越高。 情感识别遵循如下约束:
|
字时间戳信息(Word)
Word类成员如下:
参数 | 类型 | 说明 |
|---|---|---|
begin_time | int | 字开始时间,单位为ms。 |
end_time | int | 字结束时间,单位为ms。 |
text | str | 字。 |
punctuation | str | 标点。 |