AI 助理
文档备案控制台
官方文档
首页 智能语音交互 服务支持 常见问题 SDK FAQ

SDK FAQ

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

本文介绍 SDK 集成、鉴权、音频发送、回调和错误排查等常见问题。

通用问题

如何通过 SDK 设置业务专属热词？

通过控制台配置的业务专属热词表与项目 Appkey 绑定，无需在代码中重复设置。通过 POP API 创建的词表，需要在 SDK 中指定词表 ID。代码中指定的词表优先于控制台配置。

一句话识别、实时语音识别和录音文件识别的设置方法请参见使用 SDK 设置业务专属热词。

出现 DNS resolved timeout 时如何排查？

检查 /etc/resolv.conf 中的 nameserver 配置。可以增加并优先使用 nameserver 114.114.114.114。

如何使用SDK设置自学习模型？

如果是通过控制台创建的自学习模型，可在项目切换模型时选择该模型，发布上线后将与Appkey绑定，无需在代码中自行设置；而通过POP API训练获取的自学习模型，需要在SDK中设置其模型ID才可以使用。请参考使用SDK 2.0设置自学习模型，其中介绍在一句话识别、实时语音识别、录音文件识别中如何设置自学习模型。

是否有Android和iOS的SDK，能否用在专有云下？

有SDK，在专有云安装包里默认不提供，可以通过阿里云帮助中心对应的服务文档中下载，如实时语音识别的Android SDK和iOS SDK。移动端SDK可以调用公共云ASR、TTS服务，也可以用在专有云环境下。

如何使用和刷新 Token？

公有云 Token 可在同一账号下的不同项目、进程和线程间复用，应在过期前重新获取。建议在服务端获取 Token，再由客户端向业务服务端请求 Token，避免在客户端保存 AccessKey。具体请参见通过 SDK 获取 Token。

专有云 Token 默认使用 default，无需修改。

微信小程序 SDK 的 getToken() 会检查本地缓存，缓存键由 AccessKey ID、& 和 AccessKey Secret 拼接而成。缓存有效时复用 Token，缓存缺失或过期时重新获取；这不是后台定时刷新机制。生产应用仍应由业务服务端管理 AccessKey 和 Token。

Token重新获取会不会导致已获取的Token失效？

Token重新获取不会影响已获取Token的有效性，有效性只与时间有关。Token的有效期通过服务端响应消息的ExpireTime参数获取。更多信息，请参见获取Token协议说明。

Java NlsClient 的 Token 过期后需要重建客户端吗？

不必仅因 Token 过期而重建 NlsClient，但建立新连接仍需要有效 Token。可以复用客户端，在 Token 过期前获取新 Token，并调用 NlsClient.setToken() 更新凭证。

是否可以提供服务的IP白名单？

服务器的IP比较多，且会随着扩容、机器故障置换等原因动态变化，当前的IP列表不代表后续都可以使用。建议增加以下两个域名的访问规则：nls-meta.cn-shanghai.aliyuncs.com、nls-gateway-cn-shanghai.aliyuncs.com，开通80、443端口，HTTP和websocket协议。

如何进行log控制与音频保存?

SDK提供多级log控制，在初始化接口中配置。

同时提供音频数据的保存方便问题定位，需要设置save_wav和debug_path初始化参数，详情请参见接口说明。

说明

实时语音识别的save_wav和debug_path参数含义与一句话识别相同。

调用上有什么限制？

SDK已经对语音服务的访问做了封装，只需调用开始接口，在回调中进行适当事件处理。一般需要处理错误事件和识别结果事件。注意不能在回调中直接调用SDK的接口，可能导致死锁发生。

为什么必须先启动识别任务，再发送音频？

发送音频前，需要先建立连接并启动识别任务。不同 SDK 的同步、异步接口和回调名称不同，应按对应 SDK 的启动成功返回值或事件确认任务已启动，再发送音频。任务结束时按对应协议发送停止指令，并接收完成事件。

为什么链接不到framework？

framework中代码采用Objective-C和C++混合编写而成，所以需要使用.mm后缀文件进行调用，同时请确保工程的头文件路径与库文件路径设置正确。

SDK错误事件如何定位原因？

在SDK上报错误事件时，首先根据错误码查看原因，一般能够根据错误码获得问题的初步原因。

微信小程序 SDK 支持实时语音识别吗？

支持。微信小程序 SDK 提供 SpeechTranscription，通过 start() 启动任务、sendAudio() 分片发送音频，并通过识别事件接收结果。

如何指定合成音色？

调用语音合成时，在 SDK 的音色参数中指定目标音色，例如 Java SDK 的 setVoice()。应以所调用接口的音色名称和支持范围为准，不要将控制台体验页面的选择当作代码中的音色配置。

实时语音识别 Go SDK 中如何获取 taskID？

