Paraformer实时语音识别Android SDK

**用户指南：**关于模型介绍和选型建议请参见实时语音识别-Fun-ASR/Paraformer。 在线体验：仅paraformer-realtime-v2、paraformer-realtime-8k-v2和paraformer-realtime-v1支持在线体验。

快速开始

获取API Key：获取与配置 API Key，为安全起见，推荐将API Key配置到环境变量。
当需要为第三方应用或用户提供临时访问权限，或者希望严格控制敏感数据访问、删除等高风险操作时，建议使用临时API Key。临时API Key默认拥有60秒有效期，过期后需重新获取。
下载SDK并运行示例代码：
- 下载最新SDK整合包。
- 解压 ZIP 包。在 app/libs 目录中获取 AAR 格式 SDK，并添加到项目依赖。
  需要 Android CPP 接入时，使用 ZIP 包内的 android_libs 与 android_include 获取动态库和头文件。
- 用 Android Studio 打开工程。示例代码位于DashParaformerSpeechTranscriberActivity.java，替换 API Key 后体验功能。

调用步骤

初始化 SDK
按业务需求设置参数：通过initialize接口的parameters参数设置连接与控制参数；通过setParams接口设置语音识别效果参数。
调用startDialog启动识别流程。
在onNuiAudioStateChanged回调中，根据音频状态开启录音设备。
在onNuiNeedAudioData回调中持续提供录音数据。
在onNuiEventCallback回调中监听事件并获取语音识别结果。
调用stopDialog停止识别，并通过监听EVENT_TRANSCRIBER_COMPLETE事件确认识别已结束。
当识别功能不再使用时，调用release接口释放 SDK 资源。

请求参数

连接与控制参数

通过在initialize接口的parameters参数中传入一个JSON字符串来配置。

**参数示例：**以下为 JSON 字符串示例，参数未完整列出。请按实际需求在编码时补充：

{
    "url": "wss://maas.qianwenaiapi.com/api-ws/v1/inference",
    "apikey": "st-****",
    "device_id": "my_device_id",
    "service_mode": "1"
}

参数说明
| 参数 | 类型 | 是否必须 | 说明 | |---|---|---|---| | url | String | 是 | 服务地址，固定为 wss://maas.qianwenaiapi.com/api-ws/v1/inference。 | | apikey | String | 是 | API Key。建议使用时效性短、安全性更高的临时API Key，以降低长期有效Key泄露的风险。 | | service_mode | String | 是 | 运行模式。实时语音识别固定为 "1"。 | | device_id | String | 是 | 用于标识终端用户的唯一字符串，可设为应用内用户ID或客户端生成的设备唯一标识符。此ID主要用于日志追踪和问题排查。 | | debug_path | String | 否 | 日志文件的存储路径。
此参数仅在调用initialize接口时将save_log设为true时生效。此时必须设置日志文件路径，否则将报错。
本地最多保留两个日志文件。 | | save_wav | String | 否 | 是否保存调试用的音频文件。音频文件保存于debug_path下。
默认值："false"。
取值范围：
- "true"：是
- "false"：否
此参数仅在调用initialize接口时将save_log设为true时生效。同时，debug_path也必须被设置。 | | max_log_file_size | int | 否 | 设定日志文件的最大字节数。
此参数仅在调用initialize接口时将save_log设为true时生效。
默认值：104857600（100 * 1024 * 1024 字节，即 100MiB）。 | | log_track_level | int | 否 | 控制通过日志回调（onNuiLogTrackCallback）对外发送的日志内容的过滤级别。
默认值：2。
取值范围：
- 0：LOG_LEVEL_VERBOSE
- 1：LOG_LEVEL_DEBUG
- 2：LOG_LEVEL_INFO
- 3：LOG_LEVEL_WARNING
- 4：LOG_LEVEL_ERROR
- 5：LOG_LEVEL_NONE（表示关闭此功能）
注意：log_track_level与level（通过initialize接口设置）共同决定最终回调的日志。一条日志的级别数值必须同时大于或等于log_track_level和level的值，才会被回调。例如，log_track_level设为2 (INFO)，level设为3 (WARNING)，则只有WARNING及以上级别（数值>=3）的日志才会被回调。 |

语音识别效果参数

通过在setParams接口的params参数中传入一个JSON字符串来配置。

**参数示例：**以下为 JSON 字符串示例，参数未完整列出。请按实际需求在编码时补充：

{
    "service_type": 4,
    "nls_config": {
        "model": "paraformer-realtime-v2",
        "sr_format": "pcm",
        "sample_rate": "16000"
    }
}

