移动端SDK说明 - 智能语音交互

本文为您介绍传入录音文件，完成音频文件识别并返回结果的流程说明。

使用须知

输入格式：WAV/MP3/AAC。
时长限制：识别语音文件大小不能超过100 MB。
设置多语言识别：在管控台编辑项目中进行模型选择，详情请参见管理项目。

服务地址

访问类型	URL	说明
外网访问	https://nls-gateway.cn-shanghai.aliyuncs.com/stream/v1/FlashRecognizer	所有服务器均可使用外网访问URL。

交互流程

下图展示iOS SDK和Android SDK的交互流程。

鉴权和初始化

客户端与服务端建立连接时，使用Access Token进行鉴权。关于Token获取请参见获取Token。

初始化参数表

参数	类型	是否必选	说明
url	String	是	语音服务URL地址。
app_key	String	是	管控台创建项目的appkey。
token	String	是	请确保该Token可以使用并在有效期内。说明 Token可以在初始化时设置，也可通过参数设置进行更新。
device_id	String	是	设备标识，唯一表示一台设备（如Mac地址/SN/UniquePsuedoID）。

开始文件识别

客户端发起文件识别请求时，需要通过接口传入JSON格式的params参数。

参数	类型	是否必选	说明
file_path	String	是	需要进行识别的文件绝对路径。
direct_ip	String	否	您可自行完成服务地址DNS解析，传入IP地址进行访问。
nls_config	JsonObject	否	服务细节参数配置。

其中，nls_config字段用于设置服务的具体配置参数，多与识别效果相关。

参数	类型	是否必选	说明
format	String	是	音频编码格式，支持WAV/MP3/AAC格式。
sample_rate	Integer	否	识别模型使用的采样率，一般不设置，在管控台进行配置。
enable_inverse_text_normalization	Boolean	否	是否打开ITN，中文数字将转为阿拉伯数字输出，默认值为 false，开启时需要设置version为”4.0”， enable_unify_post 必须为 true 。注意：不会对词信息进行ITN转换。
max_end_silence	Integer	否	允许的最大结束静音，默认值450，单位是毫秒。
customization_id	String	否	通过POP API创建的定制模型id，默认不添加。
vocabulary_id	String	否	创建的泛热词表ID，默认不添加。
enable_word_level_result	Boolean	否	是否开启词信息返回，默认false。
first_channel_only	Boolean	否	是否开启只处理第一个声道，默认false。

获取识别结果

启动任务后一段时间（根据文件长度和网络情况而定）将收到EVENT_FILE_TRANS_RESULT事件，即完整转写结果，示例如下。

{
    "task_id":"e76f979b33d9443eb6fbf770315a****",
    "status":20000000,
    "message":"SUCCESS",
    "flash_result":{
        "duration":299,  //音频时长
        "completed":true, 
        "sentences":[
            {
                "text":"啊，",  //句子级别的识别结果
                "begin_time":3700,  //句子的开始时间，单位：毫秒
                "end_time":3940,  //句子的结束时间，单位：毫秒
                "channel_id":0,  //多个声道的音频文件会区分返回识别结果，声道id从0计数
                "words":[
                    {
                        "text":"啊",  //当前句子包含的词信息
                        "begin_time":3700,  //当前词开始时间，单位：毫秒
                        "end_time":3940,  //当前词结束时间，单位：毫秒
                        "punc":"，"  //当前词尾的标点信息，没有标点则为空
                    }
                ]
            },
            {
                "text":"我在哪呀了。",
                "begin_time":3940,
                "end_time":4720,
                "channel_id":0,
                "words":[
                    {
                        "text":"我",
                        "begin_time":3940, 
                        "end_time":4040,
                        "punc":"，"
                    },
                    {
                        "text":"在哪",
                        "begin_time":4040,
                        "end_time":4340,
                        "punc":"，"
                    },
                    {
                        "text":"呀了",
                        "begin_time":4340,
                        "end_time":4720,
                        "punc":"，"
                    }
                ]
            }
        ]
    }
}

