Paraformer实时语音识别iOS SDK

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

快速开始

获取API Key：获取与配置 API Key
当需要为第三方应用或用户提供临时访问权限，或者希望严格控制敏感数据访问、删除等高风险操作时，建议使用临时API Key。临时API Key拥有固定的60秒有效期，过期后需重新获取。
下载SDK并运行示例代码：
- 下载最新SDK整合包。
- 解压 ZIP 包，将其中的 nuisdk.framework 添加到工程。
- 在 Build Phases → Link Binary With Libraries 中添加 nuisdk.framework。
- 在 General → Frameworks, Libraries, and Embedded Content 中将 nuisdk.framework 设置为 Embed & Sign。
- 用 Xcode 打开示例工程。示例代码位于DashParaformerSpeechTranscriberViewController，替换 API Key 后体验功能。

调用步骤

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

请求参数

连接与控制参数

通过在nui_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 | 否 | 日志文件的存储路径。
此参数仅在调用nui_initialize接口时将save_log设为YES时生效。此时必须设置日志文件路径，否则将报错。
本地最多保留两个日志文件。 | | save_wav | String | 否 | 是否保存调试用的音频文件。音频文件保存于debug_path下。
默认值："false"。
取值范围：
- "true"：是
- "false"：否
此参数仅在调用nui_initialize接口时将save_log设为YES时生效。同时，debug_path也必须被设置。 | | max_log_file_size | int | 否 | 设定日志文件的最大字节数。
此参数仅在调用nui_initialize接口时将save_log设为YES时生效。
默认值：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（通过nui_initialize接口设置）共同决定最终回调的日志。一条日志的级别数值必须同时大于或等于log_track_level和level的值，才会被回调。例如，log_track_level设为2 (INFO)，level设为3 (WARNING)，则只有WARNING及以上级别（数值>=3）的日志才会被回调。 |

语音识别效果参数

通过在nui_set_params接口的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"
              }
          ]
    }
}

关键接口

NeoNui

nui_initialize

初始化语音识别SDK实例。SDK为单例模式，在调用 nui_release 前禁止重复初始化。

方法签名

-(NuiResultCode) nui_initialize:(const char *)parameters
                       logLevel:(NuiSdkLogLevel)level
                        saveLog:(BOOL)save_log;

参数说明 | 参数 | 类型 | 说明 | |---|---|---| | parameters | char* | JSON字符串，包含鉴权、连接和调试参数。参见连接与控制参数。 | | level | NuiSdkLogLevel | 控制SDK自身日志的打印级别。 | | save_log | BOOL | 是否保存本地日志。若为YES，须在连接与控制参数通过debug_path指定路径，并可通过max_log_file_size设置文件大小。 |
返回值说明

nui_set_params

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

方法签名

-(NuiResultCode) nui_set_params:(const char *)params;

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

nui_dialog_start

开始识别。

方法签名

-(NuiResultCode) nui_dialog_start:(NuiVadMode)vad_mode
                      dialogParam:(const char *)dialog_params;

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

示例 1（说明）：

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

返回值说明

nui_dialog_cancel

结束识别或者立即取消当前交互。

方法签名

-(NuiResultCode) nui_dialog_cancel:(BOOL)force;

参数说明
| 参数 | 类型 | 说明 | |---|---|---| | force | BOOL | 是否强制结束而忽略最终结果。
- YES：不等待服务端返回最终识别结果就立即结束任务。
- NO：结束任务，但是会等待完整结果返回。
|
返回值说明

nui_release

释放SDK所有内部资源，并强制终止所有正在进行的任务。此方法调用后，SDK实例将变为不可用状态，如需再次使用，必须重新调用 nui_initialize 进行初始化。

方法签名

-(NuiResultCode) nui_release;

返回值说明

nui_get_version

获得当前SDK版本信息。

方法签名

-(const char*) nui_get_version;

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

nui_get_all_response

获得当前事件回调的完整信息。

方法签名

-(const char*) nui_get_all_response;

返回值说明 JSON字符串格式的完整事件信息。

NeoNuiSdkDelegate：监听回调

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

方法签名

-(void) onNuiEventCallback:(NuiCallbackEvent)nuiEvent
                    dialog:(long)dialog
                 kwsResult:(const char *)wuw
                 asrResult:(const char *)asr_result
                  ifFinish:(BOOL)finish
                   retCode:(int)code;

参数说明 | 参数 | 类型 | 说明 | |---|---|---| | nuiEvent | NuiCallbackEvent | 回调事件。 | | dialog | long | 会话编码，无需关注该参数。 | | wuw | char* | 语音唤醒功能。无需关注该参数。 | | asr_result | char* | 语音识别结果。 | | finish | BOOL | 本轮识别是否结束标志。 | | code | int | 仅在出现 EVENT_ASR_ERROR 事件时有效。 |

onNuiAudioStateChanged：监听音频状态

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

方法签名

-(void) onNuiAudioStateChanged:(NuiAudioState)state;

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

onNuiNeedAudioData：填充待识别音频数据

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

方法签名

-(int) onNuiNeedAudioData:(char *)audioData length:(int)len;

参数说明 | 参数 | 类型 | 说明 | |---|---|---| | audioData | char * | 填充的音频数据。 | | len | int | 填充的音频数据的字节数。 |

onNuiLogTrackCallback：监听追踪日志

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

-(void) onNuiLogTrackCallback:(NuiSdkLogLevel)level
                   logMessage:(const char *)log;

NuiCallbackEvent：事件类型

事件	说明
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	语音识别结束。

​快速开始

​调用步骤

​请求参数

​连接与控制参数

​语音识别效果参数

​关键接口

​NeoNui

​nui_initialize

​nui_set_params

​nui_dialog_start

​nui_dialog_cancel

​nui_release

​nui_get_version

​nui_get_all_response

​NeoNuiSdkDelegate：监听回调

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

​onNuiAudioStateChanged：监听音频状态

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

​onNuiLogTrackCallback：监听追踪日志

​NuiCallbackEvent：事件类型

快速开始

调用步骤

请求参数

连接与控制参数

语音识别效果参数

关键接口

NeoNui

nui_initialize

nui_set_params

nui_dialog_start

nui_dialog_cancel

nui_release

nui_get_version

nui_get_all_response

NeoNuiSdkDelegate：监听回调

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

onNuiAudioStateChanged：监听音频状态

onNuiNeedAudioData：填充待识别音频数据

onNuiLogTrackCallback：监听追踪日志

NuiCallbackEvent：事件类型