本文介紹如何使用智能語音交互一句話識別的Java SDK,包括SDK的安裝方法及SDK代碼示例等。
注意事項
在使用SDK前,請先閱讀接口說明,詳情請參見接口說明。
從2.1.0版本開始,原有nls-sdk-short-asr更名為nls-sdk-recognizer,升級時需確認已刪除nls-sdk-short-asr,并按編譯提示添加相應的回調方法。
下載安裝
從Maven服務器下載最新版本SDK。
<dependency> <groupId>com.alibaba.nls</groupId> <artifactId>nls-sdk-recognizer</artifactId> <version>2.2.1</version> </dependency>
解壓ZIP文件,在pom目錄運行
mvn package
,會在target目錄生成可執行JAR:nls-example-recognizer-2.0.0-jar-with-dependencies.jar,將JAR包拷貝至目標服務器,用于快速驗證及服務壓測。服務驗證。
運行如下代碼,并按提示提供相應參數。運行后在命令執行目錄生成logs/nls.log。
java -cp nls-example-recognizer-2.0.0-jar-with-dependencies.jar com.alibaba.nls.client.SpeechRecognizerDemo
服務壓測。
運行如下代碼,并按提示提供相應參數。其中阿里云服務URL參數為:
wss://nls-gateway-cn-shanghai.aliyuncs.com/ws/v1
,語音文件為16k采樣率PCM格式文件,并發數根據您的購買情況進行選擇。java -jar nls-example-recognizer-2.0.0-jar-with-dependencies.jar
重要自行壓測超過2路并發會產生費用。
關鍵接口
NlsClient:語音處理客戶端,利用該客戶端可以進行一句話識別、實時語音識別和語音合成的語音處理任務。該客戶端為線程安全,建議全局僅創建一個實例。
SpeechRecognizer:一句話識別處理類,通過該接口設置請求參數,發送請求及聲音數據。非線程安全。
SpeechRecognizerListener:識別結果監聽類,監聽識別結果。非線程安全。
更多介紹,請參見Java API接口說明。
SDK調用注意事項:
NlsClient使用了Netty框架,NlsClient對象的創建會消耗一定時間和資源,一經創建可以重復使用。建議調用程序將NlsClient的創建和關閉與程序本身的生命周期結合。
SpeechRecognizer對象不可重復使用,一個識別任務對應一個SpeechRecognizer對象。例如,N個音頻文件要進行N次識別任務,需要創建N個SpeechRecognizer對象。
SpeechRecognizerListener對象和SpeechRecognizer對象是一一對應的,不能將一個SpeechRecognizerListener對象設置到多個SpeechRecognizer對象中,否則不能將各識別任務區分開。
Java SDK依賴Netty網絡庫,如果您的應用依賴Netty,其版本需更新至4.1.17.Final及以上。
代碼示例
示例中使用的音頻文件為16000 Hz采樣率,請在管控臺中將AppKey對應項目的模型設置為通用模型,以獲取準確的識別效果。如果使用其他音頻,請設置為支持該音頻場景的模型,關于模型設置,請參見管理項目。
示例中使用SDK內置的默認一句話識別服務的外網訪問服務URL,如果您使用阿里云上海ECS,且需要使用內網訪問服務URL,則在創建NlsClient對象時,設置內網訪問的URL:
client = new NlsClient("ws://nls-gateway-cn-shanghai-internal.aliyuncs.com/ws/v1", accessToken);
調用接口前,需配置環境變量,通過環境變量讀取訪問憑證。智能語音交互的AccessKey ID、AccessKey Secret和AppKey的環境變量名:ALIYUN_AK_ID、ALIYUN_AK_SECRET、NLS_APP_KEY。
import java.io.File;
import java.io.FileInputStream;
import java.io.IOException;
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 org.slf4j.Logger;
import org.slf4j.LoggerFactory;
/**
* 此示例演示了:
* ASR一句話識別API調用。
* 動態獲取Token。獲取Token具體操作,請參見:http://m.bestwisewords.com/document_detail/450514.html
* 通過本地文件模擬實時流發送。
* 識別耗時計算。
*/
public class SpeechRecognizerDemo {
private static final Logger logger = LoggerFactory.getLogger(SpeechRecognizerDemo.class);
private String appKey;
NlsClient client;
public SpeechRecognizerDemo(String appKey, String id, String secret, String url) {
this.appKey = appKey;
//應用全局創建一個NlsClient實例,默認服務地址為阿里云線上服務地址。
//獲取Token,實際使用時注意在accessToken.getExpireTime()過期前再次獲取。
AccessToken accessToken = new AccessToken(id, secret);
try {
accessToken.apply();
System.out.println("get token: " + accessToken.getToken() + ", expire time: " + accessToken.getExpireTime());
if(url.isEmpty()) {
client = new NlsClient(accessToken.getToken());
}else {
client = new NlsClient(url, accessToken.getToken());
}
} catch (IOException e) {
e.printStackTrace();
}
}
private static SpeechRecognizerListener getRecognizerListener(int myOrder, String userParam) {
SpeechRecognizerListener listener = new SpeechRecognizerListener() {
//識別出中間結果。僅當setEnableIntermediateResult為true時,才會返回該消息。
@Override
public void onRecognitionResultChanged(SpeechRecognizerResponse response) {
//getName是獲取事件名稱,getStatus是獲取狀態碼,getRecognizedText是語音識別文本。
System.out.println("name: " + response.getName() + ", status: " + response.getStatus() + ", result: " + response.getRecognizedText());
}
//識別完畢
@Override
public void onRecognitionCompleted(SpeechRecognizerResponse response) {
//getName是獲取事件名稱,getStatus是獲取狀態碼,getRecognizedText是語音識別文本。
System.out.println("name: " + response.getName() + ", status: " + response.getStatus() + ", result: " + response.getRecognizedText());
}
@Override
public void onStarted(SpeechRecognizerResponse response) {
System.out.println("myOrder: " + myOrder + "; myParam: " + userParam + "; task_id: " + response.getTaskId());
}
@Override
public void onFail(SpeechRecognizerResponse response) {
//task_id是調用方和服務端通信的唯一標識,當遇到問題時,需要提供此task_id。
System.out.println("task_id: " + response.getTaskId() + ", status: " + response.getStatus() + ", status_text: " + response.getStatusText());
}
};
return listener;
}
//根據二進制數據大小計算對應的同等語音長度
//sampleRate僅支持8000或16000。
public static int getSleepDelta(int dataSize, int sampleRate) {
// 僅支持16位采樣。
int sampleBytes = 16;
// 僅支持單通道。
int soundChannel = 1;
return (dataSize * 10 * 8000) / (160 * sampleRate);
}
public void process(String filepath, int sampleRate) {
SpeechRecognizer recognizer = null;
try {
//傳遞用戶自定義參數
String myParam = "user-param";
int myOrder = 1234;
SpeechRecognizerListener listener = getRecognizerListener(myOrder, myParam);
recognizer = new SpeechRecognizer(client, listener);
recognizer.setAppKey(appKey);
//設置音頻編碼格式。如果是OPUS文件,請設置為InputFormatEnum.OPUS。
recognizer.setFormat(InputFormatEnum.PCM);
//設置音頻采樣率
if(sampleRate == 16000) {
recognizer.setSampleRate(SampleRateEnum.SAMPLE_RATE_16K);
} else if(sampleRate == 8000) {
recognizer.setSampleRate(SampleRateEnum.SAMPLE_RATE_8K);
}
//設置是否返回中間識別結果
recognizer.setEnableIntermediateResult(true);
//設置是否打開語音檢測(即vad)
recognizer.addCustomedParam("enable_voice_detection",true);
//此方法將以上參數設置序列化為JSON發送給服務端,并等待服務端確認。
long now = System.currentTimeMillis();
recognizer.start();
logger.info("ASR start latency : " + (System.currentTimeMillis() - now) + " ms");
File file = new File(filepath);
FileInputStream fis = new FileInputStream(file);
byte[] b = new byte[3200];
int len;
while ((len = fis.read(b)) > 0) {
logger.info("send data pack length: " + len);
recognizer.send(b, len);
//本案例用讀取本地文件的形式模擬實時獲取語音流,因為讀取速度較快,這里需要設置sleep時長。
// 如果實時獲取語音則無需設置sleep時長,如果是8k采樣率語音第二個參數設置為8000。
int deltaSleep = getSleepDelta(len, sampleRate);
Thread.sleep(deltaSleep);
}
//通知服務端語音數據發送完畢,等待服務端處理完成。
now = System.currentTimeMillis();
//計算實際延遲,調用stop返回之后一般即是識別結果返回時間。
logger.info("ASR wait for complete");
recognizer.stop();
logger.info("ASR stop latency : " + (System.currentTimeMillis() - now) + " ms");
fis.close();
} catch (Exception e) {
System.err.println(e.getMessage());
} finally {
//關閉連接
if (null != recognizer) {
recognizer.close();
}
}
}
public void shutdown() {
client.shutdown();
}
public static void main(String[] args) throws Exception {
String appKey = System.getenv().get("NLS_APP_KEY");
String id = System.getenv().get("ALIYUN_AK_ID");
String secret = System.getenv().get("ALIYUN_AK_SECRET");
String url = System.getenv().getOrDefault("NLS_GATEWAY_URL", "wss://nls-gateway-cn-shanghai.aliyuncs.com/ws/v1");
SpeechRecognizerDemo demo = new SpeechRecognizerDemo(appKey, id, secret, url);
//本案例使用本地文件模擬發送實時流數據。
demo.process("./nls-sample-16k.wav", 16000);
//demo.process("./nls-sample.opus", 16000);
demo.shutdown();
}
}
常見問題
使用Java SDK,SpeechRecognizer recognizer如何調用stop()實現通知服務端語音數據發送完畢?
正常情況下自動取調用,不需要單獨調用stop()。如果10秒之內沒有語音數據發給服務側, 會報錯41010120。如果一直實時發送語音數據給服務端,識別在服務側是一直進行的,您可以通過設置
enable_intermediate_result=true
參數實時獲取識別結果。如果您判斷一句話結束,也可以主動調用stop()停止發送數據,獲取最終識別結果。
Java版SDK可以直接提供上傳音頻文件的方式進行識別嗎?
如下圖所示,SDK示例通過調用RESTfulAPI接口,實現上傳音頻文件進行識別,詳情請參見一句話識別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是用語音文件模擬實時語音流的速度發送語音,通常一次發送間隔時間為100 ms或200 ms(sleepInterval)的語音數據,數據量(batchSize)和采樣率有關:發送間隔過大,會導致延遲較大,容易斷連;發送間隔過小,會消耗服務端和網絡資源。可以適當實驗調整到合適數值。
第2個接口中ins
為模擬語音流,需要控制發送速率。ins中的數據每間隔100 ms,發送3200字節(16000采樣率)。調用示例:
public void send(ins, 3200, 100); // 16 kHz語音
第3個接口中data
為一次性發送的數據,控制循環調用的間隔,調用示例:
recognizer.send(data); // 100 ms 語音數據
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?
請參見V1.0 Java SDK(不推薦)安裝Alibaba Cloud SDK for Java。
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>