C# SDK を使用して、WebSocket を介して Qwen-Audio-Realtime に音声をストリーミングし、テキストおよび音声の応答を受信します。
前提条件
API キーを取得し、環境変数 DASHSCOPE_API_KEY に設定します。ワークスペースと同じリージョンの API キーを使用してください。
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 を参照することもできます。IDE で API ドキュメントを表示するには、DLL の隣に DashScope.xml を配置してください。
クイックスタート
同梱サンプルの実行
- .NET 10 コンソールプロジェクトを作成し、上の手順で SDK をインストールします。
input.pcmをプロジェクトディレクトリに配置します。音声は 16 kHz、モノラル、16 ビットリトルエンディアンのヘッダーなし PCM を使用してください。WAV ファイルは、あらかじめヘッダーなし PCM に変換します。
シンガポールリージョンのワークスペース専用 WebSocket エンドポイントを設定します。WorkspaceId を実際のワークスペース ID に置き換えてください。サポートされているリージョンとエンドポイントは WebSocket での接続 をご覧ください。
export DASHSCOPE_REALTIME_URL="wss://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime"
プロジェクトからの呼び出し
このプログラムはリアルタイムで RAW 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}");
クイックスタートで使用した RAW PCM ファイルをプロジェクトディレクトリに配置し、例を実行してください。
dotnet run -- input.pcm qwen-audio-3.1-realtime-plus longanfengyue_v3.1
リクエストパラメーター
| オプション | 型 | デフォルト | 説明 |
|---|---|---|---|
ApiKey | string? | null | Model Studio API キー。省略された場合、SDK は DASHSCOPE_API_KEY を読み取ります。 |
Url | string | wss://dashscope.aliyuncs.com/api-ws/v1/realtime | WebSocket エンドポイント。SDK は Model を model クエリパラメータとして追加します。 |
WorkspaceId | string? | null | X-DashScope-WorkSpace ヘッダーに送信されるワークスペース ID。ワークスペース固有のエンドポイントを使用するには、Url に完全なアドレスを設定してください。 |
ConnectTimeout | TimeSpan | 10 s | WebSocket 接続を開くためのタイムアウト。 |
StartTimeout | TimeSpan | 10 s | session.created を受信するためのタイムアウト。 |
StopTimeout | TimeSpan | 10 s | 終了モードがそのイベントを待つ場合の、session.finished 受信のタイムアウト。 |
FinishMode | QwenRealtimeFinishMode? | null | 省略された場合、SDK はモデルに基づいて終了モードを選択します。インスタンスの 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 ~ 6,000 ミリ秒)。ServerVad に適用される。省略された場合、モデルはサーバーのデフォルト値を使用する。 |
Url をワークスペース固有のエンドポイントに設定してください。地域エンドポイントについては Audio Realtime WebSocket アクセス または Omni Realtime WebSocket アクセス を参照してください。
API リファレンス
Audio Realtime および Omni Realtime は両方とも DashScope.Qwen.QwenRealtimeConversation を使用します。コンストラクタに QwenRealtimeConversationOptions を渡してください。デフォルトでは Audio Realtime モデルが指定されます。Omni を使用する場合は、明示的に Omni モデル ID を設定してください。
メソッド
以下のメソッドは Task を返すが、DisposeAsync を除く。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) | バッファリングされた音声を input_audio_buffer.commit でコミットし、PushToTalk モードで処理する。 |
CreateResponseAsync(JsonObject? responseOptions = null, CancellationToken ct = default) | response.create で応答を要求する。responseOptions は現在の応答に対するオプションの上書きを提供する。 |
SendItemAsync(JsonObject item, CancellationToken ct = default) | item を conversation.item.create を使用して会話に追加する。 |
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ビットリトルエンディアンの生データ形式の応答音声チャンク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のいずれかになります。会話の使用状況は1ターンごと、翻訳の使用状況はセッション全体で累積されます。 |
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、および下位の例外。 |
セッションの終了
複数の会話ターンにわたり接続を再利用します。最終的なResponseCompletedイベントの後にFinishAsyncを呼び出すことで、応答の切り捨てを回避できます。
| 終了モード | 動作 |
|---|---|
FinishWithoutWait | session.finish を送信し、接続を閉じます。これは Audio Realtime の既定値です。 |
CloseOnly | 接続を閉じます。これは Omni Realtime の既定値です。 |
FinishAndWait | session.finish を送信し、session.finished の受信を待ちます。サーバーは接続の閉鎖によりセッションを終了することもできます。 |