全部產品
Search
文件中心

Alibaba Cloud Model Studio:Qwen-Audio-Realtime C# SDK

更新時間:Nov 17, 2026

使用 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 中查看介面註釋。

快速開始

  1. 取得 API Key 並將 API Key 設定為環境變數 DASHSCOPE_API_KEY。API Key 和業務空間須屬於同一地區。
  2. 建立 .NET 10 主控台專案並依照上文安裝 SDK。
  3. 將 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。

連接與會話選項

選項類型預設值說明
ApiKeystring?null百煉 API Key。未設定時讀取 DASHSCOPE_API_KEY。
Urlstringwss://dashscope.aliyuncs.com/api-ws/v1/realtimeWebSocket 地址。SDK 將 Model 拼接到 URL 的 model 查詢參數。
WorkspaceIdstring?null業務空間 ID。設定後透過 X-DashScope-WorkSpace 請求頭傳遞。使用業務空間專屬網域時,透過 Url 指定完整地址。
ConnectTimeoutTimeSpan10 s建立 WebSocket 連接的逾時時間。
StartTimeoutTimeSpan10 s等待 session.created 的逾時時間。
StopTimeoutTimeSpan10 s等待 session.finished 的逾時時間,適用於等待該事件的收尾方式。
FinishModeQwenRealtimeFinishMode?null留空時依模型選擇收尾方式。可讀取實例的 FinishMode 查看實際取值。
Modelstringqwen-audio-3.1-realtime-plus模型 ID。呼叫 Omni 時顯式設定為所選 Omni Realtime 模型。
ModalitiesIList<string>["text", "audio"]輸出模態。僅需文字時設為 ["text"]。
Voicestring?null輸出音頻使用的音色。null 由服務端選擇預設值。Audio 3.1 範例明確傳入 longanfengyue_v3.1。
EnableSpeechEmotionbool?null情感語音開關,適用範圍以模型的客戶端事件參考為準。
Instructionsstring?null系統提示詞。
MaxHistoryTurnsint?null保留的歷史問答輪數,取值 1 至 50。
ToolsJsonstring?null函數工具定義,傳入 OpenAI 格式的 tools JSON 數組字串。
TurnDetectionModeQwenTurnDetectionModeServerVad輪次檢測模式。ServerVad 由服務端檢測語音起止。部分模型也支援 SmartTurn。PushToTalk 由客戶端提交音頻並請求應答。
VadThresholddouble?null服務端 VAD 閾值,取值 -1.0 至 1.0,僅用於 ServerVad。
VadSilenceMsint?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。

事件

事件事件參數觸發條件
SessionReadystring?對話已準備就緒,值為 session.id。
UserSpeechStartedQwenSpeechEventArgs服務端 VAD 檢測到使用者開始說話。
UserSpeechStoppedQwenSpeechEventArgs服務端 VAD 檢測到使用者停止說話。
UserTranscriptUpdatedQwenTranscriptEventArgs目前的輸入轉寫文字,後續可修正。
UserTranscriptCompletedQwenTranscriptEventArgs一句輸入語音的最終轉寫。
AssistantTextDeltaQwenTextDeltaEventArgs回應文字增量。依序拼接。
AssistantTextCompletedQwenTranscriptEventArgs完整的回應文字。
AssistantAudioChunkQwenAudioChunkEventArgs回應音頻片段,24 kHz 單聲道 16 bit 小端裸 PCM。
AssistantAudioCompletedEventArgs本回合回應音頻全部傳送完畢。
FunctionCallReceivedQwenFunctionCallEventArgs模型請求調用工具,提供調用 ID、工具名稱與 JSON 參數。
ResponseCompletedQwenResponseSummary收到 response.done,回傳狀態與用量。
RawServerEventQwenServerEventArgs原始服務端事件,可讀取事件類型與 JSON 物件。
ErrorOccurredDashScopeErrorEventArgs服務端錯誤或連接異常。

結果物件

類型屬性說明
QwenResponseSummaryStatus: string?, FailureReason: string?, TotalTokens: int?, InputTokens: int?, OutputTokens: int?, AudioInputTokens: int?, AudioOutputTokens: int?回應狀態、失敗原因和用量。Status 可為 completed、failed 或 incomplete。對話用量以回合返回,翻譯用量為會話累計值。
QwenSpeechEventArgsAudioMs: long, ItemId: string?語音起止在輸入流中的毫秒位置與項目 ID。
QwenTranscriptEventArgsText: string, ItemId: string?目前轉寫或完整文字及項目 ID。
QwenTextDeltaEventArgsDelta: string, ItemId: string?文字增量及項目 ID。
QwenAudioChunkEventArgsPcm: byte[]音頻片段。
QwenFunctionCallEventArgsCallId: string, Name: string?, ArgumentsJson: string?工具調用 ID、名稱與參數。回傳結果時使用原始 CallId。
QwenServerEventArgsType: string?, Root: JsonObject事件類型與完整 JSON。
DashScopeErrorEventArgsCode: 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。伺服器也可透過關閉連接結束會話。