响应消息为JSON格式，包含如下字段。

字段	说明
task_id	任务ID，任务唯一标识。
status	状态码
message	状态消息
flash_result	识别结果对象

其中，flash_result对象包括如下字段。

字段	说明
sentences	句子级别的识别结果，是一个对象数组。

其中，sentences数组对象包含如下字段。

字段	说明
text	识别结果。
begin_time	识别结果的语音起点在音频流的时间偏移，单位毫秒。
end_time	识别结果的语音尾点在音频流的时间偏移，单位毫秒。

错误码

识别成功

错误码	错误信息	描述
0	SUCCESS	成功

配置或参数错误

错误码	错误消息	描述	解决方案
240999	DEFAULT_ERROR	内部默认错误。	内部未明确错误，可提工单通过日志文件寻求支持。
240001	NUI_CONFIG_INVALID	配置文件错误。	配置文件错误，请确认传入的资源路径内是否有资源文件。如果是Android平台，请参考代码样例主动使用copyAssets接口。
240002	ILLEGAL_PARAM	非法参数。	请确认传入的格式是否正确，包括字段类型，值范围限制。
240003	ILLEGAL_INIT_PARAM	初始化参数非法。	请确认初始化参数格式错误或缺少必须字段。
240004	NECESSARY_PARAM_LACK	缺少必须参数。	请确认接口调用时的必须参数。
240005	NULL_PARAM_ERROR	参数为空。	确认参数是否为空。
240006	NULL_LISTENER_ERROR	未定义事件回调。	确认回调事件是否正确赋值。
240007	NULL_DIALOG_ERROR	无有效对话实例，一般在内部状态错误时发生。	请确认接口调用前是否为正确状态，可使用cancel接口恢复idle状态。仍不能解决可提工单获得支持。
240008	NULL_ENGINE_ERROR	无有效引擎实例，请检查是否初始化成功。	请确认是否初始化成功。
240009	ILLEGAL_DATA	传入音频数据地址或长度非法。	请确认传入的数据长度值。

SDK状态错误

错误码	错误消息	描述	解决方案
240010	ILLEGAL_REENTRANT	退出后调用SDK接口。	不影响功能时可忽略。
240011	SDK_NOT_INIT	SDK未正确初始化。	确认初始化返回值正确再进行其他接口使用。
240012	SDK_ALREADY_INIT	重复调用SDK初始化接口。	确认初始化调用逻辑。
240013	DIALOG_INVALID_STATE	内部对话状态错误。	请阅读SDK流程图，确认是否在错误状态下调用接口。
240014	STATE_INVALID	SDK内部状态错误。	同DIALOG_INVALID_STATE。
240015	ILLEGAL_FUNC_CALL	该模式无法调用接口。	请确认接口调用是否合理。

系统调用错误

错误码	错误信息	描述	解决方法
240020	MEM_ALLOC_ERROR	内存分配错误。	检查内存是否不足。
240021	FILE_ACCESS_FAIL	文件访问错误。	检查文件读写权限是否提供。
240022	CREATE_DIR_ERROR	创建目录错误。	检查是否有写权限。

SDK内部调用错误

错误码	错误消息	描述	解决方法
240030	CREATE_NUI_ERROR	引擎创建失败。	创建实例失败，一般为系统资源不足。
240031	TEXT_DIALOG_START_FAIL	发起文本理解失败。	文本转语义理解失败，检查网络连接或url以及token等信息是否有效。
240032	TEXT_CANCEL_START_FAIL	取消文本理解失败。	可忽略。
240033	WUW_DUPLICATE	动态唤醒词重复。	可忽略。

本地引擎调用错误

错误码	错误消息	描述	解决方法
240040	CEI_INIT_FAIL	本地引擎初始化失败。	请确认本地引擎的模型是否有效，目录是否可读写。可提交工单跟进。
240041	CEI_SET_PARAM_FAIL	引擎参数设置失败。	请提工单。
240042	CEI_COMPILE_GRAMMER_FAIL	语法编译失败。	可忽略。
240043	CEI_STOP_FAIL	停止识别失败。	请提工单。
240044	CEI_CANCEL_FAIL	取消识别失败。	请提工单。
240045	CEI_UNLOAD_KWS_FAIL	取消唤醒词失败。	请提工单。
240046	GET_WUW_ERROR	获取唤醒词失败。	请提工单。

