Gunakan Android SDK untuk Qwen-Audio-3.0-Realtime guna membangun percakapan suara waktu nyata dengan input audio dan output audio atau teks.
Mulai cepat
- Dapatkan dan konfigurasikan API key.
-
Unduh SDK dan jalankan kode contoh:
- Unduh paket SDK terbaru.
- Ekstrak paket ZIP. Dapatkan SDK AAR dari
app/libsdan tambahkan ke dependensi proyek Anda. Untuk integrasi C++ Android, gunakanandroid_libsdanandroid_includedalam paket ZIP untuk mendapatkan pustaka dinamis dan file header. - Buka proyek di Android Studio. Kode contoh ada di
DashQwenAudioChatActivity.java. Ganti API key untuk mencoba fitur ini.
Prosedur pemanggilan
- Inisialisasi SDK.
- Atur parameter untuk kasus penggunaan Anda. Gunakan argumen
parametersdari initialize untuk mengatur parameter koneksi dan kontrol, dan gunakan setParams untuk mengatur parameter percakapan suara. - Panggil startDialog untuk memulai percakapan.
- Di onNuiAudioStateChanged, mulai perangkat perekaman berdasarkan status audio.
- Sediakan data perekaman secara terus-menerus di onNuiNeedAudioData, atau panggil updateAudio untuk mendorong data perekaman secara aktif.
- Terima secara terus-menerus audio yang dikembalikan oleh model di onNuiAssistEventCallback.
- Dengarkan event dan dapatkan informasi event di onNuiEventCallback.
- Panggil stopDialog untuk menghentikan percakapan, dan dengarkan
EVENT_TRANSCRIBER_COMPLETEuntuk mengonfirmasi bahwa percakapan telah berakhir. - Saat fitur percakapan tidak lagi diperlukan, panggil release untuk melepaskan sumber daya SDK.
Parameter permintaan
Parameter koneksi dan kontrol
Berikan string JSON pada argumen parameters dari initialize.
Contoh: String JSON berikut tidak mencantumkan setiap parameter. Tambahkan parameter sesuai kebutuhan untuk kasus penggunaan Anda.
| Parameter | Tipe | Wajib | Deskripsi |
|---|---|---|---|
url | String | Ya | Endpoint layanan:
{WorkspaceId} dengan ID Workspace. |
apikey | String | Ya | API key. |
service_mode | String | Ya | Mode runtime. Atur parameter ini ke "1" untuk percakapan suara real-time. |
device_id | String | Ya | String unik yang mengidentifikasi pengguna akhir. Anda dapat menggunakan ID pengguna dalam aplikasi atau pengidentifikasi perangkat yang dibuat klien. ID ini terutama digunakan untuk pelacakan log dan pemecahan masalah. |
audio_update_manually | String | Tidak | Apakah akan mendorong data audio secara aktif. Default: "false". Jika diatur ke "true" dan SDK mendukung kemampuan audio on-device seperti AEC dan VAD, kemampuan tersebut diaktifkan secara default. |
workspace | String | Tidak | Jalur penyimpanan untuk file sumber daya on-device. Parameter ini wajib diisi jika audio_update_manually adalah "true" dan kemampuan audio on-device seperti AEC atau VAD diaktifkan. |
debug_path | String | Tidak | Jalur penyimpanan file log. Parameter ini hanya berlaku jika save_log adalah true di initialize. Dalam hal ini, jalur wajib diisi. SDK menyimpan paling banyak dua file log secara lokal. |
save_wav | String | Tidak | Apakah akan menyimpan audio debug di bawah debug_path. Default: "false". Nilai yang valid adalah "true" dan "false". Parameter ini hanya berlaku jika save_log adalah true, dan debug_path juga harus diatur. |
max_log_file_size | int | Tidak | Ukuran file log maksimum dalam byte. Parameter ini hanya berlaku jika save_log adalah true. Default: 104857600 (100 × 1024 × 1024 byte, atau 100 MiB). |
log_track_level | int | Tidak | Tingkat filter untuk log yang dikirim melalui onNuiLogTrackCallback. Default: 2. Nilai yang valid: 0 (VERBOSE), 1 (DEBUG), 2 (INFO), 3 (WARNING), 4 (ERROR), dan 5 (NONE). Log hanya dikembalikan jika tingkatnya lebih besar dari atau sama dengan log_track_level dan level yang diteruskan ke initialize. Misalnya, jika log_track_level adalah 2 (INFO) dan level adalah 3 (WARNING), hanya log WARNING dan tingkat lebih tinggi (nilai lebih besar dari atau sama dengan 3) yang dikembalikan. |
aec_params | object | Tidak | Konfigurasi AEC on-device tingkat lanjut. Objek ini hanya berlaku jika audio_update_manually adalah "true". |
aec_params.enable_aec | boolean | Tidak | Apakah akan mengaktifkan AEC on-device. Jika audio_update_manually adalah "true" dan SDK mendukung AEC on-device, AEC diaktifkan secara default. |
aec_params.save_audio | boolean | Tidak | Apakah akan menyimpan audio yang diproses oleh modul AEC on-device. Jika save_wav adalah "true" dan debug_path diatur, fitur ini diaktifkan secara default dan audio disimpan di bawah debug_path. |
aec_params.enable_aec_data_callback | boolean | Tidak | Apakah akan mengembalikan audio yang diproses AEC melalui EVENT_AEC_DATA di onNuiAssistEventCallback. Default: false. |
vad_params | object | Tidak | Konfigurasi VAD on-device tingkat lanjut. Objek ini hanya berlaku jika audio_update_manually adalah "true". |
vad_params.enable_vad | boolean | Tidak | Apakah akan mengaktifkan VAD on-device. Jika audio_update_manually adalah "true" dan SDK mendukung VAD on-device, VAD diaktifkan secara default. |
vad_params.save_audio | boolean | Tidak | Apakah akan menyimpan audio yang diproses oleh modul VAD on-device. Jika save_wav adalah "true" dan debug_path diatur, fitur ini diaktifkan secara default dan audio disimpan di bawah debug_path. |
Parameter percakapan suara
Berikan string JSON pada argumen params dari setParams.
Contoh: String JSON berikut tidak mencantumkan setiap parameter. Tambahkan parameter sesuai kebutuhan untuk kasus penggunaan Anda.
| Parameter tingkat atas | Tipe | Wajib | Deskripsi |
|---|---|---|---|
service_type | int | Ya | Tipe layanan suara. Atur parameter ini ke 4 untuk percakapan suara real-time. |
nls_config | object | Ya | Konfigurasi inti percakapan suara, termasuk pemilihan model dan perilaku percakapan. |
nls_config.model | string | Ya | Nama model. Mendukung seri model qwen-audio-3.1-realtime-plus, qwen-audio-3.0-realtime-plus, dan qwen-audio-3.0-realtime-flash. |
nls_config.sr_format | string | Ya | Format audio input. Hanya pcm yang didukung. Format defaultnya adalah PCM mono 16 kHz, 16-bit. |
nls_config.modalities | string | Tidak | String yang berisi array modalitas output. Nilai yang valid:
|
nls_config.voice | string | Tidak | Suara TTS. Defaultnya adalah longanqian_v3.1 untuk 3.1 Plus dan longanqian untuk 3.0 Plus/Flash. Parameter ini hanya dapat diatur pada session.update pertama; nilai berikutnya akan diabaikan. Suara sistem: longanqian, longanlingxin, longanlingxi, longanxiaoxin, dan longanlufeng. Anda juga dapat menentukan voice_id kloning yang dibuat melalui API kloning suara. Lihat Konfigurasi suara.3.1 Plus juga mendukung longanqian_v3.1, longanhuan_v3.1, longanlingxin_v3.1, longanfengyue_v3.1, xunanchuan_v3.1, beth_v3.1, betty_v3.1, cally_v3.1. |
nls_config.enable_speech_emotion | boolean | Tidak | Apakah akan mengaktifkan ekspresi emosional yang ditingkatkan. Saat diaktifkan, suara respons memiliki variasi emosional yang lebih kentara. Default: true. Nilai yang valid: true dan false. |
nls_config.instructions | string | Tidak | Instruksi sistem yang menentukan peran model, gaya respons, dan preferensi perilaku untuk seluruh sesi. |
nls_config.max_history_turns | int | Tidak | Jumlah maksimum giliran tanya-jawab historis yang diizinkan dalam satu permintaan. Nilai yang valid: 1 hingga 50. Default: 20. |
nls_config.tools | string | Tidak | String yang berisi array definisi alat Function Calling. Setelah Anda mengonfigurasi parameter ini, model memutuskan apakah akan memanggil alat berdasarkan input pengguna. Setiap definisi menggunakan type (wajib dan ditetapkan ke function) dan objek function yang berisi name (wajib), description (opsional), dan parameters (opsional). Jika fungsi tidak memiliki argumen, abaikan parameters.Contoh: |
nls_config.turn_detection | string | Tidak | String yang berisi objek JSON untuk deteksi giliran. Jika diabaikan, sesi menggunakan mode push-to-talk, di mana audio dikirim dan inferensi dipicu secara manual. Jika diatur, mode percakapan dupleks diaktifkan. |
nls_config.turn_detection.type | string | Tidak | Tipe VAD. server_vad (default) mendeteksi batasan ucapan dari fitur akustik dan secara otomatis memicu inferensi. smart_turn menggabungkan sinyal akustik dan semantik; suara tanpa konten semantik, seperti suara pengisi, tidak memulai giliran atau mengganggu pemutaran model. |
nls_config.turn_detection.threshold | float | Tidak | Sensitivitas VAD. Parameter ini hanya berlaku untuk server_vad dan tidak berpengaruh pada smart_turn. Nilai yang lebih rendah membuat VAD lebih sensitif terhadap suara pelan dan kebisingan latar belakang; nilai yang lebih tinggi memerlukan ucapan yang lebih jelas dan lebih keras. Rentang yang valid: [-1.0, 1.0]. Default: 0.5. |
nls_config.turn_detection.silence_duration_ms | int | Tidak | Durasi hening minimum setelah ucapan, dalam milidetik, sebelum respons model dipicu. Parameter ini hanya berlaku untuk server_vad dan tidak berpengaruh pada smart_turn. Nilai yang lebih rendah mengurangi latensi tetapi dapat terpicu pada jeda singkat. Rentang yang valid: [200, 6000]. Default: 800. Direkomendasikan untuk percakapan: 400 hingga 800. |
nls_config.turn_detection.voiceprint_audio_urls | string | Tidak | String yang berisi array URL audio prarekaman yang dapat diakses publik untuk pembicara target. Parameter ini hanya berlaku untuk smart_turn. Dalam percakapan dupleks, ini membantu model fokus pada pembicara target dan mengabaikan pembicara lain serta kebisingan latar belakang. Mendukung hingga lima URL. Audio harus berupa PCM atau WAV 16 kHz. |
API Utama
NativeNui
initialize
Menginisialisasi instance SDK percakapan suara. SDK adalah singleton. Jangan menginisialisasinya lebih dari sekali sebelum Anda memanggil release.
Metode ini memblokir, jadi panggil pada thread non-UI.
Signature metode
Parameter | Tipe | Deskripsi |
|---|---|---|
| Implementasi antarmuka callback event dan data. | |
|
| String JSON yang berisi parameter autentikasi, koneksi, dan debug. Lihat Parameter koneksi dan kontrol. |
|
| Mengontrol tingkat pencetakan log SDK itu sendiri. |
|
| Apakah akan menyimpan log lokal. Jika diatur ke |
setParams
Mengatur Parameter percakapan suara dalam format JSON. Panggil metode ini sebelum startDialog.
Signature metode
Parameter | Tipe | Deskripsi |
|---|---|---|
|
|
startDialog
Memulai percakapan.
Signature metode
| Parameter | Tipe | Deskripsi |
|---|---|---|
vad_mode | VadMode | Mode VAD. Tetap pada VadMode.TYPE_P2T. |
dialog_params | String | Jika apikey dalam parameter koneksi dan kontrol adalah API key sementara, perbarui di sini setelah kedaluwarsa.Format JSON: |
stopDialog
Mengakhiri percakapan. Setelah Anda memanggil metode ini, server akan mengembalikan hasil percakapan akhir dan mengakhiri tugas.
Signature metode
cancelDialog
Mengakhiri percakapan segera. Setelah Anda memanggil metode ini, tugas langsung berakhir tanpa menunggu server mengembalikan hasil percakapan akhir.
Signature metode
updateAction
Mengirimkan perintah tindakan percakapan selama interaksi untuk memperbarui perilaku runtime seperti konteks percakapan.
Signature metode
| Parameter | Tipe | Deskripsi |
|---|---|---|
params | String | String JSON yang digunakan untuk memperbarui perilaku runtime seperti konteks percakapan. |
params.type | String | Atur ke "action". |
params.command | String | Perintah runtime. Nilai yang valid:
|
params.context | String | Pembaruan permintaan function call. Digunakan ketika command adalah "function_call". |
params.context.type | String | Tipe event. Parameter ini wajib diisi jika command adalah "function_call". conversation.item.create menyisipkan item percakapan untuk konteks historis, teks tambahan, atau hasil alat. Setelah mengirim conversation.item.create, gunakan response.create untuk memicu inferensi lain. |
params.context.item | object | Wajib ketika params.context.type adalah conversation.item.create. Item percakapan yang akan dibuat. |
params.context.response | object | Opsional jika params.context.type adalah response.create. Menimpa default sesi untuk inferensi ini. Jika diabaikan, konfigurasi sesi saat ini akan digunakan. |
context.item:
| Parameter | Tipe | Deskripsi |
|---|---|---|
id | String | ID item percakapan unik opsional. Jika diabaikan, server akan membuatnya. Error akan dikembalikan jika ID yang ditentukan sudah ada. |
type | String | Tipe item wajib. Nilai yang valid:
|
role | String | Wajib untuk message. Nilai yang valid: system, user, dan assistant. |
content | array | Wajib untuk message. Setiap item berisi type dan bidang data terkait. system mendukung input_text dengan text; user mendukung input_text dengan text dan input_audio dengan audio yang dienkode Base64; assistant mendukung output_text dengan text. |
call_id | String | Wajib untuk function_call dan function_call_output. ID unik yang mengaitkan permintaan pemanggilan fungsi dengan hasilnya. |
name | String | Wajib untuk function_call. Nama fungsi yang akan dipanggil. |
arguments | String | Wajib untuk function_call. Argumen fungsi sebagai string JSON. |
output | String | Wajib untuk function_call_output. Hasil eksekusi tool sebagai string JSON. |
context.response:
| Parameter | Tipe | Deskripsi |
|---|---|---|
modalities | array | Modalitas output. ["text"] hanya mengembalikan teks. ["audio", "text"] (default) mengembalikan audio dan teks. |
voice | string | Menimpa suara TTS untuk inferensi ini. |
updateAudio
Saat audio_update_manually diatur ke "true", panggil metode ini untuk mendorong data perekaman secara aktif alih-alih menyediakan data melalui onNuiNeedAudioData.
Signature metode
Parameter | Tipe | Deskripsi |
|---|---|---|
|
| Data audio yang akan di-push. |
|
| Jumlah byte data audio yang akan di-push. |
|
| Abaikan parameter ini. |
updateRefAudio
Saat audio_update_manually diatur ke "true" dan AEC on-device diaktifkan, panggil metode ini untuk mendorong audio yang diputar oleh pemutar sebagai sinyal referensi.
Signature metode
Parameter | Tipe | Deskripsi |
|---|---|---|
|
| Data audio yang akan di-push. |
|
| Jumlah byte data audio yang akan di-push. |
|
| Abaikan parameter ini. |
release
Melepaskan semua sumber daya internal SDK. Setelah Anda memanggil metode ini, instance SDK menjadi tidak tersedia. Untuk menggunakannya lagi, Anda harus menginisialisasi ulang dengan memanggil initialize.
Signature metode
GetVersion
Mendapatkan informasi versi SDK saat ini.
Signature metode
INativeNuiCallback: callback listener
onNuiEventCallback: mendengarkan informasi event
Signature metode
Parameter | Tipe | Deskripsi |
|---|---|---|
| Event callback. | |
|
| Hanya valid saat event |
|
| Parameter yang dicadangkan. |
|
| Hasil pengenalan ucapan. |
|
| Fitur voice wake-up. Anda tidak perlu menggunakan parameter ini. |
onNuiAudioStateChanged: mendengarkan status audio
SDK menggunakan callback ini untuk memberi tahu Anda kapan harus memulai atau menghentikan perekaman.
Signature metode
Status | Deskripsi |
|---|---|
| Interaksi telah dimulai. Anda dapat membuka perangkat perekaman dan memulai perekaman. |
| Interaksi telah berhenti. Anda dapat menghentikan perekaman. |
| Instans SDK telah dilepaskan. Anda dapat menutup perangkat perekaman sepenuhnya. |
onNuiNeedAudioData: memasok data audio
Setelah percakapan dimulai, callback ini dipicu secara terus-menerus. Sediakan data audio di callback ini. Anda tidak perlu menggunakan callback ini saat audio_update_manually diatur ke "true".
Signature metode
Parameter | Tipe | Deskripsi |
|---|---|---|
|
| Data audio yang akan diisi. |
|
| Jumlah byte data audio yang akan diisi. |
onNuiAssistEventCallback: menerima event dan data tambahan
Callback ini menerima event tambahan dan data terkait dari SDK.
Signature metode
Parameter | Tipe | Deskripsi |
|---|---|---|
|
| Event |
|
| Abaikan parameter ini. |
|
| Abaikan parameter ini. |
|
| Data tambahan, seperti audio TTS yang dikembalikan oleh model. |
onNuiLogTrackCallback: mendengarkan log trace
Callback ini menerima log internal terperinci dari SDK untuk membantu pemecahan masalah dan debugging.
NuiEvent: tipe event
| Event | Deskripsi |
|---|---|
EVENT_TRANSCRIBER_STARTED | Tugas berhasil dimulai. |
EVENT_VAD_START | Dipicu segera setelah tugas dimulai. Ini tidak berarti bahwa awal ucapan telah terdeteksi. |
EVENT_VAD_END | Akhir ucapan terdeteksi. |
EVENT_ASR_PARTIAL_RESULT | Hasil pengenalan ucapan sementara. |
EVENT_ASR_ERROR | Terjadi kesalahan selama percakapan suara. |
EVENT_MIC_ERROR | Dipicu ketika tidak ada data audio yang diterima selama dua detik berturut-turut. |
EVENT_SENTENCE_END | Akhir kalimat terdeteksi dan hasil pengenalan lengkap dikembalikan. |
EVENT_TRANSCRIBER_COMPLETE | Percakapan suara berakhir. |
EVENT_AUDIO_TRANSCRIPTION | Event transkripsi teks inkremental untuk output audio. Segmen transkripsi dikembalikan dalam mode streaming. |
EVENT_AUDIO_TRANSCRIPTION_COMPLETED | Transkrip untuk output audio telah selesai. |
EVENT_OTHER_RESULT | Informasi event lainnya, seperti hasil Function Calling. |
EVENT_ASR_TTS_START | Model mulai mengembalikan audio TTS. |
EVENT_ASR_TTS_DATA | Audio TTS yang dikembalikan oleh model. |
EVENT_ASR_TTS_COMPLETE | Model selesai mengembalikan audio TTS. |
EVENT_AEC_DATA | Data audio yang diproses oleh AEC. |