参数说明
| 一级参数 | 类型 | 是否必须 | 说明 | |---|---|---|---| | service_type | int | 是 | 语音服务类型。实时语音识别固定为 4。 | | nls_config | object | 是 | 语音识别核心配置对象，包含模型选择、识别效果控制等关键参数。 | | nls_config.model | string | 是 | 语音识别模型。 | | nls_config.sr_format | string | 是 | 待识别音频格式。支持的音频格式：pcm、wav、opus。 提示： - opus：必须为PCM编码，SDK内部会将其编码成OPUS格式；
- wav/pcm：必须为PCM编码。
| | nls_config.sample_rate | int | 是 | 待识别音频采样率（单位Hz）。因模型而异：
- paraformer-realtime-v2支持任意采样率。
- paraformer-realtime-v1仅支持16000Hz采样。
- paraformer-realtime-8k-v2仅支持8000Hz采样率。
- paraformer-realtime-8k-v1仅支持8000Hz采样率。
| | nls_config.disfluency_removal_enabled | boolean | 否 | 是否过滤语气词，如“嗯”、“啊”等。默认值：false。 | | nls_config.language_hints | array[string] | 否 | 设置待识别语言代码。如果无法提前确定语种，可不设置，模型会自动识别语种。支持的语言代码：
- zh: 中文
- en: 英文
- ja: 日语
- yue: 粤语
- ko: 韩语
- de：德语
- fr：法语
- ru：俄语
该参数仅对支持多语言的模型生效 | | nls_config.semantic_punctuation_enabled | boolean | 否 | 设置断句模式。默认值：false。取值范围：
- true：开启语义断句，关闭VAD断句。
- false：开启VAD断句，关闭语义断句。
语义断句准确性更高，适合会议转写场景；VAD（Voice Activity Detection，语音活动检测）断句延迟较低，适合实时交互场景。该参数仅在模型为v2及更高版本时生效。 | | nls_config.max_sentence_silence | int | 否 | VAD（Voice Activity Detection，语音活动检测）断句的静音时长阈值（单位为ms）。默认值：800。取值范围：[200, 6000]。当一段语音后的静音时长超过该阈值时，系统会判定该句子已结束。该参数仅在semantic_punctuation_enabled参数为false且模型为v2及更高版本时生效。 | | nls_config.multi_threshold_mode_enabled | boolean | 否 | 是否开启防过长切割模式。开启可防止VAD断句切割过长。默认值：false（关闭）。取值范围：
- true：开启
- false：关闭
该参数仅在semantic_punctuation_enabled参数为false且模型为v2及更高版本时生效。 | | nls_config.punctuation_prediction_enabled | boolean | 否 | 是否在识别结果中自动添加标点符号。默认值：true（是）。取值范围：
- true：是
- false：否
该参数仅在模型为v2及更高版本时生效。 | | nls_config.heartbeat | boolean | 否 | 是否和服务端保持长连接。默认值：false。取值范围：
- true：在持续发送静音音频的情况下，可保持与服务端的连接不中断。
- false：即使持续发送静音音频，连接也将在一定时间后因超时而断开。该超时为服务端默认行为，客户端不可配置。
该参数仅在模型为v2及更高版本时生效。 | | nls_config.inverse_text_normalization_enabled | boolean | 否 | 是否开启ITN（Inverse Text Normalization，逆文本正则化）。开启后，中文数字将转换为阿拉伯数字。默认值：true（开启）。取值范围：
- true：开启
- false：关闭
该参数仅在模型为v2及更高版本时生效。 | | nls_config.vocabulary_id | string | 否 | 热词词表ID，用于提升特定词汇的识别准确率。该参数适用于v2及更高版本模型。热词的使用方法请参见定制热词。 | | nls_config.resources | array[object] | 否 | 热词资源配置，用于v1版本模型。功能与vocabulary_id相同，但配置方式不同： resources 是一个对象数组，其每个元素包含 resource_id 和 resource_type 字段：
- resource_id：string类型，热词ID。
- resource_type：string类型，取值为固定字符串“asr_phrase”。
示例：示例 1 请参见表格下方热词的使用方法请参见Paraformer语音识别热词定制与管理。 |

示例 1（说明）：

{
    "nls_config": {
          "resources": [
              {
                  "resource_id": "xxxxxxxxxxxx",
                  "resource_type": "asr_phrase"
              }
          ]
    }
}

关键接口

NativeNui

initialize

初始化语音识别SDK实例。SDK为单例模式，在调用release前禁止重复初始化。此接口会引起阻塞，应在非UI线程调用。

方法签名

public synchronized int initialize(final INativeNuiCallback callback,
                                   String parameters,
                                   final Constants.LogLevel level,
                                   final boolean save_log)

参数说明 | 参数 | 类型 | 说明 | |---|---|---| | callback | INativeNuiCallback | 事件和数据回调接口的实现。 | | parameters | String | JSON字符串，包含鉴权、连接和调试参数。参见连接与控制参数。 | | level | Constants.LogLevel | 控制SDK自身日志的打印级别。 | | save_log | boolean | 是否保存本地日志。若为true，须在连接与控制参数中通过debug_path指定路径，并可通过max_log_file_size设置文件大小。 |
返回值说明

