全部产品

Java SDK

更新时间:2017-08-16 11:30:07   分享:   

功能介绍

语音SDK的Java版本提供自然语音理解NLU服务。

SDK下载地址

NLU_JavaSDK

请注意:sdk内部不自带语音采集的功能,只提供将语音流与文字互转和语意识别的功能。

示例说明

下载地址中包含了Java SDK的jar包,以及测试用的demo工程,用户只需在工程中通过“Java Build Path”->“Add External JARs”将jar包导入,即可运行

SDK调用顺序

  1. 创建一个NlsClient的实例并调用init()方法来初始化客户端

  2. 提取语音数据并创建语音识别请求,至少填写appKey及需要识别的语音数据的格式。创建一个NlsListener的实现类。

  3. 调用NlsClient的createNlsFuture(第2步中的listener实例作为入参之一,用来处理返回结果)方法获取future,通过future的sendVoice方法来发送语音数据并在listener中处理返回结果。

  4. 通过future的sendFinishSignal来结束语音文件的发送,ASR服务收到这个结束信号后,会返回处理结果。

  5. 如有多个识别需要,重复步骤2-4。

  6. 调用NlsClient的close()方法来关闭客户端并释放资源。

SDK调用注意事项

  1. NlsClient创建一次可以重复使用,每次创建消耗性能

  2. NlsClient使用了netty的框架,创建时比较消耗时间和资源,但创建之后可以重复利用。建议调用程序将NlsClient的创建和关闭与程序本身的生命周期结合。

  3. 每一次调用语音识别请求时注入的NlsListener只对本次语音识别的生命周期负责。

  4. 每次调用createNlsFuture(NlsRequest req, com.alibaba.idst.nls.event.NlsListener listener)方法做语音识别和对话时,注入的listener只对本次识别起作用。其他的语音识别进程不会触发该listener。

  5. NlsRequest里面的语音格式请与语音文件的格式保持一致。目前SDK支持pcm和opu格式,opu格式请参考opus编解码文档进行压缩。

  6. sdk只会根据该格式来切分和发送语音文件,如果两个不一致,后续的一切都是错误的。

  7. NlsListener的实现类里面,处理返回结果的代码尽量耗时剪短,最好不要涉及I/O操作。

  8. NlsListener的实现类中的处理方法是在NlsClient的语音识别线程中调用的,太长的操作时间导致线程不能及时释放会影响其他识别进程的顺利进行,同时也会影响整个程序的loading。I/O操作应该禁止在该实现类中出现,最好使用触发的方式将操作转移到其他线程中去进行。

  9. 并发或多线程支持,如果需要在您的应用支持多个并发请求,请不要重复创建NlsClient对象。正确的做法是构建不同的NlsRequest对象,同时创建不同的NlsListener,并传入NlsRequest对象。这样就可以并发不同请求并且拿到正确的相应的结果。

重要接口说明

com.alibaba.idst.nls.NlsClient


语音sdk对外暴露的类,调用程序通过调用该类的init()、close()、createNlsFuture()等方法来打开、关闭或发送语音数据。

初始化NlsClient

