SDK HarmonyOS pengenalan ucapan waktu nyata Paraformer

Alibaba Cloud Model Studio telah memperkenalkan domain khusus workspace untuk wilayah Tiongkok (Beijing). Domain ini memberikan kinerja unggul dan stabilitas lebih tinggi untuk permintaan inferensi. Kami menyarankan untuk bermigrasi dari dashscope.aliyuncs.com ke {WorkspaceId}.cn-beijing.maas.aliyuncs.com.

Ganti {WorkspaceId} dengan ID workspace aktual Anda. Domain yang ada tetap tersedia. Panduan pengguna: Untuk pengenalan model dan rekomendasi pemilihan, lihat Pengenalan ucapan waktu nyata - Fun-ASR dan Paraformer. Pengalaman online: Hanya paraformer-realtime-v2, paraformer-realtime-8k-v2, dan paraformer-realtime-v1 yang mendukung pengalaman online.

Mulai cepat

Dapatkan kunci API: Dapatkan dan konfigurasikan kunci API. Demi keamanan, kami menyarankan untuk mengonfigurasi kunci API sebagai variabel lingkungan.
Untuk memberikan akses sementara ke aplikasi atau pengguna pihak ketiga, atau untuk mengontrol operasi berisiko tinggi secara ketat seperti mengakses atau menghapus data sensitif, gunakan kunci API sementara. Kunci API sementara berlaku selama 60 detik secara default. Dapatkan yang baru setelah kedaluwarsa.
Unduh SDK dan jalankan kode sampel:
- Unduh paket SDK terbaru.
- Ekstrak paket TAR. Dapatkan SDK format HAR dari direktori neonui dan tambahkan ke dependensi proyek Anda. Untuk integrasi C++, dapatkan pustaka dinamis dan file header dari native/libs dan native/include dalam paket TAR.
- Buka proyek di DevEco Studio. Kode sampel terletak di DashParaformerSpeechTranscriberPage.ets. Ganti kunci API untuk mencoba fitur ini.

Langkah pemanggilan

Inisialisasi SDK.
Konfigurasikan parameter berdasarkan kebutuhan bisnis Anda: Gunakan parameter parameters dari initialize untuk menetapkan parameter koneksi dan kontrol, dan gunakan setParams untuk menetapkan parameter efek pengenalan ucapan.
Panggil startDialog untuk memulai pengenalan.
Dalam callback onNuiAudioStateChanged, mulailah perangkat perekaman berdasarkan status audio.
Dalam callback onNuiNeedAudioData, sediakan data audio rekaman secara terus-menerus.
Dalam callback onNuiEventCallback, dengarkan peristiwa dan peroleh hasil pengenalan ucapan.
Panggil stopDialog untuk menghentikan pengenalan, dan dengarkan peristiwa EVENT_TRANSCRIBER_COMPLETE untuk mengonfirmasi bahwa pengenalan telah berakhir.
Ketika pengenalan ucapan tidak lagi diperlukan, panggil release untuk melepaskan sumber daya SDK.

Parameter permintaan

Parameter koneksi dan kontrol

Berikan string JSON ke parameter parameters dari initialize untuk mengonfigurasi parameter berikut. Contoh: String JSON berikut adalah contoh dan tidak mencakup semua parameter. Tambahkan parameter sesuai kebutuhan:

{
    "url": "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference",
    "apikey": "st-****",
    "device_id": "my_device_id",
    "service_mode": "1"
}

Deskripsi parameter