音频错误

错误码	错误消息	描述	解决方法
240050	SELECT_RECORDER_ERROR	选择音频设备错误。	内部错误，请提工单。
240051	UPDATE_AUDIO_ERROR	推送音频错误，一般为输入音频长度大于所需音频。	确认推送的音频长度是否非法。
240052	MIC_ERROR	连续2s未获取到音频。	请确认在音频数据回调中是否正确提供所需长度的音频。

调用超时错误

错误码	错误消息	描述	解决方法
240080	ENGINE_INIT_TIMEOUT	初始化引擎超时。	如果偶现可忽略，否则请提工单。
240081	SET_PARAM_TIMEOUT	设置参数超时。	如果偶现可忽略，否则请提工单。
240082	SET_WUW_TIMEOUT	设置唤醒词超时。	如果偶现可忽略，否则请提工单。
240083	SELECT_RECORDER_TIMEOUT	选择录音设备超时。	如果偶现可忽略，否则请提工单。
240084	STOP_TIMEOUT	结束对话超时。	如果偶现可忽略，否则请提工单。
240085	ASR_ENGINE_STOP_TIMEOUT	结束引擎超时。	如果偶现可忽略，否则请提工单。
240086	UNLOAD_DYNAMIC_WUW_TIMEOUT	取消动态唤醒词超时。	如果偶现可忽略，否则请提工单。
240087	ADD_DYNAMIC_WUW_TIMEOUT	增加动态唤醒词超时。	如果偶现可忽略，否则请提工单。
240100	WAIT_TIMEOUT	引擎接口调用超时。	如果偶现可忽略，否则请提工单。
240101	HANDLE_API_TIMEOUT	API层接口调用超时。	如果偶现可忽略，否则请提工单。

网络错误

错误码	错误消息	描述	解决方法
240060	CREATE_DA_REQUEST_ERROR	创建对话助手实例失败。	可忽略。
240061	START_DA_REQUEST_ERROR	发起对话助手请求失败。	可忽略。
240062	DEFAULT_NLS_ERROR	服务端发生错误。说明该错误同时包含服务端返回错误内容，具体请参见服务端错误码。	请参考服务端返回码进一步定位。
240063	SSL_ERROR	创建ssl实例错误。	偶现请忽略，否则请提交工单。
240064	SSL_CONNECT_FAILED	ssl连接失败。	连接异常，请检查服务url或者本地网络连接是否正常。
240065	HTTP_CONNECT_FAILED	HTTP连接失败。	服务连接错误，可通过日志文件查看HTTP返回值确认原因，或提工单跟进。
240066	DNS_FAILED	DNS解析失败。	请检查本地网络是否正常，DNS服务是否正常。
240067	CONNECT_FAILED	socket连接失败。	检查网络连接。
240068	SERVER_NOT_ACCESS	服务端无法访问。	请检查token是否过期或者url是否正确，仍无法定位请提工单。
240069	SOCKET_CLOSED	socket已关闭。	偶现可忽略，否则提交工单跟进。
240070	AUTH_FAILED	鉴权失败。	请检查是否提供正确的ak_serect，ak_id，app_key，sdk_code，device_id等信息，以及确认是否开通足够配额。
240071	HTTPDNS_FAILED	使用客户端传入的IP连接失败。	如果使用直接传入IP进行访问，请确认IP是否可访问。
240072	HTTP_SEND_FAILED	文件转写HTTP发送失败。	确认网络连接是否正常。
240073	HTTP_RECEIVE_FAILED	文件转写HTTP接收失败。	确认网络连接是否正常。
240074	HTTP_RESPONSE_ERROR	文件转写接收内容解析失败。	服务端返回内容错误，请提工单跟进。
240075	HTTP_SERVER_ERROR	文件转写服务错误，详细错误请参考服务错误码。	请参考服务端错误码进一步确认原因。