在实时语音识别 Go SDK 中，taskID 位于回调函数返回的 JSON 数据的 header.task_id 字段中。示例返回结构如下：

{
  "header": {
    "task_id": "fba2f3db6e7e42bc804c2d99295db109",
    "namespace": "SpeechTranscriber",
    "name": "TranscriptionStarted",
    "status": 20000000,
    "status_text": "Gateway:SUCCESS:Success."
  }
}

在回调函数中，通过解析该 JSON 数据并读取 header.task_id 字段即可获取 taskID，用于日志关联和问题追踪。

页面刷新后如何保留实时转写内容？

如果识别结果只保存在页面内存中，刷新页面后会丢失。可以在收到结果时将文本保存到 IndexedDB 等持久化存储中，在页面重新加载时读取并恢复显示。该数据保存逻辑由应用实现。

如何选择移动端 SDK 的版本应用号？

039、01B 等是能力组合不同的版本应用号。应根据语音识别、语音合成和端侧能力等实际需求，对照 SDK 下载页中的能力表选择对应包；整合包与改名包也应核对具体版本及集成要求。

Android SDK 的本地 AAR 可以通过 Gradle 集成吗？

可以。本地 AAR 导入也是 Gradle 支持的依赖方式。将下载包中的 AAR 放入项目的依赖目录，并配置本地文件依赖即可。

Java SDK

一句话识别、实时语音识别SDK中，send接口参数含义及使用方式？

以Java为例。java SDK中，一句话识别和实时语音识别分别提供了三个重载的send()接口。如下：

public void send(InputStream ins);
public void send(InputStream ins, int batchSize, int sleepInterval);
public void send(byte[] data);

三个接口使用时要保证持续、实时地向服务端发送语音数据。

demo是用语音文件模拟实时语音流的速度发送语音，通常一次发送间隔时间为100ms或200ms（sleepInterval）的语音数据，数据量（batchSize）和采样率有关：发送间隔过大，会导致延迟较大，容易断连；发送间隔过小，会消耗服务端和网络资源。可以适当实验调整到合适数值。

第2个接口中ins为模拟语音流，需要控制发送速率。ins中的数据每间隔100ms，发送3200字节（16000采样率）。调用示例：

recognizer.send(ins, 3200, 100); // 16 KHz语音

第3个接口中data为一次性发送的数据，控制循环调用的间隔，调用示例：

recognizer.send(data); // 100ms语音数据
try {
 Thread.sleep(100);
} catch (InterruptedException e) {
 e.printStackTrace();
}

如何结合SDK日志，分析延迟问题？

以Java SDK日志为例。

  • 一句话识别的延迟为一句话说完开始，到收到最终识别结果为止，消耗的时间。

    在日志中搜索关键字StopRecognition以及RecognitionCompleted，分别找到语音发送完毕时的日志，以及一句话识别结束的日志。记录的时间差即为SDK端记录的一句话延时，如下日志延迟为：984-844=140（ms）。

    14:24:44.844 DEBUG [           main] [c.a.n.c.transport.netty4.NettyConnection] thread:1,send:{"header":{"namespace":"SpeechRecognizer","name":"StopRecognition","message_id":"bccac69b505f4e2897d12940e5b38953","appkey":"FWpPCaVYDRp6J1rO","task_id":"8c5c28d9a40c4a229a5345c09bc9c968"}}
14:24:44.984 DEBUG [ntLoopGroup-2-1] [  c.a.n.c.p.asr.SpeechRecognizerListener] on message:{"header":{"namespace":"SpeechRecognizer","name":"RecognitionCompleted","status":20000000,"message_id":"2869e93427b9429190206123b7a3d397","task_id":"8c5c28d9a40c4a229a5345c09bc9c968","status_text":"Gateway:SUCCESS:Success."},"payload":{"result":"北京的天气。","duration":2959}}

  • 语音合成关注首包延迟，即从发送合成请求开始，到收到第一个语音包为止，消耗的时间。

    日志中搜索关键字send，找到这条日志和紧随其后的一条收到语音包的日志。记录的时间差即为SDK端记录的首包延时。如下日志延时为1035-813=222（ms）。

    14:32:13.813 DEBUG [           main] [c.a.n.c.transport.netty4.NettyConnection] thread:1,send:{"payload":{"volume":50,"voice":"Ruoxi","sample_rate":8000,"format":"wav","text":"国家是由领土、人民、文化和政府四个要素组成的，国家也是政治地理学名词。从广义的角度，国家是指拥有共同的语言、文化、血统、领土、政府或者历史等的社会群体。从狭义的角度，国家是一定范围内的人群所形成的共同体形式。"},"context":{"sdk":{"name":"nls-sdk-java","version":"2.1.0"},"network":{"upgrade_cost":160,"connect_cost":212}},"header":{"namespace":"SpeechSynthesizer","name":"StartSynthesis","message_id":"6bf2a84444434c0299974d8242380d6c","appkey":"FWpPCaVYDRp6J1rO","task_id":"affa5c90986e4378907fbf49eddd283a"}}
