Akses WebSocket Qwen-Omni-Realtime
Cakupan penggunaan
Dokumen ini ditujukan untuk Qwen-Omni-Realtime dengan model contoh qwen3.8-omni-flash-realtime. Konfigurasi qwen3.5-omni-plus-realtime dan qwen3.5-omni-flash-realtime tersedia dalam referensi peristiwa. Parameter model lama qwen3-omni-flash-realtime-2025-09-15 dijelaskan dalam SDK Python.
- Gunakan API Key dan ID ruang kerja yang sesuai dengan wilayah dan ruang kerja yang dipilih.
- domain Singapura:
{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com. - Simpan API Key jangka panjang di server dan jangan letakkan dalam browser atau aplikasi seluler.
Alamat dan autentikasi
WebSocket
wss://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=qwen3.8-omni-flash-realtimeqwen3.8-omni-flash-realtime harus menggunakan domain khusus ruang kerja. Model lama dapat tetap menggunakan domain awal: wss://dashscope.aliyuncs.com untuk Beijing dan wss://dashscope-intl.aliyuncs.com untuk Singapura. Untuk detailnya, lihat SDK Python.
Atur Authorization: Bearer <API_KEY> dalam header permintaan handshake WebSocket. Ganti ID ruang kerja dan nama model yang sebenarnya. Jangan letakkan API Key jangka panjang di browser atau aplikasi seluler.
Header permintaan opsional user-agent digunakan untuk mengidentifikasi klien. Dokumentasi integrasi WebSocket umum juga mencantumkan X-DashScope-WorkSpace (ID ruang kerja) dan X-DashScope-DataInspection (konfigurasi pemeriksaan kepatuhan data), yang digunakan sesuai persyaratan model.
Untuk cara membuat API Key sementara dan izinnya, lihat Membuat API Key sementara.
Konfigurasi sesi
Kirim session.update setelah membuat koneksi dan menerima session.created. Kirim input hanya setelah menerima konfirmasi session.updated. Tangani error melalui peristiwa error.
Contoh berikut sesuai dengan qwen3.8-omni-flash-realtime. Versi lain harus menggunakan konfigurasi dari referensi peristiwanya masing-masing tanpa mencampur tingkat bidang.
Input, hasil, dan penghentian
Audio dikirim melalui input_audio_buffer.append. Format input, kondisi pengiriman, dan batas input gambar dijelaskan dalam Peristiwa klien. Proses hasil, status, dan error dalam Peristiwa server. Jangan menganggap pembuatan koneksi sebagai selesainya permintaan bisnis.
Lihat alur interaksi untuk giliran otomatis, mode Manual, dan Function Calling. Untuk MCP, lihat pemanggilan tool MCP dalam bahasa Inggris. Tutup koneksi WebSocket setelah menerima hasil yang diperlukan.
Alur interaksi
Mode VAD
Untuk mengaktifkan mode VAD, atur parameter session.turn_detection dari client event ke "server_vad". Dalam mode ini, server melakukan Voice Activity Detection (VAD) pada audio masuk dan memberikan respons saat mendeteksi adanya suara. Mode ini merupakan mode default dan dirancang untuk skenario di mana klien terus-menerus mengirim audio ke server.
- Server mengirim event
input_audio_buffer.speech_startedsaat mendeteksi awal percakapan. - Klien dapat menambahkan audio ke buffer kapan saja dengan mengirim event
input_audio_buffer.append. - Server mengirim event
input_audio_buffer.speech_stoppedsaat mendeteksi akhir percakapan. - Server melakukan commit terhadap input audio buffer dengan mengirim event
input_audio_buffer.committed. - Server mengirim event
conversation.item.created, yang berisi item message pengguna yang dibuat dari buffer audio.
Alur pemanggilan tool
Dalam mode VAD, ketika respons yang dihasilkan server memerlukan pemanggilan tool, alur interaksi berikut terjadi:
- Setelah mendeteksi akhir percakapan dan menghasilkan respons, server menentukan bahwa pemanggilan tool diperlukan.
- Server mengirim event
response.function_call_arguments.delta, yang berisi data inkremental untuk argumen pemanggilan tool. - Server mengirim event
response.function_call_arguments.doneuntuk menandakan bahwa seluruh argumen pemanggilan tool telah dikirim. - Klien mengeksekusi pemanggilan tool dan memperoleh hasilnya.
- Klien mengirim event
conversation.item.createyang berisi hasil pemanggilan tool. - Server secara otomatis menghasilkan respons berdasarkan hasil pemanggilan tool tersebut.
Mode Manual
Untuk mengaktifkan Mode Manual, atur parameter session.turn_detection dari client event ke null. Dalam mode ini, klien meminta respons dari server dengan secara eksplisit mengirim event input_audio_buffer.commit dan response.create. Mode ini cocok untuk skenario push-to-talk, seperti mengirim pesan suara dalam aplikasi chat.
- Klien dapat menambahkan audio ke buffer dengan mengirim event
input_audio_buffer.append. - Klien melakukan commit terhadap input audio buffer dengan mengirim event
input_audio_buffer.commit. Commit ini membuat item message pengguna baru dalam percakapan. - Server merespons dengan mengirim event
input_audio_buffer.committed. - Klien mengirim
response.createevent untuk memicu model menghasilkan respons akhir. - Server merespons dengan mengirim event
conversation.item.created.
Alur pemanggilan tool
- Setelah klien mengirim event
response.create, server menghasilkan respons dan mendeteksi bahwa pemanggilan tool diperlukan. - Server mengirim event
response.function_call_arguments.delta, yang berisi data inkremental untuk argumen pemanggilan tool. - Server mengirim event
response.function_call_arguments.doneuntuk menandakan bahwa transfer argumen pemanggilan tool telah selesai. - Klien mengeksekusi pemanggilan tool dan memperoleh hasilnya.
- Klien mengirim hasil pemanggilan tool menggunakan event
conversation.item.create. - Klien mengirim event
response.createuntuk memicu model menghasilkan respons akhir. - Server menghasilkan respons berdasarkan hasil pemanggilan tool dan mengirimkannya ke klien menggunakan event
response.audio.deltaatauresponse.text.delta.
Penanganan kesalahan
Jika handshake gagal, periksa domain, region, ruang kerja, API Key, nama model, status aktivasi model, dan izin. Setelah koneksi dibuat, identifikasi masalah berdasarkan peristiwa error dan lihat Kode error. Simpan ID peristiwa untuk pemecahan masalah. Jangan menganggap protokol tidak didukung hanya karena tidak ada respons.