Skip to main content

Akses WebSocket Qwen-Audio-Realtime

Akses WebSocket Qwen-Audio-Realtime

Panduan pengguna: Percakapan suara realtime (Qwen-Audio-Realtime). Untuk definisi peristiwa terperinci, lihat Peristiwa klien dan Peristiwa server. Model yang didukung: 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.
Alibaba Cloud Model Studio telah merilis domain khusus ruang kerja untuk wilayah China (Beijing) dan Singapore. Domain khusus baru ini memberikan performa lebih unggul dan stabilitas lebih tinggi untuk permintaan inferensi. Kami merekomendasikan migrasi ke domain baru:
  • Tiongkok (Beijing): dari dashscope.aliyuncs.com ke {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapura: dari dashscope-intl.aliyuncs.com ke {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
Ganti {WorkspaceId} dengan ID ruang kerja Anda. Domain yang ada tetap dapat digunakan.

Endpoint

Gunakan URL WebSocket berikut. Parameter kueri model menentukan model yang digunakan. Ganti <model_name> dengan nama model:
  • Tiongkok (Beijing)
  • Singapura
WebSocketwss://WorkspaceId.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>
Saat memanggil API, ganti {WorkspaceId} dengan ID ruang kerja Anda.

URL harus menggunakan wss://. Atur Authorization dalam header permintaan dan tentukan model melalui parameter kueri model.

Header permintaan

Sertakan informasi berikut dalam header permintaan:

Parameter

Tipe

Wajib

Deskripsi

Authorization

string

Ya

Token autentikasi dengan format Bearer <your_api_key>. Ganti <your_api_key> dengan API Key Anda.

user-agent

string

Tidak

Pengidentifikasi klien untuk melacak sumber permintaan.

X-DashScope-WorkSpace

string

Tidak

ID ruang kerja Alibaba Cloud Model Studio.

Authorization divalidasi selama handshake WebSocket. Jika API Key tidak valid atau tidak ada, handshake gagal dengan HTTP 401/403. Simpan API Key jangka panjang di server, bukan di browser atau aplikasi seluler. Untuk prosedur dan izin API Key sementara, lihat Membuat API Key sementara.
Referensi umum WebSocket juga mencantumkan header 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 mengirim response.create untuk 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 type ke server_vad.

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 type ke smart_turn atau smart_turn_v2 (direkomendasikan).

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

null

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
Diagram berikut menunjukkan urutan interaksi umum dalam mode server_vad:
111
Klien dan server berinteraksi dengan urutan berikut:
  1. Klien membuat koneksi WebSocket. Server mengembalikan session.created.
  2. Klien mengirim session.update untuk mengonfigurasi sesi. Server mengembalikan session.updated.
  3. Klien terus mengirim input_audio_buffer.append untuk menambahkan data audio.
  4. Saat mendeteksi awal ucapan, server mengembalikan input_audio_buffer.speech_started dan mengalirkan delta transkripsi ASR melalui conversation.item.input_audio_transcription.delta.
  5. Saat mendeteksi akhir ucapan, server mengembalikan input_audio_buffer.speech_stopped, input_audio_buffer.committed, dan conversation.item.created.
  6. Server otomatis membuat respons dan mengalirkan delta teks serta audio (response.audio_transcript.delta dan response.audio.delta), lalu mengembalikan response.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
Diagram berikut menunjukkan urutan interaksi umum dalam mode smart_turn / smart_turn_v2:
111
Perbedaan utama dari mode server_vad adalah:
  • 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_stopped mengembalikan reason=turn_invalid. Dalam hal ini, inferensi tidak dipicu.
  • Saat menunggu input pengguna berikutnya, klien dapat mengirim response.create secara 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:
  1. Klien membuat koneksi WebSocket. Server mengembalikan session.created.
  2. Klien mengirim session.update pertama dengan URL audio sidik suara dalam turn_detection.voiceprint_audio_urls.
  3. Server segera memulai pendaftaran sidik suara secara asinkron. Sebelum mengembalikan session.updated, server mengirim voiceprint_audio_list.in_progress dengan pengidentifikasi tugas pendaftaran unik item_id.
  4. Server mengembalikan session.updated untuk mengonfirmasi bahwa konfigurasi sesi telah berlaku.
  5. Setelah pendaftaran sidik suara selesai, server mengirim peristiwa terminal. Nilai item_id sama dengan nilai pada langkah 3:
    • Pendaftaran berhasil: voiceprint_audio_list.completed.
    • Pendaftaran gagal: voiceprint_audio_list.failed, dengan bidang reason yang menjelaskan penyebabnya, misalnya URL audio yang tidak dapat diunduh.
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
Diagram berikut menunjukkan urutan interaksi umum dalam mode push-to-talk:
111
Klien dan server berinteraksi dengan urutan berikut:
  1. Klien terus mengirim input_audio_buffer.append untuk menambahkan data audio.
  2. Setelah pengguna selesai berbicara, klien mengirim input_audio_buffer.commit untuk meng-commit buffer.
  3. Klien mengirim response.create untuk memicu inferensi secara manual.
  4. 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 input_audio_buffer.commit. Jangan memicu respons lain saat respons sedang dibuat.

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 input_audio_buffer.speech_started hingga response.done.

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 (invalid_request_error)

Koneksi tetap terbuka; error dilaporkan

Parameter tidak valid, operasi yang tidak diizinkan pada status saat ini, atau item_id duplikat

Error server (server_error)

Koneksi dihentikan

Kegagalan koneksi LLM atau penyimpanan

SDK dan referensi

SDK yang tersedia