使用 C# SDK 透過 WebSocket 向 Qwen-Audio-Realtime 即時傳送音訊,接收文字與音訊回應。
安裝 SDK
下載 Bailian.DashScope-1.1.0.zip 並解壓。SDK 支援 net8.0 和 net10.0。在項目目錄執行以下命令,將範例路徑改為解壓後的 packages/ 目錄。
dotnet add package Bailian.DashScope --version 1.1.0 --source "/path/to/Bailian.DashScope-1.1.0/packages"
也可直接引用解壓目錄 sdk/net8.0/ 或 sdk/net10.0/ 下與項目目標框架對應的 DashScope.dll。將 DashScope.xml 放在 DLL 同一目錄可在 IDE 中查看介面註釋。
快速開始
- 取得 API Key 並將 API Key 設定為環境變數
DASHSCOPE_API_KEY。API Key 和業務空間須屬於同一地區。 - 建立 .NET 10 主控台專案並依照上文安裝 SDK。
- 將
input.pcm放在專案目錄。使用 16 kHz、單聲道、16 bit 小端序裸 PCM。若來源檔案是 WAV,請先轉成裸 PCM。
設定新加坡地區的業務空間 WebSocket 位址。將 WorkspaceId 替換為實際的業務空間 ID。各模型適用的地區與位址請參閱 WebSocket 接入。
export DASHSCOPE_REALTIME_URL="wss://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime"
C# 呼叫範例
以下程式碼將一段裸 PCM 音訊按即時節奏傳送,等待回應結束後,再將音訊寫入 output.pcm。用以下程式碼取代 Program.cs。
using DashScope.Qwen;
if (args.Length < 2)
throw new ArgumentException("Usage: <input.pcm> <model> [voice]");
using var timeout = new CancellationTokenSource(TimeSpan.FromSeconds(60));
var ct = timeout.Token;
await using var client = new QwenRealtimeConversation(new QwenRealtimeConversationOptions
{
Model = args[1],
Voice = args.Length > 2 ? args[2] : null,
Url = Environment.GetEnvironmentVariable("DASHSCOPE_REALTIME_URL")
?? throw new InvalidOperationException("Set DASHSCOPE_REALTIME_URL to your workspace WebSocket endpoint."),
Modalities = ["text", "audio"],
TurnDetectionMode = QwenTurnDetectionMode.ServerVad,
});
using var output = File.Create("output.pcm");
var completed = new TaskCompletionSource<string?>(TaskCreationOptions.RunContinuationsAsynchronously);
client.AssistantTextCompleted += (_, e) => Console.WriteLine(e.Text);
client.AssistantAudioChunk += (_, e) => output.Write(e.Pcm);
client.ResponseCompleted += (_, e) => completed.TrySetResult(e.Status);
client.ErrorOccurred += (_, e) => completed.TrySetException(
new InvalidOperationException($"{e.ServerErrorCode}: {e.ServerErrorMessage}"));
await client.ConnectAsync(ct);
using var input = File.OpenRead(args[0]);
var frame = new byte[640];
int size;
while ((size = await input.ReadAsync(frame.AsMemory(), ct)) > 0)
{
await client.AppendAudioAsync(frame.AsMemory(0, size), ct);
await Task.Delay(20, ct);
}
Array.Clear(frame);
for (var i = 0; i < 60; i++)
{
await client.AppendAudioAsync(frame, ct);
await Task.Delay(20, ct);
}
var status = await completed.Task.WaitAsync(ct);
await client.FinishAsync(ct);
if (status != "completed" || output.Length == 0)
throw new InvalidOperationException($"Status: {status}, audio bytes: {output.Length}");
將快速開始中的裸 PCM 檔案放到專案目錄,執行。
dotnet run -- input.pcm qwen-audio-3.1-realtime-plus longanfengyue_v3.1
API 參考
Audio Realtime 與 Omni Realtime 均使用 DashScope.Qwen.QwenRealtimeConversation。建立實例時傳入 QwenRealtimeConversationOptions。預設模型為 Audio Realtime,呼叫 Omni 時需顯式傳入 Omni 模型 ID。
連接與會話選項
| 選項 | 類型 | 預設值 | 說明 |
|---|---|---|---|
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 接入。
方法
除 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 可覆蓋本輪 response 設定。 |
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。伺服器也可透過關閉連接結束會話。 |