本文檔介紹如何使用 DashScope Python SDK 調用即時語音辨識(Qwen-ASR-Realtime)模型。
前提條件
- 安裝SDK,確保DashScope SDK版本不低於2.0.1。
- 擷取API Key。
- 瞭解WebSocket API。
快速開始
your_audio_file.pcm(PCM16、16 kHz、單聲道)。如僅有 MP3/WAV 等格式,可使用 ffmpeg 轉換:請求參數
-
以下參數通過
client.audio.realtime.connect方法設定。點擊查看範例程式碼
參數
類型
是否必須
說明
modelstr是
指定要使用的模型名稱。
ws_urlstr否
完整WebSocket端點,未指定時按
Client的workspace與region自動選擇端點:華北2(北京)地區:
wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime。調用時請將{WorkspaceId}替換為真實的Workspace ID。新加坡地區:
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime。調用時請將{WorkspaceId}替換為真實的業務空間ID。
-
以下參數通過
RealtimeSession的update_session方法設定。點擊查看範例程式碼
參數
類型
是否必須
說明
output_modalitiesList[str]是
模型輸出模態,固定為
["text"]。enable_turn_detectionbool否
是否開啟服務端語音活動檢測(VAD)。關閉後,需手動調用
commit()方法觸發識別。預設值:
True。取值範圍:
True:開啟False:關閉
turn_detection_typestr否
服務端VAD類型,固定為
server_vad。turn_detection_thresholdfloat否
VAD檢測閾值。推薦將該值設為
0.0。預設值:
0.2。取值範圍:
[-1, 1]。較低的閾值會提高 VAD 的靈敏度,可能將背景雜音誤判為語音。較高的閾值則降低靈敏度,有助於在嘈雜環境中減少誤觸發。
turn_detection_silence_duration_msint否
VAD斷句檢測閾值(ms)。靜音持續時間長度超過該閾值將被認為是語句結束。推薦將該值設為
400。預設值:
800。取值範圍:
[200, 6000]。較低的值(如 300ms)可使模型更快響應,但可能導致在自然停頓處發生不合理的斷句。較高的值(如 1200ms)可更好地處理長句內的停頓,但會增加整體響應延遲。
transcription_paramsdict否
語音辨識相關配置。
-
以下參數通過
update_session的transcription_params字典設定。點擊查看範例程式碼
參數
類型
是否必須
說明
languagestr否
音頻源語言。
zh:中文(普通話、四川話、閩南語、吳語)
yue:粵語
en:英文
ja:日語
de:德語
ko:韓語
ru:俄語
fr:法語
pt:葡萄牙語
ar:阿拉伯語
it:意大利語
es:西班牙語
hi:印地語
id:印尼語
th:泰語
tr:土耳其語
uk:烏克蘭語
vi:越南語
cs:捷克語
da:丹麥語
fil:菲律賓語
fi:芬蘭語
is:冰島語
ms:馬來語
no:挪威語
pl:波蘭語
sv:瑞典語
sample_rateint否
音頻採樣率(Hz)。支援
16000和8000。預設值:
16000。設定為
8000時,服務端會先升採樣到16000Hz再進行識別,可能引入微小延遲。建議僅在源音頻為8000Hz(如電話線路)時使用。input_audio_formatstr否
音頻格式。支援
pcm和opus。預設值:
pcm。
介面參考
RealtimeSession(client.audio.realtime.connect)
即時識別會話通過client.audio.realtime.connect(model=...)建立:進入with上下文(或調用會話的connect()方法)後建立串連。
| 方法簽名 | 服務端響應事件(通過events()下發) | 說明 |
|---|---|---|
session.created會話已建立session.updated 會話配置已更新 | 和服務端建立串連。進入with上下文時自動調用,勿先connect()再進入同一會話的with。 | |
session.updated會話配置已更新 | 用於更新會話配置,建議在串連建立後首先調用該方法進行設定。若未調用該方法,系統將使用預設配置。只需關注請求參數中的涉及到的參數。 | |
| 無 | 將音頻資料片段追加到雲端輸入音頻緩衝區。str視為已編碼的Base64,bytes會自動Base64編碼。 | |
input_audio_buffer.committed服務端收到提交的音頻 | 提交之前通過append添加到雲端緩衝區的音視頻,如果輸入的音頻緩衝區為空白將產生錯誤。禁用情境:請求參數enable_turn_detection設為True時。 | |
session.finished服務端完成語音辨識,結束會話 | 通知服務端結束會話,服務端收到會話結束通知後將完成最後的語音辨識。調用時機:
| |
| 無 | 終止任務,並關閉串連(冪等,不發送session.finish)。 | |
| 無 | 擷取當前任務的session_id、最近一次response的response_id(屬性)。 |
事件迭代(events())
服務端會通過事件的方式,將服務端響應事件和資料返回給用戶端。您需要在接收線程中迭代會話的events(),按event["type"]分發處理(完整事件列表參見服務端事件)。
| 方法簽名 | 參數 | 說明 |
|---|---|---|
| event:服務端事件 | 連續讀取並逐個產出服務端事件(dict)。串連關閉或收到session.finished後迭代結束。 | |
| 無 | 阻塞讀取單條服務端事件,不自動迴圈;無事件(串連關閉)時返回None。 |