使用 C# SDK 透過 WebSocket 向 Qwen-Audio-Realtime 即時傳送音訊,接收文字與音訊回應。
前提條件
取得 API Key 並將 API Key 設定為環境變數 DASHSCOPE_API_KEY。API Key 和業務空間須屬於同一地區。
安裝 SDK
下載 Bailian.DashScope-1.1.0.zip 並解壓。SDK 支援 net8.0 和 net10.0。在項目目錄執行以下命令,--source 使用解壓後 packages/ 目錄的路徑。
sdk/net8.0/ 或 sdk/net10.0/ 下與項目目標框架對應的 DashScope.dll。將 DashScope.xml 放在 DLL 同一目錄可在 IDE 中查看介面註釋。
快速開始
執行隨附範例
- 建立 .NET 10 主控台專案並依照上文安裝 SDK。
- 將
input.pcm放在專案目錄。使用 16 kHz、單聲道、16 bit 小端序裸 PCM。若來源檔案是 WAV,請先轉成裸 PCM。
WorkspaceId 替換為實際的業務空間 ID。各模型適用的地區與位址請參閱 WebSocket 接入。
在專案中呼叫
以下程式碼將一段裸 PCM 音訊按即時節奏傳送,等待回應結束後,再將音訊寫入 output.pcm。用以下程式碼取代 Program.cs。
請求參數
| 選項 | 類型 | 預設值 | 說明 |
|---|---|---|---|
ApiKey | string? | null | 百煉 API Key。未設定時讀取 DASHSCOPE_API_KEY。 |
Url | string | wss://dashscope.aliyuncs.com/api-ws/v1/realtime | WebSocket 地址。SDK 將 Model 拼接到 URL 的 model 查詢參數。 |
WorkspaceId | string? | null | 業務空間 ID。設定後透過 X-DashScope-WorkSpace 請求頭傳遞。使用業務空間專屬網域時,透過 Url 指定完整地址。 |
ConnectTimeout | TimeSpan | 10 s | 建立 WebSocket 連接的逾時時間。 |
StartTimeout | TimeSpan | 10 s | 等待 session.created 的逾時時間。 |
StopTimeout | TimeSpan | 10 s | 等待 session.finished 的逾時時間,適用於等待該事件的收尾方式。 |
FinishMode | QwenRealtimeFinishMode? | null | 留空時依模型選擇收尾方式。可讀取實例的 FinishMode 查看實際取值。 |
Model | string | qwen-audio-3.1-realtime-plus | 模型 ID。呼叫 Omni 時顯式設定為所選 Omni Realtime 模型。 |
Modalities | IList<string> | ["text", "audio"] | 輸出模態。僅需文字時設為 ["text"]。 |
Voice | string? | null | 輸出音頻使用的音色。null 由服務端選擇預設值。Audio 3.1 範例明確傳入 longanfengyue_v3.1。 |
EnableSpeechEmotion | bool? | null | 情感語音開關,適用範圍以模型的客戶端事件參考為準。 |
Instructions | string? | null | 系統提示詞。 |
MaxHistoryTurns | int? | null | 保留的歷史問答輪數,取值 1 至 50。 |
ToolsJson | string? | null | 函數工具定義,傳入 OpenAI 格式的 tools JSON 數組字串。 |
TurnDetectionMode | QwenTurnDetectionMode | ServerVad | 輪次檢測模式。ServerVad 由服務端檢測語音起止。部分模型也支援 SmartTurn。PushToTalk 由客戶端提交音頻並請求應答。 |
VadThreshold | double? | null | 服務端 VAD 閾值,取值 -1.0 至 1.0,僅用於 ServerVad。 |
VadSilenceMs | int? | null | 句尾靜音時長,取值 200 至 6000 毫秒,僅用於 ServerVad。未設定時使用服務端預設值。 |
Url 設定業務空間專屬域名。各地域位址見 Audio Realtime WebSocket 接入 或 Omni Realtime WebSocket 接入。
介面參考
Audio Realtime 與 Omni Realtime 均使用 DashScope.Qwen.QwenRealtimeConversation。建立實例時傳入 QwenRealtimeConversationOptions。預設模型為 Audio Realtime,呼叫 Omni 時需顯式傳入 Omni 模型 ID。
方法
除 DisposeAsync 外,下列方法返回 Task。ct 為可選取消令牌。
| 方法 | 說明 |
|---|---|
ConnectAsync(CancellationToken ct = default) | 建立連接,等待 session.created,然後傳送 session.update。 |
AppendAudioAsync(ReadOnlyMemory<byte> pcm, CancellationToken ct = default) | 傳送一幀音頻。SDK 將字節編碼為 Base64 並透過 input_audio_buffer.append 發送。 |
CommitAudioAsync(CancellationToken ct = default) | 在 PushToTalk 下用 input_audio_buffer.commit 提交音頻緩衝。 |
CreateResponseAsync(JsonObject? responseOptions = null, CancellationToken ct = default) | 傳送 response.create 請求應答。responseOptions 為本輪回應提供可選的覆蓋設定。 |
SendItemAsync(JsonObject item, CancellationToken ct = default) | 使用 conversation.item.create 將 item 加入會話。 |
SendFunctionCallOutputAsync(string callId, string outputJson, CancellationToken ct = default) | 使用事件提供的 callId 和結果 JSON 文本回傳工具結果。 |
SendRawEventAsync(string frameJson, CancellationToken ct = default) | 原樣傳送一條完整的客戶端事件 JSON,可用於 SDK 尚未單獨封裝的事件。 |
FinishAsync(CancellationToken ct = default) | 按實際 FinishMode 正常結束會話。 |
AbortAsync() | 立即關閉連接,放棄途中的結果。 |
DisposeAsync() | 異步釋放資源,返回 ValueTask。 |
PushToTalk 模式下,傳送音頻後依序呼叫 CommitAudioAsync 和 CreateResponseAsync。處理函數呼叫時,收到 FunctionCallReceived 後執行工具並回傳結果。需要模型繼續應答時,再呼叫 CreateResponseAsync。
事件
| 事件 | 事件參數 | 觸發條件 |
|---|---|---|
SessionReady | string? | 對話已準備就緒,值為 session.id。 |
UserSpeechStarted | QwenSpeechEventArgs | 服務端 VAD 檢測到使用者開始說話。 |
UserSpeechStopped | QwenSpeechEventArgs | 服務端 VAD 檢測到使用者停止說話。 |
UserTranscriptUpdated | QwenTranscriptEventArgs | 目前的輸入轉寫文字,後續可修正。 |
UserTranscriptCompleted | QwenTranscriptEventArgs | 一句輸入語音的最終轉寫。 |
AssistantTextDelta | QwenTextDeltaEventArgs | 回應文字增量。依序拼接。 |
AssistantTextCompleted | QwenTranscriptEventArgs | 完整的回應文字。 |
AssistantAudioChunk | QwenAudioChunkEventArgs | 回應音頻片段,24 kHz 單聲道 16 bit 小端裸 PCM。 |
AssistantAudioCompleted | EventArgs | 本回合回應音頻全部傳送完畢。 |
FunctionCallReceived | QwenFunctionCallEventArgs | 模型請求調用工具,提供調用 ID、工具名稱與 JSON 參數。 |
ResponseCompleted | QwenResponseSummary | 收到 response.done,回傳狀態與用量。 |
RawServerEvent | QwenServerEventArgs | 原始服務端事件,可讀取事件類型與 JSON 物件。 |
ErrorOccurred | DashScopeErrorEventArgs | 服務端錯誤或連接異常。 |
結果物件
| 類型 | 屬性 | 說明 |
|---|---|---|
QwenResponseSummary | Status: string?, FailureReason: string?, TotalTokens: int?, InputTokens: int?, OutputTokens: int?, AudioInputTokens: int?, AudioOutputTokens: int? | 回應狀態、失敗原因和用量。Status 可為 completed、failed 或 incomplete。對話用量按回合統計,翻譯用量為會話累計值。 |
QwenSpeechEventArgs | AudioMs: long, ItemId: string? | 語音邊界的毫秒位置與輸入項目 ID。 |
QwenTranscriptEventArgs | Text: string, ItemId: string? | 目前轉寫或完整文字及項目 ID。 |
QwenTextDeltaEventArgs | Delta: string, ItemId: string? | 文字增量及項目 ID。 |
QwenAudioChunkEventArgs | Pcm: byte[] | 音頻片段。 |
QwenFunctionCallEventArgs | CallId: string, Name: string?, ArgumentsJson: string? | 工具調用 ID、名稱與參數。回傳結果時使用原始 CallId。 |
QwenServerEventArgs | Type: string?, Root: JsonObject | 事件類型與完整 JSON。 |
DashScopeErrorEventArgs | Code: int, ServerErrorCode: string?, ServerErrorMessage: string?, TaskId: string?, InnerException: Exception? | SDK 錯誤碼、服務端錯誤碼與訊息、任務或會話 ID,以及底層例外狀況。 |
會話收尾
多輪對話可重複使用同一條 WebSocket 連接。在最後一輪的 ResponseCompleted 到達後呼叫 FinishAsync,避免截斷回應。
| 收尾模式 | 行為 |
|---|---|
FinishWithoutWait | 發送 session.finish 後斷開。Audio Realtime 預設使用此模式。 |
CloseOnly | 直接關閉連接。Omni Realtime 預設使用此模式。 |
FinishAndWait | 發送 session.finish 並等待 session.finished。伺服器也可透過關閉連接結束會話。 |