Parameter	Tipe	Wajib	Deskripsi
`url`	`string`	Ya	Titik akhir. Nilai ini tetap `wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference`. Ganti `{WorkspaceId}` dengan ID ruang kerja aktual Anda.
`apikey`	`string`	Ya	Kunci API. Kami menyarankan untuk menggunakan kunci API sementara yang lebih aman dengan masa berlaku singkat guna mengurangi risiko kebocoran kunci jangka panjang.
`service_mode`	`string`	Ya	Mode operasi. Untuk pengenalan ucapan waktu nyata, ini ditetapkan tetap pada `"1"`.
`device_id`	`string`	Ya	String unik yang mengidentifikasi pengguna akhir. Anda dapat mengaturnya ke ID pengguna dalam aplikasi atau pengenal perangkat unik yang dihasilkan oleh klien. ID ini terutama digunakan untuk pelacakan log dan pemecahan masalah.
`debug_path`	`string`	Tidak	Jalur penyimpanan untuk file log. Parameter ini hanya berlaku jika Anda menetapkan `save_log` ke true saat memanggil initialize. Dalam hal ini, Anda harus menentukan jalur file log. Jika tidak, kesalahan akan terjadi. Maksimum dua file log dipertahankan secara lokal.
`save_wav`	`string`	Tidak	Menentukan apakah akan menyimpan file audio untuk debugging. File audio disimpan di bawah `debug_path`. Nilai default: `"false"`. Nilai yang valid: - `"true"`: ya - `"false"`: tidak. Parameter ini hanya berlaku jika Anda menetapkan `save_log` ke true saat memanggil initialize. Anda juga harus menetapkan `debug_path`.
`max_log_file_size`	`number`	Tidak	Menetapkan ukuran maksimum file log dalam byte. Parameter ini hanya berlaku jika Anda menetapkan `save_log` ke true saat memanggil initialize. Nilai default: 104857600 (100 * 1024 * 1024 byte, atau 100 MiB).
`log_track_level`	`number`	Tidak	Mengontrol tingkat pemfilteran konten log yang dikirim secara eksternal melalui callback `onNuiLogTrackCallback`. Nilai default: 2. Nilai yang valid: - 0: LOG_LEVEL_VERBOSE - 1: LOG_LEVEL_DEBUG - 2: LOG_LEVEL_INFO - 3: LOG_LEVEL_WARNING - 4: LOG_LEVEL_ERROR - 5: LOG_LEVEL_NONE (menonaktifkan fitur ini). Catatan: `log_track_level` dan `level`, yang ditetapkan melalui initialize, bersama-sama menentukan log mana yang dikirim ke callback. Tingkat log harus lebih besar dari atau sama dengan kedua `log_track_level` dan `level` untuk memicu callback. Misalnya, jika `log_track_level` adalah 2 (INFO) dan `level` adalah 3 (WARNING), hanya log pada tingkat WARNING atau lebih tinggi (nilai >=3) yang memicu callback.

Parameter efek pengenalan ucapan

Berikan string JSON ke parameter params dari setParams untuk mengonfigurasi parameter berikut. Contoh: String JSON berikut adalah contoh dan tidak mencakup semua parameter. Tambahkan parameter sesuai kebutuhan:

{
    "service_type": 4,
    "nls_config": {
        "model": "paraformer-realtime-v2",
        "sr_format": "pcm",
        "sample_rate": "16000"
    }
}

Deskripsi parameter