setParams

以JSON格式设置语音识别效果参数。在startDialog之前调用。

方法签名

public synchronized int setParams(String params)

参数说明 | 参数 | 类型 | 说明 | |---|---|---| | params | String | 语音识别效果参数。 |
返回值说明

startDialog

开始识别。

方法签名

public synchronized int startDialog(VadMode vad_mode, String dialog_params)

参数说明 | 参数 | 类型 | 说明 | |---|---|---| | vad_mode | VadMode | VAD模式。固定为VadMode.TYPE_P2T。 | | dialog_params | String | 当连接与控制参数的apikey参数对应的临时API Key过期时，可在此处进行更新。内容为JSON格式：示例 1 请参见表格下方 |

示例 1（说明）：

{
  "apikey": "st-****"
}

返回值说明

stopDialog

结束识别，调用该接口后，服务端将返回最终识别结果并结束任务。

方法签名

public synchronized int stopDialog();

返回值说明

cancelDialog

立即结束识别，调用该接口后，不等待服务端返回最终识别结果就立即结束任务。

方法签名

public synchronized int cancelDialog();

返回值说明

release

释放SDK所有内部资源。此方法调用后，SDK实例将变为不可用状态，如需再次使用，必须重新调用initialize进行初始化。

方法签名

public synchronized int release();

返回值说明

GetVersion

获得当前SDK版本信息。

方法签名

public synchronized String GetVersion();

返回值说明 当前SDK版本信息。

INativeNuiCallback：监听回调

onNuiEventCallback：监听事件和语音识别结果

方法签名

void onNuiEventCallback(NuiEvent event, final int resultCode, final int arg2, KwsResult kwsResult, AsrResult asrResult);

参数说明 | 参数 | 类型 | 说明 | |---|---|---| | event | NuiEvent | 回调事件。 | | resultCode | int | 仅在出现 EVENT_ASR_ERROR 事件时有效。 | | asrResult | AsrResult | 语音识别结果。 | | kwsResult | KwsResult | 语音唤醒功能。无需关注该参数。 | | arg2 | int | 保留参数。 |

onNuiAudioStateChanged：监听音频状态

SDK 通过此回调通知何时应该开始或停止录音。

方法签名

void onNuiAudioStateChanged(AudioState state);

AudioState状态说明 | 状态 | 说明 | |---|---| | STATE_OPEN | 交互启动，可以打开录音设备进行录音。 | | STATE_PAUSE | 交互停止，可以停止录音。 | | STATE_CLOSE | SDK 实例已释放，可以彻底关闭录音设备。 |

onNuiNeedAudioData：填充待识别音频数据

开始识别后，该回调被连续触发，需在其中提供待识别音频数据。

方法签名

int onNuiNeedAudioData(byte[] buffer, int len);

参数说明 | 参数 | 类型 | 说明 | |---|---|---| | buffer | byte[] | 填充的音频数据。 | | len | int | 填充的音频数据的字节数。 |
返回值说明 实际填充的字节数。

onNuiLogTrackCallback：监听追踪日志

此回调用于接收 SDK 内部的详细日志，方便进行问题定位和调试。

default void onNuiLogTrackCallback(Constants.LogLevel level, String log)

`NuiEvent`：事件类型

事件	说明
EVENT_TRANSCRIBER_STARTED	任务启动成功。
EVENT_VAD_START	任务启动后即触发该事件。不代表检测到人声起点。
EVENT_VAD_END	检测到人声终点。
EVENT_ASR_PARTIAL_RESULT	语音识别中间结果。
EVENT_ASR_ERROR	语音识别过程中出现错误。
EVENT_MIC_ERROR	因连续2秒未收到任何音频数据而触发。
EVENT_SENTENCE_END	检测到一句话结束，此时会返回一句完整的识别结果。
EVENT_TRANSCRIBER_COMPLETE	语音识别结束。

​快速开始

​调用步骤

​请求参数

​连接与控制参数

​语音识别效果参数

​关键接口

​NativeNui

​initialize

​setParams

​startDialog

​stopDialog

​cancelDialog

​release

​GetVersion

​INativeNuiCallback：监听回调

​onNuiEventCallback：监听事件和语音识别结果

​onNuiAudioStateChanged：监听音频状态

​onNuiNeedAudioData：填充待识别音频数据

​onNuiLogTrackCallback：监听追踪日志

​NuiEvent：事件类型

快速开始

调用步骤

请求参数

连接与控制参数

语音识别效果参数

关键接口

NativeNui

initialize

setParams

startDialog

stopDialog

cancelDialog

release

GetVersion

INativeNuiCallback：监听回调

onNuiEventCallback：监听事件和语音识别结果

onNuiAudioStateChanged：监听音频状态

onNuiNeedAudioData：填充待识别音频数据

onNuiLogTrackCallback：监听追踪日志

`NuiEvent`：事件类型