本文介紹Fun-ASR即時語音辨識Java SDK的參數和介面細節。
使用者指南:關於模型介紹和選型建議請參見即時語音辨識-Fun-ASR/Gummy/Paraformer。
前提條件
已開通服務並擷取API Key。請配置API Key到環境變數(準備下線,併入配置 API Key),而非寫入程式碼在代碼中,防範因代碼泄露導致的安全風險。
模型列表
國際
在國際部署模式下,存取點與資料存放區均位於新加坡地區,模型推理計算資源在全球範圍內動態調度(不含中國內地)。
模型名稱 | 版本 | 單價 | 免費額度(注) |
fun-asr-realtime 當前等同fun-asr-realtime-2025-11-07 | 穩定版 | $0.00009/秒 | 36,000秒(10小時) 有效期間90天 |
fun-asr-realtime-2025-11-07 | 快照版 |
支援的語種:中文(普通話、粵語、吳語、閩南語、客家話、贛語、湘語、晉語;並支援中原、西南、冀魯、江淮、蘭銀、膠遼、東北、北京、港台等,包括河南、陝西、湖北、四川、重慶、雲南、貴州、廣東、廣西、河北、天津、山東、安徽、南京、江蘇、杭州、甘肅、寧夏等地區官話口音)、英文、日語
支援的採樣率:16kHz
支援的音頻格式:pcm、wav、mp3、opus、speex、aac、amr
中國內地
在中國內地部署模式下,存取點與資料存放區均位於北京地區,模型推理計算資源僅限於中國內地。
模型名稱 | 版本 | 單價 | 免費額度(注) |
fun-asr-realtime 當前等同fun-asr-realtime-2025-11-07 | 穩定版 | $0.000047/秒 | 無免費額度 |
fun-asr-realtime-2026-02-28 | 快照版 | ||
fun-asr-realtime-2025-11-07 | 快照版 | ||
fun-asr-realtime-2025-09-15 | |||
fun-asr-flash-8k-realtime 當前等同fun-asr-flash-8k-realtime-2026-01-28 | 穩定版 | $0.000032/秒 | |
fun-asr-flash-8k-realtime-2026-01-28 | 快照版 |
支援的語種:
fun-asr-realtime、fun-asr-realtime-2026-02-28、fun-asr-realtime-2025-11-07:中文(普通話、粵語、吳語、閩南語、客家話、贛語、湘語、晉語;並支援中原、西南、冀魯、江淮、蘭銀、膠遼、東北、北京、港台等,包括河南、陝西、湖北、四川、重慶、雲南、貴州、廣東、廣西、河北、天津、山東、安徽、南京、江蘇、杭州、甘肅、寧夏等地區官話口音)、英文、日語
fun-asr-realtime-2025-09-15:中文(普通話)、英文
支援的採樣率:
fun-asr-flash-8k-realtime、fun-asr-flash-8k-realtime-2026-01-28:8kHz
其他模型:16kHz
支援的音頻格式:pcm、wav、mp3、opus、speex、aac、amr
快速開始
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)。 fun-asr-realtime支援16000Hz採樣。 |
format | String | - | 是 | 設定待識別音頻格式。 支援的音頻格式:pcm、wav、mp3、opus、speex、aac、amr。 重要 opus/speex:必須使用Ogg封裝; wav:必須為PCM編碼; amr:僅支援AMR-NB類型。 |
semantic_punctuation_enabled | boolean | false | 否 | 設定是否開啟語義斷句,預設關閉。
語義斷句準確性更高,適合會議轉寫情境;VAD(Voice Activity Detection,語音活動檢測)斷句延遲較低,適合互動情境。 通過調整 說明
通過parameter設定通過parameters設定 |
max_sentence_silence | Integer | 1300 | 否 | 設定VAD(Voice Activity Detection,語音活動檢測)斷句的靜音時間長度閾值(單位為ms)。 當一段語音後的靜音時間長度超過該閾值時,系統會判定該句子已結束。 參數範圍為200ms至6000ms,預設值為1300ms。 該參數僅在 說明
通過parameter設定通過parameters設定 |
multi_threshold_mode_enabled | boolean | false | 否 | 該開關開啟時(true)可以防止VAD斷句切割過長。預設關閉。 該參數僅在 說明
通過parameter設定通過parameters設定 |
punctuation_prediction_enabled | boolean | true | 否 | 設定是否在識別結果中自動添加標點:
說明
通過parameter設定通過parameters設定 |
heartbeat | boolean | false | 否 | 當需要與服務端保持長串連時,可通過該開關進行控制:
說明 使用該欄位時,SDK版本不能低於2.19.1。
通過parameter設定通過parameters設定 |
language_hints | String[] | - | 否 | 設定待識別語言代碼。如果無法提前確定語種,可不設定,模型會自動識別語種。 系統僅讀取數組中的首個值。多餘值將被忽略。 不同模型支援的語言代碼如下:
說明
通過parameter設定通過parameters設定 |
speech_noise_threshold | float | - | 否 | 控制語音與噪音的判定閾值,用於調整語音活動檢測(VAD)的靈敏度。 取值範圍:[-1.0, 1.0]。 取值說明:
重要 此參數為進階配置參數,調整可能顯著影響識別效果,建議:
說明
通過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集合 | 返回字時間戳記資訊。 |
字時間戳記資訊(Word)
介面/方法 | 參數 | 傳回值 | 描述 |
| 無 | 字開始時間,單位為ms | 返回字開始時間。 |
| 無 | 字結束時間,單位為ms | 返回字結束時間。 |
| 無 | 字 | 返回識別的字。 |
| 無 | 標點 | 返回標點。 |
錯誤碼
如遇報錯問題,請參見錯誤資訊進行排查。
若問題仍未解決,請加入開發人員群反饋遇到的問題,並提供Request ID,以便進一步排查問題。
常見問題
功能特性
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.opusQ:如何識別本地檔案(錄音檔案)?
識別本地檔案有兩種方式:
直接傳入本地檔案路徑:此種方式在最終識別結束後擷取完整識別結果,不適合即時反饋的情境。
參見非流式調用,在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請檢查
language_hints設定的語言是否與音頻實際語言一致。例如:音頻實際為中文,但
language_hints設定為en(英文)。