本文介紹 Fun-ASR-Realtime 即時語音辨識服務中用戶端通過 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（必選） 輸入對象。不攜帶上下文時傳入{}。 重要僅 fun-asr-realtime 模型支援上下文。 屬性 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（必選） 音頻格式。 取值範圍：
pcmwavmp3opusspeexaacamr 重要opus/speex：必須使用Ogg封裝； wav：必須為PCM編碼； amr：僅支援AMR-NB類型。 sample_rateinteger（必選） 採樣率（Hz）。 取值範圍：8k模型僅支援 8000 Hz，其他模型支援任意採樣率。 vocabulary_idstring（可選） 先行編譯熱詞列表 ID。 需預先調用建立熱詞列表介面產生，識別時傳入該 ID 即可使用列表中的熱詞。 適用於詞彙已知且相對穩定、需要跨請求複用同一詞表的情境。 使用方法請參見先行編譯熱詞。 language_hintsarray[string]（可選） 待識別音頻語種。無預設值，不設定時模型自動識別。 僅支援設定 1 個值，設定多個時僅第一個生效。 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": "fun-asr-realtime",
"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": "fun-asr-realtime",
"parameters": {
"format": "pcm",
"sample_rate": 16000
},
"input": {
"context": [
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "你好啊"
}
]
},
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "你好啊，我是通義千問，有什麼可以協助你的？"
}
]
}
]
}
}
}
|
continue-task
在任務執行過程中更新對話上下文資訊，用於輔助識別。
發送時機：任務運行中，需要更新對話上下文時發送。
重要僅 fun-asr-realtime 模型支援該事件。
headerobject（必選） 屬性 actionstring（必選） 指令類型，固定為 continue-task。 task_idstring（必選） 用戶端產生的任務 ID（UUID 格式），需與run-task事件中的 task_id 保持一致。 streamingstring（必選） 固定為 duplex。 payloadobject（必選） 屬性 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 時，填入前幾輪大語言模型的回複內容。 | {
"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（必選） | {
"header": {
"action": "finish-task",
"task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
"streaming": "duplex"
},
"payload": {
"input": {}
}
}
|