本文介绍Fun-ASR-Realtime实时语音识别Python SDK的参数和接口细节。
前提条件
- 已开通服务并获取与配置 API Key。请配置API Key到环境变量,而非硬编码在代码中,防范因代码泄露导致的安全风险。
- 安装最新版DashScope SDK。
快速开始
核心资源(client.audio.asr)提供了非流式调用和双向流式调用等接口。请根据实际需求选择合适的调用方式:
- 非流式调用(
recognize_file):针对本地文件进行识别,SDK自动分块发送音频并驱动到任务结束。适合处理录制好的音频。 - 双向流式调用(
recognize会话):可直接对音频流进行识别,并实时输出结果。音频流可以来自外部设备(如麦克风)或从本地文件读取。适合需要即时反馈的场景。
- 非流式调用
- 双向流式调用
提交单个语音实时转写任务,通过传入本地文件的方式同步阻塞地拿到转写结果。调用核心资源(
client.audio.asr)的recognize_file方法绑定请求参数并传入本地文件路径,迭代服务端事件获取识别结果。接口地址
SDK 的实时识别走 WebSocket 接口,端点为下方地址。在client.audio.asr.recognize/recognize_file中通过ws_url参数传入:
wss://maas.qianwenaiapi.com/api-ws/v1/inference
请求参数
请求参数通过核心资源(client.audio.asr)的recognize/recognize_file方法进行设置:model、format、sample_rate、vocabulary_id为具名参数,其余参数(如language_hints)通过parameters字典传入。
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
model | str | 是 | 模型名称。 |
sample_rate | int | 是 | 采样率(Hz)。 取值范围:8k模型仅支持 8000 Hz,其他模型支持任意采样率。 |
format | str | 是 | 音频格式。 取值范围:
|
vocabulary_id | str | 否 | 预编译热词列表 ID。 需预先调用创建热词列表接口生成,识别时传入该 ID 即可使用列表中的热词。 适用于词汇已知且相对稳定、需要跨请求复用同一词表的场景。 使用方法请参见预编译热词。 |
max_sentence_silence | int | 否 | VAD 断句静音阈值(ms)。当一段语音后的静音时长超过该阈值时,系统会判定该句子已结束。 默认值:1300。 取值范围:[200, 6000]。 |
multi_threshold_mode_enabled | bool | 否 | 是否启用多阈值模式。启用后可防止 VAD 断句切割过长。 默认值:False。 |
punctuation_prediction_enabled | bool | 否 | 设置是否在识别结果中自动添加标点:
|
heartbeat | bool | 否 | 是否启用心跳包。 默认值:False。
|
language_hints | list[str] | 否 | 待识别音频语种。无默认值,不设置时模型自动识别。 仅支持设置 1 个值,设置多个时仅第一个生效。
|
speech_noise_threshold | float | 否 | 语音与噪音的判定阈值,用于调整语音活动检测(VAD)的灵敏度。 取值范围:[-1.0, 1.0]。 取值说明:
|
special_word_filter | str | 否 | 指定在语音识别过程中需要处理的敏感词,并支持对不同敏感词设置不同的处理方式。详情请参见敏感词过滤。 |
recognize/recognize_file方法的input关键字参数传入。
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
input | dict | 否 | 输入对象,用于传入对话上下文(context)。上下文用于辅助识别、提升专有词汇的识别准确率。使用方法详见提升识别准确率。 提示: 仅 fun-asr-realtime 模型支持 context 参数。 dict 中需包含 context 键,值为消息列表(list[dict]),每条消息包含以下字段:
input_text 和 text 类型)各最多 5 条,超出时保留最近的 5 条。每轮上下文文本总长度不超过 400 个字符,超出部分从末尾截断。 提示: 携带上下文时,context 中的消息顺序有要求:上下文消息必须按对话轮次排列,每轮中 user(input_text 类型)必须在对应的 assistant(text 类型)之前。 说明: 使用该字段时,SDK版本不能低于2.0.1。 示例 1 请参见表格下方 |
关键接口
核心资源(client.audio.asr)
实时语音识别能力挂载在client.audio.asr资源上:recognize创建双向流式识别会话(Recognition),recognize_file对本地文件一次性识别。
| 成员方法 | 方法签名 | 说明 |
|---|---|---|
recognize | 示例 1 请参见表格下方 | 创建双向流式识别会话,进入with上下文时自动调用start建立连接并发送任务。发送音频与消费事件需并发进行(配合send_audio_frame、events()/results()和stop使用)。 |
recognize_file | 示例 2 请参见表格下方 | 基于本地文件的非流式调用:自动分块发送音频并驱动到任务结束,逐个产出服务端事件。该方法要求所识别文件具有可读权限。 |
start | 示例 3 请参见表格下方 | 开始语音识别:建立连接、发送任务并等待task-started。进入with上下文时自动调用,启动成功后才能发送音频。 |
send_audio_frame | 示例 4 请参见表格下方 | 推送音频。每次推送的音频流不宜过大或过小,建议每包音频时长为100ms左右,大小在1KB~16KB之间。 识别结果通过事件迭代(events()/results())获取。 |
stop | 示例 5 请参见表格下方 | 停止语音识别:只通知服务端输入结束,接收线程需继续消费events()直到task-finished事件。 |
events / results | 示例 6 请参见表格下方 | 迭代服务端事件:events()产出原始事件dict(识别文本位于payload.output.sentence);results()只产出识别结果帧,返回识别结果(RecognitionResult)类型化对象(心跳帧已过滤)。 |
close | 示例 7 请参见表格下方 | 关闭识别会话。退出with上下文时自动调用。 |
request_id / first_package_delay / last_package_delay / last_response | 示例 8 请参见表格下方 | 获取request_id、首包延迟(从发送第一包音频到收到首包识别结果延迟)和尾包延迟(发送stop指令到最后一包识别结果下发耗时),在任务完成后使用;last_response为最近一次成功读取的原始报文,可用于获取task-failed报错。会话关闭后仍可读取。 |
事件迭代(events()/results())
双向流式调用时,服务端会通过事件的方式,将关键流程信息和数据返回给客户端。您需要在接收线程中迭代会话的events()(原始事件dict)或results()(类型化识别结果帧),处理服务端返回的信息或者数据。
| 事件/迭代方法 | 产出内容 | 返回值 | 描述 |
|---|---|---|---|
| 示例 1 请参见表格下方 | task-started事件 | 无 | 由start()内部读取,启动返回时保存在last_response中,不会由events()再次产出。 |
| 示例 2 请参见表格下方 | event:服务端事件dict | 迭代器 | 当服务有回复时产出事件。识别结果位于payload.output.sentence,可能为心跳或空文本事件,应用可按需忽略。请由一个接收线程持续消费,不要并发创建多个读取者。 |
| 示例 3 请参见表格下方 | result:识别结果(RecognitionResult) | 迭代器 | 只产出识别结果帧(心跳帧已过滤),全部识别结果返回后迭代结束。 |
| 示例 4 请参见表格下方 | DashScopeError异常 | 无 | 发生异常时在发送/接收线程中抛出,可使用try/except捕获。 |
| 示例 5 请参见表格下方 | task-finished事件 | 无 | 当服务已经完成全部识别后由events()产出,随后迭代结束;发送stop()后仍须读取此事件。 |
响应结果
识别结果(RecognitionResult)
RecognitionResult代表会话results()迭代产出的一次识别结果帧(双向流式调用与非流式调用均可使用;events()产出的是原始事件dict,如需该类型化视图请改用results())。
| 成员方法 | 方法签名 | 说明 |
|---|---|---|
get_sentence | 示例 1 请参见表格下方 | 获取当前识别的句子及时间戳信息,此方法返回类型为Dict[str, Any](单句信息)。 详情请参见单句信息(Sentence)。 |
request_id | 示例 2 请参见表格下方 | 当前事件对应的请求request_id。 |
is_sentence_end | 示例 3 请参见表格下方 | 判断当前句子是否已经结束。该方法通过检查 get_sentence() 返回的单句信息中 end_time 字段是否为 None 来判定——end_time 不为 None 时表示句子已结束。 |
单句信息(Sentence)
Sentence类成员如下:
| 参数 | 类型 | 说明 |
|---|---|---|
begin_time | int | 句子开始时间,单位为ms。 |
end_time | int | 句子结束时间,单位为ms。 |
text | str | 识别文本。 |
words | 字时间戳信息(Word)的list集合 | 字时间戳信息。 |
字时间戳信息(Word)
Word类成员如下:
| 参数 | 类型 | 说明 |
|---|---|---|
begin_time | int | 字开始时间,单位为ms。 |
end_time | int | 字结束时间,单位为ms。 |
text | str | 字。 |
punctuation | str | 标点。 |
错误码
如遇报错问题,请参见错误码进行排查。
若问题仍未解决,可加入语音 SDK 示例仓库中列出的开发者群反馈问题,并提供Request ID,以便进一步排查问题。
常见问题
功能特性
Q:在长时间静默的情况下,如何保持与服务端长连接?
将请求参数heartbeat设置为true,并持续向服务端发送静音音频。
静音音频指的是在音频文件或数据流中没有声音信号的内容。静音音频可以通过多种方法生成,例如使用音频编辑软件如Audacity或Adobe Audition,或者通过命令行工具如FFmpeg。
Q:如何将音频格式转换为满足要求的格式?
可使用FFmpeg工具,更多用法请参见FFmpeg官网。
Q:如何识别本地文件(录音文件)?
识别本地文件有两种方式:
-
直接传入本地文件路径:此种方式在最终识别结束后获取完整识别结果,不适合即时反馈的场景。
参见非流式调用,调用
recognize_file方法传入文件路径对录音文件直接进行识别。 -
将本地文件转成二进制流进行识别:此种方式一边识别文件一边流式获取识别结果,适合即时反馈的场景。
参见双向流式调用,通过识别会话的
send_audio_frame方法向服务端发送二进制流对其进行识别。
故障排查
Q:无法识别语音(无识别结果)是什么原因?
-
请检查请求参数中的音频格式(
format)和采样率(sampleRate/sample_rate)设置是否正确且符合参数约束。以下为常见错误示例:- 音频文件扩展名为 .wav,但实际为 MP3 格式,而请求参数
format设置为 mp3(参数设置错误)。 - 音频采样率为 3600Hz,但请求参数
sampleRate/sample_rate设置为 48000(参数设置错误)。
- 音频文件扩展名为 .wav,但实际为 MP3 格式,而请求参数
- 若以上检查均无问题,可通过定制热词提升对特定词语的识别效果。