Parameter Level-1	Tipe	Wajib	Deskripsi
`service_type`	`int`	Ya	Jenis layanan ucapan. Untuk pengenalan ucapan waktu nyata, ini ditetapkan tetap pada `4`.
`nls_config`	`object`	Ya	Objek konfigurasi pengenalan ucapan inti, yang berisi parameter kunci untuk pemilihan model dan kontrol efek pengenalan.
`nls_config.model`	`string`	Ya	Model pengenalan ucapan.
`nls_config.sr_format`	`string`	Ya	Format audio yang akan dikenali. Format yang didukung: pcm, wav, dan opus. opus: Audio sumber harus dikodekan PCM. SDK mengkodekannya menjadi OPUS. wav/pcm: Audio harus dikodekan PCM.
`nls_config.sample_rate`	`int`	Ya	Laju sampel audio yang akan dikenali, dalam Hz. Hal ini bervariasi menurut model: - paraformer-realtime-v2 mendukung laju sampel apa pun. - paraformer-realtime-v1 hanya mendukung 16000 Hz. - paraformer-realtime-8k-v2 hanya mendukung 8000 Hz. - paraformer-realtime-8k-v1 hanya mendukung 8000 Hz.
`nls_config.disfluency_removal_enabled`	`boolean`	Tidak	Menentukan apakah akan menghapus disfluensi seperti kata pengisi. Nilai default: false.
`nls_config.language_hints`	`array[string]`	Tidak	Menentukan kode bahasa untuk audio yang akan dikenali. Jika bahasa tidak dapat ditentukan sebelumnya, hilangkan parameter ini dan model akan mendeteksi bahasa secara otomatis. Kode bahasa yang didukung: - zh: Mandarin - en: Inggris - ja: Jepang - yue: Kanton - ko: Korea - de: Jerman - fr: Prancis - ru: Rusia. Parameter ini hanya berlaku untuk model yang mendukung banyak bahasa.
`nls_config.semantic_punctuation_enabled`	`boolean`	Tidak	Menentukan mode segmentasi kalimat. Nilai default: false. Nilai yang valid: - true: Mengaktifkan segmentasi semantik dan menonaktifkan segmentasi VAD. - false: Mengaktifkan segmentasi VAD dan menonaktifkan segmentasi semantik. Segmentasi semantik lebih akurat dan cocok untuk transkripsi rapat. Segmentasi VAD (Voice Activity Detection) memiliki latensi lebih rendah dan cocok untuk interaksi waktu nyata. Parameter ini hanya berlaku untuk model v2 dan yang lebih baru.
`nls_config.max_sentence_silence`	`int`	Tidak	Ambang batas keheningan untuk segmentasi kalimat VAD (Voice Activity Detection), dalam milidetik. Nilai default: 800. Rentang yang valid: `[200, 6000]`. Ketika keheningan setelah sebuah segmen melebihi ambang batas ini, sistem menentukan bahwa kalimat telah berakhir. Parameter ini hanya berlaku ketika `semantic_punctuation_enabled` bernilai false dan modelnya adalah v2 atau lebih baru.
`nls_config.multi_threshold_mode_enabled`	`boolean`	Tidak	Menentukan apakah akan mengaktifkan mode pencegahan segmen terlalu panjang. Mode ini mencegah segmen VAD menjadi terlalu panjang. Nilai default: false (dinonaktifkan). Nilai yang valid: - true: mengaktifkan mode - false: menonaktifkan mode. Parameter ini hanya berlaku ketika `semantic_punctuation_enabled` bernilai false dan modelnya adalah v2 atau lebih baru.
`nls_config.punctuation_prediction_enabled`	`boolean`	Tidak	Menentukan apakah akan menambahkan tanda baca secara otomatis ke hasil pengenalan. Nilai default: true. Nilai yang valid: - true: ya - false: tidak. Parameter ini hanya berlaku untuk model v2 dan yang lebih baru.
`nls_config.heartbeat`	`boolean`	Tidak	Menentukan apakah akan mempertahankan koneksi persisten ke server. Nilai default: false. Nilai yang valid: - true: Koneksi tetap aktif sementara audio hening dikirimkan secara terus-menerus. - false: Meskipun audio hening dikirimkan secara terus-menerus, koneksi akan habis waktunya setelah periode tertentu. Waktu habis adalah default sisi server dan tidak dapat dikonfigurasi pada klien. Parameter ini hanya berlaku untuk model v2 dan yang lebih baru.
`nls_config.inverse_text_normalization_enabled`	`boolean`	Tidak	Menentukan apakah akan mengaktifkan normalisasi teks invers (ITN). Saat diaktifkan, angka Tiongkok dikonversi menjadi angka Arab. Nilai default: true (diaktifkan). Nilai yang valid: - true: diaktifkan - false: dinonaktifkan. Parameter ini hanya berlaku untuk model v2 dan yang lebih baru.
`nls_config.vocabulary_id`	`string`	Tidak	ID kosakata kata panas, yang meningkatkan akurasi pengenalan kata-kata tertentu. Parameter ini berlaku untuk model v2 dan yang lebih baru. Untuk informasi selengkapnya, lihat Kata panas kustom.
`nls_config.resources`	`array[object]`	Tidak	Konfigurasi sumber daya kata panas untuk model v1. Ini menyediakan fungsi yang sama dengan `vocabulary_id` tetapi menggunakan metode konfigurasi yang berbeda. `resources` adalah array objek. Setiap objek berisi `resource_id` dan `resource_type`: - `resource_id`: Sebuah `string` yang menentukan ID kata panas. - `resource_type`: Sebuah `string` yang ditetapkan tetap pada `asr_phrase`. Contoh: `{ "nls_config": { "resources": [ { "resource_id": "xxxxxxxxxxxx", "resource_type": "asr_phrase" } ] } }`. Untuk informasi selengkapnya, lihat Membuat dan mengelola kata panas untuk pengenalan ucapan Paraformer.