14:32:14.035  INFO [ntLoopGroup-2-1] [  c.a.n.c.protocol.tts.SpeechSynthesizer] write array:6896

  • 实时语音识别SDK日志类似一句话识别，可以从日志中计算语音末尾处延迟（关键字：StopTranscription和TranscriptionCompleted）。

  • RESTful形式访问，客户端自带日志中没有体现延迟。需要用户自己编写代码，或者查看服务端日志。

Java SDK找不到com.alibaba的JAR包，如何安装Alibaba Cloud SDK for Java？

请参见原版 SDK 使用指南安装Alibaba Cloud SDK for Java。

SpeechRecognizer.stop() 等待完成确认超时怎么办？

timeout after 10 seconds waiting for complete confirmation. state: STATE_STOP_SENT 表示已发送停止指令，但在等待时间内没有收到完成确认，不等于该状态本身表示连接已断开。检查网络是否稳定，以及停止指令前后的请求和回调日志；偶发情况可能与网络抖动有关。

录音文件转写接口Java SDK Demo运行报错如何排查？

  1. 检查智能语音交互服务开通地和代码使用是否一致。在智能语音交互控制台中，确认当前所选地域（如上海）与代码中配置的Region一致，并检查所需服务（如录音文件识别）状态为已开通。

    private static String appKey = "你的appkey";
private static String accessKeyId = "你的AccessKey ID";
private static String accessKeySecret = "你的AccessKey Secret";
private static String REGION_ID = "cn-shanghai";

  2. 检查SDK的fastjson和aliyun-java-sdk-core两个库的依赖版本。阿里云Java SDK的核心库版本支持3.5.0及以上（如果版本在4.0.0及以上，需要根据错误提示补充对应的第三方依赖），详情请参见录音文件识别Java SDK。

    <dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-java-sdk-core</artifactId>
    <version>3.7.1</version>
</dependency>
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>fastjson</artifactId>
    <version>1.2.83</version>
</dependency>

Android SDK 支持哪种录音文件识别接口？

Android SDK 提供录音文件识别极速版的 startFileTranscriber 接口。不能将这一接口与普通录音文件识别的异步提交、查询接口混用；选择接入方式时应先确认所用产品形态。

Java SDK 如何通知服务端音频已发送完毕？

一句话识别使用 SpeechRecognizer，实时语音识别使用 SpeechTranscriber，不要混用两者的结束规则。音频发送完毕后，通过对应对象的 stop() 通知服务端结束输入，并等待最终结果或完成回调。enable_intermediate_result=true 控制中间结果，不代替停止指令。

实时流识别模式，Java SDK中如何触发回调onTranscriptionComplete？

onTranscriptionComplete可以通过stop触发，状态为STATE_STOP_SENT，回调处理完状态为STATE_COMPLETE。

调用Java SDK时报错，提示java.lang.IllegalStateException: complete already: DefaultChannelPromise@75822ea8(failure: java.lang.Exception: WebSocket Client failed to connect,status:403 Forbidden,reason:Meta:ACCESS_DENIED:The token '***' is invalid!)"如何解决？

报错原因是Token无效，请重新生成一个Token，具体操作方法请参见获取Token。

在生成synthesizer = new SpeechSynthesizer时一直失败，提示java.nio.channels.ClosedChannelException如何解决？

建议使用Java环境，并使用Demo在新的空项目中进行测试。如果测试Demo没有问题，说明不是SDK集成问题，建议检查客户端的前端集成情况。

在哪里获取语音识别和语音合成的 Java SDK 依赖？

按照对应 Java SDK 文档配置依赖。实时语音识别的依赖和示例请参见实时语音识别 Java SDK。

Java SDK实时识别NlsClient类去连接server报错， 提示ERROR NlsClient:102 - failed to connect to server after 3 tries,error msg is :hostname can't be null如何解决？

如果不再使用Demo，需要指定hostname，即请求阿里语音服务侧的接口。

接口详情请参见wss://nls-gateway-cn-shanghai.aliyuncs.com/ws/v1或实时语音识别Java SDK。

Java SDK语音合成报错，提示java.nio.channels.ClosedChannelException at io.netty.channel.AbstractChannel$AbstractUnsafe.ensureOpen(...)如何解决？

如果未生成TaskId，说明请求未成功到达智能语音交互的服务端，一般为本地环境问题。建议优先排查本地网络和环境，将线上Demo和本地对比检查。

Java SDK通过传入阿里云账号的AccessKey ID和AccessKey Secret，调用阿里云Java SDK得到client提示错误org.json.JSONArray.iterator()Ljava/util/Iterator如何解决？

请确认依赖包是否完整，查找并添加如下两个依赖JAR包。

