一句話識別將 60 秒以內的短語音轉換為文本,適用於對話聊天、控制口令、語音輸入法和語音搜尋等情境。用戶端通過 WebSocket 發送音頻流,接收識別事件和結果。
使用須知
音頻編碼和請求參數必須一致,否則可能導致識別失敗或結果為空白。
聲道和採樣位元:單聲道、16 bit。
音頻格式:PCM、PCM 編碼的 WAV、OGG 封裝的 OPUS、OGG 封裝的 SPEEX、AMR。
採樣率:8000 Hz 或 16000 Hz。專案模型必須支援音頻所用的採樣率和語言。
音頻時間長度:不超過 60 秒。
音頻大小:不超過 2 MB。
通過請求參數可配置中間結果、標點和逆文本正則化(ITN)等功能。
選擇識別模型
語種和方言模型不能通過請求參數指定。在Intelligent Speech Interaction控制台的全部專案頁面,找到目標專案,單擊專案功能配置,選擇與音頻語言和採樣率匹配的模型。配置方法請參見管理專案。
可選模型以專案功能配置頁面為準。先選擇採樣率,再選擇對應的語言模型。
服務地址
通過公網使用以下 WebSocket 地址:wss://nls-gateway-ap-southeast-1.aliyuncs.com/ws/v1。
互動流程
以下流程適用於 WebSocket 及基於該協議的 SDK。RESTful API 的調用方式,請參見RESTful API。
所有服務端事件的 header 均包含本次識別任務的 task_id,可用於關聯請求、響應和排查問題。
1. 鑒權
用戶端建立 WebSocket 串連時,使用 NLS Token 進行鑒權。
Token 的擷取方法,請參見擷取 Token。
2. 開始識別
用戶端發送 StartRecognition 指令並設定識別參數。服務端確認請求有效後,返回 RecognitionStarted 事件。收到該事件後再發送音頻資料。
3. 發送資料
用戶端分塊發送二進位音頻資料,同時接收服務端事件。
enable_intermediate_result為true時,服務端可多次返回RecognitionResultChanged中間結果。-
enable_intermediate_result為false時,不返回中間結果。服務端仍可能返回RecognitionCompleted或TaskFailed,用戶端需要持續處理這些事件。重要最後一次中間結果可能與最終結果不同,以
RecognitionCompleted中的結果為準。
4. 結束識別
音頻發送完畢後,用戶端發送 StopRecognition 指令。正常完成時,服務端返回 RecognitionCompleted 和最終結果;請求失敗時返回 TaskFailed。等待服務端結束事件後再關閉串連。
開啟語音檢測後,結束靜音時間長度超過 max_end_silence 時,服務端可提前完成識別,後續音頻不再識別。
請求參數
SDK 通過 SpeechRecognizer 對象提供的方法設定參數。直接使用 WebSocket 時,appkey 位於請求的 header 中,其餘識別參數位於 StartRecognition 的 payload 中。
參數 | 類型 | 是否必選 | 說明 |
appkey | String | 是 | 在控制台建立的專案 Appkey。 |
format | String | 否 | 音頻格式: |
sample_rate | Integer | 否 | 音頻採樣率,單位為 Hz,預設值為 |
enable_intermediate_result | Boolean | 否 | 是否返回中間識別結果,預設值為 |
enable_punctuation_prediction | Boolean | 否 | 是否在後處理中添加標點,預設值為 |
enable_inverse_text_normalization | Boolean | 否 | 是否開啟逆文本正則化(ITN)。設定為 |
disfluency | Boolean | 否 | 是否過濾語氣詞(順滑),預設值為 |
customization_id | String | 否 | 自學習模型 ID。配置方法請參見語言模型定製。 |
vocabulary_id | String | 否 | 定製泛熱詞 ID。配置方法請參見定製熱詞。 |
enable_voice_detection | Boolean | 否 | 是否開啟語音檢測。開啟後檢測有效語音的開始和結束,剔除噪音資料。預設值為 |
max_start_silence | Integer | 否 | 僅在 |
max_end_silence | Integer | 否 | 僅在 |
響應事件
header 的通用欄位如下。
|
參數 |
類型 |
說明 |
|
namespace |
String |
命名空間,取值為 |
|
name |
String |
事件名稱,見下方各事件說明。 |
|
status |
Integer |
狀態代碼, |
|
status_text |
String |
狀態訊息。 |
|
task_id |
String |
本次識別任務的全域唯一 ID,與用戶端請求中的任務 ID 對應。記錄該值以便排查問題。 |
|
message_id |
String |
本條服務端響應訊息的 ID。 |
RecognitionStarted
服務端已接受開始識別請求,可以發送音頻資料。該事件不包含識別結果。
RecognitionResultChanged
返回中間識別結果,payload.result 為 String 類型。僅在 enable_intermediate_result 為 true 時返回。
{
"header": {
"namespace": "SpeechRecognizer",
"name": "RecognitionResultChanged",
"status": 20000000,
"message_id": "f2bc60c1fd834da1bef7b9929fd1****",
"task_id": "7ce7bac115844c109c680da4bf28****",
"status_text": "Gateway:SUCCESS:Success."
},
"payload": {
"result": "開始測試今天北京的天氣很好我想購買三十二個蘋果請撥打到電話一二三四五結束測試"
}
}
RecognitionCompleted
識別正常完成,payload.result 為 String 類型,表示最終結果。
{
"header": {
"namespace": "SpeechRecognizer",
"name": "RecognitionCompleted",
"status": 20000000,
"message_id": "22ac941179bf45a8989d660bd9e8****",
"task_id": "7ce7bac115844c109c680da4bf28****",
"status_text": "Gateway:SUCCESS:Success."
},
"payload": {
"result": "開始測試今天北京的天氣很好我想購買三十二個蘋果請撥打到電話一二三四五結束測試"
}
}
TaskFailed
識別任務失敗。根據 header.status 和 header.status_text 排查原因。例如,未發送音頻資料就結束請求,會返回 40000000 和 Gateway:CLIENT_ERROR:Empty audio data!。
服務狀態代碼
結合 status 和 status_text 判斷錯誤。同一狀態代碼可能對應不同原因,應以具體狀態訊息為準。
通用錯誤碼
|
狀態代碼 |
狀態訊息 |
原因 |
解決方案 |
|
40000000 |
預設的用戶端錯誤碼,對應了多個錯誤訊息。 |
使用了不合理的參數或調用邏輯。 |
檢查請求參數、指令順序及具體狀態訊息。 |
|
40000001 |
The token 'xxx' has expired. The token 'xxx' is invalid |
Token 到期或無效。 |
擷取有效 NLS Token 後重新調用。 |
|
40000002 |
Gateway:MESSAGE_INVALID:Can't process message in state'FAILED'! |
訊息無效,或當前任務狀態不接受該訊息。 |
檢查訊息結構和指令順序。任務失敗後重新發起識別。 |
|
40000003 |
PARAMETER_INVALID; Failed to decode url params |
參數無效。 |
檢查參數名稱、類型和值是否符合介面要求。 |
|
40000005 |
Gateway:TOO_MANY_REQUESTS:Too many requests! |
並發請求過多。 |
降低同時進行的請求數,並檢查可用並發額度。 |
|
40000009 |
Invalid wav header! |
錯誤的訊息頭。 |
如果發送的是WAV語音檔案,且設定 |
|
40000009 |
Too large wav header! |
傳輸的語音WAV頭不合法。 |
建議使用PCM、OPUS等格式發送音頻流,如果是WAV,建議關注語音檔案的WAV頭資訊是否為正確的資料長度大小。 |
|
40000010 |
Gateway:FREE_TRIAL_EXPIRED:The free trial has expired! |
試用期已結束且未開通商用版,或帳號欠費。 |
在控制台檢查一句話識別服務的開通狀態和賬戶餘額。 |
|
40010001 |
Gateway:NAMESPACE_NOT_FOUND:RESTful url path illegal |
使用了不支援的介面或參數。 |
檢查服務地址、命名空間和參數是否符合介面要求。 |
|
40010003 |
Gateway:DIRECTIVE_INVALID:[xxx] |
參數或指令無效。 |
根據具體狀態訊息檢查參數及指令。 |
|
40010004 |
Gateway:CLIENT_DISCONNECT:Client disconnected before task finished! |
任務完成前,用戶端主動中斷連線。 |
等待服務端返回任務結束事件後再關閉串連。 |
|
40010005 |
Gateway:TASK_STATE_ERROR:Got stop directive while task is stopping! |
在當前任務狀態下發送了不支援的指令。 |
檢查指令順序,避免重複發送停止指令。 |
|
40020105 |
Meta:APPKEY_NOT_EXIST:Appkey not exist! |
Appkey 不存在。 |
在控制台專案配置中核對 Appkey。 |
|
40020106 |
Meta:APPKEY_UID_MISMATCH:Appkey and user mismatch! |
Appkey 與 Token 不屬於同一帳號。 |
使用同一帳號的專案 Appkey 和 NLS Token。 |
|
403 |
Forbidden |
Token 不存在、到期或無效。 |
使用有效 NLS Token,並在到期前擷取新 Token。 |
|
41000003 |
MetaInfo doesn't have end point info |
無法擷取 Appkey 的路由資訊。 |
檢查 Appkey,並確認 Appkey 與 Token 所屬帳號一致。 |
|
41010101 |
UNSUPPORTED_SAMPLE_RATE |
採樣率不受當前配置支援。 |
確認音頻採樣率為 8000 Hz 或 16000 Hz,且與請求參數及專案模型匹配。 |
|
50000000 |
GRPC_ERROR:Grpc error! |
服務端調用異常,可能與負載或網路有關。 |
重試請求;如問題持續存在,聯絡支援人員並提供 task_id。 |
|
50000001 |
GRPC_ERROR:Grpc error! |
服務端調用異常,可能與負載或網路有關。 |
重試請求;如問題持續存在,聯絡支援人員並提供 task_id。 |
|
52010001 |
GRPC_ERROR:Grpc error! |
服務端調用異常,可能與負載或網路有關。 |
重試請求;如問題持續存在,聯絡支援人員並提供 task_id。 |
一句話識別錯誤碼
|
狀態代碼 |
狀態訊息 |
原因 |
解決方案 |
|
40000000 |
Gateway:CLIENT_ERROR:Empty audio data! |
未發送音頻資料。 |
發送非空的二進位音頻資料,再發送停止指令。 |
|
40000004 |
Gateway:IDLE_TIMEOUT:Websocket session is idle for too long time |
WebSocket 串連建立後,長時間未發送資料,空閑超過 10 秒。 |
建立串連後及時發送識別指令和音頻資料,音頻發送完畢後及時發送停止指令。 |
|
40010002 |
Gateway:DIRECTIVE_NOT_SUPPORTED:Directive'SpeechRecognizer.EnhanceRecognition'isnotsupported! |
發送了服務端不支援的指令。 |
檢查指令名稱,使用一句話識別介面支援的指令。 |
|
40010003 |
Gateway:DIRECTIVE_INVALID:Too many items for ‘vocabulary'!(173) |
熱詞數量過多。 |
按所用熱詞配置方式的數量限制調整熱詞。 |
|
40270002 |
NO_VALID_AUDIO_ERROR |
音頻無效,未識別出有效文本。 |
檢查音頻是否包含清晰語音,以及編碼、採樣率和模型是否匹配。 |
|
41010104 |
TOO_LONG_SPEECH |
音頻時間長度超過一句話識別限制。 |
使用 60 秒以內的音頻;較長語音使用即時語音辨識介面。 |
|
41010105 |
SILENT_SPEECH |
靜音或噪音導致未檢測到有效語音。 |
檢查音頻內容;若開啟語音檢測,檢查開始靜音時間長度設定。 |