全部產品
Search
文件中心

Intelligent Speech Interaction:Java SDK

更新時間:Oct 29, 2026

通過一句話識別Java SDK發送音頻流並接收識別結果。本文提供SDK安裝、用戶端初始化和完整調用樣本,以及發送音頻、結束識別和排查依賴問題的說明。

使用前準備

  • 已開通Intelligent Speech Interaction服務並建立專案。操作方法,請參見快速開始。

  • 準備專案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需屬於用於調用服務的帳號。

環境變數

含義

ALIYUN_AK_ID

AccessKey ID,用於申請NLS Token。

ALIYUN_AK_SECRET

AccessKey Secret,用於申請NLS Token。

NLS_APP_KEY

Intelligent Speech Interaction專案的Appkey。

重要

AccessKey用於身份認證,避免將其寫入程式碼在程式中或寫入日誌。NLS Token有有效期間,長期啟動並執行應用需在到期前重新擷取Token,並通過NlsClient.setToken()更新用戶端。

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,
                "nlsmeta.ap-southeast-1.aliyuncs.com", "ap-southeast-1", "2019-07-17");
        accessToken.apply();
        NlsClient client = new NlsClient(
                "wss://nls-gateway-ap-southeast-1.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

語音處理用戶端,支援一句話識別、即時語音辨識和語音合成。安全執行緒,建議全域複用一個執行個體,在應用退出時調用shutdown()釋放資源。

SpeechRecognizer

設定一句話識別參數、發送音頻和結束識別。非安全執行緒,每個識別任務建立一個對象,不重複用於其他任務;任務結束後調用close()。

SpeechRecognizerListener

接收開始、中間結果、完成和失敗事件。非安全執行緒,與SpeechRecognizer一一對應,不將同一個監聽器綁定到多個識別對象。

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-ap-southeast-1.aliyuncs.com/ws/v1。

壓測使用16 kHz PCM音頻,並發數需在已開通服務的並發額度內。壓測調用同樣適用服務的計費規則,運行前確認服務版本、計費方式和並發額度。

常見問題

何時調用stop()?

音頻發送完成後,調用recognizer.stop()發送StopRecognition指令,並等待識別完成。開啟語音檢測(VAD)時,服務端也可以在檢測到語音結束後返回RecognitionCompleted事件。

語音發送期間需保持連續、即時的資料流;長時間未發送資料會觸發空閑逾時。需要中間結果時,在start()前調用setEnableIntermediateResult(true)。

如何識別本地音頻檔案?

本頁樣本從本地檔案讀取音頻,並按即時速度發送給服務端。也可以通過RESTful API上傳音頻檔案,調用方式請參見一句話識別RESTful API。

如何使用send()發送音頻?

一句話識別提供以下四個send()重載:

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);

send(byte[])、send(byte[], int)和send(InputStream)按資料到達或讀取的速度發送,不自動按音頻時間長度設定間隔。即時採集音頻時,按採集速度連續發送;從檔案類比即時資料流時,可使用帶batchSize和sleepInterval的方法控制發送速度。

16位、單聲道PCM音頻在16 kHz採樣率下,每100毫秒對應3200位元組;8 kHz時,3200位元組對應200毫秒。其他編碼格式需按壓縮後的資料量調整每批位元組數和發送間隔。發送間隔過大可能增加延遲或導致斷連,過小會增加服務端和網路資源消耗。

基於前面的完整樣本,發送16 kHz音頻檔案流可使用:

recognizer.send(audio, 3200, 100);

自行迴圈讀取檔案時,也可以使用send(byte[], int),或為完整的100毫秒音頻資料調用send(byte[]):

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

上述data表示16 kHz、16位、單聲道PCM的3200位元組音頻;最後一批不足3200位元組時,使用send(data, length)傳入實際長度。

如何通過日誌分析延遲?

一句話識別的結束延遲,可以用發送StopRecognition到收到RecognitionCompleted的時間差計算。例如,兩條日誌的時間分別為14:24:44.844和14:24:44.984,對應延遲為140毫秒。

同樣的方法也適用於其他語音處理任務:

  • 即時語音辨識使用StopTranscription和TranscriptionCompleted的時間差。

  • 語音合成的首包延遲使用發送StartSynthesis到收到首個音頻包的時間差。例如,14:32:13.813到14:32:14.035對應222毫秒。

完整樣本包已配置日誌。自行整合SDK時,按應用的日誌架構配置日誌輸出。通過RESTful API調用時,可在用戶端記錄請求和回應時間來計算延遲。

找不到com.alibaba的JAR包怎麼辦?

通過Alibaba Cloud SDK for Java擷取Token時,需安裝相應依賴。安裝方法,請參見V1.0 Java SDK。

org.json.JSONArray.iterator()報錯怎麼辦?

舊工程通過Alibaba Cloud SDK for Java擷取用戶端或Token時,若出現org.json.JSONArray.iterator()Ljava/util/Iterator方法不存在的錯誤,檢查運行時載入的JSON庫與SDK所需版本是否一致,並排除重複依賴。檢查org.json:json和com.google.code.gson:gson等相關依賴是否完整,使用與當前Alibaba Cloud SDK相容的版本。