网络超时错误

错误码	错误消息	描述	解决方法
240090	UPDATE_CONTEXT_TIMEOUT	更新客户端信息超时	偶现请忽略，否则提交工单。
240091	CONNECTION_TIMEOUT	网络连接超时	偶现请忽略，否则提交工单。
240092	PARTIAL_ASR_TIMEOUT	获取中间识别结果超时	偶现请忽略，否则提交工单。
240093	ASR_TIMEOUT	获取最终识别结果超时	偶现请忽略，否则提交工单。
240094	DIALOG_TIMEOUT	获取对话理解结果超时	偶现请忽略，否则提交工单。
240095	WWV_TIMEOUT	获取云端唤醒确认结果超时	偶现请忽略，否则提交工单。

服务端错误码

当收到EVENT_ASR_ERROR事件，并且错误码为DEFAULT_NLS_ERROR（240062）或HTTP_SERVER_ERROR（240075）时，可以通过错误事件header中status字段获取服务端错误码进行进一步问题定位。

错误码	原因	解决方法
40000001	身份认证失败。	检查使用的令牌是否正确、是否过期。
40000002	无效的消息。	检查发送的消息是否符合要求。
403	令牌过期或无效的参数	检查使用的令牌是否过期。检查参数值设置是否合理。
40000004	空闲超时。	确认是否长时间（10秒）未发送数据到服务端。
40000005	请求数量过多。	检查是否超过了并发连接数或者每秒钟请求数。如果超过并发数，建议从免费版升级到商用版，或者商用版扩容并发资源。
40000000	默认的客户端错误码。	查看错误消息或提交工单。
41010120	客户端超时错误。	客户端连续10秒及以上没有发送数据，导致客户端超时错误。
50000000	默认的服务端错误。	如果偶现可以忽略，重复出现请提交工单。
50000001	内部调用错误。	如果偶现可以忽略，重复出现请提交工单。
52010001	内部调用错误。	如果偶现可以忽略，重复出现请提交工单。
40010001	不支持的接口。	使用了不支持的接口，如果使用SDK请提交工单。
40010002	不支持的指令。	使用了不支持的指令，如果使用SDK请提交工单。
40010003	无效的指令。	指令格式错误，如果使用SDK请提交工单。
40010004	客户端提前断开连接。	检查是否在请求正常完成之前关闭了连接。
40010005	任务状态错误。	发送了当前任务状态不能处理的指令。
40020105	应用不存在。	解析路由时找不到应用。
40020106	appkey和token不匹配。	检查应用appkey是否正确，是否与令牌归属同一个账号。
40020503	子账户鉴权失败。	使用父账户对调用的子账户授权POP API的访问权限。
41040201	客户端10s内停止发送数据。	检查网络问题，或者检查业务中是否存在不发数据的情况。
41040202	客户端发送数据过快，服务器资源已经耗尽。	检测客户端发包是否过快，是否按照1:1的实时率发包。
41040203	客户端发送音频格式不正确。	请将音频数据的格式转换为SDK目前支持的音频格式。
41040204	客户端调用方法异常。	客户端应该先调用发送请求接口，发送请求完毕后再调用其他接口。
41040205	客户端设置MAXSILENCE_PARAM方法异常。	参数MAXSILENCE_PARAM的范围为200～2000。
41050008	采样率不匹配。	检查调用时设置的采样率和管控台上appkey绑定的ASR模型采样率是否一致。
51040101	服务端内部错误。	未知错误。
51040103	实时语音识别服务不可用	检查实时语音识别服务是否有任务堆积等导致任务提交失败
51040104	请求实时语音识别服务超时。	排查实时语音识别日志。
51040105	调用实时语音识别服务失败。	检查实时语音识别服务是否启动，端口是否正常开启。
51040106	实时语音识别服务负载均衡失败，未获取到实时语音识别服务的IP地址。	检查VPC中的实时语音识别服务机器是否有异常。