AI 助理
文档备案控制台
官方文档
首页 大模型服务平台百炼 API参考（模型） Realtime API 接入模型与应用 WebSocket 实时语音识别 Paraformer iOS SDK

Paraformer实时语音识别iOS SDK

更新时间：
复制 MD 格式
产品详情
我的收藏

本文档提供了Paraformer实时语音识别iOS SDK的详细使用指南，帮助您将语音转换为文本。

重要阿里云百炼为华北2（北京）地域推出了业务空间专属域名，能够为推理请求提供卓越的性能和更高的稳定性，建议从 dashscope.aliyuncs.com 迁移至 {WorkspaceId}.cn-beijing.maas.aliyuncs.com。

{WorkspaceId}需要替换为真实的Workspace ID。现有域名仍可正常使用。

用户指南：关于模型介绍和选型建议请参见实时语音识别-Fun-ASR/Paraformer。

快速开始

  1. 获取API Key：获取与配置 API Key

    说明当需要为第三方应用或用户提供临时访问权限，或者希望严格控制敏感数据访问、删除等高风险操作时，建议使用临时API Key。临时API Key拥有固定的60秒有效期，过期后需重新获取。

  2. 下载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 后体验功能。

调用步骤

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

请求参数

连接与控制参数

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

  • 参数示例：以下为 JSON 字符串示例，参数未完整列出。请按实际需求在编码时补充：
{
    "url": "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference",
    "apikey": "st-****",
    "device_id": "my_device_id",
    "service_mode": "1"
}
  • 参数说明

    参数

    类型

    是否必须

    说明

    url

    String

    是

    服务地址，固定为 wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference。调用时请将{WorkspaceId}替换为真实的Workspace ID。

    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-8k-v2仅支持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及更高版本模型。热词的使用方法请参见定制热词。

关键接口

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;

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格式：

    {
  "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

语音识别结束。

上一篇：Android SDK下一篇：HarmonyOS SDK