Antarmuka utama

NativeNui

initialize

Menginisialisasi instance SDK pengenalan ucapan. Jangan menginisialisasi instance lagi sebelum Anda memanggil release. Antarmuka ini memblokir thread pemanggil. Panggil dari thread non-UI.

Tanda tangan metode

public initialize(callback: INativeNuiCallback,
                  parameters: string,
                  level: number,
                  save_log: boolean = false): number

Deskripsi parameter

Parameter	Tipe	Deskripsi
`callback`	`INativeNuiCallback`	Implementasi antarmuka callback peristiwa dan data.
`parameters`	`string`	String JSON yang berisi parameter autentikasi, koneksi, dan debugging. Lihat Parameter koneksi dan kontrol.
`level`	`number`	Mengontrol level log SDK. Nilai yang valid didefinisikan oleh enumerasi Constants.LogLevel.
`save_log`	`boolean`	Menentukan apakah akan menyimpan log lokal. Jika parameter ini bernilai `true`, gunakan `debug_path` dalam Parameter koneksi dan kontrol untuk menentukan jalur. Anda juga dapat menggunakan `max_log_file_size` untuk mengatur ukuran file.

Nilai kembalian

setParams

Menetapkan parameter efek pengenalan ucapan dalam format JSON. Panggil antarmuka ini sebelum startDialog.

Tanda tangan metode

public setParams(params: string): number

Deskripsi parameter

Parameter	Tipe	Deskripsi
`params`	`string`	Parameter efek pengenalan ucapan.

Nilai kembalian

startDialog

Memulai pengenalan.

Tanda tangan metode

public startDialog(vad_mode: Constants.VadMode, dialog_params: string): number

Deskripsi parameter

Parameter	Tipe	Deskripsi
`vad_mode`	`Constants.VadMode`	Mode VAD. Ini ditetapkan tetap pada `Constants.VadMode.TYPE_P2T`.
`dialog_params`	`string`	Jika kunci API sementara yang ditentukan oleh `apikey` dalam Parameter koneksi dan kontrol telah kedaluwarsa, perbarui di sini. Nilainya dalam format JSON: `typescript { "apikey": "st-****" }`

Nilai kembalian

stopDialog

Menghentikan pengenalan. Setelah Anda memanggil antarmuka ini, server mengembalikan hasil pengenalan akhir dan mengakhiri tugas.

Tanda tangan metode

public stopDialog(): number

Nilai kembalian

cancelDialog

Segera menghentikan pengenalan tanpa menunggu server mengembalikan hasil pengenalan akhir.

Tanda tangan metode

public cancelDialog(): number

Nilai kembalian

release

Melepaskan semua sumber daya internal SDK. Setelah metode ini dipanggil, instance SDK menjadi tidak tersedia. Untuk menggunakannya kembali, panggil initialize untuk menginisialisasinya ulang.

Tanda tangan metode

public release(): number

Nilai kembalian

GetVersion

Mendapatkan informasi versi SDK saat ini.

Tanda tangan metode

public GetVersion(): string

