实时语音识别移动端 SDK 接口说明-智能语音交互(ISI)-阿里云帮助中心

NUI 移动端 SDK 支持对持续输入的语音流进行实时识别，适用于会议演讲、视频直播等场景。本文介绍初始化参数、识别参数和回调事件。

功能简介

NUI SDK 提供语音能力和状态管理，可用于集成完整语音处理流程，也可按需调用独立能力，并使用统一的接口。

使用限制与配置

输入音频须为 PCM 编码、16 位采样位数、单声道，支持 8000 Hz 和 16000 Hz 采样率。音频不符合要求时，可能识别失败或返回空结果。
SDK 接收 PCM 音频后，可按 sr_format 设置以 PCM 或 OPUS 格式传输；选择 OPUS 时，由 SDK 编码压缩。8000 Hz 仅支持 PCM 传输。
中间识别结果、标点预测和中文数字转阿拉伯数字均为可选功能，根据需要开启。
语种和方言模型不能通过代码指定，需要在控制台为项目配置，并与音频采样率和场景匹配。配置方法请参见管理项目。

服务地址

SDK 默认使用上海公网地址。公网地址可从所有服务器访问；内网地址仅供同地域 VPC 内的 ECS 实例访问，经典网络不支持。使用内网地址不产生 ECS 实例的公网流量费用。

地域	公网地址	内网地址
上海	`wss://nls-gateway-cn-shanghai.aliyuncs.com/ws/v1`	`ws://nls-gateway-cn-shanghai-internal.aliyuncs.com:80/ws/v1`
北京	`wss://nls-gateway-cn-beijing.aliyuncs.com/ws/v1`	`ws://nls-gateway-cn-beijing-internal.aliyuncs.com:80/ws/v1`
深圳	`wss://nls-gateway-cn-shenzhen.aliyuncs.com/ws/v1`	`ws://nls-gateway-cn-shenzhen-internal.aliyuncs.com:80/ws/v1`

交互流程

初始化 SDK 并设置识别参数后，启动识别，通过音频回调持续提供数据。SDK 通过事件回调返回句子开始、中间结果和句子结束等信息。音频发送完毕后，结束识别并等待任务完成。

识别事件以 JSON 表示。header.task_id 标识同一次识别任务，header.message_id 标识一条消息；排查问题时应记录任务 ID。

鉴权和初始化

客户端建立 WebSocket 连接时，使用 NLS Token 鉴权。获取方式请参见获取Token。以下参数用于 SDK 初始化。

参数	类型	必填	说明
`workspace`	String	是	工作目录路径，SDK 从该路径读取配置文件。
`app_key`	String	是	项目 Appkey，获取方法请参见管理项目。
`token`	String	是	有效的 NLS Token。可在初始化时设置，也可在参数设置时更新。
`device_id`	String	是	唯一标识设备的字符串，例如 MAC 地址、序列号或 UniquePsuedoID。
`debug_path`	String	否	调试目录。初始化接口的 `save_log` 为 `true` 时，用于保存中间音频文件。
`save_wav`	String	否	是否保存调试音频，取值为字符串 `"true"` 或 `"false"`。仅在 `save_log` 为 `true` 时生效，且 `debug_path` 必须有效、可写。

识别参数

初始化后、开始识别前，通过参数设置接口传入 JSON 字符串。Android 使用 setParams，iOS 使用 nui_set_params。通常设置一次即可；需要更新 Token 时可重新设置。

顶层参数

参数	类型	必填	说明
`app_key`	String	否	项目 Appkey，一般在初始化时设置。
`token`	String	否	需要更新 NLS Token 时设置。
`service_type`	Int	是	语音服务类型。实时语音识别取值为 `4`。
`direct_ip`	String	否	客户端自行进行 DNS 解析后，用于访问服务的 IP 地址。
`nls_config`	JsonObject	否	识别服务参数，具体字段见下表。

nls_config

参数	类型	必填	说明
`sr_format`	String	否	音频传输编码，取值为 `opus` 或 `pcm`，默认为 `opus`。8000 Hz 仅支持 `pcm`。
`sample_rate`	Integer	否	音频采样率，默认为 16000 Hz。项目模型须支持所用采样率和场景。
`enable_intermediate_result`	Boolean	否	是否返回中间识别结果，默认为 `false`。
`enable_punctuation_prediction`	Boolean	否	是否在后处理中添加标点，默认为 `false`。
`enable_inverse_text_normalization`	Boolean	否	是否开启逆文本正则化（ITN），将中文数字转换为阿拉伯数字，默认为 `false`。
`customization_id`	String	否	自学习模型 ID。
`vocabulary_id`	String	否	定制泛热词 ID。
`max_sentence_silence`	Integer	否	静音断句阈值，单位为毫秒。静音时长超过该值时判断为句子结束。取值范围为 200～2000，默认为 800。
`enable_words`	Boolean	否	是否返回词信息，默认为 `false`。
`disfluency`	Boolean	否	是否过滤语气词，默认为 `false`。
`vad_model`	String	否	服务端 VAD 模型 ID，默认无需设置。
`speech_noise_threshold`	float	否	噪音判定阈值，取值范围为 -1～+1。越接近 -1，越多音频被判为语音，可能误识别噪声；越接近 +1，越多音频被判为噪音，可能漏识别语音。该参数属于高级参数，应谨慎调整并重点测试。
`extend_config`	JsonObject	否	配置交互协议支持、但本表未列出的扩展参数。具体设置方法请参见对应 SDK 的参数设置示例。

