前提條件
快速開始
以下呼叫範例可共用。依下表替換範例中的模型 ID。
| 模型 | 範例中的模型 ID |
|---|---|
| Qwen-Audio-ASR-Streaming | qwen-audio-3.0-asr-flash-streaming |
| Qwen-Audio-ASR-Message | qwen-audio-3.1-asr-flash-message |
| Fun-ASR-Realtime | fun-asr-realtime |
- 非流式調用:針對本地檔案進行識別,並一次性返回完整的處理結果。適合處理錄製好的音頻。
- 雙向流式調用:可直接對音頻流進行識別,並即時輸出結果。音頻流可以來自外部裝置(如麥克風)或從本地檔案讀取。適合需要即時反饋的情境。
- 非流式調用
- 雙向流式調用:基於回調
- 雙向流式調用:基於Flowable
提交單個語音即時轉寫任務,通過傳入本地檔案的方式同步阻塞地拿到轉寫結果。執行個體化Recognition類,調用
call方法綁定請求參數和待識別檔案,進行識別並最終擷取識別結果。高並發調用
在DashScope Java SDK中,採用了OkHttp3的串連池技術,以減少重複建立串連的開銷。詳情請參見高並發最佳實務。
請求參數
Qwen-Audio-ASR-Streaming
通過RecognitionParam的鏈式方法配置模型、採樣率、音頻格式等參數。配置完成的參數對象傳入Recognition類的call/streamCall方法中使用。
| 參數 | 類型 | 是否必須 | 說明 |
|---|---|---|---|
model | String | 是 | 模型名稱。 |
sampleRate | Integer | 是 | 採樣率(Hz),支援任意採樣率。 |
format | String | 是 | 音頻格式。取值範圍:
|
keep_dialect | boolean | 否 | 僅適用於 qwen-audio-3.1-asr-flash-streaming。false,將方言轉寫為普通話文本。設為 true 時保留方言表達。 透過 .parameter("keep_dialect", value) 設定。 |
vad_model | String | 否 | 僅適用於 qwen-audio-3.1-asr-flash-streaming。near_meeting_16k(近場)或 far_field_meeting_16k(遠場,預設值)。 透過 .parameter("vad_model", value) 設定。 |
vocabularyId | String | 否 | 先行編譯熱詞列表 ID。需預先調用建立熱詞列表介面產生,識別時傳入該 ID 即可使用列表中的熱詞。適用於詞彙已知且相對穩定、需要跨請求複用同一詞表的情境。使用方法請參見先行編譯熱詞。 |
vocabulary | Map<String, Integer> | 否 | 即時熱詞。以索引值對形式傳入,鍵為熱詞文本(string),值為熱詞權重(integer),無需預先建立熱詞列表。權重取值範圍為 [1, 5] 或 50:取 [1, 5] 時值越大模型越傾向輸出該詞;取 50 時為超級熱詞,召回率大幅提升,但超級熱詞數量最多不超過 50 個。適用於臨時性、會話層級的熱詞最佳化。與先行編譯熱詞同時配置時,僅即時熱詞生效。使用方法請參見即時熱詞。vocabulary需要通過 RecognitionParam 執行個體的 parameter 方法或者 parameters 方法進行設定: |
max_sentence_silence | Integer | 否 | VAD 斷句靜音閾值(ms)。當一段語音後的靜音時間長度超過該閾值時,系統會判定該句子已結束。預設值:800。取值範圍:[200, 6000]。max_sentence_silence需要通過RecognitionParam執行個體的parameter方法或者parameters方法進行設定: |
multi_threshold_mode_enabled | boolean | 否 | 是否啟用多閾值模式。啟用後可防止 VAD 斷句切割過長。預設值:false。multi_threshold_mode_enabled需要通過RecognitionParam執行個體的parameter方法或者parameters方法進行設定: |
punctuation_prediction_enabled | boolean | 否 | 設定是否在識別結果中自動添加標點:
punctuation_prediction_enabled需要通過RecognitionParam執行個體的parameter方法或者parameters方法進行設定: |
heartbeat | boolean | 否 | 是否啟用心跳包。預設值:false。
使用該欄位時,SDK版本不能低於2.19.1。 heartbeat需要通過RecognitionParam執行個體的parameter方法或者parameters方法進行設定: |
language_hints | String[] | 否 | 待識別音頻語種。無預設值,不設定時模型自動識別。最多支援設定 4 個值,超出時僅前 4 個生效。
點擊查看支援的語言代碼
language_hints需要通過RecognitionParam執行個體的parameter方法或者parameters方法進行設定: |
speech_noise_threshold | float | 否 | 語音與噪音的判定閾值,用於調整語音活動檢測(VAD)的靈敏度。取值範圍:[-1.0, 1.0]。取值說明:
speech_noise_threshold需要通過RecognitionParam執行個體的parameter方法或者parameters方法進行設定: |
special_word_filter | String | 否 | 指定在語音辨識過程中需要處理的敏感詞,並支援對不同敏感詞設定不同的處理方式。詳情請參見敏感詞過濾。special_word_filter需要通過RecognitionParam執行個體的parameter方法或者parameters方法進行設定: |
input | Map<String, Object> | 否 | 輸入對象,用於傳入對話上下文(context)。上下文用於輔助識別、提升專有詞彙的識別準確率。使用方法詳見快速開始。Map 中需包含 context 鍵,值為 List<Map<String, Object>> 類型的訊息數組,每條訊息包含以下欄位:
使用該欄位時,SDK版本不能低於2.22.23。 input通過RecognitionParam執行個體的input方法進行設定: |
apiKey | String | 否 | 使用者API Key。 |
Qwen-Audio-ASR-Message
通過RecognitionParam的鏈式方法配置模型、採樣率、音頻格式等參數。配置完成的參數對象傳入Recognition類的call/streamCall方法中使用。
| 參數 | 類型 | 是否必須 | 說明 |
|---|---|---|---|
model | String | 是 | 模型名稱。 |
sampleRate | Integer | 是 | 採樣率(Hz),僅支援 16000。 |
format | String | 是 | 音頻格式。取值範圍:
|
keep_dialect | boolean | 否 | 預設為 false,將方言轉寫為普通話文本。設為 true 時保留方言表達。 透過 .parameter("keep_dialect", value) 設定。僅在最終結果(sentence_end=true)生效,中間結果(sentence_end=false)不支援。 |
vad_model | String | 否 | VAD 模型。取值為 near_meeting_16k(近場)或 far_field_meeting_16k(遠場,預設值)。 透過 .parameter("vad_model", value) 設定。 |
disfluency_removal_enabled | boolean | 否 | 是否過濾語氣詞並潤飾輸出。預設為 false,設為 true 時啟用。 透過 .parameter("disfluency_removal_enabled", value) 設定。 |
intermediate_result_enabled | boolean | 否 | 是否傳回串流中間結果。預設為 false,設為 true 時傳回中間結果。 透過 .parameter("intermediate_result_enabled", value) 設定。 |
vocabularyId | String | 否 | 先行編譯熱詞列表 ID。需預先調用建立熱詞列表介面產生,識別時傳入該 ID 即可使用列表中的熱詞。適用於詞彙已知且相對穩定、需要跨請求複用同一詞表的情境。使用方法請參見先行編譯熱詞。 |
vocabulary | Map<String, Integer> | 否 | 即時熱詞。以索引值對形式傳入,鍵為熱詞文本(string),值為熱詞權重(integer),無需預先建立熱詞列表。權重取值範圍為 [1, 5] 或 50:取 [1, 5] 時值越大模型越傾向輸出該詞;取 50 時為超級熱詞,召回率大幅提升,但超級熱詞數量最多不超過 50 個。適用於臨時性、會話層級的熱詞最佳化。與先行編譯熱詞同時配置時,僅即時熱詞生效。使用方法請參見即時熱詞。vocabulary需要通過 RecognitionParam 執行個體的 parameter 方法或者 parameters 方法進行設定: |
language_hints | String[] | 否 | 待識別音頻語種。無預設值,不設定時模型自動識別。最多支援設定 4 個值,超出時僅前 4 個生效。
點擊查看支援的語言代碼
RecognitionParam 的 .parameter("language_hints", new String[]{"zh"}) 設定。僅在最終結果(sentence_end=true)生效,中間結果(sentence_end=false)不支援。 |
max_sentence_silence | Integer | 否 | VAD 斷句靜音閾值(毫秒)。語音後的靜音時長超過此值時判定句子結束。預設值為 800,取值範圍為 [200, 6000]。 |
heartbeat | boolean | 否 | 是否啟用心跳包。預設值:false。
使用該欄位時,SDK版本不能低於2.19.1。 heartbeat需要通過RecognitionParam執行個體的parameter方法或者parameters方法進行設定: |
speech_noise_threshold | float | 否 | 語音與噪音的判定閾值,用於調整語音活動檢測(VAD)的靈敏度。取值範圍:[-1.0, 1.0]。取值說明:
speech_noise_threshold需要通過RecognitionParam執行個體的parameter方法或者parameters方法進行設定: |
input | Map<String, Object> | 否 | 輸入對象,用於傳入對話上下文(context)。上下文用於輔助識別、提升專有詞彙的識別準確率。使用方法詳見快速開始。Map 中需包含 context 鍵,值為 List<Map<String, Object>> 類型的訊息數組,每條訊息包含以下欄位:
使用該欄位時,SDK版本不能低於2.22.23。 input通過RecognitionParam執行個體的input方法進行設定: |
apiKey | String | 否 | 使用者API Key。 |
Fun-ASR-Realtime
通過RecognitionParam的鏈式方法配置模型、採樣率、音頻格式等參數。配置完成的參數對象傳入Recognition類的call/streamCall方法中使用。
| 參數 | 類型 | 是否必須 | 說明 |
|---|---|---|---|
model | String | 是 | 模型名稱。 |
sampleRate | Integer | 是 | 採樣率(Hz)。取值範圍:8k模型僅支援 8000 Hz,其他模型支援任意採樣率。 |
format | String | 是 | 音頻格式。取值範圍:
|
vocabularyId | String | 否 | 先行編譯熱詞列表 ID。需預先調用建立熱詞列表介面產生,識別時傳入該 ID 即可使用列表中的熱詞。適用於詞彙已知且相對穩定、需要跨請求複用同一詞表的情境。使用方法請參見先行編譯熱詞。 |
max_sentence_silence | Integer | 否 | VAD 斷句靜音閾值(ms)。當一段語音後的靜音時間長度超過該閾值時,系統會判定該句子已結束。預設值:1300。取值範圍:[200, 6000]。max_sentence_silence需要通過RecognitionParam執行個體的parameter方法或者parameters方法進行設定: |
multi_threshold_mode_enabled | boolean | 否 | 是否啟用多閾值模式。啟用後可防止 VAD 斷句切割過長。預設值:false。multi_threshold_mode_enabled需要通過RecognitionParam執行個體的parameter方法或者parameters方法進行設定: |
punctuation_prediction_enabled | boolean | 否 | 設定是否在識別結果中自動添加標點:
punctuation_prediction_enabled需要通過RecognitionParam執行個體的parameter方法或者parameters方法進行設定: |
heartbeat | boolean | 否 | 是否啟用心跳包。預設值:false。
使用該欄位時,SDK版本不能低於2.19.1。 heartbeat需要通過RecognitionParam執行個體的parameter方法或者parameters方法進行設定: |
language_hints | String[] | 否 | 待識別音頻語種。無預設值,不設定時模型自動識別。僅支援設定 1 個值,設定多個時僅第一個生效。
點擊查看支援的語言代碼
language_hints需要通過RecognitionParam執行個體的parameter方法或者parameters方法進行設定: |
speech_noise_threshold | float | 否 | 語音與噪音的判定閾值,用於調整語音活動檢測(VAD)的靈敏度。取值範圍:[-1.0, 1.0]。取值說明:
speech_noise_threshold需要通過RecognitionParam執行個體的parameter方法或者parameters方法進行設定: |
special_word_filter | String | 否 | 指定在語音辨識過程中需要處理的敏感詞,並支援對不同敏感詞設定不同的處理方式。詳情請參見敏感詞過濾。special_word_filter需要通過RecognitionParam執行個體的parameter方法或者parameters方法進行設定: |
input | Map<String, Object> | 否 | 輸入對象,用於傳入對話上下文(context)。上下文用於輔助識別、提升專有詞彙的識別準確率。使用方法詳見快速開始。Map 中需包含 context 鍵,值為 List<Map<String, Object>> 類型的訊息數組,每條訊息包含以下欄位:
使用該欄位時,SDK版本不能低於2.22.23。 input通過RecognitionParam執行個體的input方法進行設定: |
apiKey | String | 否 | 使用者API Key。 |
介面參考
共用介面
介面地址
SDK的介面地址需在初始化前設定為下方地址(包含WorkspaceId)。如需切換到其他地區,請修改 Constants.baseWebsocketApiUrl為對應地區的URL。
- 新加坡
- 華北2(北京)
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference調用時請將{WorkspaceId}替換為真實的Workspace ID。Recognition類
Recognition通過import com.alibaba.dashscope.audio.asr.recognition.Recognition;方式引入。它的關鍵介面如下:
| 介面/方法 | 參數 | 傳回值 | 描述 |
|---|---|---|---|
| 無 | 基於回調形式的流式即時識別,該方法不會阻塞當前線程。 | |
| 識別結果 | 基於本地檔案的非流式調用,該方法會阻塞當前線程直到全部音頻讀完,該方法要求所識別檔案具有可讀許可權。 | |
| Flowable<RecognitionResult> | 基於Flowable的流式即時識別。 | |
| 無 | 推送音頻,每次推送的音頻流不宜過大或過小,建議每包音頻時間長度為100ms左右,大小在1KB~16KB之間。識別結果通過回調介面(ResultCallback)的onEvent方法擷取。 | |
| 無 | 無 | 停止即時識別。該方法會阻塞當前線程,直到回調執行個體ResultCallback的onComplete或者onError被調用之後才會解除對當前線程的阻塞。 | |
| code: WebSocket關閉碼(Close Code)reason:關閉原因這兩個參數可參考The WebSocket Protocol文檔進行配置 | true | 在任務結束後,無論是否出現異常都需要關閉WebSocket串連,避免造成串連泄漏。關於如何複用串連提升效率請參考即時語音辨識高並發情境。 | |
| 無 | requestId | 擷取當前任務的requestId,在調用call、streamingCall開始新任務之後可以使用。該方法自2.18.0版本及以後的SDK中才開始提供。 | |
| 無 | 首包延遲 | 擷取首包延遲,從發送第一包音頻到收到首包識別結果延遲,在任務完成後使用。 該方法自2.18.0版本及以後的SDK中才開始提供。 | |
| 無 | 尾包延遲 | 獲得尾包延遲,發送stop指令到最後一包識別結果下發耗時,在任務完成後使用。該方法自2.18.0版本及以後的SDK中才開始提供。 |
回調介面(ResultCallback)
雙向流式調用時,服務端會通過回調的方式,將關鍵流程資訊和資料返回給用戶端。您需要實現回調方法,處理服務端返回的資訊或者資料。
回調方法的實現,通過繼承抽象類別ResultCallback完成,繼承該抽象類別時,您可以指定泛型為RecognitionResult。RecognitionResult封裝了伺服器返回的資料結構。
由於Java支援串連複用,因此沒有onClose和onOpen。
| 介面/方法 | 參數 | 傳回值 | 描述 |
|---|---|---|---|
result:即時識別結果(RecognitionResult) | 無 | 當服務有回複時會被回調。 | |
| 無 | 無 | 任務完成後該介面被回調。 | |
e:異常資訊 | 無 | 發生異常時該介面被回調。 |
即時識別結果(RecognitionResult)
RecognitionResult代表一次即時識別的結果。
| 介面/方法 | 參數 | 傳回值 | 描述 |
|---|---|---|---|
| 無 | requestId | 擷取requestId。 | |
| 無 | 是否是完整句子,即產生斷句 | 判斷給定句子是否已經結束。 | |
| 無 | 單句資訊(Sentence) | 擷取單句資訊,包括時間戳記和文本資訊等。 |
單句資訊(Sentence)
| 介面/方法 | 參數 | 傳回值 | 描述 |
|---|---|---|---|
| 無 | 句子開始時間,單位為ms | 返回句子開始時間。 | |
| 無 | 句子結束時間,單位為ms | 返回句子結束時間。 | |
| 無 | 識別文本 | 返回識別文本。 | |
| 無 | 字時間戳記資訊(Word)的List集合 | 返回字時間戳記資訊。 |
字時間戳記資訊(Word)
| 介面/方法 | 參數 | 傳回值 | 描述 |
|---|---|---|---|
| 無 | 字開始時間,單位為ms | 返回字開始時間。 | |
| 無 | 字結束時間,單位為ms | 返回字結束時間。 | |
| 無 | 字 | 返回識別的字。 | |
| 無 | 標點 | 返回標點。 |