<dependency>
<groupId>org.json</groupId>
<artifactId>json</artifactId>
<version>20170516</version>
</dependency>

<dependency>
<groupId>com.google.code.gson</groupId>
<artifactId>gson</artifactId>
<version>2.8.2</version>
</dependency>

Java版SDK可以直接提供上传音频文件的方式进行识别吗？

SDK示例通过调用RESTfulAPI接口，实现上传音频文件进行识别，详情请参见一句话识别Java SDK。

// SDK示例通过调用RESTfulAPI接口，实现上传音频文件进行识别
String result = SpeechFlashRecognizer.submit(url, appKey, token);

使用Java Demo识别录音文件没有识别结果，使用文档中的语音文件识别可以正常识别，该如何解决？

可以使用file命令查看语音格式，检查该格式是否符合产品要求。模型支持的标准8K数据格式为8 KHz采样率、16 bit采样位数、单声道WAV格式；16K语音数据标准格式为16 KHz采样率、16 bit采样位数、单声道WAV格式。如果测试使用，可以使用Sox或者ffmpeg等工具转成标准工具测试；如果线上使用，请参考相关产品说明。

以实时语音识别的接口说明为例。

实时语音识别接口支持的音频格式参数如下：采样率（sample_rate）支持8000和16000，音频编码格式（format）支持pcm、wav、opus、opu，采样位数为16 bit，声道数为单声道。

Maven 依赖已导入，但找不到类时如何排查？

先确认包含目标类的依赖已加入项目，并检查依赖的版本、作用域和实际运行时类路径。若这些配置正确，再重新加载 Maven 项目，必要时清理 IDE 缓存。

创建 Java FlowingSpeechSynthesizer 时如何控制连接等待时间？

FlowingSpeechSynthesizer 构造过程中会建立连接。Java SDK 2.2.19 的 NlsClient 支持系统属性 nls.ws.connect.timeout，单位为毫秒，默认值为 5000，应在 NlsClient 类初始化前设置。连接过程可能重试，因此单次超时配置不等于整个构造过程的总耗时。构造器也可能直接抛出异常，应在调用处处理，不能只依赖错误回调。

C++ SDK

C++ SDK语音合成时传入的文本没有采用UTF-8编码会有什么错误信息？

如果传入的文本没有采用UTF-8编码，在文本中含有中文字符时，语音合成SDK调用start函数会失败，返回错误信息Socket recv failed, errorCode: 0。错误码为0表示服务端已经关闭了连接，此时应检查传入的文本是否采用UTF-8编码。

C++ SDK如何获取Token？

具体操作请参见获取Token。

下载后可获取NlsCommonSDK目录，其中包含lib/和include/子目录。

下载C++ Token SDK后获取到NlsCommonSDK，功能包括获取Token和录音文件识别。

NlsCppSDK（3.0.X和2.X旧版本）内部不包含NlsCommonSDK，功能包括实时识别、一句话识别、长/短语音合成，非NLS CPP SDK需要按照上述方式重新获取Token。

NlsCppSDK（3.1.X新版本）内部包含NlsCommonSDK，功能包括获取Token、录音文件识别、实时识别、一句话识别、长/短语音合成，不需要按照上述方式重新获取Token。

C++ SDK调用智能实时语音解析接口失败，提示 {"TaskFailed":"connect failed."} {"channeclClosed": "nls request finished."}如何解决？

  1. C++ SDK3.0及以前的版本有小概率出现这个问题，无需特别关注；3.1及以后版本出现这个问题可能是运行环境的网络问题导致，建议检查本地网络环境。

  2. 如果没有返回TaskId，说明在连接过程中直接断开，实时语音交互不需要重复调用接口，重复调用会有并发上限和超时时间，并发超过限制会直接返回超过限制，WebSocket连接超过10秒没有音频就会自动断开，但是会返回TaskId。

  3. 这种情况一般是由于当时网络拥堵造成的，建议使用抓包工具查看分析实际发送的包是否重传了tcp retransmission，可以在客户端使用traceroute命令或者使用MTR工具到nls-gateway-cn-shanghai.aliyuncs.com进行链路测试，判断从客户端到接口服务之间网络是否不稳定。

