Skip to main content

SDK C# untuk Qwen-Audio-Realtime

Gunakan C# SDK untuk mengalirkan audio ke Qwen-Audio-Realtime melalui WebSocket dan menerima respons teks serta audio.

Prasyarat

Dapatkan kunci API dan simpan nilainya di variabel lingkungan DASHSCOPE_API_KEY. Gunakan kunci API dari wilayah yang sama dengan workspace Anda.

Instal SDK

Unduh dan ekstrak Bailian.DashScope-1.1.0.zip. SDK ini ditujukan untuk net8.0 dan net10.0. Jalankan perintah berikut dari direktori proyek Anda, menggunakan jalur ke direktori packages/ yang diekstrak.
dotnet add package Bailian.DashScope --version 1.1.0 --source "/path/to/Bailian.DashScope-1.1.0/packages"
Anda juga dapat merujuk DashScope.dll dari direktori sdk/net8.0/ atau sdk/net10.0/ yang diekstrak yang sesuai dengan kerangka kerja tujuan Anda. Pastikan DashScope.xml berada di sebelah DLL agar dokumentasi API muncul di IDE Anda.

Mulai cepat

Menjalankan contoh bawaan

  1. Buat proyek konsol .NET 10 dan instal SDK seperti dijelaskan di atas.
  2. Simpan input.pcm di direktori proyek. Gunakan PCM mentah 16 kHz, mono, 16-bit little-endian. Konversikan berkas WAV ke PCM mentah terlebih dahulu.
Atur endpoint WebSocket untuk workspace di wilayah Singapura. Ganti WorkspaceId dengan ID workspace Anda. Untuk daftar wilayah dan endpoint yang didukung, lihat Akses WebSocket.
export DASHSCOPE_REALTIME_URL="wss://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime"

Memanggil SDK dalam proyek

Program ini mengalirkan rekaman raw PCM secara real time, menunggu hingga respons selesai, lalu menulis audio ke output.pcm. Ganti Program.cs dengan kode berikut.
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}");
Tempatkan file raw PCM dari panduan cepat di direktori proyek Anda dan jalankan contohnya.
dotnet run -- input.pcm qwen-audio-3.1-realtime-plus longanfengyue_v3.1

Parameter permintaan

OpsiTipeDefaultDeskripsi
ApiKeystring?nullModel Studio kunci API. Jika dilewatkan, SDK membaca DASHSCOPE_API_KEY.
Urlstringwss://dashscope.aliyuncs.com/api-ws/v1/realtimeEndpoint WebSocket. SDK menambahkan Model sebagai parameter query model.
WorkspaceIdstring?nullID Workspace yang dikirim dalam header X-DashScope-WorkSpace. Untuk menggunakan endpoint khusus workspace, atur alamat lengkap di Url.
ConnectTimeoutTimeSpan10 sWaktu tunggu pembukaan koneksi WebSocket.
StartTimeoutTimeSpan10 sWaktu tunggu penerimaan session.created.
StopTimeoutTimeSpan10 sWaktu tunggu penerimaan session.finished saat mode finish menunggu peristiwa tersebut.
FinishModeQwenRealtimeFinishMode?nullJika dilewatkan, SDK memilih mode finish berdasarkan model. Baca FinishMode pada instance untuk melihat mode mana yang digunakan.
Modelstringqwen-audio-3.1-realtime-plusID Model. Untuk Omni, atur ini secara eksplisit ke ID model Omni Realtime yang diinginkan.
ModalitiesIList<string>["text", "audio"]Modality output. Gunakan ["text"] untuk output hanya teks.
Voicestring?nullSuara untuk output audio. null membiarkan pilihan kepada server. Contoh Audio 3.1 mengatur longanfengyue_v3.1 secara eksplisit.
EnableSpeechEmotionbool?nullMengaktifkan ucapan emosional jika didukung. Lihat referensi acara klien untuk model.
Instructionsstring?nullInstruksi sistem.
MaxHistoryTurnsint?nullJumlah putaran percakapan yang disimpan, dari 1 hingga 50.
ToolsJsonstring?nullDefinisi alat fungsi sebagai string array JSON gaya OpenAI.
TurnDetectionModeQwenTurnDetectionModeServerVadMode deteksi putaran. ServerVad mendeteksi batas ucapan di server. Beberapa model mendukung SmartTurn. Dengan PushToTalk, klien mengirim audio dan meminta respons.
VadThresholddouble?nullAmbang VAD server dari -1,0 hingga 1,0. Berlaku untuk ServerVad.
VadSilenceMsint?nullDurasi keheningan akhir ucapan, dari 200 hingga 6.000 milidetik. Berlaku untuk ServerVad. Jika dilewatkan, model menggunakan nilai default server.
Set Url ke titik akhir khusus workspace Anda. Untuk titik akhir regional, lihat akses Audio Realtime WebSocket atau akses Omni Realtime WebSocket.

Referensi API

Audio Realtime dan Omni Realtime keduanya menggunakan DashScope.Qwen.QwenRealtimeConversation. Teruskan QwenRealtimeConversationOptions ke konstruktor. Nilai default mengarah ke model Audio Realtime. Untuk menggunakan Omni, set ID model Omni secara eksplisit.

Metode