Nilai kembalian

Informasi versi SDK saat ini.

INativeNuiCallback

Mendengarkan peristiwa, status audio, perubahan volume, dan log selama pengenalan ucapan waktu nyata.

onNuiEventCallback

Mendengarkan peristiwa pengenalan dan memperoleh hasil pengenalan ucapan.

Tanda tangan metode

onNuiEventCallback: (event: Constants.NuiEvent, resultCode: number, arg2: number,
                    kwsResult: KwsResult, asrResult: AsrResult) => void;

Deskripsi parameter

Parameter	Tipe	Deskripsi
`event`	`Constants.NuiEvent`	Peristiwa callback.
`resultCode`	`number`	Hanya valid saat event `EVENT_ASR_ERROR` terjadi.
`asrResult`	`AsrResult`	Hasil pengenalan ucapan.
`kwsResult`	`KwsResult`	Fitur bangun suara. Anda tidak perlu menggunakan parameter ini.
`arg2`	`number`	Parameter yang dipesan.

onNuiAudioStateChanged

SDK menggunakan callback ini untuk menunjukkan kapan perekaman harus dimulai atau dihentikan.

Tanda tangan metode

onNuiAudioStateChanged: (state: Constants.AudioState) => void

Deskripsi AudioState

Status	Deskripsi
`STATE_OPEN`	Interaksi dimulai. Anda dapat memulai perangkat perekaman.
`STATE_PAUSE`	Interaksi dijeda. Anda dapat menjeda perekaman.
`STATE_CLOSE`	Interaksi berhenti. Anda dapat menghentikan perangkat perekaman sepenuhnya.

onNuiAudioRMSChanged

Memantau volume data audio yang direkam untuk tampilan UI.

Tanda tangan metode

onNuiAudioRMSChanged: (val: number) => number

Deskripsi parameter

Parameter	Tipe	Deskripsi
`val`	`number`	Volume data audio yang direkam. Rentang keluaran umumnya adalah `[-160, 0]`.

onNuiNeedAudioData

Setelah pengenalan dimulai, callback ini dipicu secara terus-menerus. Sediakan data audio yang akan dikenali di dalam callback.

Tanda tangan metode

onNuiNeedAudioData: (buffer: ArrayBuffer) => number

Deskripsi parameter

Parameter	Tipe	Deskripsi
`buffer`	`ArrayBuffer`	Data audio yang akan disediakan. SDK menggunakan `buffer.byteLength` sebagai jumlah byte yang diminta.

Nilai kembalian

Jumlah byte aktual yang disediakan. Nilai kembalian <=0 menunjukkan kesalahan atau tidak ada data.

onNuiLogTrackCallback

Callback ini menerima log internal SDK yang terperinci untuk pemecahan masalah dan debugging.

onNuiLogTrackCallback: (level: Constants.LogLevel, log: string) => void

Constants.NuiEvent

Tipe event HarmonyOS SDK didefinisikan oleh enumerasi Constants.NuiEvent. Event berikut berlaku untuk pengenalan ucapan waktu nyata:

Peristiwa	Deskripsi
`EVENT_TRANSCRIBER_STARTED`	Tugas berhasil dimulai.
`EVENT_VAD_START`	Event ini dipicu segera setelah tugas dimulai. Hal ini tidak menandakan bahwa awal ucapan telah terdeteksi.
`EVENT_VAD_END`	Akhir ucapan terdeteksi.
`EVENT_ASR_PARTIAL_RESULT`	Hasil pengenalan ucapan sementara.
`EVENT_ASR_RESULT`	Hasil pengenalan ucapan lengkap.
`EVENT_ASR_ERROR`	Terjadi kesalahan selama pengenalan ucapan.
`EVENT_MIC_ERROR`	Peristiwa ini dipicu ketika tidak ada data audio yang diterima selama 2 detik berturut-turut.
`EVENT_SENTENCE_START`	Awal kalimat terdeteksi.
`EVENT_SENTENCE_END`	Akhir kalimat terdeteksi, dan hasil pengenalan lengkap dikembalikan.
`EVENT_TRANSCRIBER_COMPLETE`	Pengenalan ucapan berakhir.

