Qwen-Audio-ASR-Streaming 用戶端事件 - Alibaba Cloud Model Studio

本文介紹 Qwen-Audio-ASR-Streaming 即時語音辨識服務中用戶端通過 WebSocket 發送給服務端的用戶端事件，包括 run-task（啟動任務）、finish-task（結束任務）等指令的資料結構與欄位含義。

run-task

啟動語音辨識任務，設定模型、音頻格式、採樣率等參數。

發送時機：建立 WebSocket 串連後立即發送。

響應事件：服務端返回 task-started 事件後才能發送音頻。

headerobject（必選）

屬性

actionstring（必選）

指令類型，固定為 run-task。

task_idstring（必選）

用戶端產生的任務 ID（UUID 格式），用於關聯後續事件。

streamingstring（必選）

固定為 duplex。

payloadobject（必選）

屬性

task_groupstring（必選）

工作群組，固定為 audio。

taskstring（必選）

任務類型，固定為 asr。

functionstring（必選）

功能類型。固定為recognition。

modelstring（必選）

模型名稱。

inputobject（必選）

輸入對象。不攜帶上下文時傳入{}。

屬性

contextarray(object)（可選）

對話上下文，用於輔助識別、提升專有詞彙的識別準確率。使用方法詳見上下文增強。

重要約束：上下文訊息（input_text 和 text 類型）各最多 5 條，超出時保留最近的 5 條。每輪上下文文本總長度（user 和 assistant 的 text 欄位長度之和）不超過 400 個字元（按字元數計算，每個字元計為 1），超出部分從末尾截斷。

重要攜帶上下文時，context 中的訊息順序有要求：上下文訊息必須按對話輪次排列，每輪中 user（input_text 類型）必須在對應的 assistant（text 類型）之前。

屬性

rolestring（必選）

訊息角色。取值範圍：

user：前幾輪使用者語音的識別結果或領域相關的詞表。
assistant：前幾輪大語言模型的回複內容。

contentarray(object)（必選）

訊息內容列表。

屬性

typestring（必選）

內容類型。取值範圍：

input_text：前幾輪使用者語音的識別結果或領域相關的詞表（role 為 user 時使用），需同時傳入 text 欄位。
text：前幾輪大語言模型的回複內容（role 為 assistant 時使用），需同時傳入 text 欄位。

textstring（必選）

常值內容。當 type 為 input_text 時，填入前幾輪使用者語音的識別結果或領域相關的詞表；當 type 為 text 時，填入前幾輪大語言模型的回複內容。

parametersobject（必選）

語音辨識參數。

屬性

keep_dialect boolean (可選)

說明僅適用於 qwen-audio-3.1-asr-flash-streaming。

預設為 false，將方言轉寫為普通話文本。設為 true 時保留方言表達。

vad_model string (可選)

說明僅適用於 qwen-audio-3.1-asr-flash-streaming。

VAD 模型。取值為 near_meeting_16k（近場）或 far_field_meeting_16k（遠場，預設值）。

formatstring（必選）

音頻格式。

取值範圍：

pcm
wav
mp3
opus
speex
aac
amr

重要opus/speex：必須使用Ogg封裝；

wav：必須為PCM編碼；

amr：僅支援AMR-NB類型。

sample_rateinteger（必選）

採樣率（Hz），支援任意採樣率。

vocabulary_idstring（可選）

先行編譯熱詞列表 ID。

需預先調用建立熱詞列表介面產生，識別時傳入該 ID 即可使用列表中的熱詞。

適用於詞彙已知且相對穩定、需要跨請求複用同一詞表的情境。

使用方法請參見先行編譯熱詞。

vocabularyobject（可選）

即時熱詞。

以索引值對形式傳入，鍵為熱詞文本（string），值為熱詞權重（integer），無需預先建立熱詞列表。權重取值範圍為 [1, 5] 或 50：取 [1, 5] 時值越大模型越傾向輸出該詞；取 50 時為超級熱詞，召回率大幅提升，但超級熱詞數量最多不超過 50 個。

適用於臨時性、會話層級的熱詞最佳化。

與先行編譯熱詞同時配置時，僅即時熱詞生效。使用方法請參見即時熱詞。

language_hintsarray[string]（可選）

待識別音頻語種。無預設值，不設定時模型自動識別。

最多支援設定 4 個值，超出時僅前 4 個生效。

點擊查看支援的語言代碼

zh: 中文
en: 英文
ja: 日語
ko：韓語
vi：越南語
th：泰語
id：印尼語
ms：馬來語
tl：菲律賓語
hi：印地語
ar：阿拉伯語
fr：法語
de：德語
es：西班牙語
pt：葡萄牙語
ru：俄語
it：意大利語
nl：荷蘭語
sv：瑞典語
da：丹麥語
fi：芬蘭語
no：挪威語
el：希臘語
pl：波蘭語
cs：捷克語
hu：匈牙利語
ro：羅馬尼亞語
bg：保加利亞語
hr：克羅地亞語
sk：斯洛伐克語

semantic_punctuation_enabledboolean（可選）

是否啟用語義斷句。

預設值：false。

true：開啟語義斷句，關閉 VAD 斷句。
false（預設）：開啟 VAD 斷句，關閉語義斷句。

語義斷句準確性更高，適合會議轉寫情境；VAD（Voice Activity Detection，語音活動檢測）斷句延遲較低，適合互動情境。

max_sentence_silenceinteger（可選）

VAD 斷句靜音閾值（ms）。當一段語音後的靜音時間長度超過該閾值時，系統會判定該句子已結束。當semantic_punctuation_enabled為true時，不作為sentence_end返回依據，但設定過小可能會影響識別效果。

預設值：1300。