C++ SDK进行语音合成时，报错未设置appkey，但是代码已经设置该如何解决？OnSynthesisTaskFailed: status code=10000002 task id=***error message={TaskFailed":"{"task_id":"00000000000000000000000000000000","result":"","status":40000003,"message":"Gateway:PARAMETER_INVALID:appkey not set"}"}"

status为40000003指传入的参数有误，请重新检查传入的参数值是否正确，例如appkey、voice、url等。

C++ SDK（3.0及以后版本）使用语音合成和语音识别功能，可以提高GCC5.0以上的编译版本吗？

可以。Linux下支持GCC 4.8.5或以上版本。目前已验证且顺利编译运行的GCC版本包括4.8.5、5.5.0、8.4.0。

speechRecognizerDemo.cpp 的 g_akid 和 g_akSecret 从哪里获取？

这两个变量分别填写 AccessKey ID 和 AccessKey Secret，用于获取 NLS Token。获取凭证及 Token 的方法请参见通过 SDK 获取 Token。不要将真实凭证提交到代码仓库。

C++ SDK实时语音识别报错，提示status_text:Gateway:IDLE_TIMEOUT:Websocket session is idle for too long time, the last directive is 'StartTranscription'!如何解决？

  1. 因为超过10秒没有发送数据到服务端，空闲超时自动断连。同时请检查URI是否正确，wss://nls-gateway-cn-shanghai.aliyuncs.com/ws/v1。如果发生这种情况，可以增加重试机制再次请求。

  2. 也可能服务端瞬间收到大量请求导致单个case无法及时处理，建议重试。

C++ SDK获取Token，当系统的时间不是标准时间时会获取失败，在C++ SDK中，可以自己设置timestamp，而不是获取系统的时间吗？

不可以。Token需要根据系统时间来生成。

C++ SDK ASR请求有DNS解析失败的情况导致异常，报错ali-recog-skd.log:AliSpeech_C++SDK(ERROR): GetInetAddressByHostname:252 DNS: resolved timeout.ali-recog-skd.log:AliSpeech_C++SDK(ERROR): start:76 start failed: DNS: resolved timeout..unimrcpserver_current.log: [ERROR] [[./ali/AliRecogChannel.cpp:772,onTaskFailed]]Ali Task start failed Msg :DNS: resolved timeout., start finised."如何解决？

  • 旧版本：在高并发或者电脑DNS忙碌的情况下容易出现以上问题，建议更新到3.1.X版本，或进行再次重启请求。

  • 更新后的版本：已经对此问题进行防御，若仍然偶现此问题，则为电脑DNS忙碌，需要再次重启请求。

C++ SDK 返回 10000002 时如何定位问题？

10000002 是 C++ SDK 的通用错误码 DefaultErrorCode，不是可以单独确定根因的 OpenSSL 错误码。应结合回调中的详细错误信息、最后发送的指令以及连接日志判断原因。若同时返回 IDLE_TIMEOUT，再按对应任务的空闲超时检查音频发送时序。

C++ SDK（新）集成到其他项目中时，将CMakeLists.txt中的add_definitions(-D_GLIBCXX_USE_CXX11_ABI=0) 修改为add_definitions(-D_GLIBCXX_USE_CXX11_ABI=1)后编译不通过该如何解决？

除了CMakeLists.txt，全工程都需要修改该参数，例如config/linux.thirdparty.debug.cmake和config/linux.thirdparty.release.cmake，请在全目录搜索_GLIBCXX_USE_CXX11_ABI进行修改。

C++ SDK在Windows上使用，报错缺少nlsCommonSdk.dll如何解决？

3.1及以后版本无nlsCommonSdk.dll。

C++ SDK旧版NlsSdkCpp2.0和新版NlsSdkCpp3.X的区别是什么？

NlsSdkCpp2.0版本的SDK每一个请求为一个线程，且接口为同步接口。

NlsSdkCpp3.X版本的SDK内部由第三方库libevent统一处理事件消息，并发性能更强，且接口为异步接口。

_GLIBCXX_USE_CXX11_ABI 与 C11、C++11 有什么区别？

_GLIBCXX_USE_CXX11_ABI 控制 libstdc++ 的新旧 ABI，不是 C11 规范或 C++11 语言标准的启用开关。项目与 SDK 及依赖库的 ABI 配置需要兼容。原工程默认值为 0；需要使用新 ABI 时，应检查整个工程及依赖的构建配置，而不是只改一处宏定义。

C++ 版SDK集成语音识别报错，提示Meta:ACCESS_DENIED:The token '' is invalid!, start finised.start() failed.CbParam: 1 exg.onTaskFailed: status code: 10000011, error message: Stop invoke error. Please check the order of execution or whether the data sent is valid.如何解决？

Meta:ACCESS_DENIED:The token '' is invalid!, start finised.指令牌无效，鉴权失败，请检查appkey是否错误、Token是否填入、Token是否过期。status code: 10000011指接口调用顺序错误（接收到Failed/complete事件时，SDK内部会关闭连接，此时再调用send方法会上报错误）。

C++ 版SDK集成语音识别一句话报错，提示transcriber process start...alispeech-DEBUG start:60 starting transcriber...alispeech-WARNING _on_error:123 retry start: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:852)alispeech-DEBUG _on_close:110 callback on_channel_closedMyCallback.OnRecognitionChannelClosed如何解决？

SSL证书校验失败，请检查发起调用的机器系统时间是否正确。

