本文介绍Paraformer实时语音识别Python SDK的参数和接口细节。
前提条件
模型列表
| paraformer-realtime-v2(推荐) | paraformer-realtime-8k-v2(推荐) | paraformer-realtime-v1 | paraformer-realtime-8k-v1 | |
|---|---|---|---|---|
| 适用场景 | 直播、会议等场景 | 电话客服、语音信箱等 8kHz 音频的识别场景 | 直播、会议等场景 | 电话客服、语音信箱等 8kHz 音频的识别场景 |
| 采样率 | 任意 | 8kHz | 16kHz | 8kHz |
| 语种 | 中文(包含中文普通话和各种方言)、英文、日语、韩语、德语、法语、俄语支持的中文方言:上海话、吴语、闽南语、东北话、甘肃话、贵州话、河南话、湖北话、湖南话、江西话、宁夏话、山西话、陕西话、山东话、四川话、天津话、云南话、粤语 | 中文 | 中文 | 中文 |
| 标点符号预测 | ✅ 默认支持,无需配置 | ✅ 默认支持,无需配置 | ✅ 默认支持,无需配置 | ✅ 默认支持,无需配置 |
| 逆文本正则化(ITN) | ✅ 默认支持,无需配置 | ✅ 默认支持,无需配置 | ✅ 默认支持,无需配置 | ✅ 默认支持,无需配置 |
| 定制热词 | ✅ 参见定制热词 | ✅ 参见定制热词 | ✅ 参见Paraformer语音识别热词定制与管理 | ✅ 参见Paraformer语音识别热词定制与管理 |
| 指定待识别语种 | ✅ 通过language_hints参数指定 | ❌ | ❌ | ❌ |
| 情感识别 | ❌ |
✅ (点击查看使用方式) 情感识别遵循如下约束:
emo_tag和emo_confidence字段分别获取当前句子的情感和情感置信度。 | ❌ | ❌ |
快速开始
Recognition类提供了非流式调用和双向流式调用接口。请根据实际需求选择合适的调用方式:
- 非流式调用:针对本地文件进行识别,并一次性返回完整的处理结果。适合处理录制好的音频。
- 双向流式调用:可直接对音频流进行识别,并实时输出结果。音频流可以来自外部设备(如麦克风)或从本地文件读取。适合需要即时反馈的场景。
非流式调用
提交单个语音实时转写任务,通过传入本地文件的方式同步阻塞地拿到转写结果。
call进行识别/翻译并最终获取识别结果(RecognitionResult)。
点击查看完整示例
点击查看完整示例
result.get_sentence()在非流式调用(call)中返回句子列表(List[Dict]),每个元素为Dict[str, Any],包含text(识别文本)、begin_time / end_time(时间戳)、words(字时间戳)等字段。如需获取识别文本,需遍历列表并通过sentence['text']提取。在流式回调(on_event)中,result.get_sentence()返回单句信息(Dict[str, Any]),可直接使用sentence['text']获取识别文本。两种调用模式的返回值类型不同,详见识别结果(RecognitionResult)中的get_sentence方法说明。双向流式调用
提交单个语音实时转写任务,通过实现回调接口的方式流式输出实时识别结果。
-
启动流式语音识别
实例化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)。 因模型而异:
|
format | str | - | 是 | 设置待识别音频格式。 支持的音频格式:pcm、wav、mp3、opus、speex、aac、amr。 opus/speex:必须使用Ogg封装; wav:必须为PCM编码; amr:仅支持AMR-NB类型。 |
vocabulary_id | str | - | 否 | 设置热词ID,若未设置则不生效。v2及更高版本模型设置热词ID时使用该字段。 在本次语音识别中,将应用与该热词ID对应的热词信息。具体使用方法请参见定制热词。 |
phrase_id | str | - | 否 | 设置热词ID,若未设置则不生效。v1系列模型设置热词ID时使用该字段。 在本次语音识别中,将应用与该热词ID对应的热词信息。具体使用方法请参见Paraformer语音识别热词定制与管理。 |
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。 |
inverse_text_normalization_enabled | bool | True | 否 | 设置是否开启ITN(Inverse Text Normalization,逆文本正则化)。 默认开启(true)。开启后,中文数字将转换为阿拉伯数字。 该参数仅在模型为v2及更高版本时生效。 |
callback | RecognitionCallback | - | 否 |
关键接口
Recognition类
Recognition通过“from dashscope.audio.asr import *”方式引入。
| 成员方法 | 方法签名 | 说明 |
|---|---|---|
| call | 基于本地文件的非流式调用,该方法会阻塞当前线程直到全部音频读完,该方法要求所识别文件具有可读权限。识别结果以RecognitionResult类型数据返回。 | |
| start | 开始语音识别。基于回调形式的流式实时识别,该方法不会阻塞当前线程。需要配合send_audio_frame和stop使用。 | |
| send_audio_frame | 推送音频。每次推送的音频流不宜过大或过小,建议每包音频时长为100ms左右,大小在1KB~16KB之间。识别结果通过回调接口(RecognitionCallback)的on_event方法获取。 | |
| stop | 停止语音识别,阻塞到服务将收到的音频都识别后结束任务。 | |
| get_last_request_id | 获取request_id,在构造函数调用(创建对象)后可以使用。 | |
| get_first_package_delay | 获取首包延迟,从发送第一包音频到收到首包识别结果延迟,在任务完成后使用。 | |
| get_last_package_delay | 获得尾包延迟,发送stop指令到最后一包识别结果下发耗时,在任务完成后使用。 |
回调接口(RecognitionCallback)
双向流式调用时,服务端会通过回调的方式,将关键流程信息和数据返回给客户端。您需要实现回调方法,处理服务端返回的信息或者数据。
点击查看示例
点击查看示例
| 方法 | 参数 | 返回值 | 描述 |
|---|---|---|---|
| 无 | 无 | 当和服务端建立连接完成后,该方法立刻被回调。 | |
result:识别结果(RecognitionResult) | 无 | 当服务有回复时会被回调。 | |
| 无 | 无 | 当所有识别结果全部返回后进行回调。 | |
result:识别结果(RecognitionResult) | 无 | 发生异常时该方法被回调。 | |
| 无 | 无 | 当服务已经关闭连接后进行回调。 |
响应结果
识别结果(RecognitionResult)
RecognitionResult代表双向流式调用中一次实时识别或非流式调用的识别结果。
| 成员方法 | 方法签名 | 说明 |
|---|---|---|
| get_sentence | 获取当前识别的句子及时间戳信息。回调中返回的是单句信息,所以此方法返回类型为Dict[str, Any]。详情请参见单句信息(Sentence)。 | |
| get_request_id | 获取请求的request_id。 | |
| is_sentence_end | 判断给定句子是否已经结束。 |
单句信息(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 | 标点。 |
错误码
如遇报错问题,请参见错误码进行排查。
若问题仍未解决,请加入开发者群反馈遇到的问题,并提供Request ID,以便进一步排查问题。
更多示例
更多示例,请参见GitHub。
常见问题
功能特性
Q:在长时间静默的情况下,如何保持与服务端长连接?
将请求参数heartbeat设置为true,并持续向服务端发送静音音频。
静音音频指的是在音频文件或数据流中没有声音信号的内容。静音音频可以通过多种方法生成,例如使用音频编辑软件如Audacity或Adobe Audition,或者通过命令行工具如FFmpeg。
Q:如何将音频格式转换为满足要求的格式?
可使用FFmpeg工具,更多用法请参见FFmpeg官网。
Q:是否支持查看每句话对应的时间范围?
支持。语音识别结果中会包含每句话的开始时间戳和结束时间戳,可通过它们确定每句话的时间范围。Q:如何识别本地文件(录音文件)?
识别本地文件有两种方式:
-
直接传入本地文件路径:此种方式在最终识别结束后获取完整识别结果,不适合即时反馈的场景。
参见非流式调用,在Recognition类的
call方法中传入文件路径对录音文件直接进行识别。 -
将本地文件转成二进制流进行识别:此种方式一边识别文件一边流式获取识别结果,适合即时反馈的场景。
参见双向流式调用,通过Recognition类的
send_audio_frame方法向服务端发送二进制流对其进行识别。
故障排查
Q:无法识别语音(无识别结果)是什么原因?
-
请检查请求参数中的音频格式(
format)和采样率(sampleRate/sample_rate)设置是否正确且符合参数约束。以下为常见错误示例:- 音频文件扩展名为 .wav,但实际为 MP3 格式,而请求参数
format设置为 mp3(参数设置错误)。 - 音频采样率为 3600Hz,但请求参数
sampleRate/sample_rate设置为 48000(参数设置错误)。
- 音频文件扩展名为 .wav,但实际为 MP3 格式,而请求参数
-
使用
paraformer-realtime-v2模型时,请检查language_hints设置的语言是否与音频实际语言一致。 例如:音频实际为中文,但language_hints设置为en(英文)。 - 若以上检查均无问题,可通过定制热词提升对特定词语的识别效果。
Q:音频文件扩展名与实际编码格式不一致导致无识别结果,如何处理?
当音频文件的扩展名与实际编码格式不一致时(例如文件扩展名为.wav但实际编码为 MP3),请求参数format必须与音频的实际编码格式一致,而非文件扩展名。
您可以按以下步骤排查和解决:
- 检查音频实际格式:使用
ffprobe工具查看音频文件的实际编码格式。
- 转换音频格式:如果音频的实际编码格式与目标格式不一致,可使用
ffmpeg工具将音频转换为标准 WAV 格式(PCM 编码)。
- 修改请求参数:将
format参数设置为与转换后音频一致的格式(如wav),并确保sample_rate参数与音频的实际采样率一致。