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.
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
- Buat proyek konsol .NET 10 dan instal SDK seperti dijelaskan di atas.
- Simpan
input.pcmdi direktori proyek. Gunakan PCM mentah 16 kHz, mono, 16-bit little-endian. Konversikan berkas WAV ke PCM mentah terlebih dahulu.
WorkspaceId dengan ID workspace Anda. Untuk daftar wilayah dan endpoint yang didukung, lihat Akses WebSocket.
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.
Parameter permintaan
| Opsi | Tipe | Default | Deskripsi |
|---|---|---|---|
ApiKey | string? | null | Model Studio kunci API. Jika dilewatkan, SDK membaca DASHSCOPE_API_KEY. |
Url | string | wss://dashscope.aliyuncs.com/api-ws/v1/realtime | Endpoint WebSocket. SDK menambahkan Model sebagai parameter query model. |
WorkspaceId | string? | null | ID Workspace yang dikirim dalam header X-DashScope-WorkSpace. Untuk menggunakan endpoint khusus workspace, atur alamat lengkap di Url. |
ConnectTimeout | TimeSpan | 10 s | Waktu tunggu pembukaan koneksi WebSocket. |
StartTimeout | TimeSpan | 10 s | Waktu tunggu penerimaan session.created. |
StopTimeout | TimeSpan | 10 s | Waktu tunggu penerimaan session.finished saat mode finish menunggu peristiwa tersebut. |
FinishMode | QwenRealtimeFinishMode? | null | Jika dilewatkan, SDK memilih mode finish berdasarkan model. Baca FinishMode pada instance untuk melihat mode mana yang digunakan. |
Model | string | qwen-audio-3.1-realtime-plus | ID Model. Untuk Omni, atur ini secara eksplisit ke ID model Omni Realtime yang diinginkan. |
Modalities | IList<string> | ["text", "audio"] | Modality output. Gunakan ["text"] untuk output hanya teks. |
Voice | string? | null | Suara untuk output audio. null membiarkan pilihan kepada server. Contoh Audio 3.1 mengatur longanfengyue_v3.1 secara eksplisit. |
EnableSpeechEmotion | bool? | null | Mengaktifkan ucapan emosional jika didukung. Lihat referensi acara klien untuk model. |
Instructions | string? | null | Instruksi sistem. |
MaxHistoryTurns | int? | null | Jumlah putaran percakapan yang disimpan, dari 1 hingga 50. |
ToolsJson | string? | null | Definisi alat fungsi sebagai string array JSON gaya OpenAI. |
TurnDetectionMode | QwenTurnDetectionMode | ServerVad | Mode deteksi putaran. ServerVad mendeteksi batas ucapan di server. Beberapa model mendukung SmartTurn. Dengan PushToTalk, klien mengirim audio dan meminta respons. |
VadThreshold | double? | null | Ambang VAD server dari -1,0 hingga 1,0. Berlaku untuk ServerVad. |
VadSilenceMs | int? | null | Durasi keheningan akhir ucapan, dari 200 hingga 6.000 milidetik. Berlaku untuk ServerVad. Jika dilewatkan, model menggunakan nilai default server. |
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.
| Metode | Deskripsi |
|---|---|
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. |
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
| Acara | Argumen acara | Kapan acara tersebut dipicu |
|---|---|---|
SessionReady | string? | Sesi siap. Nilainya adalah session.id. |
UserSpeechStarted | QwenSpeechEventArgs | VAD server mendeteksi awal ucapan pengguna. |
UserSpeechStopped | QwenSpeechEventArgs | VAD server mendeteksi akhir ucapan pengguna. |
UserTranscriptUpdated | QwenTranscriptEventArgs | Transkrip input saat ini, yang dapat berubah. |
UserTranscriptCompleted | QwenTranscriptEventArgs | Transkrip akhir dari satu ucapan input. |
AssistantTextDelta | QwenTextDeltaEventArgs | Delta teks respons. Gabungkan delta secara berurutan. |
AssistantTextCompleted | QwenTranscriptEventArgs | Teks respons lengkap. |
AssistantAudioChunk | QwenAudioChunkEventArgs | Potongan audio respons dalam format raw mono 16-bit little-endian 24 kHz PCM. |
AssistantAudioCompleted | EventArgs | Semua audio respons untuk giliran ini telah tiba. |
FunctionCallReceived | QwenFunctionCallEventArgs | Model meminta pemanggilan alat dan menyediakan ID panggilan, nama fungsi, serta argumen JSON. |
ResponseCompleted | QwenResponseSummary | response.done tiba dengan status dan penggunaan. |
RawServerEvent | QwenServerEventArgs | Peristiwa server mentah dengan jenisnya dan objek JSON. |
ErrorOccurred | DashScopeErrorEventArgs | Terjadi kesalahan server atau kegagalan koneksi. |
Jenis hasil
| Jenis | Properti | Deskripsi |
|---|---|---|
QwenResponseSummary | Status: 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. |
QwenSpeechEventArgs | AudioMs: long, ItemId: string? | Batasan suara dalam milidetik dan ID item input. |
QwenTranscriptEventArgs | Text: string, ItemId: string? | Transkrip saat ini atau teks akhir dan ID item. |
QwenTextDeltaEventArgs | Delta: string, ItemId: string? | Delta teks dan ID item. |
QwenAudioChunkEventArgs | Pcm: byte[] | Potongan audio. |
QwenFunctionCallEventArgs | CallId: string, Name: string?, ArgumentsJson: string? | ID panggilan alat, nama, dan argumen. Gunakan CallId asli saat mengembalikan hasil. |
QwenServerEventArgs | Type: string?, Root: JsonObject | Jenis peristiwa dan JSON lengkap. |
DashScopeErrorEventArgs | Code: 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 selesai | Perilaku |
|---|---|
FinishWithoutWait | Mengirim session.finish dan menutup koneksi. Ini adalah default untuk Audio Realtime. |
CloseOnly | Menutup koneksi. Ini adalah default untuk Omni Realtime. |
FinishAndWait | Mengirim session.finish dan menunggu session.finished. Server juga dapat mengakhiri sesi dengan menutup koneksi. |