C++ SDK一句话识别调用stop后返回错误回调状态码40000004该如何解决？{"header":{"namespace":"Default","name":"TaskFailed","status":40000004,"message_id":"xxxxxxxxxxxxxxxxxxxxxxxxx","task_id":"xxxxxxxxxxxxxxxxxxxxxxxxx","status_text":"Gateway:IDLE_TIMEOUT:Websocket session is idle for too long time, the last directive is 'StopRecognition'!"}}

可能是服务端瞬间收到大量请求导致的单个实例无法及时处理，建议重试。

C++ SDK测试Demo成功，集成项目报错，DNS解析失败，报错nls-gateway-cn-shanghai.aliyuncs.com dns failed: nodename nor servname provided, or not known如何解决？

  1. SDK中会查看当前设备开启的所有协议族（IPv4、IPv6）进行DNS解析请求，nls-gateway-cn-shanghai.aliyuncs.com不支持 IPv6，返回解析错误，从而导致SDK DNS解析失败退出。可禁用当前设备的IPv6协议族，后续CppSdk产品改进对这方面进行可配置处理。

  2. 建议升级到3.1.12及以后版本。

C++ SDK测试Demo可以成功，集成项目报错，网络链接失败，报错[dnsEventCallback:465]Node:0x7f087c001030 ai_canonname: nls-gateway-cn-shanghai.aliyuncs.com.gds.alibabadns.com[dnsEventCallback:477]Node:0x7f087c001030 IpV4:106.15.XX.XX[connectProcess:1329]Node:0x7f087c001030 sockFd:41[connectProcess:1347]Node:0x7f087c001030 new Socket ip:106.15.XX.XX port:443 Fd:41.[socketConnect:1458]Node:0x7f087c001030 Connect failed:Network is unreachable. retry...如何解决？

以上现象为无法连接网络，查看日志发现DNS域名解析出来的IP链接不成功，进一步通过Ping判断网络不通。由于本地拦截DNS解析，导致SDK内部libevent的evdns_getaddrinfo获得错误的IP。

解决办法：

  • 3.1.12版本以前可将evdns_getaddrinfo()手动替换成系统的getaddrinfo()。

  • 3.1.12版本可在CMakeLists.txt中修改add_definitions(-DNLS_USE_NATIVE_GETADDRINFO)。

  • 3.1.12及以后版本增加setDirectHost()接口，可以在SDK外部进行DNS解析，获取正确IP后通过该接口设入。

  • 3.1.13及以后版本已解决此问题，若运行时仍存在上述问题，建议调用接口setUseSysGetAddrInfo(true)。

C++ 语音合成Demo，NlsCommonSdk版本20211018基于vc16.0，NlsSdkCpp3.X版本20210629基于vc14.0，Demo程序只执行到OnSynthesisTaskFailed，返回20000000，在win10 X64 vs2015中得不到WAV的可能原因？log信息如下ERROR alibabaNlsLog: [ID:15284][AlibabaNls::ConnectNode::parseFrame:1014]Node:000001D733079F20 Result conversion failed.

NlsSdkCpp3.X-20210629里的Demo不适用于Windows版本程序，alibabacloud-nls-cpp-sdk（github的）里的才是Windows的Demo。

Android SDK

Android SDK是否可以上传opus音频数据，实现实时语音转文字？

ASR中一句话识别和录音文件极速版支持opus数据，实时语音转文字仅支持PCM编码、16 bit采样位数、单声道（mono）。具体详情，请参见接口说明。

Android SDK中使用onNuiNeedAudioData录音数据回调，并在该回调过程中填充录音数据ret = audioRecord.read(buffer, 0, len)。在实时录音转写过程中，突然断网后再连网，录音SDK会自动连接并继续转写吗？

断网后需要重新连接录音SDK，不会自动连接，需要增加重试机制。

Android SDK 的最低系统版本是什么？

移动端 SDK 2.7.4 要求 Android 5.0 及以上版本，API Level 21。其他 SDK 包应以其对应版本的系统要求为准。

Android SDK录音文件识别极速版，是否支持通过任务ID查询任务状态？

不支持。

Android SDK调用文件上传转写极速版，调用int startFileTranscriber(String params, byte[] task_id)后无法收到回调，报错提示“EventE/iDST::NativeNui: no java instance, maybe already released”。

需要核实：

  • 资源文件是否复制成功。

  • CommonUtils.copyAssetsData函数是否已调用。

使用实时语音识别Android SDK，管控台模型选择为8K，但是实际测试中为何将采样率设置成16K才能识别正确？

识别正确与否与设置参数有关，需要排查：

  • nls_config.put("sr_format", "pcm")参数值是否配置为小写模式。

  • 是否设置静态变量SAMPLE_RATE为8000，即public final static int SAMPLE_RATE = 8000。

  • 模型选择是否正确选择为8K模型。

int ret = nui_instance.initialize(this, genInitParams(assets_path,debug_path), Constants.LogLevel.LOG_LEVEL_VERBOSE, true)。在该段代码中，录音权限是打开的，但代码仍然报错240021。