取值範圍：[200, 6000]。

multi_threshold_mode_enabledboolean（可選）

重要僅在semantic_punctuation_enabled參數為false時生效。

是否啟用多閾值模式。啟用後可防止 VAD 斷句切割過長。

預設值：false。

heartbeatboolean（可選）

是否啟用心跳包。

預設值：false。

true：在持續發送靜音音訊情況下，可保持與服務端的串連不中斷。
false（預設）：即使持續發送靜音音頻，串連也將在一定時間後因逾時而斷開。

靜音音頻指的是在音頻檔案或資料流中沒有聲音訊號的內容。靜音音頻可以通過多種方法產生，例如使用音頻編輯軟體如Audacity或Adobe Audition，或者通過命令列工具如FFmpeg。

speech_noise_thresholdfloat（可選）

語音與噪音的判定閾值，用於調整語音活動檢測（VAD）的靈敏度。

取值範圍：[-1.0, 1.0]。

取值說明：

取值越接近 -1：降低噪音判定閾值，噪音被識別為語音的機率增大，可能導致更多噪音被轉寫
取值越接近 +1：提高噪音判定閾值，語音被誤判為噪音的機率增大，可能導致部分語音被過濾

此參數為進階配置參數，調整可能顯著影響識別效果，建議：

調整前充分測實驗證效果
根據實際音頻環境小幅度調整（建議步長 0.1）

special_word_filter string（可選）

指定在語音辨識過程中需要處理的敏感詞，並支援對不同敏感詞設定不同的處理方式。詳情請參見敏感詞過濾。

基本請求

{
    "header": {
        "action": "run-task",
        "task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
        "streaming": "duplex"
    },
    "payload": {
        "task_group": "audio",
        "task": "asr",
        "function": "recognition",
        "model": "qwen-audio-3.0-asr-flash-streaming",
        "parameters": {
            "format": "pcm",
            "sample_rate": 16000
        },
        "input": {}
    }
}

攜帶上下文

{
    "header": {
        "action": "run-task",
        "task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
        "streaming": "duplex"
    },
    "payload": {
        "task_group": "audio",
        "task": "asr",
        "function": "recognition",
        "model": "qwen-audio-3.0-asr-flash-streaming",
        "parameters": {
            "format": "pcm",
            "sample_rate": 16000
        },
        "input": {
            "context": [
                {
                    "role": "user",
                    "content": [
                        {
                            "type": "input_text",
                            "text": "你好啊"
                        }
                    ]
                },
                {
                    "role": "assistant",
                    "content": [
                        {
                            "type": "text",
                            "text": "你好啊，我是通義千問，有什麼可以協助你的？"
                        }
                    ]
                }
            ]
        }
    }
}

即時熱詞

{
    "header": {
        "action": "run-task",
        "task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
        "streaming": "duplex"
    },
    "payload": {
        "task_group": "audio",
        "task": "asr",
        "function": "recognition",
        "model": "qwen-audio-3.0-asr-flash-streaming",
        "parameters": {
            "format": "pcm",
            "sample_rate": 16000,
            "vocabulary": {"張三": 5, "李四": 5}
        },
        "input": {}
    }
}

continue-task

在任務執行過程中更新對話上下文資訊，用於輔助識別。

發送時機：任務運行中，需要更新對話上下文時發送。

headerobject（必選）

屬性

actionstring（必選）

指令類型，固定為 continue-task。

task_idstring（必選）

用戶端產生的任務 ID（UUID 格式），需與run-task事件中的 task_id 保持一致。

streamingstring（必選）

固定為 duplex。

payloadobject（必選）

屬性

inputobject（必選）

輸入對象。

屬性

contextarray(object)（可選）

對話上下文，用於輔助識別、提升專有詞彙的識別準確率。使用方法詳見上下文增強。

屬性

rolestring（必選）

訊息角色。取值範圍：

user：前幾輪使用者語音的識別結果或領域相關的詞表。
assistant：前幾輪大語言模型的回複內容。

contentarray(object)（必選）

訊息內容列表。

屬性

typestring（必選）

內容類型。取值範圍：

input_text：前幾輪使用者語音的識別結果或領域相關的詞表（role 為 user 時使用），需同時傳入 text 欄位。
text：前幾輪大語言模型的回複內容（role 為 assistant 時使用），需同時傳入 text 欄位。

textstring（必選）

常值內容。當 type 為 input_text 時，填入前幾輪使用者語音的識別結果或領域相關的詞表；當 type 為 text 時，填入前幾輪大語言模型的回複內容。

{
    "header": {
        "action": "continue-task",
        "task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
        "streaming": "duplex"
    },
    "payload": {
        "input": {
            "context": [
                {
                    "role": "user",
                    "content": [
                        {
                            "type": "input_text",
                            "text": "你好啊"
                        }
                    ]
                },
                {
                    "role": "assistant",
                    "content": [
                        {
                            "type": "text",
                            "text": "你好啊，我是通義千問，有什麼可以協助你的？"
                        }
                    ]
                }
            ]
        }
    }
}

finish-task

通知服務端音頻發送完畢，請求結束任務。

發送時機：所有音頻資料發送完畢後。

響應事件：服務端返回 task-finished 事件。

headerobject（必選）

屬性

actionstring（必選）

指令類型，固定為 finish-task。

task_idstring（必選）

用戶端產生的任務 ID（UUID 格式），需與run-task事件中的 task_id 保持一致。

streamingstring（必選）

固定為 duplex。

payloadobject（必選）

屬性

inputobject（必選）

固定為{}。

{
    "header": {
        "action": "finish-task",
        "task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
        "streaming": "duplex"
    },
    "payload": {
        "input": {}
    }
}