参数设置示例请参见Android SDK或iOS SDK。

发送音频与处理事件

开始识别后，在 onNuiNeedAudioData 回调中持续提供 PCM 音频。SDK 通过 onNuiEventCallback 返回识别事件。SDK 事件枚举与消息中的 header.name 对应关系如下。

SDK 事件	header.name	含义
`EVENT_SENTENCE_START`	`SentenceBegin`	检测到一句话开始。
`EVENT_ASR_PARTIAL_RESULT`	`TranscriptionResultChanged`	句子中间结果，需要开启 `enable_intermediate_result`。
`EVENT_SENTENCE_END`	`SentenceEnd`	句子结束，返回该句的完整结果。

公共 header 字段

字段	类型	说明
`namespace`	String	消息命名空间，本接口为 `SpeechTranscriber`。
`name`	String	消息名称。
`status`	Integer	业务状态码，`20000000` 表示成功。
`message_id`	String	本条消息的 ID。
`task_id`	String	识别任务的全局唯一 ID。
`status_text`	String	状态描述。

事件详情

SentenceBegin

以下 JSON 示例说明消息结构。

{
  "header": {
    "namespace": "SpeechTranscriber",
    "name": "SentenceBegin",
    "status": 20000000,
    "message_id": "a426f3d4618447519c9d85d1a0d1****",
    "task_id": "5ec521b5aa104e3abccf3d361822****",
    "status_text": "Gateway:SUCCESS:Success."
  },
  "payload": {
    "index": 1,
    "time": 0
  }
}

payload 字段

字段	类型	说明
`index`	Integer	句子编号，从 1 开始递增。
`time`	Integer	当前已处理的音频时长，单位为毫秒。

TranscriptionResultChanged

以下 JSON 示例说明消息结构。

{
  "header": {
    "namespace": "SpeechTranscriber",
    "name": "TranscriptionResultChanged",
    "status": 20000000,
    "message_id": "dc21193fada84380a3b6137875ab****",
    "task_id": "5ec521b5aa104e3abccf3d361822****",
    "status_text": "Gateway:SUCCESS:Success."
  },
  "payload": {
    "index": 1,
    "time": 1835,
    "result": "北京的天",
    "confidence": 1.0,
    "words": [
      {
        "text": "北京",
        "startTime": 630,
        "endTime": 930
      },
      {
        "text": "的",
        "startTime": 930,
        "endTime": 1110
      },
      {
        "text": "天",
        "startTime": 1110,
        "endTime": 1140
      }
    ]
  }
}

payload 字段

字段	类型	说明
`index`	Integer	句子编号，从 1 开始递增。
`time`	Integer	当前已处理的音频时长，单位为毫秒。
`result`	String	当前句子的中间识别结果。
`words`	`List<Word>`	词信息列表，需要开启 `enable_words`。
`confidence`	Double	句子识别结果的置信度，取值范围为 0.0～1.0，值越大表示置信度越高。

SentenceEnd

以下 JSON 示例说明消息结构。

{
  "header": {
    "namespace": "SpeechTranscriber",
    "name": "SentenceEnd",
    "status": 20000000,
    "message_id": "c3a9ae4b231649d5ae05d4af36fd****",
    "task_id": "5ec521b5aa104e3abccf3d361822****",
    "status_text": "Gateway:SUCCESS:Success."
  },
  "payload": {
    "index": 1,
    "time": 2000,
    "begin_time": 0,
    "result": "北京的天气。",
    "confidence": 1.0,
    "words": [
      {
        "text": "北京",
        "startTime": 630,
        "endTime": 930
      },
      {
        "text": "的",
        "startTime": 930,
        "endTime": 1110
      },
      {
        "text": "天气",
        "startTime": 1110,
        "endTime": 1380
      }
    ]
  }
}

payload 字段

字段	类型	说明
`index`	Integer	句子编号，从 1 开始递增。
`time`	Integer	当前已处理的音频时长，单位为毫秒。
`begin_time`	Integer	该句对应的 `SentenceBegin` 事件时间，单位为毫秒。
`result`	String	当前句子的完整识别结果。
`words`	`List<Word>`	词信息列表，需要开启 `enable_words`。
`confidence`	Double	句子识别结果的置信度，取值范围为 0.0～1.0，值越大表示置信度越高。

Word 字段

字段	类型	说明
`text`	String	词文本。
`startTime`	Integer	词在音频中的开始时间，单位为毫秒。
`endTime`	Integer	词在音频中的结束时间，单位为毫秒。

结束识别

音频发送完毕后，调用 SDK 的结束识别接口。Android 调用 stopDialog；iOS 调用 nui_dialog_cancel，需要保留最终结果时将 force 设为 false。通过 EVENT_TRANSCRIBER_COMPLETE 确认识别任务已结束。

句子结果与任务完成是不同事件。没有有效语音时，任务可以完成而不返回句子结果。

错误码

调用失败时，根据错误码和任务 ID 排查问题。通用错误码、实时语音识别错误码和 SDK 错误码及处理方法，请参见错误码查询。

功能简介

使用限制与配置

服务地址

交互流程

鉴权和初始化

识别参数

顶层参数

nls_config

发送音频与处理事件

公共 header 字段

事件详情

SentenceBegin

TranscriptionResultChanged

SentenceEnd

结束识别

错误码

相关文档