Gunakan iOS SDK untuk Qwen-Audio-3.0-Realtime guna membangun percakapan suara real-time dengan input audio dan output audio atau teks.
Mulai cepat
- Dapatkan API key: Dapatkan dan konfigurasikan API key.
-
Unduh SDK dan jalankan kode contoh:
- Unduh paket SDK terbaru.
- Ekstrak paket ZIP dan tambahkan
nuisdk.xcframeworkke proyek Anda. - Di Build Phases > Link Binary With Libraries, tambahkan
nuisdk.xcframework. - Di General > Frameworks, Libraries, and Embedded Content, atur
nuisdk.xcframeworkke Embed & Sign. - Buka proyek di Xcode. Kode contoh ada di
DashQwenAudioChatViewController.m. Ganti API key untuk mencoba fitur ini.
Prosedur pemanggilan
- Inisialisasi SDK.
- Atur parameter untuk kasus penggunaan Anda. Gunakan argumen
parametersdari nui_initialize untuk mengatur connection and control parameters, dan gunakan nui_set_params untuk mengatur voice conversation parameters. - Panggil nui_dialog_start untuk memulai percakapan.
- Di onNuiAudioStateChanged, mulai perangkat perekaman berdasarkan status audio.
- Pasok data rekaman secara terus-menerus di onNuiNeedAudioData, atau panggil nui_update_audio_data untuk mendorong data rekaman secara aktif.
- Terima secara terus-menerus audio yang dikembalikan oleh model di onNuiAssistEventCallback.
- Dengarkan event dan dapatkan informasi event di onNuiEventCallback.
- Panggil nui_dialog_cancel untuk menghentikan percakapan, dan dengarkan
EVENT_TRANSCRIBER_COMPLETEuntuk mengonfirmasi bahwa percakapan telah berakhir. - Ketika fitur percakapan tidak lagi diperlukan, panggil nui_release untuk melepaskan sumber daya SDK.
Parameter permintaan
Parameter koneksi dan kontrol
Berikan string JSON dalam argumen parameters dari nui_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 nui_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 nui_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. |
Parameter percakapan suara
Berikan string JSON dalam argumen params dari nui_set_params.
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 | BOOL | Tidak | Apakah akan mengaktifkan ekspresi emosional yang ditingkatkan. Saat diaktifkan, suara respons memiliki variasi emosional yang lebih kentara. Default: YES. Nilai yang valid: YES dan NO. |
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
NeoNui
nui_initialize
Menginisialisasi instance SDK percakapan suara. SDK ini adalah singleton. Jangan menginisialisasinya lagi sebelum Anda memanggil nui_release.
Signature metode
Parameter | Tipe | Deskripsi |
|---|---|---|
|
| String JSON yang berisi parameter autentikasi, koneksi, dan debugging. Lihat Parameter koneksi dan kontrol. |
|
| Tingkat cetak untuk log SDK itu sendiri. |
| BOOL | Apakah akan menyimpan log secara lokal. Jika diatur ke |
nui_set_params
Mengatur Voice conversation parameters dalam format JSON. Panggil metode ini sebelum nui_dialog_start.
Signature metode
Parameter | Tipe | Deskripsi |
|---|---|---|
|
|
nui_dialog_start
Memulai percakapan.
Signature metode
| Parameter | Tipe | Deskripsi |
|---|---|---|
vad_mode | NuiVadMode | Mode VAD. Tetap pada MODE_P2T. |
dialog_params | char* | Jika apikey dalam parameter koneksi dan kontrol adalah API key sementara, perbarui di sini setelah kedaluwarsa.Format JSON: |
nui_dialog_cancel
Mengakhiri percakapan atau segera membatalkan interaksi saat ini.
Signature metode
Parameter | Tipe | Deskripsi |
|---|---|---|
|
| Apakah akan mengakhiri secara paksa dan membuang hasil akhir.
|
nui_dialog_action
Mengirimkan perintah tindakan percakapan selama interaksi untuk memperbarui perilaku runtime seperti konteks percakapan.
Signature metode
| Parameter | Tipe | Deskripsi |
|---|---|---|
params | char* | 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. |
nui_update_audio_data
Saat audio_update_manually diatur ke "true", data rekaman tidak lagi dipasok melalui onNuiNeedAudioData. Gunakan metode ini untuk mendorongnya secara aktif sebagai gantinya.
Signature metode
Parameter | Tipe | Deskripsi |
|---|---|---|
|
| Data audio yang akan di-push. |
|
| Panjang data audio, dalam byte. |
|
| Anda tidak perlu menggunakan parameter ini. |
nui_push_reference_data
Saat audio_update_manually diatur ke "true" dan acoustic echo cancellation (AEC) pada perangkat diaktifkan, gunakan metode ini untuk mendorong audio yang diputar oleh pemutar sebagai sinyal referensi.
Signature metode
Parameter | Tipe | Deskripsi |
|---|---|---|
|
| Data audio yang akan di-push. |
|
| Panjang data audio, dalam byte. |
|
| Anda tidak perlu menggunakan parameter ini. |
nui_release
Melepaskan semua sumber daya internal SDK dan menghentikan paksa semua tugas yang berjalan. Setelah Anda memanggil metode ini, instance SDK menjadi tidak tersedia. Untuk menggunakannya lagi, Anda harus memanggil nui_initialize untuk menginisialisasinya kembali.
Signature metode
nui_get_version
Mendapatkan versi SDK saat ini. Metode ini mengembalikan nilai hanya setelah nui_initialize dipanggil.
Signature metode
nui_get_all_response
Mendapatkan informasi lengkap untuk callback event saat ini.
Signature metode
NeoNuiSdkDelegate: listener callback
onNuiEventCallback: mendengarkan informasi event
Signature metode
Parameter | Tipe | Deskripsi |
|---|---|---|
| Event callback. | |
|
| ID Sesi. Anda tidak perlu menggunakan parameter ini. |
|
| Voice wake-up. Anda tidak perlu menggunakan parameter ini. |
|
| Hasil pengenalan ucapan. |
|
| Apakah putaran pengenalan saat ini telah selesai. |
|
| Hanya valid saat event |
onNuiAudioStateChanged: mendengarkan status audio
SDK menggunakan callback ini untuk memberi tahu Anda kapan harus memulai atau menghentikan perekaman.
Signature metode
Parameter | 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 diberikan. |
|
| Ukuran data audio yang diberikan, dalam byte. |
onNuiAssistEventCallback: menerima data dan informasi tambahan
Menerima event tambahan dan data terkait dari SDK.
Signature metode
Parameter | Tipe | Deskripsi |
|---|---|---|
|
| Event callback. |
|
| Anda tidak perlu menggunakan parameter ini. |
|
| Anda tidak perlu menggunakan parameter ini. |
|
| Data tambahan, seperti audio TTS yang dikembalikan oleh model. |
|
| Panjang data tambahan, dalam byte. |
onNuiLogTrackCallback: mendengarkan log pelacakan
Callback ini menerima log internal terperinci SDK untuk membantu Anda menemukan dan men-debug masalah.
NuiCallbackEvent: 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. |