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

功能简介

NUI SDK 提供统一接口和状态管理，支持全链路语音能力，也可作为独立的语音能力 SDK 使用。本文说明一句话识别的交互流程、初始化参数、识别参数和响应字段。SDK 接入与完整调用示例，请参见Android SDK和iOS SDK。

使用限制

输入音频为 PCM 编码、16 bit 采样位数、单声道。
音频采样率为 8000 Hz 或 16000 Hz，须与项目配置的模型匹配。
单次语音数据时长不能超过 60 秒。

语种和方言模型在控制台的项目中配置，不能通过识别代码指定。配置方法请参见管理项目。中间结果、标点预测和逆文本规范化（ITN）均为可选功能，可按需开启。

服务地址

SDK 默认使用上海地域的公网地址。ECS 实例可通过同地域的专有网络（VPC）访问内网地址，不产生 ECS 实例的公网流量费用。经典网络不支持通过 AnyTunnel 访问语音服务，使用内网访问时需在 VPC 中部署。

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

交互流程

iOS SDK 和 Android SDK 的交互流程如下。

服务端识别响应中的 header.task_id 是任务的唯一标识，排查问题时需提供该值。

1. 鉴权和初始化

客户端使用有效的 NLS Token 与服务端建立 WebSocket 连接。获取方法请参见获取 Token。初始化参数请参见初始化参数表。

2. 开始识别

开始识别前，通过参数设置接口配置 JSON 格式的识别参数。参数通常设置一次即可；需要更新 Token 或调整配置时重新设置。识别参数请参见识别参数表。

3. 发送数据

客户端持续发送音频数据。enable_intermediate_result 为 true 时，SDK 通过 onNuiEventCallback 回调上报 EVENT_ASR_PARTIAL_RESULT 事件，返回中间识别结果；为 false 时，不返回中间识别结果。

关闭中间结果不影响完成或失败事件。开启语音活动检测（VAD）后，服务端可在音频发送过程中检测到语音结束并完成识别。

4. 结束识别

手动结束：客户端发送结束请求，通知服务端音频数据已发送完毕。服务端结束任务并返回最终识别结果。
VAD 自动结束：开启 enable_voice_detection 后，达到 max_end_silence 指定的结束静音条件时，服务端返回 RecognitionCompleted 并结束任务，后续音频不再识别。

说明
最后一次中间结果可能与最终结果不同，应以 EVENT_ASR_RESULT 事件中的结果为准。

参数说明

初始化参数

以下为通用初始化参数。各平台的完整初始化配置和调用方法，请参见Android SDK和iOS SDK。

参数	类型	是否必选	说明
`workspace`	String	是	工作目录路径，SDK 从该目录读取配置文件。
`app_key`	String	是	在控制台创建的项目的 Appkey。
`token`	String	是	有效且未过期的 NLS Token。可在初始化时设置，也可通过参数设置接口更新。
`device_id`	String	是	设备的唯一标识，例如 MAC 地址、SN 或 UniquePsuedoID。
`debug_path`	String	否	调试目录。初始化 SDK 时，`save_log` 为 `true` 才使用该目录保存中间音频文件。
`save_wav`	String	否	是否保存调试音频。仅当初始化 SDK 时的 `save_log` 为 `true` 时生效，音频保存在 `debug_path` 指定的目录中，该目录必须有效且可写。

识别参数

通过参数设置接口传入以下 JSON 字段。

参数	类型	是否必选	说明
`app_key`	String	否	项目的 Appkey，通常在初始化时设置。
`token`	String	否	需要更新 NLS Token 时设置。
`service_type`	Int	是	语音服务类型，一句话识别为 `0`。
`direct_ip`	String	否	客户端自行解析 DNS 后，可传入 IP 地址访问服务。
`nls_config`	JsonObject	否	语音识别配置对象。

语音识别配置

nls_config 包含以下字段。输入 SDK 的 PCM 音频要求与 sr_format 指定的传输编码属于不同配置。

参数	类型	是否必选	说明
`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。
`enable_voice_detection`	Boolean	否	是否启用语音活动检测（VAD），检测有效语音的开始和结束。默认值为 `false`。
`max_start_silence`	Integer	否	允许的最大开始静音时长，单位为毫秒。仅当 `enable_voice_detection` 为 `true` 时生效。开始识别后，在该时长内未检测到语音，服务端返回 `TaskFailed` 并结束任务。
`max_end_silence`	Integer	否	允许的最大结束静音时长，单位为毫秒，取值范围为 200～6000。仅当 `enable_voice_detection` 为 `true` 时生效。超过该时长，服务端返回 `RecognitionCompleted` 并结束任务，后续音频不再识别。
`extend_config`	JsonObject	否	扩展配置，可设置交互协议支持但未在本表列出的参数。

响应说明

以下 JSON 展示识别结果消息的格式。

中间识别结果

{
    "header": {
        "namespace": "SpeechRecognizer",
        "name": "RecognitionResultChanged",
        "status": 20000000,
        "message_id": "e06d2b5d50ca40d5a50d4215c7c8****",
        "task_id": "4c3502c7a5ce4ac3bdc488749ce4****",
        "status_text": "Gateway:SUCCESS:Success."
    },
    "payload": {
        "result": "北京的天气"
    }
}

最终识别结果

{
    "header": {
        "namespace": "SpeechRecognizer",
        "name": "RecognitionCompleted",
        "status": 20000000,
        "message_id": "10490c992aef44eaa4246614838f****",
        "task_id": "4c3502c7a5ce4ac3bdc488749ce4****",
        "status_text": "Gateway:SUCCESS:Success."
    },
    "payload": {
        "result": "北京的天气。"
    }
}

响应字段

header

字段	类型	说明
`namespace`	String	消息命名空间，此处为 `SpeechRecognizer`。
`name`	String	消息名称。`RecognitionResultChanged` 表示中间结果，`RecognitionCompleted` 表示识别完成。
`status`	Integer	服务状态码，表示请求是否成功。
`message_id`	String	本次消息的 ID，由 SDK 自动生成。
`task_id`	String	任务的全局唯一 ID，用于排查问题。
`status_text`	String	状态消息。

payload

字段	类型	说明
`result`	String	识别文本。`RecognitionResultChanged` 中为中间结果，`RecognitionCompleted` 中为最终结果。

错误码

服务端和移动端 SDK 的错误码及处理方法，请参见错误码查询。