表示FILE_ACCESS_FAIL文件访问错误。需要检查：

  • 是否有文件读写权限。

  • 是否完成SDK配置文件的拷贝，检查是否拷贝完成的代码示例如下。

if (CommonUtils.copyAssetsData(this)) {
Log.i(TAG, "copy assets data done");
} else {
Log.i(TAG, "copy assets failed");
return;
}

使用离线语音合成Android SDK，语音播报时出现不合理断句，该如何处理？

可以通过SSML标记语言尝试解决，更多信息，请参见SSML标记语言介绍。

使用语音合成Android SDK，在调用cancel时候出现一次anr，该如何处理？

SDK接口为同步调用，建议不要在主线程调用SDK接口。

实时语音识别对 Android 版本有要求吗？

有，要求由集成的 SDK 包版本决定。例如，移动端 SDK 2.7.4 要求 Android 5.0 及以上版本，API Level 21。

调用Android SDK时，手机报错提示“audio recoder not init”。

可以通过以下方式排查：

  • 检查AudioRecord是否初始化正常。

  • 检查语音播放器是否有问题。

  • 编写AudioRecord录音代码，测试是否正常。

在模拟器上运行下载的Android程序，程序出现闪退现象，是什么原因？

模拟器可能会出现未知问题，建议使用真机测试。

使用语音识别Android SDK回调onNuiNeedAudioData，但在onNuiEventCallback中回调延迟，并显示错误码50000000。

表示服务端内部错误，请重试。

使用语音合成Android SDK TTS时，报错提示“tts event:TTS_EVENT_ERROR ret 140002”。

建议检查下输入文本是否合规。

不能正常使用语音合成Android SDK。

需要检查以下条件是否满足：

  • 是否已经满足Android SDK语音合成的前提条件，详情请参见前提条件。

  • 是否已开通商用。

iOS SDK

是否支持后台处理？

SDK本身不限制前后台，iOS SDK的样例工程默认仅支持前台处理，如果需要支持后台处理，可以做如下修改：

  1. 在工程Info.plist中添加Required background modes配置，并在该配置下添加item，Value设置为App plays audio or streams audio/video using AirPlay。其中配置类型为Array。

  2. 在录音模块中进入后台时，不停止录音。亦即NLSVoiceRecorder.m中_appResignActive接口中不做停止录音调用。

    - (void)_appResignActive {
    // 进入后台时不停止录音
    // [self stop];
}

下载语音交互iOS SDK至本地库，测试代码时，在模拟器可以正常运行，真机却无法运行，报错提示“Reason: no suitable image found. Did find:xxx”。

建议删除手机上对应的APP后，执行xcode clean，并重新尝试运行。除此以外，还需检查签名的正确性，如果签名不正确，需撤销原来的inHouse证书，重新制作新的证书和provisioning profile，并将代码重新签名，再次打包。

使用智能语音服务集成iOS SDK，接入NuiSdk运行报错MIC。

建议检查下当前录音设备是否有被占用。

使用智能语音服务集成iOS SDK，接入nuisdk.framework后，导入头文件项目失败。

一般情况下是SDK导入有问题导致，请确认以下参数是否已勾选，如果已勾选，建议将头文件导入方式换为#import <nuisdk/NeoNui.h>。即在Xcode项目的Frameworks, Libraries, and Embedded Content中确认nuisdk.framework已添加且设置为Embed & Sign。

使用iOS SDK接入nuisdk.framework后，报错提示“/Users/admin/FlashTranscription_iOS/Fc_ASR.xcodeproj Building for iOS, but the linked and embedded framework 'nuisdk.framework' was built for iOS + iOS Simulator”。

可能因为版本过高导致，建议修改项目配置Validate Workspace为Yes后，重新编译。

使用集成语音服务iOS SDK，在接入nuisdk.framework后报错，需要修改Legacy Build system，才可以运行，是什么原因？

建议修改项目配置Validate Workspace为Yes后，重新编译。

使用一句话识别iOS SDK，配置nuisdk.framework为Embed & Sign后，提示“nuisdk.framework/Headers/NeoNui.h”。

建议检查下头文件是否按照文档正常导入，头文件导入格式为#import <nuisdk/NeoNui.h>。

使用App集成iOS SDK，提交到App store失败，提示“Unsupported Architectures. The executable for AliYunSmart.app/Frameworks/nuisdk.framework contains unsupported architectures '[x86_ _64, i386]'. With error code”。

可能是模拟器架构影响，可以参考如下方法查看framework版本并移除framework模拟器架构。

  1. 进入到framework目录。

  2. 输入命令lipo -info xxxFramework，查看framework的架构版本，如果含有模拟器打包需要把模拟器架构移除。

TRTC实时音视频和语音识别结合，当同时调用麦克风时可能会发生冲突，导致有一方没有声音，如何解决？

