Qwen-Audio adalah model interaksi suara real-time end-to-end untuk percakapan suara berlatensi rendah. Kasus penggunaannya mencakup asisten suara, layanan pelanggan cerdas, dan teman AI.
Ikhtisar
Qwen-Audio mengonversi audio real-time menjadi ucapan dan teks melalui koneksi full-duplex dengan input dan output streaming.
Selain WebSocket, model ini juga mendukung protokol AOQ dan WebRTC. Untuk integrasi sisi klien yang memprioritaskan latensi stabil, ketahanan pada jaringan lemah, serta penekanan noise full-duplex dan pembatalan gema bawaan, disarankan menggunakan AOQ. Untuk perbandingan protokol, lihat Ikhtisar API Realtime.
- Tiga mode interaksi: VAD akustik (server_vad), deteksi giliran semantik cerdas (smart_turn), dan kontrol manual (push-to-talk)
- Pada mode smart_turn, model menggabungkan persepsi akustik dan pemahaman semantik untuk menentukan batas giliran, sehingga suara pengisi seperti "uh" atau "hmm" tidak mengganggu percakapan
- Dukungan Function Calling memungkinkan model memutuskan kapan harus memanggil tool eksternal untuk informasi tambahan
- Manajemen konteks percakapan: buat, ambil, dan hapus item percakapan untuk menyuntikkan konteks historis atau menghapus item yang tidak relevan
- Output suara ekspresif yang secara dinamis menyesuaikan nada, kecepatan, dan emosi berdasarkan konteks percakapan
- Dukungan untuk suara sistem dan suara kloning; gunakan Voice Cloning untuk membuat suara AI kustom untuk output ucapan
- Peningkatan speaker pada mode smart_turn: kirimkan audio rekaman sebelumnya dari pengguna target agar model dapat mengunci speaker tersebut selama percakapan duplex, secara efektif memblokir suara lain dan kebisingan latar belakang
Cara kerja
Qwen-Audio menggunakan koneksi full-duplex dengan arsitektur berbasis event. Klien dan server bertukar data secara simultan melalui koneksi persisten: klien terus-menerus mengalirkan audio mikrofon, sementara server mengembalikan respons ucapan dan teks secara real-time. Seluruh interaksi berbasis event: klien mengirim event seperti session.update dan input_audio_buffer.append, dan server merespons dengan event seperti response.audio.delta dan response.done. Tidak diperlukan polling.
Siklus hidup koneksi tipikal adalah: membuat koneksi WebSocket, mengirim session.update untuk mengonfigurasi parameter sesi, mengalirkan audio dan menerima respons, lalu menutup koneksi.
Format audio
Petunjuk | Format | Spesifikasi |
|---|---|---|
Input (klien ke server) | PCM | Laju sampel 16 kHz, kedalaman 16-bit, mono |
Output (server ke klien) | PCM | Laju sampel 24 kHz, kedalaman 16-bit, mono |
qwen-audio-3.1-realtime-plus, Anda dapat menggunakan session.input_audio_transcription.language untuk menentukan bahasa sumber audio input dan session.output_audio.language untuk menentukan bahasa target audio output. Untuk kode bahasa yang valid bagi masing-masing parameter, lihat Event klien. Dari kedua parameter tersebut, session.output_audio.language berlaku untuk text-to-speech (TTS): model berusaha semaksimal mungkin menghasilkan audio dalam bahasa target, tetapi tidak dijamin selalu berhasil, dan bahasa teks balasan model tidak berubah.
Kapasitas konteks
Model mempertahankan riwayat percakapan. Ketika jumlah giliran atau durasi audio kumulatif melebihi batas berikut, riwayat sebelumnya akan dibuang secara otomatis. Durasi maksimum adalah batas atas durasi audio kumulatif yang dapat dipertahankan oleh konteks model.
Model | Giliran audio maks | Durasi audio maks |
|---|---|---|
qwen-audio-3.0-realtime-plus | 50 | 300 detik |
qwen-audio-3.0-realtime-flash | 50 | 300 detik |
Prasyarat
- Dapatkan Kunci API dan konfigurasikan sebagai Variabel lingkungan.
- Untuk menggunakan protokol AOQ, unduh dan integrasikan SDK klien AOQ. Untuk detailnya, lihat Ikhtisar SDK.
Mulai cepat
Ikuti langkah-langkah berikut untuk memulai percakapan suara real-time dengan model Qwen-Audio.
- WebSocket native
server_vad. Sebelum menjalankan, instal dependensi yang diperlukan:realtime_quickstart.py:python realtime_quickstart.py dan bicaralah ke mikrofon Anda untuk memulai percakapan real-time. Server secara otomatis mendeteksi aktivitas ucapan dan memicu respons.Contoh lengkapContoh berikut memperluas percakapan dasar dengan penanganan interupsi suara dan pembatalan gema. Buat dua file berikut dalam direktori yang sama:B64PCMPlayer.py
B64PCMPlayer.py
realtime_demo.py
realtime_demo.py
websockets versi lebih awal dari 11, ubah additional_headers menjadi extra_headers dalam kode, atau lakukan peningkatan: pip install --upgrade websockets.python realtime_demo.py dan bicaralah ke mikrofon Anda untuk memulai percakapan real-time. Sistem secara otomatis mendeteksi aktivitas ucapan dan memicu respons.Konfigurasi sesi
Mode interaksi
Qwen-Audio mendukung tiga mode interaksi: server_vad (VAD akustik untuk deteksi ucapan otomatis), smart_turn (deteksi giliran semantik cerdas yang menggabungkan analisis akustik dan semantik), dan push-to-talk (kontrol manual oleh klien). Untuk penjelasan lebih rinci serta diagram alur interaksi event, lihat Mode interaksi.
turn_detection hanya dapat diatur sebelum audio pertama dikirim (status IDLE). Untuk mengganti mode interaksi di tengah sesi, tutup dan buat kembali koneksi.turn_detection dalam event session.update:
- server_vad:
- smart_turn:
- push-to-talk:
manual_funchat.py
manual_funchat.py
Instruksi sistem
Gunakan parameter instructions untuk menentukan peran model, gaya respons, dan preferensi perilaku. Konfigurasikan parameter ini dalam session.update untuk menerapkannya ke seluruh sesi.
- Tentukan identitas peran yang jelas (misalnya, "You are an intelligent voice assistant" atau "You are an English conversation tutor"), dan opsional sertakan detail seperti nama atau jenis kelamin.
- Tentukan nada percakapan dan gaya frasa, sambil menekankan bahwa nada alami tidak mengorbankan kelengkapan konten — detail, angka, dan rekomendasi spesifik tetap harus disertakan, hanya diekspresikan dengan cara yang santai dan alami.
- Instruksikan model untuk mempertimbangkan semua batasan konteks dalam percakapan (seperti anggaran, preferensi, batasan, atau perjanjian sebelumnya). Saat berlaku beberapa kondisi, tangani masing-masing dan jangan menghilangkan informasi penting.
- Kontrol format output: kecuali jika pengguna meminta sebaliknya, hindari emoji dan karakter khusus lainnya serta format Markdown. Outputkan teks biasa untuk memastikan pemutaran TTS yang alami.
- Tentukan strategi respons: pertahankan salam sederhana dan pertukaran kasual tetap singkat dan alami; untuk penalaran, masalah multi-kondisi, daftar rekomendasi, atau saran keselamatan, utamakan kelengkapan — pastikan informasi kunci (seperti harga, lokasi, dan kondisi) sepenuhnya ada, tanpa pembukaan, pengulangan, atau pengisi yang tidak perlu.
- Tentukan strategi tindak lanjut: ikuti prinsip "jawab pertanyaan pengguna saat ini terlebih dahulu, lalu ajukan pertanyaan tindak lanjut secara alami di akhir untuk memajukan percakapan." Ajukan hanya satu pertanyaan dalam satu waktu; jangan ajukan beberapa pertanyaan berturut-turut atau konfirmasi berulang kali.
instructions yang direkomendasikan untuk skenario percakapan suara umum. Ini mencakup definisi peran, gaya percakapan, kontrol format, dan strategi tindak lanjut. Gunakan langsung atau sesuaikan dengan kebutuhan Anda:
instructions berikut mencakup berbagai gaya persona. Pilih salah satu yang sesuai dengan kasus penggunaan Anda atau sesuaikan lebih lanjut:
- Daisy (Teman Manis & Keren):
- Len (Keren & Bertutur Tajam):
- Mochen (Tenang & Karismatik):
- Hannibal (Elegan & Tajam):
- Heizi (Teman dari Timur Laut):
Konfigurasi suara
Gunakan parameter voice untuk mengatur suara TTS untuk respons model. Default-nya adalah longanqian. Dua jenis suara didukung.
Suara sistem: tentukan nama suara secara langsung. Nilai yang tersedia: longanqian, longanlingxin, longanlingxi, longanxiaoxin, longanlufeng.
target_model ke qwen-audio-3.0-realtime-plus atau qwen-audio-3.0-realtime-flash), lalu masukkan voice_id yang dikembalikan sebagai nilai voice.
Modalitas output
Gunakan parameter modalities untuk mengontrol jenis output model:
["audio", "text"](default): menghasilkan ucapan dan teks.["text"]: hanya menghasilkan teks, tanpa ucapan. Cocok untuk debugging, logging, atau skenario yang hanya membutuhkan respons teks.
response.modalities dalam response.create untuk mengganti pengaturan modalitas untuk satu respons saja.
Konfigurasi VAD
Pada mode server_vad, konfigurasikan parameter berikut dalam objek session.turn_detection untuk menyesuaikan perilaku VAD (parameter ini tidak berlaku pada mode smart_turn):
Parameter | Tipe | Deskripsi |
|---|---|---|
| float | Sensitivitas VAD. Nilai yang lebih rendah meningkatkan sensitivitas VAD, membuatnya lebih mudah mendeteksi suara pelan (termasuk kebisingan latar belakang) sebagai ucapan. Nilai yang lebih tinggi mengurangi sensitivitas, membutuhkan ucapan yang lebih jelas dan keras untuk memicu deteksi. Rentang: [-1.0, 1.0]. Default: 0.5. |
| integer | Durasi diam minimum (dalam milidetik) setelah ucapan berakhir sebelum memicu respons model. Nilai yang lebih rendah menghasilkan respons lebih cepat tetapi dapat menyebabkan pemicuan palsu selama jeda singkat. Rentang: [200, 6000]. Default: 800. Rentang yang direkomendasikan untuk percakapan: 400-800. |
Kontrol giliran riwayat
Gunakan parameter max_history_turns untuk mengontrol berapa banyak giliran QA historis yang direferensikan model selama inferensi. Nilai yang lebih tinggi memungkinkan model meninjau lebih banyak riwayat percakapan untuk pemahaman konteks yang lebih baik, tetapi meningkatkan konsumsi token dan latensi inferensi.
max_history_turns: 1–50. Default: 20.
Tips penyetelan:
- Percakapan pendek (seperti tanya jawab cepat): atur nilai lebih rendah (misalnya, 5–10) untuk mengurangi latensi.
- Percakapan panjang (seperti layanan pelanggan multi-giliran): atur nilai lebih tinggi (misalnya, 30–50) untuk membantu model memahami konteks penuh.
Fitur lanjutan
Function Calling
Qwen-Audio mendukung Function Calling, yang memungkinkan model memutuskan kapan harus memanggil tool eksternal berdasarkan konteks percakapan.
1. Daftarkan perangkat
Konfigurasikan tools melalui session.update:
response.function_call_arguments.done, jalankan tool di klien dan kirimkan hasilnya kembali melalui conversation.item.create:
response.create untuk membuat model menghasilkan respons berdasarkan hasil tool:
function_call, dan dapat mencakup pesan reguler maupun panggilan fungsi. Konten panggilan fungsi tidak dikirim ke TTS untuk pemutaran.realtime_demo.py dari mulai cepat. Pastikan B64PCMPlayer.py berada dalam direktori yang sama sebelum menjalankan.
realtime_fc_demo.py
realtime_fc_demo.py
python realtime_fc_demo.py dan bicaralah ke mikrofon Anda untuk mencoba percakapan real-time dengan Function Calling. Misalnya, tanyakan "Apa cuaca di Hangzhou?" atau "Berapa harga tiket kereta dari Beijing ke Shanghai?" dan model secara otomatis memanggil tool yang sesuai dan merespons dengan hasilnya.
Manajemen konteks percakapan
Qwen-Audio memungkinkan Anda mengelola item percakapan dalam konteks melalui event klien. Gunakan ini untuk menyuntikkan konteks historis, menambahkan informasi teks, atau menghapus item percakapan yang tidak relevan.
-
Buat item percakapan (
conversation.item.create): menyisipkan item percakapan ke dalam konteks. Tiga nilaiitem.typeberikut didukung:message: pesan percakapan reguler. Tentukanrole(system,user, atauassistant) dan arraycontent. Gunakan ini untuk menyuntikkan riwayat percakapan atau instruksi sistem.function_call: permintaan panggilan fungsi. Tentukancall_id,name, danarguments(string JSON). Biasanya dihasilkan oleh server, tetapi klien juga dapat menggunakannya untuk menyuntikkan catatan panggilan fungsi historis.function_call_output: hasil eksekusi tool. Tentukancall_iddanoutput(string JSON). Setelah menerimafunction_call, jalankan tool di klien dan kembalikan hasilnya dengan tipe ini.
previous_item_idmenentukan item percakapan yang sudah ada setelahnya item baru akan disisipkan. Ini memungkinkan Anda menyisipkan konten di posisi mana pun dalam riwayat percakapan. Jika dihilangkan, item baru ditambahkan di akhir.- Sisipkan pesan pengguna di posisi tertentu:
- Kembalikan hasil Function Calling:
item.id yang ditentukan dalam conversation.item.create sudah ada dalam percakapan, kesalahan akan dikembalikan.- Ambil item percakapan (
conversation.item.retrieve): menanyakan item percakapan yang disimpan di server. Untuk konten bertipe audio, hanya teks transkripsi yang dikembalikan, bukan data audio mentahnya.
- Hapus item percakapan (
conversation.item.delete): menghapus item tertentu dari konteks percakapan.
Transkripsi audio ambient
Hanya mode smart_turn. Saat VAD mendeteksi aktivitas ucapan tetapi analisis semantik menentukan itu bukan giliran yang valid (seperti kebisingan atau suara pengisi seperti "uh" atau "hmm"), server tidak memicu giliran percakapan. Sebagai gantinya, server mengirim hasil ASR ke klien sebagai event ambient_audio_transcription. Transkripsi ini tidak ditulis ke konteks percakapan.
delta dan completed. Gunakan event ini untuk mengimplementasikan pemantauan audio ambient atau kesadaran adegan percakapan.
Peningkatan speaker
Hanya mode smart_turn. Kirimkan URL audio rekaman sebelumnya dari pengguna target dalam session.update. Model akan mengunci speaker tersebut selama percakapan duplex, secara efektif mengabaikan suara lain dan kebisingan latar belakang, memungkinkan interaksi duplex yang lancar di lingkungan terbuka.
Konfigurasi: kirimkan URL audio voiceprint yang dapat diakses publik dalam turn_detection.voiceprint_audio_urls dalam session.update pertama.
- Maksimal 5 URL. Audio harus dalam format PCM atau WAV 16 kHz.
- Parameter ini hanya berlaku dalam
session.updatepertama. Field ini diabaikan dalam panggilan berikutnya.
voiceprint_audio_list.in_progress: pendaftaran telah dimulai. Dikirim sebelumsession.updated, membawaitem_id.voiceprint_audio_list.completed: pendaftaran berhasil.item_idcocok dengan yang ada diin_progress.voiceprint_audio_list.failed: pendaftaran gagal, dengan fieldreasonyang menjelaskan kesalahan (misalnya, URL audio tidak dapat diakses). Kegagalan pendaftaran tidak menghentikan percakapan yang sedang berlangsung.
Peluncuran
Siapkan toleransi kesalahan
- Koneksi ulang klien: Terapkan koneksi ulang otomatis untuk menangani fluktuasi jaringan. Atur sinyal koneksi ulang di callback
on_errordan gunakan exponential backoff (misalnya, tunggu 1 s, 2 s, 4 s) untuk percobaan ulang. - Klasifikasi kesalahan: kesalahan klien (
invalid_request_error) tidak memutus sesi; catat atau sesuaikan parameter. Kesalahan server (server_error) mengakhiri koneksi dan memerlukan rekoneksi. - Penanganan interupsi: dalam mode server_vad / smart_turn, ucapan pengguna baru secara otomatis menginterupsi respons model yang sedang berlangsung (
response.donemengembalikanstatus=cancelled). Saat menerimainput_audio_buffer.speech_started, segera bersihkan buffer pemutaran lokal untuk menghindari tumpang tindih audio.
Siklus hidup koneksi
Sesi WebSocket tipikal mengikuti siklus hidup ini:
- Koneksi: klien memulai koneksi WebSocket dan server mengembalikan event
session.created. - Konfigurasi: klien mengirim
session.updateuntuk mengatur mode interaksi, suara, tool, dan parameter lainnya. Selesaikan langkah ini sebelum mengirim audio apa pun. - Berinteraksi: klien terus-menerus mengalirkan audio (
input_audio_buffer.append). Server melakukan inferensi berdasarkan deteksi VAD atau pemicu manual dan mengembalikan ucapan dan teks secara streaming. - Tutup: klien menutup koneksi WebSocket. Server juga dapat memutus jika koneksi tidak aktif terlalu lama.
Optimasi latensi
- Ukuran chunk audio: kirim sekitar 100 md data audio per chunk (16 kHz x 16 bit x mono = 3.200 byte per chunk). Ini menyeimbangkan kinerja real-time dengan efisiensi jaringan.
- Pemutaran streaming: mulai memutar audio segera setelah
response.audio.deltatiba. Jangan tungguresponse.doneuntuk memutar respons penuh. - Bersihkan buffer pada interupsi: saat menerima
input_audio_buffer.speech_started, segera bersihkan buffer pemutaran lokal untuk mencegah audio lama terus diputar.
Model dan wilayah yang didukung
- Singapura
- China (Beijing)
- qwen-audio-3.0-realtime-plus
- qwen-audio-3.0-realtime-flash
Referensi API
- API WebSocket
- Event klien
- Event server
- SDK Klien AOQ
- Ikhtisar API Realtime (deskripsi protokol WebRTC)