Gunakan SDK iOS percakapan suara realtime Qwen-Audio-Realtime untuk mengaktifkan input audio realtime serta output ucapan atau teks.
Untuk koneksi dan autentikasi, lihat Akses WebSocket. Untuk bidang event dan contoh JSON, lihat Event klien dan Event server.
Panduan pengguna:Untuk pengenalan model dan rekomendasi pemilihan, lihat Percakapan suara real-time.
Buka proyek contoh di Xcode. Kode contoh berada di
Konfigurasikan dengan meneruskan string JSON ke parameter
Deskripsi parameter
Dikonfigurasi dengan meneruskan string JSON ke parameter
Deskripsi parameter
Menginisialisasi instance SDK percakapan suara. SDK adalah singleton; jangan menginisialisasinya berulang kali sebelum memanggil
Deskripsi parameter
Mengatur parameter efek percakapan suara dalam format JSON. Panggil sebelum
Deskripsi parameter
Memulai percakapan.
Signature metode
Deskripsi parameter
Mengakhiri percakapan atau segera membatalkan interaksi saat ini.
Signature metode
Deskripsi parameter
Mengirimkan perintah aksi percakapan selama interaksi, digunakan untuk memperbarui perilaku runtime seperti konteks percakapan.
Signature metode
Deskripsi parameter
Parameter
Parameter
Contoh:
Saat
Deskripsi parameter
Saat
Deskripsi parameter
Melepaskan semua sumber daya internal SDK dan mengakhiri secara paksa semua tugas yang sedang berjalan. Setelah metode ini dipanggil, instance SDK menjadi tidak tersedia. Untuk menggunakannya kembali, Anda harus memanggil
Mendapatkan informasi versi SDK saat ini. Antarmuka ini harus dipanggil setelah
Deskripsi nilai kembalian
Informasi versi SDK saat ini.
Mendapatkan informasi lengkap dari callback event saat ini.
Signature metode
Deskripsi nilai kembalian
Informasi event lengkap dalam format string JSON.
Signature metode
Deskripsi parameter
SDK menggunakan callback ini untuk memberi tahu kapan harus memulai atau menghentikan perekaman.
Signature metode
Deskripsi NuiAudioState
Setelah percakapan dimulai, callback ini dipicu secara terus-menerus, dan Anda harus menyediakan data audio yang akan diproses di dalamnya. Anda dapat mengabaikan callback ini jika parameter audio_update_manually diatur ke "true".
Signature metode
Deskripsi parameter
Callback ini digunakan untuk menerima event auxiliari dan data terkait dari dalam SDK.
Signature metode
Deskripsi parameter
Callback ini digunakan untuk menerima log terperinci dari dalam SDK, yang memfasilitasi pemecahan masalah dan debugging.
Prasyarat
- Dapatkan dan konfigurasikan kunci API. Jangan menanamkan kunci API jangka panjang secara langsung di aplikasi seluler. Kami menyarankan server aplikasi Anda membuat kunci API sementara lalu membagikannya ke klien.
Instal SDK
- Unduh paket integrasi SDK terbaru.
- Ekstrak paket ZIP dan tambahkan nuisdk.xcframework ke proyek Anda.
- Di Build Phases → Link Binary With Libraries, tambahkan nuisdk.xcframework.
- Di General → Frameworks, Libraries, and Embedded Content, atur nuisdk.xcframework ke Embed & Sign.
Mulai cepat
Buka proyek contoh di Xcode. Kode contoh berada di DashQwenAudioChatViewController.m. Ganti API Key dan coba fiturnya.
Prosedur
- Inisialisasi SDK.
- Atur parameter berdasarkan kebutuhan bisnis Anda: gunakan antarmuka nui_initialize untuk mengatur parameter koneksi dan kontrol; gunakan antarmuka nui_set_params untuk mengatur parameter efek percakapan suara.
- Panggil nui_dialog_start untuk memulai proses percakapan.
- Di callback onNuiAudioStateChanged, mulai perangkat perekaman berdasarkan status audio.
- Di callback onNuiNeedAudioData, sediakan data perekaman secara terus-menerus, atau gunakan nui_update_audio_data untuk mendorong data perekaman secara terus-menerus.
- Di callback onNuiAssistEventCallback, terima data suara yang dikembalikan oleh AI secara terus-menerus.
- Di callback onNuiEventCallback, dengarkan event dan dapatkan informasi event.
- Panggil nui_dialog_cancel untuk menghentikan percakapan, dan konfirmasikan bahwa percakapan telah berakhir dengan mendengarkan event EVENT_TRANSCRIBER_COMPLETE.
- Ketika fungsi percakapan tidak lagi diperlukan, panggil antarmuka nui_release untuk melepaskan sumber daya SDK.
Parameter permintaan
Parameter koneksi dan kontrol
Konfigurasikan dengan meneruskan string JSON ke parameter parameters dari antarmuka nui_initialize.
Contoh parameter:Berikut adalah contoh string JSON. Parameter tidak dicantumkan seluruhnya. Tambahkan sesuai kebutuhan selama pengembangan:
Contoh ini menggunakan qwen-audio-3.1-realtime-plus. Saat Anda mengganti model, perbarui model di URL dan nls_config.model pada parameter efek percakapan suara secara sesuai.
| Parameter | Tipe | Wajib | Deskripsi |
|---|---|---|---|
url | String | Ya | URL layanan:
{WorkspaceId} dengan ID Workspace Anda yang sebenarnya. |
apikey | String | Ya | Kunci API. |
service_mode | String | Ya | Mode operasi. Untuk percakapan suara real-time, parameter ini tetap "1". |
device_id | String | Ya | String unik yang digunakan untuk mengidentifikasi pengguna akhir. Anda dapat mengaturnya ke ID pengguna dalam aplikasi atau pengidentifikasi unik perangkat yang dibuat oleh klien. ID ini terutama digunakan untuk pelacakan log dan pemecahan masalah. |
audio_update_manually | String | Tidak | Apakah akan mengaktifkan mode dorong data audio proaktif. Nilai default: "false". Saat diatur ke "true" untuk mengaktifkan mode dorong data audio proaktif dan versi SDK mendukung kemampuan audio on-device (seperti AEC dan VAD), kemampuan audio on-device diaktifkan secara default. |
workspace | String | Tidak | Jalur penyimpanan file sumber daya on-device. Parameter ini wajib diatur saat audio_update_manually diatur ke "true" dan kemampuan audio on-device (seperti AEC dan VAD) diaktifkan. |
debug_path | String | Tidak | Jalur penyimpanan file log. Parameter ini hanya berlaku saat save_log diatur ke YES saat memanggil metode nui_initialize. Dalam kasus ini, jalur file log wajib diatur; jika tidak, kesalahan akan dilaporkan. Maksimal dua file log disimpan secara lokal. |
save_wav | String | Tidak | Apakah akan menyimpan file audio untuk debugging. File audio disimpan di bawah debug_path. Nilai default: "false".Nilai yang valid:
save_log diatur ke true saat memanggil metode nui_initialize. Selain itu, debug_path juga harus diatur. |
max_log_file_size | int | Tidak | Mengatur jumlah byte maksimum untuk file log. Parameter ini hanya berlaku saat save_log diatur ke YES saat memanggil metode nui_initialize. Nilai default: 104857600 (100 × 1024 × 1024 byte, yaitu 100MiB). |
log_track_level | int | Tidak | Mengontrol tingkat filter untuk konten log yang dikirim ke eksternal melalui callback log (onNuiLogTrackCallback). Nilai default: 2. Nilai yang valid:
log_track_level dan level (diatur melalui metode nui_initialize) bersama-sama menentukan log yang pada akhirnya dipanggil kembali. Log hanya dipanggil kembali jika nilai tingkatnya lebih besar dari atau sama dengan log_track_level dan level. Misalnya, jika log_track_level diatur ke 2 (INFO) dan level diatur ke 3 (WARNING), hanya log dengan tingkat WARNING dan lebih tinggi (nilai >=3) yang akan dipanggil kembali. |
Parameter efek percakapan suara
Dikonfigurasi dengan meneruskan string JSON ke parameter params dari metode nui_set_params.
Contoh parameter:Berikut adalah contoh string JSON. Parameter tidak dicantumkan seluruhnya. Tambahkan sesuai kebutuhan selama pengembangan:
| Parameter tingkat atas | Tipe | Wajib | Deskripsi |
|---|---|---|---|
service_type | int | Ya | Tipe layanan suara. Tetap ke 4 untuk percakapan suara real-time. |
nls_config | object | Ya | Objek konfigurasi inti percakapan suara, berisi parameter kunci seperti pemilihan model dan kontrol efek percakapan. |
nls_config.model | string | Ya | Menentukan nama model. Model yang didukung meliputi seri 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. |
nls_config.sr_format | string | Ya | Format audio input. Saat ini, hanya pcm (16kHz 16bit mono) yang didukung, yang merupakan nilai default. |
nls_config.modalities | string | Tidak | String dalam format array. Pengaturan modalitas output model. Nilai yang valid:
|
nls_config.voice | string | Tidak | Nama suara TTS. Nilai default untuk 3.1 Plus/Flash adalah longanqian_v3.1, dan nilai default untuk 3.0 Plus/Flash adalah longanqian. Hanya dapat diatur di session.update pertama; input berikutnya akan diabaikan.
|
| nls_config.enable_speech_emotion | BOOL | Tidak | Apakah akan mengaktifkan peningkatan emosi. Saat diaktifkan, perubahan emosional suara balasan lebih terlihat. Nilai default: YES. Nilai yang valid: YES, NO. |
| nls_config.instructions | string | Tidak | Instruksi sistem, digunakan untuk menentukan peran model, gaya respons, dan preferensi perilaku. Berlaku untuk seluruh sesi. |
| nls_config.max_history_turns | int | Tidak | Jumlah maksimum giliran tanya-jawab historis yang diizinkan per permintaan. Rentang nilai: 1-50. Nilai default: 20. |
| nls_config.tools | string | Tidak | String dalam format array. Daftar definisi alat Function Calling. Setelah dikonfigurasi, model dapat secara mandiri memutuskan apakah akan memanggil alat berdasarkan input pengguna. Deskripsi parameter internal: type string(wajib)Tetap ke function.function.name string(wajib)Nama fungsi alat. function.description string (opsional)Deskripsi fungsionalitas fungsi alat, berdasarkan hal tersebut model memutuskan apakah akan memanggil alat. function.parameters object (opsional)Deskripsi parameter input fungsi alat, berdasarkan hal tersebut model mengekstrak parameter input yang diperlukan. Jika fungsi tidak memerlukan parameter input, bagian ini dapat dihilangkan. Contoh: |
| nls_config.turn_detection | string | Tidak | Deskripsi bidang deteksi giliran berikut berlaku untuk 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.String dalam format objek JSON. Konfigurasi deteksi giliran. Jika tidak diatur, beralih ke mode push-to-talk (mengirimkan audio dan memicu inferensi secara manual). Jika tidak, mode percakapan dupleks diaktifkan. |
| nls_config.turn_detection.type | string | Tidak | Tipe VAD. Nilai yang valid:
|
| nls_config.turn_detection.threshold | float | Tidak | Sensitivitas VAD. Berlaku untuk server_vad, smart_turn, dan smart_turn_v2. Semakin rendah nilainya, semakin mudah suara samar (termasuk kebisingan latar belakang) dikenali sebagai ucapan; semakin tinggi nilainya, semakin jelas dan keras ucapan yang diperlukan untuk memicu deteksi.Rentang nilai: [-1.0, 1.0], nilai default: 0.5. |
| nls_config.turn_detection.silence_duration_ms | int | Tidak | Durasi hening minimum (dalam milidetik) setelah ucapan berakhir. Hanya efektif dalam mode server_vad (tidak efektif dalam mode smart_turn dan smart_turn_v2). Setelah hening mencapai durasi ini, respons model dipicu. Nilai lebih rendah membuat respons lebih cepat, tetapi jeda singkat juga dapat menyebabkan pemicuan palsu. Rentang nilai: [200, 6000], nilai default: 800. 400-800 direkomendasikan untuk skenario percakapan. |
| nls_config.turn_detection.voiceprint_audio_urls | string | Tidak | String dalam format array. Efektif dalam mode smart_turn dan smart_turn_v2.Daftar URL yang dapat diakses publik dari audio prarekam pengguna target, digunakan untuk peningkatan pembicara. Model menggunakan sampel audio ini untuk mengunci pembicara target selama percakapan full-duplex, mengabaikan suara lain dan kebisingan latar belakang. Mendukung hingga 5 URL. Persyaratan format audio: PCM 16kHz atau WAV. |
Referensi API
NeoNui
nui_initialize
Menginisialisasi instance SDK percakapan suara. SDK adalah singleton; jangan menginisialisasinya berulang kali sebelum memanggil nui_release.
Signature metode
| Parameter | Tipe | Deskripsi |
|---|---|---|
parameters | char* | String JSON yang berisi parameter autentikasi, koneksi, dan debug. Lihat Parameter koneksi dan kontrol. |
level | NuiSdkLogLevel | Mengontrol tingkat output log dari log SDK itu sendiri. |
save_log | BOOL | Apakah akan menyimpan log lokal. Jika diatur ke YES, Anda harus menentukan jalur melalui debug_path di Parameter koneksi dan kontrol, dan Anda dapat mengatur ukuran file melalui max_log_file_size. |
nui_set_params
Mengatur parameter efek percakapan suara dalam format JSON. Panggil sebelum nui_dialog_start.
Signature metode
| Parameter | Tipe | Deskripsi |
|---|---|---|
params | char* | Parameter efek percakapan suara. |
nui_dialog_start
Memulai percakapan.
Signature metode
| Parameter | Tipe | Deskripsi |
|---|---|---|
vad_mode | NuiVadMode | Mode VAD. Tetap ke MODE_P2T. |
dialog_params | char* | Jika parameter apikey dalam Parameter koneksi dan kontrol menggunakan kunci API sementara, Anda dapat memperbaruinya di sini saat kedaluwarsa.Kontennya dalam format JSON: |
nui_dialog_cancel
Mengakhiri percakapan atau segera membatalkan interaksi saat ini.
Signature metode
| Parameter | Tipe | Deskripsi |
|---|---|---|
force | BOOL | Apakah akan mengakhiri tugas secara paksa dan mengabaikan hasil akhir.
|
nui_dialog_action
Mengirimkan perintah aksi percakapan selama interaksi, digunakan 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 | Tetap ke "action". |
params.command | String | Perintah runtime spesifik. Saat ini mendukung function_call, play_start, dan play_over.
|
params.context | String | Memperbarui permintaan function call saat command adalah "function_call". |
params.context.type | String | Tipe event; wajib saat command adalah "function_call".
|
params.context.item | object | Wajib saat params.context.type adalah conversation.item.create. Menunjukkan item percakapan yang akan dibuat. Untuk informasi lebih lanjut, lihat berikut. |
params.context.response | object | Opsional saat params.context.type adalah response.create. Menunjukkan konfigurasi default sesi yang digunakan untuk menimpa putaran inferensi saat ini. Jika tidak ditentukan, konfigurasi sesi saat ini digunakan. Untuk informasi lebih lanjut, lihat berikut. |
context.item:
| Parameter | Tipe | Deskripsi |
|---|---|---|
| id | String | Opsional. Pengidentifikasi unik item percakapan. Jika tidak ditentukan, dibuat secara otomatis oleh server. Jika ID yang ditentukan sudah ada dalam percakapan, kesalahan akan dikembalikan. |
| type | String | Wajib. Tipe item percakapan. Nilai yang valid:
|
| role | String | Wajib untuk tipe message. Peran pesan. Nilai yang valid: system, user, assistant. |
| content | array | Wajib untuk tipe message. Daftar konten pesan. Setiap elemen berisi type dan bidang data terkait.Tipe konten yang didukung oleh setiap peran: system input_text: Pesan sistem, bidang wajib text.user
output_text: Output teks asisten, bidang wajib text. |
| call_id | String | (Wajib untuk tipe function_call / function_call_output)Pengidentifikasi unik pemanggilan fungsi, digunakan untuk mengaitkan permintaan dan hasil. |
| name | String | (Wajib untuk tipe function_call)Nama fungsi yang akan dipanggil. |
| arguments | String | Wajib untuk tipe function_call)Parameter pemanggilan fungsi, dalam format string JSON. |
| output | String | (Wajib untuk tipe function_call_output)Hasil eksekusi alat, dalam format string JSON. |
context.response:
| Parameter | Tipe | Deskripsi |
|---|---|---|
| modalities | array | String dalam format array. Pengaturan modalitas output model. Nilai yang valid:
|
| voice | string | Menimpa suara TTS untuk putaran saat ini. |
nui_update_audio_data
Saat audio_update_manually diatur ke "true", data perekaman tidak lagi diisi melalui onNuiNeedAudioData; sebagai gantinya, didorong secara aktif melalui antarmuka ini.
Signature metode
| Parameter | Tipe | Deskripsi |
|---|---|---|
data | const char * | Data audio yang didorong. |
length | int | Jumlah byte data audio yang didorong. |
first_pack | BOOL | Anda tidak perlu memperhatikan parameter ini. |
nui_push_reference_data
Saat audio_update_manually diatur ke "true" dan kemampuan pembatalan gema AEC on-device diaktifkan, Anda perlu mendorong data audio yang diputar oleh pemutar melalui antarmuka ini sebagai sinyal referensi.
Signature metode
| Parameter | Tipe | Deskripsi |
|---|---|---|
data | const char * | Data audio yang didorong. |
length | int | Jumlah byte data audio yang didorong. |
first_pack | BOOL | Anda tidak perlu memperhatikan parameter ini. |
nui_release
Melepaskan semua sumber daya internal SDK dan mengakhiri secara paksa semua tugas yang sedang berjalan. Setelah metode ini dipanggil, instance SDK menjadi tidak tersedia. Untuk menggunakannya kembali, Anda harus memanggil nui_initialize lagi untuk inisialisasi.
Signature metode
nui_get_version
Mendapatkan informasi versi SDK saat ini. Antarmuka ini harus dipanggil setelah nui_initialize untuk mengembalikan nilai.
Signature metode
nui_get_all_response
Mendapatkan informasi lengkap dari callback event saat ini.
Signature metode
NeoNuiSdkDelegate: Callback listener
onNuiEventCallback: Mendengarkan informasi event
Signature metode
| Parameter | Tipe | Deskripsi |
|---|---|---|
nuiEvent | NuiCallbackEvent | Event callback. |
dialog | long | Encoding sesi. Anda tidak perlu memperhatikan parameter ini. |
wuw | char* | Wake-up suara. Anda tidak perlu memperhatikan parameter ini. |
asr_result | char* | Hasil pengenalan ucapan. |
finish | BOOL | Penanda apakah pengenalan putaran ini telah berakhir. |
code | int | Hanya valid saat event EVENT_ASR_ERROR terjadi. |
onNuiAudioStateChanged: Mendengarkan status audio
SDK menggunakan callback ini untuk memberi tahu kapan harus memulai atau menghentikan perekaman.
Signature metode
| Parameter | Deskripsi |
|---|---|
STATE_OPEN | Interaksi dimulai. Anda dapat menyalakan perangkat perekaman untuk merekam audio. |
STATE_PAUSE | Interaksi berhenti. Anda dapat menghentikan perekaman. |
STATE_CLOSE | Instance SDK telah dilepaskan. Anda dapat menutup perangkat perekaman sepenuhnya. |
onNuiNeedAudioData: Mengisi data audio untuk diproses
Setelah percakapan dimulai, callback ini dipicu secara terus-menerus, dan Anda harus menyediakan data audio yang akan diproses di dalamnya. Anda dapat mengabaikan callback ini jika parameter audio_update_manually diatur ke "true".
Signature metode
| Parameter | Tipe | Deskripsi |
|---|---|---|
audioData | char * | Data audio yang diisi. |
len | int | Jumlah byte data audio yang diisi. |
onNuiAssistEventCallback: Data auxiliari dan hasil informasi
Callback ini digunakan untuk menerima event auxiliari dan data terkait dari dalam SDK.
Signature metode
| Parameter | Tipe | Deskripsi |
|---|---|---|
nuiEvent | NuiCallbackEvent | Event callback. |
info | char * | Anda tidak perlu memperhatikan parameter ini. |
info_len | int | Anda tidak perlu memperhatikan parameter ini. |
buffer | char * | Data auxiliari, seperti audio TTS yang dikembalikan oleh AI. |
len | int | Jumlah byte data auxiliari. |
onNuiLogTrackCallback: Mendengarkan log pelacakan
Callback ini digunakan untuk menerima log terperinci dari dalam SDK, yang memfasilitasi pemecahan masalah dan debugging.
NuiCallbackEvent: Tipe event
| Event | Deskripsi |
|---|---|
| EVENT_TRANSCRIBER_STARTED | Tugas berhasil dimulai. |
| EVENT_VAD_START | Event ini dipicu segera setelah tugas dimulai. Ini tidak menunjukkan bahwa awal ucapan manusia telah terdeteksi. |
| EVENT_VAD_END | Akhir ucapan manusia terdeteksi. |
| EVENT_ASR_PARTIAL_RESULT | Hasil sementara pengenalan ucapan. |
| EVENT_ASR_ERROR | Terjadi kesalahan selama percakapan suara. |
| EVENT_MIC_ERROR | Dipicu ketika tidak ada data audio yang diterima selama 2 detik berturut-turut. |
| EVENT_SENTENCE_END | Akhir kalimat terdeteksi, dan hasil pengenalan lengkap dikembalikan pada saat ini. |
| EVENT_TRANSCRIBER_COMPLETE | Percakapan suara berakhir. |
| EVENT_AUDIO_TRANSCRIPTION | Event inkremental transkrip teks dalam mode audio, yang mengembalikan segmen transkrip secara streaming. |
| EVENT_AUDIO_TRANSCRIPTION_COMPLETED | Event penyelesaian output transkrip dalam mode audio. |
| EVENT_OTHER_RESULT | Informasi event lain yang belum diklasifikasikan, seperti hasil function_call yang dikembalikan. |
| EVENT_ASR_TTS_START | AI mulai mengembalikan data TTS. |
| EVENT_ASR_TTS_DATA | Data TTS yang dikembalikan oleh AI. |
| EVENT_ASR_TTS_COMPLETE | AI selesai mengembalikan data TTS. |
| EVENT_AEC_DATA | Data audio setelah pembatalan gema AEC. |