Pelajari parameter, antarmuka, callback, dan penggunaan SDK HarmonyOS untuk Qwen-Audio-ASR-Streaming.
Mulai cepat
- Dapatkan API key. Jangan tanamkan API key jangka panjang dalam kode aplikasi klien. Sebaiknya server aplikasi memperoleh API key sementara dan mengirimkannya ke klien.
-
Unduh SDK terbaru. Ekstrak paket, salin
entry/libs/neonui.harke direktorientry/libsaplikasi, lalu tambahkan dependensi keentry/oh-package.json5:Untuk integrasi HarmonyOS C++, gunakan pustaka bersama dinative/libsdan file header dinative/include. -
Deklarasikan izin jaringan dan mikrofon dalam
module.json5, lalu minta izin mikrofon saat runtime.reason_internetdanreason_microphoneadalah contoh nama sumber daya. Definisikan deskripsinya dalam sumber daya aplikasi. -
Buka proyek contoh dari paket SDK di DevEco Studio. Halaman contoh adalah
entry/src/main/ets/pages/dashscope/DashFunAsrSpeechTranscriberPage.ets. Atur API key dan jalankan proyek.
Urutan pemanggilan
- Buat instance
NativeNui(Constants.ModeType.MODE_DIALOG). - Panggil
initializeuntuk menginisialisasi SDK dan mengatur parameter koneksi serta kontrol. - Panggil
setParamsuntuk mengatur model dan parameter pengenalan. - Panggil
startDialoguntuk memulai pengenalan. - Dalam
onNuiAudioStateChanged, mulai, jeda, atau tutup perangkat perekaman sesuai status audio. - Pasok data rekaman terus-menerus dalam
onNuiNeedAudioData. Jika pengiriman aktif diaktifkan, gunakanupdateAudiosebagai gantinya. - Ambil hasil pengenalan dan status tugas dalam
onNuiEventCallback. - Panggil
stopDialogdan tungguEVENT_TRANSCRIBER_COMPLETE. - Saat pengenalan tidak lagi diperlukan, panggil
releaseuntuk melepaskan sumber daya.
Parameter permintaan
Parameter koneksi dan kontrol
Teruskan string JSON ke argumen parameters pada initialize.
| Parameter | Tipe | Wajib | Deskripsi |
|---|---|---|---|
url | string | Ya | Endpoint layanan:
{WorkspaceId} dengan ID ruang kerja Anda. |
service_mode | string | Ya | Mode operasi. Untuk pengenalan real-time, atur ke "1", yaitu Constants.ModeFullCloud. |
device_id | string | Ya | Pengidentifikasi pengguna akhir yang unik, seperti ID pengguna dalam aplikasi atau ID perangkat yang dibuat klien. Ini digunakan terutama untuk pelacakan log dan pemecahan masalah. |
apikey | string | Tidak | API key. Dapat diteruskan saat inisialisasi. Sebaiknya gunakan API key sementara pada dialog_params dari startDialog. |
audio_update_manually | string | Tidak | Mengaktifkan pengiriman audio aktif atau tidak. Default: "false". Jika "true", panggil updateAudio; jika "false", SDK menarik audio melalui onNuiNeedAudioData. Jika nilainya "true" dan SDK mendukung AEC atau VAD pada perangkat, kemampuan tersebut diaktifkan secara default. |
workspace | string | Tidak | Direktori sumber daya pada perangkat. Wajib jika audio_update_manually bernilai "true" dan pemrosesan lokal seperti AEC atau VAD diaktifkan. |
debug_path | string | Tidak | Direktori log. Wajib jika save_log bernilai true. SDK menyimpan maksimal dua file log. |
save_wav | string | Tidak | Menyimpan audio debug atau tidak. Default: "false". File disimpan di debug_path. Jika "true", atur juga debug_path dan teruskan true ke save_log pada initialize. |
save_wav_by_id | string | Tidak | Saat save_wav diaktifkan, menentukan apakah nama file audio menggunakan task_id agar mudah dicari. Default: "false". |
max_log_file_size | number | Tidak | Ukuran maksimum satu file log dalam byte. Default: 104857600 (100 MiB). Berlaku hanya jika save_log bernilai true. |
log_track_level | number | Tidak | Level filter log onNuiLogTrackCallback. Default: 2. Nilai: 0 (VERBOSE), 1 (DEBUG), 2 (INFO), 3 (WARNING), 4 (ERROR), 5 (NONE). Log dikembalikan hanya jika levelnya lebih besar dari atau sama dengan log_track_level dan level pada initialize. Dengan nilai 2 dan 3, hanya WARNING dan di atasnya yang dikembalikan. |
enable_reconnection | string | Tidak | Mengaktifkan koneksi ulang dan kelanjutan transmisi setelah gangguan jaringan. Default: "false". |
aec_params | object | Tidak | Pengaturan AEC pada perangkat. Digunakan hanya jika audio_update_manually bernilai "true". |
aec_params.enable_aec | boolean | Tidak | Mengaktifkan AEC pada perangkat atau tidak. Aktif secara default jika build SDK mendukungnya. |
aec_params.save_audio | boolean | Tidak | Menyimpan audio hasil AEC atau tidak. Aktif secara default jika save_wav diaktifkan dan debug_path diatur. |
aec_params.enable_aec_data_callback | boolean | Tidak | Mengembalikan data hasil AEC melalui peristiwa EVENT_AEC_DATA dari onNuiAssistEventCallback. Default: false. |
vad_params | object | Tidak | Pengaturan VAD pada perangkat. Digunakan hanya jika audio_update_manually bernilai "true". |
vad_params.enable_vad | boolean | Tidak | Mengaktifkan VAD pada perangkat atau tidak. Aktif secara default jika build SDK mendukungnya. |
vad_params.save_audio | boolean | Tidak | Menyimpan audio hasil VAD atau tidak. Aktif secara default jika save_wav diaktifkan dan debug_path diatur. |
audio_config | object | Tidak | Pengaturan perekaman saat SDK menarik audio. Digunakan hanya jika audio_update_manually bernilai "false". |
audio_config.mic.enable_volume_calculation | boolean | Tidak | Menghitung dan melaporkan volume atau tidak. Default: true. Nonaktifkan jika callback volume tidak diperlukan. |
audio_config.mic.volume_mode | string | Tidak | Mode penghitungan volume. Atur ke "dbfs" untuk menghitung dBFS standar dengan 20*log10(rms/32768), dengan skala penuh 0 dB. |
Parameter pengenalan
Teruskan string JSON ke argumen params pada setParams.
| Parameter | Jenis | Wajib | Deskripsi |
|---|---|---|---|
service_type | number | Ya | Jenis layanan suara. Tetapkan ke 4, yaitu Constants.kServiceTypeSpeechTranscriber. |
nls_config | object | Ya | Objek konfigurasi pengenalan. |
nls_config.model | string | Ya | Nama model. |
nls_config.sr_format | string | Ya | Format audio: pcm atau opus. Jika opus dipilih, aplikasi tetap memasok data PCM dan SDK mengenkodenya sebagai Opus. |
nls_config.sample_rate | number | Ya | Laju sampel dalam Hz. Semua laju sampel diterima, kecuali 8000 Hz saat AEC atau VAD pada perangkat diaktifkan. |
nls_config.semantic_punctuation_enabled | boolean | Tidak | Menentukan apakah segmentasi semantik diaktifkan. Default: false. true mengaktifkan segmentasi semantik dan menonaktifkan segmentasi VAD, cocok untuk transkripsi rapat yang mengutamakan akurasi segmentasi. false mengaktifkan segmentasi VAD dan menonaktifkan segmentasi semantik, cocok untuk interaksi yang mengutamakan latensi rendah. |
nls_config.max_sentence_silence | number | Tidak | Ambang keheningan VAD dalam milidetik. Ucapan dianggap selesai jika keheningan setelah ucapan melebihi ambang ini. Default: 1300. Rentang valid: [200, 6000]. Jika segmentasi semantik aktif, parameter ini tidak menentukan sentence_end, tetapi nilai yang terlalu kecil tetap dapat memengaruhi pengenalan. |
nls_config.multi_threshold_mode_enabled | boolean | Tidak | Menentukan apakah mode multiambang diaktifkan. Default: false. Mode ini mencegah segmen VAD terlalu panjang. Berlaku hanya jika semantic_punctuation_enabled bernilai false. |
nls_config.heartbeat | boolean | Tidak | Menentukan apakah paket heartbeat diaktifkan. Default: false. Jika aktif, pengiriman audio hening secara terus-menerus dapat menjaga koneksi. Jika tidak, koneksi mengalami timeout setelah beberapa waktu. Audio hening tidak memiliki sinyal yang terdengar dalam file atau aliran audio. |
nls_config.vocabulary_id | string | Tidak | ID daftar hotword prakompilasi. Buat daftar terlebih dahulu. Gunakan jika kosakata diketahui, relatif stabil, dan perlu digunakan kembali antarpermintaan. Lihat Hotword prakompilasi. |
nls_config.instant_vocabulary | object | Tidak | Hotword tingkat permintaan. Kunci berupa string hotword dan nilai berupa bobot bilangan bulat. Daftar tidak perlu dibuat sebelumnya, sehingga cocok untuk optimasi sementara per sesi. Bobot valid: [1, 5] atau 50. Dalam [1, 5], nilai lebih besar meningkatkan peluang kata dikeluarkan. Maksimal 50 super hotword berbobot 50 diperbolehkan. Jika hotword prakompilasi dan tingkat permintaan digunakan bersama, keduanya digabungkan. Jika hasil gabungan melebihi 2000 entri, 2000 dipilih secara acak. Lihat Hotword tingkat permintaan. |
nls_config.language_hints | string[] | Tidak | Bahasa audio. Tidak ada nilai default; model mendeteksi bahasa jika bidang ini dihilangkan. Maksimal empat nilai pertama digunakan. Untuk kode bahasa, lihat panduan pengenalan ucapan real-time. |
nls_config.speech_noise_threshold | number | Tidak | Ambang suara/noise VAD. Rentang valid: [-1.0, 1.0]. Mendekati -1 meningkatkan kemungkinan noise dianggap sebagai ucapan dan ditranskripsikan. Mendekati 1 meningkatkan kemungkinan ucapan dianggap sebagai noise dan difilter. Pengaturan lanjutan ini dapat sangat memengaruhi pengenalan. Uji secara menyeluruh dan sesuaikan sedikit demi sedikit, sebesar 0,1. |
nls_config.special_word_filter | object | Tidak | Pengaturan pemfilteran kata sensitif. Lihat Pemfilteran kata sensitif. |
nls_config.enable_connection_fast_check | boolean | Tidak | Menentukan apakah deteksi cepat gangguan jaringan diaktifkan. Default: false. |
APIs
NativeNui
Impor SDK:
Membuat instance
| Parameter | Jenis | Deskripsi |
|---|---|---|
mode_type | Constants.ModeType | Mode SDK: MODE_DIALOG untuk dialog atau pengenalan, MODE_TTS untuk sintesis ucapan, atau MODE_STREAM_INPUT_TTS untuk sintesis ucapan dengan input streaming. Gunakan MODE_DIALOG untuk pengenalan ucapan real-time. |
flag | string | ID instans opsional untuk membedakan log. |
initialize
| Parameter | Jenis | Deskripsi |
|---|---|---|
callback | INativeNuiCallback | Callback peristiwa dan data. |
parameters | string | String JSON berisi parameter koneksi dan kontrol. |
level | number | Level log SDK: LOG_LEVEL_VERBOSE (0), LOG_LEVEL_DEBUG (1), LOG_LEVEL_INFO (2), LOG_LEVEL_WARNING (3), LOG_LEVEL_ERROR (4), atau LOG_LEVEL_NONE (5). |
save_log | boolean | Menentukan apakah log lokal disimpan. Default: false. Jika true, tetapkan debug_path dalam parameters. Anda juga dapat menetapkan max_log_file_size. |
setParams
startDialog. params adalah string JSON berisi parameter pengenalan.
startDialog
| Parameter | Jenis | Deskripsi |
|---|---|---|
vad_mode | Constants.VadMode | Mode VAD. Gunakan Constants.VadMode.TYPE_P2T untuk pengenalan ucapan real-time. |
dialog_params | string | String JSON untuk memperbarui API key sementara yang kedaluwarsa atau memberikan konteks input melalui input_context. |
stopDialog
EVENT_TRANSCRIBER_COMPLETE diterima.
cancelDialog
dialogAction
| Parameter | Jenis | Deskripsi |
|---|---|---|
action_params | string | String JSON berisi tindakan. |
action_params.type | string | Tetapkan ke "action". |
action_params.command | string | Perintah tindakan: "context memperbarui konteks input, play_start memberi tahu AEC bahwa pemutaran audio referensi dimulai, dan play_over" memberi tahu bahwa pemutaran selesai. |
action_params.context | object[] | Konteks input saat command bernilai "context". |
updateAudio
audio_update_manually bernilai "true", kirim data rekaman secara aktif melalui metode ini alih-alih mengisi onNuiNeedAudioData.
| Parameter | Jenis | Deskripsi |
|---|---|---|
data | ArrayBuffer | Data audio yang akan dikenali. |
first_pack | boolean | Menentukan apakah ini paket audio pertama. Tetapkan true untuk paket pertama dan false untuk paket berikutnya. |
pushReferenceData
audio_update_manually bernilai "true" dan AEC pada perangkat diaktifkan, kirim audio yang diputar sebagai sinyal referensi AEC.
| Parameter | Jenis | Deskripsi |
|---|---|---|
data | ArrayBuffer | Data audio referensi. |
first_pack | boolean | Menentukan apakah ini paket audio pertama. Tetapkan true untuk paket pertama dan false untuk paket berikutnya. |
release
initialize terlebih dahulu untuk menggunakannya kembali.
GetVersion
refreshApikey
| Parameter | Jenis | Deskripsi |
|---|---|---|
apikey | string | API key yang sudah ada. |
url | string | Endpoint autentikasi opsional. Default: string kosong, yang menggunakan endpoint default. |
INativeNuiCallback
onNuiEventCallback
| Parameter | Jenis | Deskripsi |
|---|---|---|
event | Constants.NuiEvent | Peristiwa callback. |
resultCode | number | Berlaku hanya saat peristiwa EVENT_ASR_ERROR terjadi. |
arg2 | number | Reserved. |
kwsResult | KwsResult | Hasil kata pemicu. Abaikan bidang ini untuk pengenalan ucapan real-time. |
asrResult | AsrResult | Hasil pengenalan. allResponse berisi respons JSON lengkap dari server. Ambil ID tugas dari header.task_id dan teks ucapan dari payload.output.sentence.text. |
| Peristiwa | Deskripsi |
|---|---|
EVENT_TRANSCRIBER_STARTED | Tugas telah dimulai. header.task_id dalam asrResult.allResponse berisi ID tugas. Catat ID ini untuk pemecahan masalah. |
EVENT_VAD_START | Dipicu setelah tugas dimulai. Peristiwa ini tidak menunjukkan bahwa awal ucapan terdeteksi. |
EVENT_VAD_END | Akhir ucapan terdeteksi. |
EVENT_SENTENCE_START | Awal tuturan terdeteksi. |
EVENT_ASR_PARTIAL_RESULT | Hasil pengenalan sementara tersedia. |
EVENT_SENTENCE_END | Akhir tuturan terdeteksi dan hasil lengkap tuturan tersedia. |
EVENT_ASR_WARN | Peringatan nonfatal terjadi selama pengenalan, misalnya gangguan jaringan saat koneksi ulang diaktifkan. |
EVENT_ASR_ERROR | Kesalahan terjadi selama pengenalan. resultCode berisi kode kesalahan. |
EVENT_MIC_ERROR | Data audio tidak diterima selama dua detik berturut-turut. Periksa kode perekaman, izin, atau apakah aplikasi lain menggunakan perekam. |
EVENT_TRANSCRIBER_COMPLETE | Pengenalan telah selesai. |
EVENT_AEC_DATA | Data audio yang diproses AEC, dikembalikan melalui onNuiAssistEventCallback. |
onNuiAudioStateChanged
| State | Deskripsi |
|---|---|
STATE_OPEN | Interaksi dimulai. Perangkat perekam dapat dibuka. |
STATE_PAUSE | Interaksi berhenti. Perekaman dapat dihentikan. |
STATE_CLOSE | Instans SDK telah dilepas. Perangkat perekam dapat ditutup sepenuhnya. |
AudioCapturer dibuat secara asinkron. Buat instance perekam saat inisialisasi. Saat menerima STATE_CLOSE, hentikan perekaman tetapi simpan instance untuk digunakan kembali. Lepaskan dalam alur release terpadu. Ini mencegah perekam yang sedang dibuat ulang mengabaikan panggilan start langsung saat STATE_OPEN berikutnya tiba.
onNuiNeedAudioData
buffer.byteLength byte, biasanya 20 ms PCM mono 16-bit, dan kembalikan jumlah byte yang ditulis. Nilai ≤ 0 menunjukkan kesalahan atau tidak ada data.
onNuiAudioRMSChanged
audio_config.mic.volume_mode bernilai "dbfs", rentang val adalah -160 hingga 0. Implementasi callback dapat mengembalikan 0.
onNuiAssistEventCallback
| Parameter | Jenis | Deskripsi |
|---|---|---|
event | Constants.NuiEvent | Peristiwa tambahan. |
info | string | Informasi tambahan, biasanya berupa string JSON. |
infoLen | number | Panjang informasi tambahan. |
data | ArrayBuffer | Data tambahan, seperti audio yang diproses AEC. |
onNuiLogTrackCallback
log_track_level dan argumen level dari initialize.
Objek hasil
AsrResult
| Property | Jenis | Deskripsi |
|---|---|---|
finish | boolean | Menentukan apakah hasil saat ini adalah hasil akhir. |
resultCode | number | Kode status hasil. |
asrResult | string | Teks pengenalan. Untuk EVENT_ASR_ERROR, bidang ini berisi pesan kesalahan. |
allResponse | string | Respons server lengkap dalam bentuk string JSON, termasuk ID tugas dan teks tuturan. |
KwsResult
| Property | Jenis | Deskripsi |
|---|---|---|
type | Constants.WuwType | Jenis kata pemicu. Abaikan bidang ini untuk pengenalan ucapan real-time. |
kws | string | Kata pemicu. Abaikan bidang ini untuk pengenalan ucapan real-time. |
Konstanta dan enumerasi
| Nama | Deskripsi |
|---|---|
Constants.ModeType | Mode SDK: MODE_DIALOG, MODE_TTS, dan MODE_STREAM_INPUT_TTS. |
Constants.VadMode | Mode VAD. Pengenalan ucapan real-time menggunakan TYPE_P2T; pengguna memanggil stopDialog untuk mengakhiri pengenalan. |
Constants.AudioState | Status audio: STATE_OPEN, STATE_PAUSE, dan STATE_CLOSE. |
Constants.LogLevel | Level log dari LOG_LEVEL_VERBOSE (0) hingga LOG_LEVEL_NONE (5). |
Constants.NuiResultCode | Kode kesalahan SDK, seperti SUCCESS (0), ILLEGAL_PARAM (240002), NECESSARY_PARAM_LACK (240004), dan SDK_NOT_INIT (240011). |
Constants.kServiceTypeSpeechTranscriber | Nilai service_type untuk pengenalan ucapan real-time: 4. |
Constants.ModeFullCloud | Mode cloud penuh. Nilai service_mode adalah "1". |
Kode contoh
Kode berikut menunjukkan alur utama SDK. Untuk penanganan izin, antrean perekaman, dan penguraian respons yang lengkap, lihat DashFunAsrSpeechTranscriberPage.ets dalam paket SDK.
AudioCapturer dari @kit.AudioKit untuk merekam. Audio harus PCM mono 16-bit dengan laju sampel yang didukung model terpilih.