Tipe tambahan

Constants.LogLevel

Nilai enumerasi untuk parameter level adalah sebagai berikut:

Nilai	Deskripsi
`LOG_LEVEL_VERBOSE`	Log paling terperinci.
`LOG_LEVEL_DEBUG`	Log debug.
`LOG_LEVEL_INFO`	Log informasional (default).
`LOG_LEVEL_WARNING`	Log peringatan.
`LOG_LEVEL_ERROR`	Log kesalahan.
`LOG_LEVEL_NONE`	Menonaktifkan pencatatan log.

Manajemen perangkat audio

Berbeda dengan Android yang menggunakan AudioRecord, HarmonyOS menggunakan AudioCapturer dari @kit.AudioKit untuk menangkap audio. Sampel produk mengenkapsulasi logika ini dalam kelas utilitas AudioRecorder.ets, yang dapat Anda gunakan kembali secara langsung.

Pembuatan: audio.createAudioCapturer(capturerOptions) membuat capturer secara asinkron dengan laju sampel tetap sebesar 16 kHz, kedalaman bit 16, dan satu saluran (SAMPLE_RATE_16000/CHANNEL_1/SAMPLE_FORMAT_S16LE/ENCODING_TYPE_RAW).
Event data: capturer.on('readData', (buffer: ArrayBuffer) => void) memperoleh data audio yang direkam secara terus-menerus. Buffer data tersebut dalam antrean agar callback onNuiNeedAudioData dapat mengambilnya sesuai kebutuhan.
Event status: capturer.on('stateChange', (state: audio.AudioState) => void). STATE_RUNNING menandakan bahwa perekaman telah dimulai, dan STATE_STOPPED menandakan bahwa perekaman telah berhenti.
Kontrol: start() memulai, stop() menghentikan, dan release() melepaskan penangkap.

HarmonyOS membuat AudioCapturer secara asinkron. Panggil start() hanya setelah pembuatan selesai. Oleh karena itu, jangan membuat dan langsung memulai perekam saat STATE_OPEN terjadi. Buat terlebih dahulu, lalu panggil start() dalam callback STATE_OPEN. Sampel membuat perekam selama doInit dan memulainya selama onNuiAudioStateChanged. Ketika STATE_CLOSE terjadi, hentikan perekam tetapi pertahankan instans untuk digunakan kembali. Lepaskan di release.

Deklarasi izin

Nyatakan izin mikrofon di module.json5 untuk menggunakan perekaman:

{
  "requestPermissions": [
    { "name": "ohos.permission.MICROPHONE" }
  ]
}

​Mulai cepat

​Langkah pemanggilan

​Parameter permintaan

​Parameter koneksi dan kontrol

​Parameter efek pengenalan ucapan

​Antarmuka utama

​NativeNui

​initialize

​setParams

​startDialog

​stopDialog

​cancelDialog

​release

​GetVersion

​INativeNuiCallback

​onNuiEventCallback

​onNuiAudioStateChanged

​onNuiAudioRMSChanged

​onNuiNeedAudioData

​onNuiLogTrackCallback

​Constants.NuiEvent

​Tipe tambahan

​Constants.LogLevel

​Manajemen perangkat audio

​Deklarasi izin

Mulai cepat

Langkah pemanggilan

Parameter permintaan

Parameter koneksi dan kontrol

Parameter efek pengenalan ucapan

Antarmuka utama

NativeNui

initialize

setParams

startDialog

stopDialog

cancelDialog

release

GetVersion

INativeNuiCallback

onNuiEventCallback

onNuiAudioStateChanged

onNuiAudioRMSChanged

onNuiNeedAudioData

onNuiLogTrackCallback

Constants.NuiEvent

Tipe tambahan

Constants.LogLevel

Manajemen perangkat audio

Deklarasi izin