Java SDK

使用前准备

• 已开通智能语音交互服务并创建项目。操作方法，请参见快速开始。

• 准备项目Appkey，以及用于获取NLS Token的AccessKey ID和AccessKey Secret。项目与模型配置，请参见管理项目；Token的获取与有效期说明，请参见获取Token。

• 使用JDK 8或更高版本。音频编码、采样率和模型要求，请参见一句话识别接口说明。

安装SDK

在Maven项目的pom.xml中添加以下依赖。示例使用Java SDK 2.2.1。

<dependency>
    <groupId>com.alibaba.nls</groupId>
    <artifactId>nls-sdk-recognizer</artifactId>
    <version>2.2.1</version>
</dependency>
<!-- JDK 9及以上版本还需添加以下依赖。 -->
<dependency>
    <groupId>javax.xml.bind</groupId>
    <artifactId>jaxb-api</artifactId>
    <version>2.3.1</version>
</dependency>

从2.1.0起，nls-sdk-short-asr更名为nls-sdk-recognizer。从旧版本升级时，移除nls-sdk-short-asr依赖，并按编译提示补齐回调方法。如果项目已依赖Netty，使用4.1.17.Final或更高版本。

代码示例

下载nls-sample-16k.wav，放到程序的工作目录。该文件为单声道、16 kHz WAV音频；项目中需选择与音频语种和采样率匹配的模型。使用其他音频时，同步调整代码中的文件名、编码格式和采样率。

配置以下环境变量。AccessKey与Appkey需属于用于调用服务的账号。

import com.alibaba.nls.client.AccessToken;
import com.alibaba.nls.client.protocol.InputFormatEnum;
import com.alibaba.nls.client.protocol.NlsClient;
import com.alibaba.nls.client.protocol.SampleRateEnum;
import com.alibaba.nls.client.protocol.asr.SpeechRecognizer;
import com.alibaba.nls.client.protocol.asr.SpeechRecognizerListener;
import com.alibaba.nls.client.protocol.asr.SpeechRecognizerResponse;
import java.io.FileInputStream;
import java.io.InputStream;

public class SpeechRecognizerDemo {
    public static void main(String[] args) throws Exception {
        String appKey = requireEnv("NLS_APP_KEY");
        String accessKeyId = requireEnv("ALIYUN_AK_ID");
        String accessKeySecret = requireEnv("ALIYUN_AK_SECRET");
        String audioFile = "nls-sample-16k.wav";

        // 获取NLS Token；在有效期结束前重新获取并更新客户端。
        AccessToken accessToken = new AccessToken(accessKeyId, accessKeySecret);
        accessToken.apply();
        NlsClient client = new NlsClient(
                "wss://nls-gateway-cn-shanghai.aliyuncs.com/ws/v1", accessToken.getToken());
        SpeechRecognizer recognizer = null;
        try {
            recognizer = new SpeechRecognizer(client, createListener());
            recognizer.setAppKey(appKey);
            // 编码格式和采样率须与音频文件及项目模型一致。
            recognizer.setFormat(InputFormatEnum.WAV);
            recognizer.setSampleRate(SampleRateEnum.SAMPLE_RATE_16K);
            recognizer.setEnableIntermediateResult(true);
            recognizer.addCustomedParam("enable_voice_detection", true);

            recognizer.start();
            try (InputStream audio = new FileInputStream(audioFile)) {
                // 从文件模拟实时音频：每次发送3200字节，间隔100毫秒。
                recognizer.send(audio, 3200, 100);
            }
            recognizer.stop();
        } finally {
            if (recognizer != null) {
                recognizer.close();
            }
            client.shutdown();
        }
    }

    private static SpeechRecognizerListener createListener() {
        return new SpeechRecognizerListener() {
            @Override
            public void onStarted(SpeechRecognizerResponse response) {
                System.out.println("Task ID: " + response.getTaskId());
            }

            @Override
            public void onRecognitionResultChanged(SpeechRecognizerResponse response) {
                System.out.println("RecognitionResultChanged: " + response.getRecognizedText());
            }

            @Override
            public void onRecognitionCompleted(SpeechRecognizerResponse response) {
                System.out.println("RecognitionCompleted: " + response.getRecognizedText());
            }

            @Override
            public void onFail(SpeechRecognizerResponse response) {
                System.err.println("Task ID: " + response.getTaskId()
                        + ", status: " + response.getStatus()
                        + ", message: " + response.getStatusText());
            }
        };
    }

    private static String requireEnv(String name) {
        String value = System.getenv(name);
        if (value == null || value.isEmpty()) {
            throw new IllegalArgumentException("Missing environment variable: " + name);
        }
        return value;
    }
}

识别结果通过onRecognitionResultChanged和onRecognitionCompleted回调返回；请求失败时，通过onFail获取任务ID、状态码和错误信息。

关键接口

NlsClient使用Netty，创建实例会消耗时间和资源。客户端的创建和关闭可与应用生命周期保持一致；识别任务则分别创建和关闭SpeechRecognizer。更多方法，请参见Java API接口说明。

运行完整示例包

也可以下载完整示例工程，使用其中的调用程序和压测程序。

下载nls-sdk-java-demo。

解压后，在工程根目录运行mvn package。生成的可执行文件位于nls-example-recognizer/target/nls-example-recognizer-2.0.0-jar-with-dependencies.jar。将JAR包和配套音频复制到目标服务器后，运行以下命令，并按提示提供Appkey、NLS Token和可选的服务地址。程序会在工作目录生成logs/nls.log。

java -cp nls-example-recognizer-2.0.0-jar-with-dependencies.jar com.alibaba.nls.client.SpeechRecognizerDemo

需要压测时，使用以下命令，并按提示设置并发数：

java -jar nls-example-recognizer-2.0.0-jar-with-dependencies.jar

服务地址为wss://nls-gateway-cn-shanghai.aliyuncs.com/ws/v1。

压测使用16 kHz PCM音频，并发数需在已开通服务的并发额度内。压测调用同样适用服务的计费规则，运行前确认服务版本、计费方式和并发额度。

常见问题

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

recognizer.send(audio, 3200, 100);

recognizer.send(data);
Thread.sleep(100);