public void init((boolean sslMode, int port)

  • 说明 初始化NlsClient,创建好websocket client factory
  • 参数

    • sslMode 是否采用ssl模式,一般设置为true
    • port 端口号,一般为443
  • 返回值 null

设置服务器地址

public void setHost(String host)

  • 说明 设置服务器地址
  • 参数

  • 返回值 null

实例化NlsFuture请求

public NlsFuture createNlsFuture(NlsRequest req, com.alibaba.idst.nls.event.NlsListener listener)

  • 说明 实例化NlsFuture请求,传入请求和监听器
  • 参数

    • req 请求对象
    • listener 回调数据的监听器
  • 返回值 future

关闭NlsClient

public void close()

  • 说明 关闭websocket client factory,释放资源
  • 参数

    null

  • 返回值 null

com.alibaba.idst.nls.event.NlsListener


语音识别是一个非常漫长的过程,为了不影响服务端的正常工作,语音sdk被设计成异步模式,调用程序将语音客户端建立好并将语音数据交给sdk后就可以离开。在收到语音数据之后的处理需要通过实现该接口来完成。每一个识别过程创建的时候都需要注入侦听者以响应语音识别的结果。

识别结果回调

void onMessageReceived(NlsEvent e);

  • 说明 识别结果回调
  • 参数

    • NlsEvent Nls服务结果的对象 识别结果在e.getResponse()中
  • 返回值 null

识别失败回调

void onOperationFailed(NlsEvent e);

  • 说明 识别失败回调
  • 参数

    • NlsEvent Nls服务结果的对象 错误信息在e.getErrorMessage()中
  • 返回值 null

socket 连接关闭的回调

void onChannelClosed(NlsEvent e);

  • 说明 socket 连接关闭的回调
  • 参数

    • NlsEvent Nls服务结果的对象
  • 返回值 null

com.alibaba.idst.nls.protocol.NlsRequest


语音识别的请求封装对象。调用程序需要至少在请求对象里设定好调用者的appKey和语音数据的格式以便后台服务能正确识别并识别语音。

初始化Nls 请求:NlsRequest mNlsRequest = new NlsRequest(proto)

public void setAppKey(String app_key)

  • 说明 设置应用的appkey,appkey需要先申请再使用。
  • 参数
    • app_key
  • 返回值 null

public void setAsrFormat(String sc)

  • 说明 设置语音识别的语音格式,一般为pcm。若使用opu格式的语音,请参考opus编解码文档说明进行编码设置。

    该项在使用语音识别服务时必须设置,起到初始化作用。

  • 参数
    • sc 一般为pcm。
  • 返回值 null

public void setAsrUserId(String id)

  • 说明 设置用户id
  • 参数
    • id 设置用户id 热词必须设置。
  • 返回值 null

public void setAsrVocabularyId(String vocabularyId)

  • 说明 设置词表id
  • 参数
    • id 热词使用
  • 返回值 null

public void enableNLUResult()

  • 说明
    • 启用nlu
  • 参数
  • 返回值 null

public void authorize(String id, String secret)

  • 说明 数加认证模块,所有的请求都必须通过authorize方法认证通过,才可以使用。 id和secret需要申请获取。
  • 参数
    • id id。
    • secret 对应密钥。
  • 返回值 null

com.alibaba.idst.nls.internal.protocol.NlsRequestProto


NlsRequest对象初始化时需要注入的参数。

public void setApp_id(String app_id)

  • 设置application_id.

public void setApp_user_id(String app_user_id)

  • 设置app_user_id.

com.alibaba.idst.nls.NlsFuture


NlsFuture是具体操作语音的对象类,语音数据的发送/接收都通过这个类进行操作。public NlsFuture sendVoice(byte[] data, int offset, int length)

  • 说明 语音识别时,发送语音文件的方法
  • 参数
    • data byte[]类型的语音流
    • offset
    • length
  • 返回值 NlsFuture

public NlsFuture sendFinishSignal()

  • 说明 语音识别结束时,发送结束符
  • 参数

  • 返回值 NlsFuture

public boolean await(int timeout)

  • 说明 请求超时时间
  • 参数
    • timeout 请求发送出去后,等待服务端结果返回的超时时间,单位ms
  • 返回值 true false

com.alibaba.idst.nls.protocol.NlsResponse


语音识别的返回结果封装对象。返回结果告知语音识别是否成功,语音识别结果或部分结果(视调用程序需要的返回方式而定),语音识别是否已经结束。

public String getAsr_ret()

  • 说明 获取语音识别的结果
  • 参数
    • null
  • 返回值 String

public String getDs_ret()

  • 说明 获取NLU的结果
  • 参数
    • null
  • 返回值 String

错误码

状态 status_code CloseFrame状态码 HTTP语义
成功 200 1000 成功处理
请求格式有误 400 4400 错误请求
需要鉴权信息 401 4401 请求要求身份验证
鉴权失败 403 4403 服务器拒绝请求
超出最大并发量 429 4429 太多请求
请求超时 408 4408 处理请求超时
处理出错 500 4500 服务器内部错误
服务不可用 503 4503 服务不可用

结果回调

返回的识别结果result是一个NlsResponse的对象,NLU的返回需要参见下面的“语义表示协议”:

  1. {
  2. "status" : "1",// 服务器状态,0为失败,非零为成功
  3. "id" : "",
  4. "finish" : "1",
  5. "results" : {
  6. "asr_out" : {
  7. "result" : "",// 语音识别结果
  8. "status" : 1,// 服务器状态,0为失败,非零为成功
  9. "finish" : 1,// 0为未结束,非零为结束,识别是否已经结束
  10. "version" : "4.0"
  11. },
  12. "ds_out" : {
  13. "dm_result" : {// 保留字段
  14. },
  15. "nlg_result" : {// 保留字段
  16. },
  17. "status" : "ok",
  18. "ds_rt" : "",
  19. "nlu_result" : {// nlu结果
  20. },
  21. "web_result" : {// 保留字段
  22. }
  23. },
  24. "out" : {}// 保留字段
  25. },
  26. "bstream_attached" : false,// 应答包的后面是不是还接着二进制语音流。
  27. "version" : "4.0"// 协议版本号
  28. }

完整示例

  1. package com.demo;
  2. import java.io.*;
  3. import com.alibaba.idst.nls.protocol.NlsRequestProto;
  4. import com.alibaba.idst.nls.protocol.NlsResponse;
  5. import com.alibaba.idst.nls.NlsClient;
  6. import com.alibaba.idst.nls.NlsFuture;
  7. import com.alibaba.idst.nls.event.NlsEvent;
  8. import com.alibaba.idst.nls.event.NlsListener;
  9. import com.alibaba.idst.nls.protocol.NlsRequest;
  10. public class NluDemo implements NlsListener {
  11. private NlsClient client = new NlsClient();
  12. public NluDemo() {
  13. System.out.println("init Nls client...");
  14. // 初始化NlsClient
  15. client.init();
  16. }
  17. public void shutDown() {
  18. System.out.println("close NLS client");
  19. // 关闭客户端并释放资源
  20. client.close();
  21. System.out.println("demo done");
  22. }
  23. public void startNLU() {
  24. System.out.println("open audio file...");
  25. FileInputStream fis = null;
  26. try {
  27. String filePath = "src/test/resources/sample.pcm";
  28. File file = new File(filePath);
  29. fis = new FileInputStream(file);
  30. } catch (Exception e) {
  31. e.printStackTrace();
  32. }
  33. if(fis != null) {
  34. System.out.println("create NLS future");
  35. try {
  36. NlsRequest req = new NlsRequest();
  37. req.setAppKey(""); // appkey列表中获取,本demo可同时支持流式和非流式appkey
  38. req.setAsrFormat("pcm"); // 设置语音文件格式为pcm,我们支持16k 16bit 的无头的pcm文件。
  39. /*单独使用nlu*/
  40. req.setAsrFake("text"); //使用文本请求nlu结果
  41. /*单独使用nlu*/
  42. req.enableNLUResult(); // 设置nlu请求
  43. req.authorize("", ""); // 请替换为用户申请到的Access Key ID和Access Key Secret
  44. NlsFuture future = client.createNlsFuture(req, this);
  45. System.out.println("call NLS service");
  46. System.out.println(req.toJson());
  47. byte[] b = new byte[8000];
  48. int len = 0;
  49. if (req.getAsrFake() == null ) {
  50. while ((len = fis.read(b)) > 0) {
  51. future.sendVoice(b, 0, len); // 发送语音数据
  52. Thread.sleep(50);
  53. }
  54. future.sendFinishSignal(); // 语音识别结束时,发送结束符
  55. }
  56. System.out.println("main thread enter waiting for less than 10s.");
  57. future.await(10000); // 设置服务端结果返回的超时时间
  58. } catch(Exception e) {
  59. e.printStackTrace();
  60. }
  61. System.out.println("calling NLS service end");
  62. }
  63. }
  64. @Override
  65. public void onMessageReceived(NlsEvent e) {
  66. NlsResponse response = e.getResponse();
  67. String result = "";
  68. int statusCode = response.getStatus_code();
  69. System.out.println(statusCode);
  70. if (response.getDs_ret() != null) {
  71. result = "get ds result: statusCode=[" + statusCode + "], " + response.getDs_ret();
  72. }
  73. if (response.getAsr_ret() == null) {
  74. result += "\nget asr result: statusCode=[" + statusCode + "], " + response.getAsr_ret();
  75. }
  76. if (result != null) {
  77. System.out.println(result);
  78. }
  79. else {
  80. System.out.println(response.jsonResults.toString());
  81. }
  82. }
  83. @Override
  84. public void onOperationFailed(NlsEvent e) {
  85. //识别失败的回调
  86. String result = "";
  87. result += "on operation failed: statusCode=["+ e.getResponse().getStatus_code()+"], " +e.getErrorMessage();
  88. System.out.println(result);
  89. }
  90. @Override
  91. public void onChannelClosed(NlsEvent e) {
  92. System.out.println("on websocket closed.");
  93. }
  94. /**
  95. * @param args
  96. */
  97. public static void main(String[] args) {
  98. NluDemo nluDemo = new NluDemo();
  99. nluDemo.startNLU();
  100. nluDemo.shutDown();
  101. }
  102. }
本文导读目录
本文导读目录
以上内容是否对您有帮助?