本文介紹Paraformer即時語音辨識Java SDK的參數和介面細節。
本文檔僅適用於 “中國大陸(北京)” 地區。如需使用模型,需使用 “中國大陸(北京)” 地區的 API Key 。
使用者指南: 關於模型介紹和選型建議請參見 即時語音辨識 。
前提條件
-
已開通服務並 擷取API Key 。請 配置API Key到環境變數(準備下線,併入配置 API Key) ,而非寫入程式碼在代碼中,防範因代碼泄露導致的安全風險。
說明當您需要為第三方應用或使用者提供臨時存取權限,或者希望嚴格控制敏感性資料訪問、刪除等高風險操作時,建議使用 臨時鑒權Token 。
與長期有效 API Key 相比,臨時鑒權 Token 具備時效性短(60秒)、安全性高的特點,適用於臨時調用情境,能有效降低API Key泄露的風險。
使用方式:在代碼中,將原本用於鑒權的 API Key 替換為擷取到的臨時鑒權 Token 即可。
模型列表
|
|
paraformer-realtime-v2 |
paraformer-realtime-8k-v2 |
|
適用情境 |
直播、會議等情境 |
電話客服、語音信箱等 8kHz 音訊識別情境 |
|
採樣率 |
任意 |
8kHz |
|
語種 |
中文(包含中文普通話和各種方言)、英文、日語、韓語、德語、法語、俄語 支援的中文方言:上海話、吳語、閩南語、東北話、甘肅話、貴州話、河南話、湖北話、湖南話、江西話、寧夏話、山西話、陝西話、山東話、四川話、天津話、雲南話、粵語 |
中文 |
|
標點符號預測 |
✅ 預設支援,無需配置 |
✅ 預設支援,無需配置 |
|
逆文本正則化(ITN) |
✅ 預設支援,無需配置 |
✅ 預設支援,無需配置 |
|
定製熱詞 |
✅ 參見 定製熱詞 |
✅ 參見 定製熱詞 |
|
指定待識別語種 |
✅ 通過
|
❌ |
|
情感識別 |
❌ |
|
快速開始
Recognition類 提供了同步調用和流式調用等介面。請根據實際需求選擇合適的調用方式:
-
同步調用:針對本地檔案進行識別,並一次性返回完整的處理結果。適合處理錄製好的音頻。
-
流式調用:可直接對音頻流進行識別,並即時輸出結果。音頻流可以來自外部裝置(如麥克風)或從本地檔案讀取。適合需要即時反饋的情境。
同步調用
提交單個語音即時轉寫任務,通過傳入本地檔案的方式同步阻塞地拿到轉寫結果。
執行個體化
Recognition類
,調用
call
方法綁定
請求參數
和待識別檔案,進行識別並最終擷取識別結果。
流式調用:基於回調
提交單個語音即時轉寫任務,通過實現回調介面的方式流式輸出即時識別結果。
-
啟動流式語音辨識
執行個體化 Recognition類 ,調用
call方法綁定 請求參數 和 回調介面(ResultCallback) 並啟動流式語音辨識。 -
串流
迴圈調用 Recognition類 的
sendAudioFrame方法,將從本地檔案或裝置(如麥克風)讀取的二進位音頻流分段發送至服務端。在發送音頻資料的過程中,服務端會通過 回調介面(ResultCallback) 的
onEvent方法,將識別結果即時返回給用戶端。建議每次發送的音頻時間長度約為100毫秒,資料大小保持在1KB至16KB之間。
-
結束處理
調用 Recognition類 的
stop方法結束語音辨識。該方法會阻塞當前線程,直到 回調介面(ResultCallback) 的
onComplete或者onError回調觸發後才會釋放線程阻塞。
流式調用:基於Flowable
提交單個語音即時轉寫任務,通過實現工作流程(Flowable)的方式流式輸出即時識別結果。
Flowable 是一個用於工作流程和商務程序管理的開源架構,它基於 Apache 2.0 許可證發布。關於Flowable的使用,請參見 Flowable API詳情 。
高並發調用
在DashScope Java SDK中,採用了OkHttp3的串連池技術,以減少重複建立串連的開銷。詳情請參見 即時語音辨識高並發情境 。
請求參數
通過
RecognitionParam
的鏈式方法配置模型、採樣率、音頻格式等參數。配置完成的參數對象傳入
Recognition類
的
call
/
streamCall
方法中使用。
|
參數 |
類型 |
預設值 |
是否必須 |
說明 |
|
model |
String |
- |
是 |
用於即時語音辨識的模型。詳情請參見 模型列表 。 |
|
sampleRate |
Integer |
- |
是 |
設定待識別音頻採樣率(單位Hz)。 因模型而異:
|
|
format |
String |
- |
是 |
設定待識別音頻格式。 支援的音頻格式:pcm、wav、mp3、opus、speex、aac、amr。
重要
opus/speex:必須使用Ogg封裝; wav:必須為PCM編碼; amr:僅支援AMR-NB類型。 |
|
vocabularyId |
String |
- |
否 |
設定熱詞ID,若未設定則不生效。v2及更高版本模型設定熱詞ID時使用該欄位。 在本次語音辨識中,將應用與該熱詞ID對應的熱詞資訊。具體使用方法請參見 定製熱詞 。 |
|
disfluencyRemovalEnabled |
boolean |
false |
否 |
設定是否過濾語氣詞:
|
|
language_hints |
String[] |
["zh", "en"] |
否 |
設定待識別語言代碼。如果無法提前確定語種,可不設定,模型會自動識別語種。 目前支援的語言代碼:
該參數僅對支援多語言的模型生效(參見 模型列表 )。
說明
通過parameter設定
通過parameters設定
|
|
semantic_punctuation_enabled |
boolean |
false |
否 |
設定是否開啟語義斷句,預設關閉。
語義斷句準確性更高,適合會議轉寫情境;VAD(Voice Activity Detection,語音活動檢測)斷句延遲較低,適合互動情境。
通過調整
該參數僅在模型為v2及更高版本時生效。
說明
通過parameter設定
通過parameters設定
|
|
max_sentence_silence |
Integer |
800 |
否 |
設定VAD(Voice Activity Detection,語音活動檢測)斷句的靜音時間長度閾值(單位為ms)。 當一段語音後的靜音時間長度超過該閾值時,系統會判定該句子已結束。 參數範圍為200ms至6000ms,預設值為800ms。
該參數僅在
說明
通過parameter設定
通過parameters設定
|
|
multi_threshold_mode_enabled |
boolean |
false |
否 |
該開關開啟時(true)可以防止VAD斷句切割過長。預設關閉。
該參數僅在
說明
通過parameter設定
通過parameters設定
|
|
punctuation_prediction_enabled |
boolean |
true |
否 |
設定是否在識別結果中自動添加標點:
該參數僅在模型為v2及更高版本時生效。
說明
通過parameter設定
通過parameters設定
|
|
heartbeat |
boolean |
false |
否 |
當需要與服務端保持長串連時,可通過該開關進行控制:
該參數僅在模型為v2及更高版本時生效。
說明
使用該欄位時,SDK版本不能低於2.19.1。
通過parameter設定
通過parameters設定
|
|
inverse_text_normalization_enabled |
boolean |
true |
否 |
設定是否開啟ITN(Inverse Text Normalization,逆文本正則化)。 預設開啟(true)。開啟後,中文數字將轉換為阿拉伯數字。 該參數僅在模型為v2及更高版本時生效。
說明
通過parameter設定
通過parameters設定
|
|
apiKey |
String |
- |
否 |
使用者API Key。 |
關鍵介面
Recognition
類
Recognition
通過“
import com.alibaba.dashscope.audio.asr.recognition.Recognition;
”方式引入。它的關鍵介面如下:
|
介面/方法 |
參數 |
傳回值 |
描述 |
|
|
無 |
基於回調形式的流式即時識別,該方法不會阻塞當前線程。 |
|
|
識別結果 |
基於本地檔案的同步調用,該方法會阻塞當前線程直到全部音頻讀完,該方法要求所識別檔案具有可讀許可權。 |
|
|
|
基於Flowable的流式即時識別。 |
|
|
無 |
推送音頻,每次推送的音頻流不宜過大或過小,建議每包音頻時間長度為100ms左右,大小在1KB~16KB之間。 識別結果通過 回調介面(ResultCallback) 的onEvent方法擷取。 |
|
無 |
無 |
停止即時識別。
該方法會阻塞當前線程,直到回調執行個體
|
|
code: WebSocket關閉碼(Close Code) reason:關閉原因 這兩個參數可參考 The WebSocket Protocol 文檔進行配置 |
true |
在任務結束後,無論是否出現異常都需要關閉WebSocket串連,避免造成串連泄漏。關於如何複用串連提升效率請參考 即時語音辨識高並發情境 。 |
|
無 |
requestId |
擷取當前任務的requestId,在調用
說明
該方法自2.18.0版本及以後的SDK中才開始提供。 |
|
無 |
首包延遲 |
擷取首包延遲,從發送第一包音頻到收到首包識別結果延遲,在任務完成後使用。
說明
該方法自2.18.0版本及以後的SDK中才開始提供。 |
|
無 |
尾包延遲 |
獲得尾包延遲,發送
說明
該方法自2.18.0版本及以後的SDK中才開始提供。 |
回調介面(
ResultCallback
)
流式調用 時,服務端會通過回調的方式,將關鍵流程資訊和資料返回給用戶端。您需要實現回調方法,處理服務端返回的資訊或者資料。
回調方法的實現,通過繼承抽象類別
ResultCallback
完成,繼承該抽象類別時,您可以指定泛型為
RecognitionResult
。
RecognitionResult
封裝了伺服器返回的資料結構。
由於Java支援串連複用,因此沒有
onClose
和
onOpen
。
|
介面/方法 |
參數 |
傳回值 |
描述 |
|
|
無 |
當服務有回複時會被回調。 |
|
無 |
無 |
任務完成後該介面被回調。 |
|
|
無 |
發生異常時該介面被回調。 |
響應結果
即時識別結果(
RecognitionResult
)
RecognitionResult
代表一次即時識別的結果。
|
介面/方法 |
參數 |
傳回值 |
描述 |
|
無 |
requestId |
擷取requestId。 |
|
無 |
是否是完整句子,即產生斷句 |
判斷給定句子是否已經結束。 |
|
無 |
擷取單句資訊,包括時間戳記和文本資訊等。 |
單句資訊(
Sentence
)
|
介面/方法 |
參數 |
傳回值 |
描述 |
|
無 |
句子開始時間,單位為ms |
返回句子開始時間。 |
|
無 |
句子結束時間,單位為ms |
返回句子結束時間。 |
|
無 |
識別文本 |
返回識別文本。 |
|
無 |
字時間戳記資訊(Word) 的List集合 |
返回字時間戳記資訊。 |
|
無 |
當前句子的情感 |
返回當前句子的情感:
情感識別遵循如下約束:
|
|
無 |
當前句子識別情感的信賴度 |
返回當前句子識別情感的信賴度,取值範圍:[0.0,1.0],值越大表示信賴度越高。 情感識別遵循如下約束:
|
字時間戳記資訊(
Word
)
|
介面/方法 |
參數 |
傳回值 |
描述 |
|
無 |
字開始時間,單位為ms |
返回字開始時間。 |
|
無 |
字結束時間,單位為ms |
返回字結束時間。 |
|
無 |
字 |
返回識別的字。 |
|
無 |
標點 |
返回標點。 |
錯誤碼
如遇報錯問題,請參見 錯誤資訊 進行排查。
若問題仍未解決,請加入 開發人員群 反饋遇到的問題,並提供Request ID,以便進一步排查問題。
更多樣本
更多樣本,請參見 GitHub 。
常見問題
功能特性
Q:在長時間靜默的情況下,如何保持與服務端長串連?
將請求參數
heartbeat
設定為true,並持續向服務端發送靜音音頻。
靜音音頻指的是在音頻檔案或資料流中沒有聲音訊號的內容。靜音音頻可以通過多種方法產生,例如使用音頻編輯軟體如Audacity或Adobe Audition,或者通過命令列工具如FFmpeg。
Q:如何將音頻格式轉換為滿足要求的格式?
可使用 FFmpeg工具 ,更多用法請參見FFmpeg官網。
# 基礎轉換命令(萬能模板)
# -i,作用:輸入檔案路徑,常用值樣本:audio.wav
# -c:a,作用:音頻編碼器,常用值樣本:aac, libmp3lame, pcm_s16le
# -b:a,作用:位元速率(音質控制),常用值樣本:192k, 320k
# -ar,作用:採樣率,常用值樣本:44100 (CD), 48000, 16000
# -ac,作用:聲道數,常用值樣本:1(單聲道), 2(立體聲)
# -y,作用:覆蓋已存在檔案(無需值)
ffmpeg -i input_audio.ext -c:a 編碼器名 -b:a 位元速率 -ar 採樣率 -ac 聲道數 output.ext
# 例如:WAV → MP3(保持原始品質)
ffmpeg -i input.wav -c:a libmp3lame -q:a 0 output.mp3
# 例如:MP3 → WAV(16bit PCM標準格式)
ffmpeg -i input.mp3 -c:a pcm_s16le -ar 44100 -ac 2 output.wav
# 例如:M4A → AAC(提取/轉換蘋果音頻)
ffmpeg -i input.m4a -c:a copy output.aac # 直接提取不重編碼
ffmpeg -i input.m4a -c:a aac -b:a 256k output.aac # 重編碼提高品質
# 例如:FLAC無損 → Opus(高壓縮)
ffmpeg -i input.flac -c:a libopus -b:a 128k -vbr on output.opus
Q: 是否支援查看每句話對應的時間範圍?
支援。語音辨識結果中會包含每句話的開始時間戳和結束時間戳記,可通過它們確定每句話的時間範圍。
Q:如何識別本地檔案(錄音檔案)?
識別本地檔案有兩種方式:
-
直接傳入本地檔案路徑:此種方式在最終識別結束後擷取完整識別結果,不適合即時反饋的情境。
參見 同步調用 ,在 Recognition類 的
call方法中傳入檔案路徑對錄音檔案直接進行識別。 -
將本地檔案轉成二進位流進行識別:此種方式一邊識別檔案一邊流式擷取識別結果,適合即時反饋的情境。
-
參見 流式調用:基於回調 ,通過 Recognition類 的
sendAudioFrame方法向服務端發送二進位流對其進行識別。 -
參見 流式調用:基於Flowable ,通過 Recognition類 的
streamCall方法向服務端發送二進位流對其進行識別。
-
故障排查
Q:無法識別語音(無識別結果)是什麼原因?
-
請檢查請求參數中的音頻格式(
format)和採樣率(sampleRate/sample_rate)設定是否正確且符合參數約束。以下為常見錯誤樣本:-
音頻副檔名為 .wav,但實際為 MP3 格式,而請求參數
format設定為 mp3(參數設定錯誤)。 -
音頻採樣率為 3600Hz,但請求參數
sampleRate/sample_rate設定為 48000(參數設定錯誤)。
可以使用 ffprobe 工具擷取音訊容器、編碼、採樣率、聲道等資訊:
ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 input.xxx -
-
使用
paraformer-realtime-v2模型時,請檢查language_hints設定的語言是否與音頻實際語言一致。例如:音頻實際為中文,但
language_hints設定為en(英文)。 -
若以上檢查均無問題,可通過定製熱詞提升對特定詞語的識別效果。