建议尝试TRTC的音视频流，然后使用localStream.getAudioTrack获取MediaStreamTrack对象，并转换为符合ASR标准的音频流，之后通过语音识别SDK发起请求。

使用智能语音交互iOS SDK，App是否能在后台模式和终止应用的情况下进行语音播报？

应用被终止无法进行语音播报。

使用语音合成iOS SDK，onNuiTtsUserdataCallback不返回时间戳信息，如何解决？

默认情况SDK不返回时间戳，如果需要获取时间戳信息，可以通过接口setparamTts设置enable_subtitle，详情请参见接口说明。

使用语音合成iOS SDK，如何保存为文件，保存格式是什么？

可以在onNuiTtsUserdataCallback接口参数中将合成的数据保存成文件，合成的格式以传出参数为主，例如[nls_config setObject:@"mp3" forKey:@"encode_type"]。

目前支持格式为PCM、WAV、MP3，需要注意是，语音合成的文档案例中播放器不支持MP3格式音频，直接使用可能产生噪音，但存储的MP3格式文件可以用支持MP3格式的播放软件试听。如果个别音频文件出现少字的现象，可能是因为该发音人合成速度过快（如xiaoyun），部分数据没有写入文件被清除，可以在fwrite后调用fflush保证数据完全写入文件。

- (void)onNuiTtsUserdataCallback:(NSString *)info infoLen:(int)infoLen buffer:(NSData *)data len:(int)len {
    fwrite(data.bytes, 1, data.length, tts_file);
    fflush(tts_file);
}

使用语音合成iOS SDK，连续点击播放按钮，高频率触发播放出现页面终止情况，该如何解决？

由于在线合成时需要连接网络，网络状况会直接影响接口响应时间，如果业务需要快速停止任务并开始下一条，可以根据业务需求调整网络超时时间。

使用集成语音服务iOS SDK，flutter_plugin集成时，报错提示“Undefined symbols for architecture arm64: "std::__1::mutex::~mutex()", referenced from: ___cxx_global_var_init in libflutter_tts.a(ringBuf.o)”。

可以打开iOS工程下的Podfile文件，修改post_install do |installer|部分的代码，再次执行构建即可成功。

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['EXCLUDED_ARCHS[sdk=iphonesimulator*]'] = 'arm64'
      config.build_settings['CLANG_CXX_LANGUAGE_STANDARD'] = 'gnu++17'
    end
  end
end

离线音色“艾佳”的播放声音为什么发生变化？

“艾”字辈音色（包括艾佳）的合成音频采样率为 24000 Hz。如果播放器按 16000 Hz 播放，听感会发生变化。应将播放器的采样率调整为与实际音频一致的 24000 Hz。

使用在线合成语音iOS SDK，写入文件播放声音是杂音，是什么情况？

首先需要确认合成音频格式（PCM、WAV、MP3），如存储的音频流是MP3格式，但播放器不支持该格式音频就会出现杂音的状况，建议更换一下播放软件重试。同时也有用户出现音频只有尾部出现杂音的情况，可以用BeyondCompare查看音频流，是否有日志写入音。

WebSocket

WebSocket 如何发送音频，分片大小如何选择？

控制指令采用含 header 和 payload 的 JSON 文本帧；音频数据通过二进制帧发送，不需要包装成 JSON。

分片大小应与采样率、采样位数、声道数和发送间隔对应。例如，16 kHz、16 bit、单声道 PCM 的 100 ms 音频为 3200 字节；8 kHz 时为 1600 字节。这是按音频时长计算的分片示例，不是仅允许这两种大小。

使用实时语音识别接口WebSocket，设置了32位随机message_id，报错提示Status:40000002 Gateway:MESSAGE_INVALID:Invalid message id ''!。

WebSocket相当于自己去构建的一个请求，message_id就是随机生成的32位唯一ID。

需要将message_id改成32个hex字符，检查一下发送的消息是否符合要求。

WebSocket 连接被关闭但没有明确错误时如何排查？

检查 Token 是否有效，以及是否按任务协议及时发送音频。保留服务端返回的错误事件、关闭码和关闭原因，以便区分鉴权、音频发送和网络问题。

使用实时语音识别WebSocket，在基于Web的JavaScript WebSocket连接成功后，如何获得message_id和task_id？

message_id和task_id是在调用侧自行生成的。

message_id和task_id可以随机生成32位唯一ID，且在一次任务中，task_id保持不变，用以唯一标识该任务；message_id建议在每次发送的消息中重新随机生成，用以标识该消息的唯一性。

实时语音识别是否必须读取本地音频文件？

不需要。示例读取本地文件是为了模拟实时音频流。应用可以持续采集音频，并通过 WebSocket 按协议发送二进制音频。音频格式和控制指令应符合实时语音识别接口说明。

上一篇：语音合成FAQ下一篇：计费定价FAQ