Akses WebSocket Qwen-Audio-Realtime
qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus, dan qwen-audio-3.0-realtime-flash.
Endpoint
Gunakan URL WebSocket berikut. Parameter kueri model menentukan model yang digunakan. Ganti <model_name> dengan nama model:
- Tiongkok (Beijing)
- Singapura
wss://WorkspaceId.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>{WorkspaceId} dengan ID ruang kerja Anda.Header permintaan
Sertakan informasi berikut dalam header permintaan:
Parameter | Tipe | Wajib | Deskripsi |
|---|---|---|---|
Authorization | string | Ya | Token autentikasi dengan format |
user-agent | string | Tidak | Pengidentifikasi klien untuk melacak sumber permintaan. |
X-DashScope-WorkSpace | string | Tidak | ID ruang kerja Alibaba Cloud Model Studio. |
X-DashScope-DataInspection untuk pemeriksaan data. Gunakan sesuai persyaratan model. Contoh untuk qwen-audio-3.1-realtime-plus menggunakan x-dashscope-dataInspection: disable.
Konsep inti
- Sesi: Satu koneksi WebSocket sesuai dengan satu sesi yang menyimpan konfigurasi dan konteks percakapan.
- Item percakapan: Setiap pesan dalam percakapan, disusun sebagai linked list.
- Respons: Output dari satu inferensi model. Respons mencakup satu atau beberapa item output berupa pesan asisten atau panggilan fungsi.
- Panggilan fungsi: Permintaan model agar klien menjalankan fungsi alat. Setelah menjalankannya, klien mengirim hasil sebagai
function_call_output, lalu mengirimresponse.createuntuk memicu inferensi berikutnya. - Deteksi giliran: Mengontrol kapan inferensi dipicu.
Mode interaksi
API Qwen-Audio Realtime mendukung tiga mode interaksi yang dikonfigurasi melalui session.turn_detection dalam peristiwa session.update. Untuk deteksi otomatis, atur type di dalam objek. Untuk push-to-talk, atur seluruh bidang turn_detection ke null:
Mode | Nilai session.turn_detection | Deskripsi | Kasus penggunaan |
|---|---|---|---|
server_vad | Objek. Atur | Server menggunakan VAD untuk mendeteksi awal dan akhir ucapan serta memicu inferensi secara otomatis. | Percakapan hands-free dan asisten suara |
Deteksi giliran semantik cerdas | Objek. Atur | Menggabungkan persepsi akustik dan pemahaman semantik untuk mendeteksi batas giliran, bukan hanya mengandalkan sinyal suara. Bunyi tanpa makna semantik, seperti “uh” dan “ah”, tidak memicu giliran atau menginterupsi pemutaran model. | Percakapan alami berlatensi rendah dan penanganan interupsi yang akurat |
push-to-talk |
| Klien mengomit audio dan memicu inferensi secara manual. | Push-to-talk dan kontrol presisi |
Alur interaksi
Untuk definisi peristiwa terperinci, lihat Peristiwa klien dan Peristiwa server.
Mode server_vad
Server melakukan deteksi aktivitas suara pada audio masuk dan otomatis memicu inferensi saat mendeteksi akhir ucapan.
Mengaktifkan mode ini: Atur turn_detection.type ke server_vad dalam peristiwa session.update.
- Satu giliran percakapan lengkap
- Interupsi pengguna
- Klien membuat koneksi WebSocket. Server mengembalikan
session.created. - Klien mengirim
session.updateuntuk mengonfigurasi sesi. Server mengembalikansession.updated. - Klien terus mengirim
input_audio_buffer.appenduntuk menambahkan data audio. - Saat mendeteksi awal ucapan, server mengembalikan
input_audio_buffer.speech_starteddan mengalirkan delta transkripsi ASR melaluiconversation.item.input_audio_transcription.delta. - Saat mendeteksi akhir ucapan, server mengembalikan
input_audio_buffer.speech_stopped,input_audio_buffer.committed, danconversation.item.created. - Server otomatis membuat respons dan mengalirkan delta teks serta audio (
response.audio_transcript.deltadanresponse.audio.delta), lalu mengembalikanresponse.done.
Mode smart_turn / smart_turn_v2
Mode ini menggabungkan persepsi akustik dan pemahaman semantik untuk mendeteksi akhir ucapan. Mode ini dapat menyaring bunyi tanpa makna, seperti gumaman persetujuan dan audio latar. Bunyi tanpa makna semantik diteruskan melalui peristiwa conversation.item.ambient_audio_transcription.delta dan tidak memicu giliran percakapan.
Mengaktifkan mode ini: Atur turn_detection.type ke smart_turn atau smart_turn_v2 dalam peristiwa session.update.
smart_turn_v2 (direkomendasikan): Mengembangkan smart_turn dengan pemahaman konteks percakapan yang lebih kuat untuk mengenali maksud interaksi dalam skenario multipihak. Mode ini mengurangi respons dan interupsi yang tidak diinginkan akibat pembicara lain atau ucapan yang tidak terkait.
- Satu giliran percakapan lengkap
- Interupsi pengguna
- Giliran tidak valid
- Bunyi tanpa makna semantik, seperti “uh” dan “ah”, tidak memicu inferensi. Bunyi tersebut dikembalikan melalui peristiwa
ambient_audio_transcription. - Ucapan yang sebelumnya dianggap valid dapat dinyatakan tidak valid:
input_audio_buffer.speech_stoppedmengembalikanreason=turn_invalid. Dalam hal ini, inferensi tidak dipicu. - Saat menunggu input pengguna berikutnya, klien dapat mengirim
response.createsecara eksplisit untuk memicu inferensi.
Alur konfigurasi peningkatan speaker
Dalam mode smart_turn / smart_turn_v2, jika session.update pertama mencakup voiceprint_audio_urls, server mendaftarkan sidik suara secara asinkron dengan memuat fitur audio pembicara tujuan. Peristiwa melaporkan progres pendaftaran. Kegagalan pendaftaran tidak menghalangi percakapan normal.
Pendaftaran sidik suara berlangsung dengan urutan berikut:
-
Klien membuat koneksi WebSocket. Server mengembalikan
session.created. -
Klien mengirim
session.updatepertama dengan URL audio sidik suara dalamturn_detection.voiceprint_audio_urls. -
Server segera memulai pendaftaran sidik suara secara asinkron. Sebelum mengembalikan
session.updated, server mengirimvoiceprint_audio_list.in_progressdengan pengidentifikasi tugas pendaftaran unikitem_id. -
Server mengembalikan
session.updateduntuk mengonfirmasi bahwa konfigurasi sesi telah berlaku. -
Setelah pendaftaran sidik suara selesai, server mengirim peristiwa terminal. Nilai
item_idsama dengan nilai pada langkah 3:- Pendaftaran berhasil:
voiceprint_audio_list.completed. - Pendaftaran gagal:
voiceprint_audio_list.failed, dengan bidangreasonyang menjelaskan penyebabnya, misalnya URL audio yang tidak dapat diunduh.
- Pendaftaran berhasil:
voiceprint_audio_urls hanya berlaku dalam session.update pertama. Bidang ini diabaikan pada pembaruan berikutnya.Mode push-to-talk
Klien mengontrol secara manual kapan audio dikomit dan inferensi dipicu. Mode ini cocok untuk interaksi push-to-talk.
Mengaktifkan mode ini: Atur turn_detection ke null dalam peristiwa session.update.
- Satu giliran percakapan lengkap
- Interupsi pengguna
- Klien terus mengirim
input_audio_buffer.appenduntuk menambahkan data audio. - Setelah pengguna selesai berbicara, klien mengirim
input_audio_buffer.commituntuk meng-commit buffer. - Klien mengirim
response.createuntuk memicu inferensi secara manual. - Server membuat respons dan mengalirkan teks serta audio.
Batasan operasi menurut mode
Operasi | push-to-talk | server_vad | smart_turn / smart_turn_v2 |
|---|---|---|---|
session.update | Semua bidang dapat diubah saat IDLE; beberapa dibatasi pada status lain | Semua bidang dapat diubah saat IDLE; beberapa dibatasi pada status lain | Semua bidang dapat diubah saat IDLE; beberapa dibatasi pada status lain |
input_audio_buffer.append | Diizinkan | Diizinkan | Diizinkan |
input_audio_buffer.commit | Diizinkan | Diabaikan | Diabaikan |
input_audio_buffer.clear | Diizinkan | Diabaikan | Diabaikan |
response.create | Diizinkan setelah mengomit audio buffer dengan | Diizinkan saat tidak ada respons yang sedang dibuat. Jangan memicu respons lain selama pembuatan berlangsung. | Diizinkan saat menunggu input pengguna berikutnya. Jangan memicu respons lain dalam giliran aktif, dari |
response.cancel | Diizinkan selama inferensi | Diizinkan selama inferensi | Diizinkan selama inferensi |
conversation.item.create/delete/retrieve | Diizinkan | Diizinkan | Diizinkan |
turn_detection dan input_audio_format hanya dapat diubah sebelum audio pertama dikirim, saat sesi berstatus IDLE.Penanganan error
Jika handshake gagal, periksa domain, region, ruang kerja, API Key, nama model, status aktivasi model, dan izin. Untuk deskripsi error lengkap, lihat Kode error.
Tipe | Perilaku | Contoh |
|---|---|---|
Error klien ( | Koneksi tetap terbuka; error dilaporkan | Parameter tidak valid, operasi yang tidak diizinkan pada status saat ini, atau item_id duplikat |
Error server ( | Koneksi dihentikan | Kegagalan koneksi LLM atau penyimpanan |