即時語音辨識（Qwen-Audio-3.0-ASR-Flash-Streaming/Fun-ASR-Realtime）用戶端事件_Alibaba Cloud Model Studio(Model Studio) - Alibaba Cloud Model Studio

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

使用者指南：關於模型介紹和選型建議請參見語音辨識。

事件互動流程：如需瞭解事件互動時序，請參見WebSocket API。

run-task

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

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

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

headerobject（必選）

屬性

actionstring（必選）

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

task_idstring（必選）

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

streamingstring（必選）

固定為 duplex。

payloadobject（必選）

屬性

task_groupstring（必選）

工作群組，固定為 audio。

taskstring（必選）

任務類型，固定為 asr。

functionstring（必選）

功能類型。固定為recognition。

modelstring（必選）

指定模型名。支援Qwen-Audio-3.0-ASR-Flash-Streaming和Fun-ASR-Realtime系列模型，詳情請參見支援的模型與地區。

inputobject（必選）

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

重要僅 qwen-audio-3.0-asr-flash-streaming、fun-asr-realtime 和 fun-asr-realtime-2025-11-07 模型支援上下文。

屬性

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（必選）

語音辨識參數。

屬性

formatstring（必選）

音頻格式。

取值範圍：

pcm
wav
mp3
opus
speex
aac
amr

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

wav：必須為PCM編碼；

amr：僅支援AMR-NB類型。

sample_rateinteger（必選）

採樣率（Hz）。

取值範圍：8k模型僅支援 8000 Hz，其他模型支援任意採樣率。

vocabulary_idstring（可選）

先行編譯熱詞列表 ID。

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

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

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

vocabularyobject（可選）

即時熱詞。

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

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

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

重要僅qwen-audio-3.0-asr-flash-streaming支援即時熱詞。

language_hintsarray[string]（可選）

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

對於 Qwen-Audio-3.0-ASR-Flash-Streaming 系列模型，最多支援設定 4 個值，即便設定超出 4 個，也僅前 4 個生效；對於 Fun-ASR-Realtime 系列模型，僅支援設定 1 個值，即便設定多個，也僅第一個生效。

點擊查看支援的語言代碼

qwen-audio-3.0-asr-flash-streaming、fun-asr-realtime、fun-asr-realtime-2025-11-07：
- 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：斯洛伐克語
fun-asr-realtime-2026-02-28：
- zh: 中文
- en: 英文
- ja: 日語
fun-asr-realtime-2025-09-15：
- zh: 中文
- en: 英文
fun-asr-flash-8k-realtime、fun-asr-flash-8k-realtime-2026-01-28：
- zh: 中文

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

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

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

重要僅 qwen-audio-3.0-asr-flash-streaming、fun-asr-realtime 和 fun-asr-realtime-2025-11-07 模型支援該事件。

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": {}
    }
}