Metode di bawah ini mengembalikan Task, kecuali DisposeAsync. ct adalah token pembatalan opsional.
MetodeDeskripsi
ConnectAsync(CancellationToken ct = default)Membuka koneksi, menunggu session.created, dan mengirim session.update.
AppendAudioAsync(ReadOnlyMemory<byte> pcm, CancellationToken ct = default)Mengirim frame audio. SDK Base64-encode byte dan mengirim acara input_audio_buffer.append.
CommitAudioAsync(CancellationToken ct = default)Mengirim audio yang dibuffer dengan input_audio_buffer.commit dalam mode PushToTalk.
CreateResponseAsync(JsonObject? responseOptions = null, CancellationToken ct = default)Meminta respons dengan response.create. responseOptions menyediakan penggantian opsional untuk respons saat ini.
SendItemAsync(JsonObject item, CancellationToken ct = default)Menambahkan item ke percakapan menggunakan conversation.item.create.
SendFunctionCallOutputAsync(string callId, string outputJson, CancellationToken ct = default)Mengembalikan hasil alat menggunakan callId dari acara dan string JSON output.
SendRawEventAsync(string frameJson, CancellationToken ct = default)Mengirim JSON acara klien lengkap seperti yang diberikan. Gunakan metode ini untuk acara tanpa metode SDK khusus.
FinishAsync(CancellationToken ct = default)Mengakhiri sesi menggunakan FinishMode aktif.
AbortAsync()Menutup koneksi segera dan mengabaikan hasil yang tertunda.
DisposeAsync()Melepaskan sumber daya secara asinkron dan mengembalikan ValueTask.
Dalam mode PushToTalk, panggil CommitAudioAsync lalu CreateResponseAsync setelah mengirim audio. Untuk menangani pemanggilan alat, jalankan alat setelah FunctionCallReceived dan kembalikan hasilnya. Panggil CreateResponseAsync lagi jika model harus melanjutkan respons.

Acara

AcaraArgumen acaraKapan acara tersebut dipicu
SessionReadystring?Sesi siap. Nilainya adalah session.id.
UserSpeechStartedQwenSpeechEventArgsVAD server mendeteksi awal ucapan pengguna.
UserSpeechStoppedQwenSpeechEventArgsVAD server mendeteksi akhir ucapan pengguna.
UserTranscriptUpdatedQwenTranscriptEventArgsTranskrip input saat ini, yang dapat berubah.
UserTranscriptCompletedQwenTranscriptEventArgsTranskrip akhir dari satu ucapan input.
AssistantTextDeltaQwenTextDeltaEventArgsDelta teks respons. Gabungkan delta secara berurutan.
AssistantTextCompletedQwenTranscriptEventArgsTeks respons lengkap.
AssistantAudioChunkQwenAudioChunkEventArgsPotongan audio respons dalam format raw mono 16-bit little-endian 24 kHz PCM.
AssistantAudioCompletedEventArgsSemua audio respons untuk giliran ini telah tiba.
FunctionCallReceivedQwenFunctionCallEventArgsModel meminta pemanggilan alat dan menyediakan ID panggilan, nama fungsi, serta argumen JSON.
ResponseCompletedQwenResponseSummaryresponse.done tiba dengan status dan penggunaan.
RawServerEventQwenServerEventArgsPeristiwa server mentah dengan jenisnya dan objek JSON.
ErrorOccurredDashScopeErrorEventArgsTerjadi kesalahan server atau kegagalan koneksi.

Jenis hasil

JenisPropertiDeskripsi
QwenResponseSummaryStatus: string?, FailureReason: string?, TotalTokens: int?, InputTokens: int?, OutputTokens: int?, AudioInputTokens: int?, AudioOutputTokens: int?Status respons, alasan kegagalan, dan penggunaan. Status bisa berupa completed, failed, atau incomplete. Penggunaan percakapan adalah per giliran. Penggunaan terjemahan bersifat kumulatif selama sesi.
QwenSpeechEventArgsAudioMs: long, ItemId: string?Batasan suara dalam milidetik dan ID item input.
QwenTranscriptEventArgsText: string, ItemId: string?Transkrip saat ini atau teks akhir dan ID item.
QwenTextDeltaEventArgsDelta: string, ItemId: string?Delta teks dan ID item.
QwenAudioChunkEventArgsPcm: byte[]Potongan audio.
QwenFunctionCallEventArgsCallId: string, Name: string?, ArgumentsJson: string?ID panggilan alat, nama, dan argumen. Gunakan CallId asli saat mengembalikan hasil.
QwenServerEventArgsType: string?, Root: JsonObjectJenis peristiwa dan JSON lengkap.
DashScopeErrorEventArgsCode: int, ServerErrorCode: string?, ServerErrorMessage: string?, TaskId: string?, InnerException: Exception?Kode kesalahan SDK, kode kesalahan server dan pesan, ID tugas atau sesi, serta pengecualian dasar.

Mengakhiri sesi

Gunakan koneksi yang sama untuk beberapa giliran percakapan. Panggil FinishAsync setelah event ResponseCompleted terakhir untuk menghindari pemotongan respons.
Mode selesaiPerilaku
FinishWithoutWaitMengirim session.finish dan menutup koneksi. Ini adalah default untuk Audio Realtime.
CloseOnlyMenutup koneksi. Ini adalah default untuk Omni Realtime.
FinishAndWaitMengirim session.finish dan menunggu session.finished. Server juga dapat mengakhiri sesi dengan menutup koneksi.