SDK HarmonyOS pengenalan ucapan non-real-time Paraformer

Panduan pengguna: Non-real-time speech recognition

Panduan cepat

Dapatkan API key: Dapatkan dan konfigurasikan API key. Untuk keamanan, kami menyarankan untuk mengonfigurasi API key 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 contoh:
- 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 contoh terletak di DashParaformerFileTranscriberPage.ets. Ganti API key untuk mencoba fitur ini.

Langkah pemanggilan

Mode sinkron

Inisialisasi SDK.
Konfigurasikan parameter berdasarkan kebutuhan bisnis Anda.
Panggil startFileTranscriber untuk memulai tugas pengenalan dengan async_request diatur ke false.
Di antarmuka onFileTransEventCallback, dengarkan event EVENT_FILE_TRANS_RESULT untuk mendapatkan hasil pengenalan akhir.
Panggil release untuk melepaskan sumber daya SDK.

Mode asinkron

Inisialisasi SDK.
Konfigurasikan parameter berdasarkan kebutuhan bisnis Anda.
Panggil startFileTranscriber untuk memulai tugas pengenalan dengan async_request diatur ke true.
Panggil queryFileTranscriber untuk mengkueri progres atau hasil pengenalan.
Di antarmuka onFileTransEventCallback, dengarkan event EVENT_FILE_TRANS_QUERY_RESULT untuk mendapatkan hasil kueri saat ini.
Di antarmuka onFileTransEventCallback, dengarkan event EVENT_FILE_TRANS_RESULT untuk mendapatkan hasil pengenalan akhir.
Panggil release untuk melepaskan sumber daya SDK.

Parameter permintaan

Parameter koneksi dan kontrol

Teruskan string JSON ke parameter parameters dari initializeFileTrans untuk mengonfigurasi parameter berikut. Contoh: String JSON berikut adalah contoh dan tidak menyertakan semua parameter. Tambahkan parameter sesuai kebutuhan:

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

Deskripsi parameter

Parameter	Tipe	Wajib	Deskripsi
`url`	`string`	Ya	Endpoint. Nilai ini ditetapkan pada `wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription`. Ganti `{WorkspaceId}` dengan ID workspace Anda yang sebenarnya.
`apikey`	`string`	Ya	API key. Kami menyarankan untuk menggunakan API key sementara yang lebih aman dengan masa berlaku singkat untuk mengurangi risiko kebocoran key jangka panjang.
`service_mode`	`string`	Ya	Mode operasi. Untuk pengenalan ucapan non-real-time, nilai ini ditetapkan 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 mengatur `save_log` ke true saat memanggil initializeFileTrans. Dalam hal ini, Anda harus menentukan jalur file log. Jika tidak, error akan terjadi. Maksimal dua file log dipertahankan secara lokal.
`max_log_file_size`	`number`	Tidak	Mengatur ukuran maksimum file log dalam byte. Parameter ini hanya berlaku jika Anda mengatur `save_log` ke true saat memanggil initializeFileTrans. Nilai default: 104857600 (100 * 1024 * 1024 byte, atau 100 MiB).

Parameter efek pengenalan ucapan

Konfigurasikan parameter nls_config dengan menggunakan setParams, atau konfigurasikan semua parameter efek pengenalan ucapan dengan menggunakan startFileTranscriber. Contoh: String JSON berikut adalah contoh dan tidak mencakup semua parameter. Tambahkan parameter sesuai kebutuhan:

{
    "file_urls": [
        "{YOUR_AUDIO_URL}"
    ],
    "async_request": false,
    "nls_config": {
        "model":"paraformer-v2",
        "disfluency_removal_enabled":false,
        "timestamp_alignment_enabled": false
    }
}

Deskripsi parameter

Parameter	Tipe	Wajib	Deskripsi
`file_urls`	`array[string]`	Ya	Daftar URL untuk file audio atau video yang akan ditranskripsikan. HTTP dan HTTPS didukung. Satu permintaan hanya mendukung 1 URL. Jika file audio disimpan di Alibaba Cloud OSS, SDK tidak mendukung URL sementara yang menggunakan awalan `oss://`. - Format audio: `aac`, `amr`, `avi`, `flac`, `flv`, `m4a`, `mkv`, `mov`, `mp3`, `mp4`, `mpeg`, `ogg`, `opus`, `wav`, `webm`, `wma`, dan `wmv`. Karena format audio dan video memiliki banyak varian, secara teknis tidak mungkin untuk menguji semuanya. API tidak dapat menjamin bahwa setiap format dapat dikenali dengan benar. Uji file Anda untuk memverifikasi bahwa file tersebut menghasilkan hasil pengenalan yang valid. - Laju sampel audio bervariasi menurut model: - paraformer-v2 mendukung laju sampel apa pun. - paraformer-v1 mendukung laju sampel apa pun. - paraformer-8k-v2 hanya mendukung 8 kHz. - paraformer-8k-v1 hanya mendukung 8 kHz. - paraformer-mtl-v1 mendukung 16 kHz dan lebih tinggi. - Ukuran dan durasi file audio: File tidak boleh melebihi 2 GB, dan durasinya tidak boleh melebihi 12 jam. Untuk memproses file yang melebihi batas ini, praproses file tersebut untuk mengurangi ukuran file. Untuk praktik terbaik, lihat Praproses file video untuk meningkatkan efisiensi transkripsi pada pengenalan file audio.
`async_request`	`boolean`	Tidak	Menentukan apakah akan menggunakan permintaan asinkron. Nilai default: `false`. Nilai yang valid: - true: permintaan asinkron - false: permintaan sinkron.
`apikey`	`string`	Tidak	Jika `apikey` di Connection and control parameters adalah API key sementara, perbarui di sini sebelum kedaluwarsa.
`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.language_hints`	`array[string]`	Tidak	Menentukan kode bahasa untuk audio yang akan dikenali. Parameter ini hanya berlaku untuk paraformer-v2. Nilai default: `["zh", "en"]`. Kode bahasa yang didukung: - zh: Cina - en: Inggris - ja: Jepang - yue: Kanton - ko: Korea - de: Jerman - fr: Prancis - ru: Rusia.
`nls_config.disfluency_removal_enabled`	`boolean`	Tidak	Menentukan apakah akan menghapus disfluensi seperti kata pengisi. Nilai default: false. Nilai yang valid: - true: menghapus disfluensi - false: mempertahankan disfluensi.
`nls_config.timestamp_alignment_enabled`	`boolean`	Tidak	Menentukan apakah akan mengaktifkan penyelarasan stempel waktu. Nilai default: false. Nilai yang valid: - true: diaktifkan - false: dinonaktifkan.
`nls_config.special_word_filter`	`object`	Tidak	Menentukan kata sensitif yang akan diproses selama pengenalan ucapan dan mendukung metode pemrosesan yang berbeda untuk kata yang berbeda. Jika parameter ini dihilangkan, logika pemfilteran kata sensitif bawaan akan diaktifkan. Kata yang cocok dengan daftar kata sensitif Alibaba Cloud Model Studio akan diganti dengan jumlah karakter `` yang sama. Jika parameter ini ditentukan, kata yang cocok dapat diganti dengan karakter `` atau dihapus. Nilainya adalah objek JSON dalam format berikut: `{ "filter_with_signed": { "word_list": ["测试"] }, "filter_with_empty": { "word_list": ["开始", "发生"] }, "system_reserved_filter": true }`. Deskripsi bidang JSON: - `filter_with_signed`: Objek opsional yang menentukan kata yang akan diganti dengan jumlah karakter `` yang sama. Pada contoh sebelumnya, hasil untuk “帮我测试一下这段代码” adalah “帮我``一下这段代码”. Bidang `word_list`-nya adalah array string yang akan diganti. - `filter_with_empty`: Objek opsional yang menentukan kata yang akan dihapus dari hasil. Pada contoh sebelumnya, hasil untuk “比赛这就要开始了吗？” adalah “比赛这就要了吗”. Bidang `word_list`-nya adalah array string yang akan dihapus. - `system_reserved_filter`: Boolean opsional. Nilai default: true. Menentukan apakah akan mengaktifkan aturan kata sensitif bawaan. Jika diatur ke `true`, kata yang cocok dengan daftar kata sensitif Alibaba Cloud Model Studio akan diganti dengan jumlah karakter `` yang sama.
`nls_config.channel_id`	`array[integer]`	Tidak	Menentukan indeks track audio yang akan dikenali dalam file audio multitrack. Indeks dimulai dari 0. Misalnya, `[0]` mengenali track pertama, dan `[0, 1]` mengenali track pertama dan kedua. Jika diabaikan, track pertama yang diproses. Setiap track yang ditentukan ditagih secara terpisah. Misalnya, `[0, 1]` untuk satu file akan dikenakan dua tagihan terpisah. Nilai default: `[0]`.
`nls_config.diarization_enabled`	`boolean`	Tidak	Menentukan apakah akan mengaktifkan diarization pembicara. Fitur ini dinonaktifkan secara default. Fitur ini hanya berlaku untuk audio mono. Audio multikanal tidak mendukung diarization pembicara. Saat diaktifkan, hasil pengenalan berisi `speaker_id` untuk membedakan pembicara. Jika diarization pembicara diaktifkan, kami menyarankan untuk membatasi durasi audio hingga 2 jam untuk menghindari kegagalan pengenalan atau timeout. Untuk contoh `speaker_id`, lihat Deskripsi hasil pengenalan.
`nls_config.speaker_count`	`integer`	Tidak	Nilai referensi untuk jumlah pembicara. Untuk menggunakan fitur ini, atur `diarization_enabled` ke `true`. Secara default, jumlah pembicara ditentukan secara otomatis. Jika parameter ini diatur, parameter ini hanya memandu algoritme untuk menghasilkan jumlah yang ditentukan dan tidak menjamin jumlah tersebut. Rentang yang valid: `[2, 100]`. Minimumnya adalah 2 karena fitur ini membedakan beberapa pembicara.
`nls_config.vocabulary_id`	`string`	Tidak	ID kosakata hotword, yang meningkatkan akurasi pengenalan kata-kata tertentu. Parameter ini berlaku untuk model v2 dan yang lebih baru. Untuk informasi selengkapnya, lihat Hotword kustom.
`nls_config.resources`	`array[object]`	Tidak	Konfigurasi sumber daya hotword 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`: `string` yang menentukan ID hotword. - `resource_type`: `string` yang ditetapkan pada `asr_phrase`. Contoh: `{ "nls_config": { "resources": [ { "resource_id": "xxxxxxxxxxxx", "resource_type": "asr_phrase" } ] } }`. Untuk informasi selengkapnya, lihat Membuat dan mengelola hotword untuk pengenalan ucapan Paraformer.

Antarmuka utama

NativeNui

initializeFileTrans

Menginisialisasi instance SDK transkripsi ucapan. Jangan menginisialisasi instance lagi sebelum Anda memanggil release.

Tidak seperti pengenalan ucapan real-time, transkripsi file audio non-real-time harus menggunakan initializeFileTrans dan meneruskan callback INativeFileTransCallback alih-alih menggunakan initialize.

Antarmuka ini memblokir thread pemanggil. Panggil dari thread non-UI.

Signature metode

public initializeFileTrans(callback: INativeFileTransCallback,
                           parameters: string,
                           level: number,
                           save_log: boolean = false): number

Deskripsi parameter

Parameter	Tipe	Deskripsi
`callback`	`INativeFileTransCallback`	Implementasi antarmuka callback data dan event transkripsi file.
`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 adalah `true`, gunakan `debug_path` di Connection and control parameters untuk menentukan jalur. Anda juga dapat menggunakan `max_log_file_size` untuk mengatur ukuran file.

Nilai kembalian

setParams

Mengatur atau memperbarui hanya parameter nls_config. Jika semua parameter disediakan di startFileTranscriber, Anda tidak perlu memanggil metode ini.

Signature metode

public setParams(params: string): number

Deskripsi parameter

Parameter	Tipe	Deskripsi
`params`	`string`	Parameter `nls_config` dalam Parameter efek pengenalan ucapan. Parameter di luar `nls_config` tidak dapat diatur dengan menggunakan metode ini. Contoh: `{ "nls_config": { "model":"paraformer-v2", "disfluency_removal_enabled":false, "timestamp_alignment_enabled": false } }`

Nilai kembalian

startFileTranscriber

Memulai pengenalan.

Signature metode

public startFileTranscriber(params: string, task_id: ArrayBuffer): number

Deskripsi parameter

Parameter	Tipe	Deskripsi
`params`	`string`	Parameter efek pengenalan ucapan. Contoh: `{ "file_urls": [ "{YOUR_AUDIO_URL}" ], "async_request": false, "nls_config": { "model":"paraformer-v2", "disfluency_removal_enabled":false, "timestamp_alignment_enabled": false } }`
`task_id`	`ArrayBuffer`	Buffer ID tugas. SDK menulis string ID tugas acak yang dihasilkan secara internal ke buffer ini. Buffer harus memiliki panjang minimal 33 byte. Contoh menggunakan `new ArrayBuffer(64)`. Setelah pemanggilan berhasil, dekode buffer untuk mendapatkan `task_id` tugas.

Nilai kembalian

queryFileTranscriber

Mengkueri status dan hasil saat ini dari tugas asinkron. Setelah pemanggilan berhasil, hasil dikembalikan oleh event EVENT_FILE_TRANS_QUERY_RESULT di callback onFileTransEventCallback.

Signature metode

public queryFileTranscriber(task_id: string): number

Deskripsi parameter

Parameter	Tipe	Deskripsi
`task_id`	`string`	ID tugas yang akan dikueri, diperoleh dari buffer yang ditulis oleh `startFileTranscriber`.

Nilai kembalian

cancelFileTranscriber

Segera membatalkan tugas saat ini.

Signature metode

public cancelFileTranscriber(task_id: string): number

Deskripsi parameter

Parameter	Tipe	Deskripsi
`task_id`	`string`	ID tugas yang akan dibatalkan.

Nilai kembalian

release

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

Signature metode

public release(): number

Nilai kembalian

GetVersion

Mendapatkan informasi versi SDK saat ini.

Signature metode

public GetVersion(): string

Nilai kembalian

Informasi versi SDK saat ini.

INativeFileTransCallback

Mendefinisikan callback untuk event transkripsi file dan hasil pengenalan.

onFileTransEventCallback

Mendengarkan event transkripsi file dan mendapatkan hasil pengenalan ucapan.

Signature metode

onFileTransEventCallback: (event: Constants.NuiEvent, resultCode: number, finish: number,
                           asrResult: AsrResult, taskId: string) => void;

Deskripsi parameter

Parameter	Tipe	Deskripsi
`event`	`Constants.NuiEvent`	Event callback.
`resultCode`	`number`	Hanya valid saat event `EVENT_ASR_ERROR` terjadi.
`finish`	`number`	Menunjukkan apakah tugas telah berakhir.
`asrResult`	`AsrResult`	Hasil pengenalan ucapan.
`taskId`	`string`	ID tugas.

Constants.NuiEvent

Tipe event HarmonyOS SDK didefinisikan oleh enumerasi Constants.NuiEvent. Event berikut berlaku untuk transkripsi file audio:

Event	Deskripsi
`EVENT_FILE_TRANS_CONNECTED`	Layanan terhubung.
`EVENT_FILE_TRANS_UPLOADED`	File audio yang akan dikenali telah diunggah.
`EVENT_FILE_TRANS_QUERY_RESULT`	Hasil kueri tugas.
`EVENT_FILE_TRANS_RESULT`	Hasil pengenalan akhir.
`EVENT_ASR_ERROR`	Terjadi error selama pengenalan ucapan.

Tipe tambahan

Constants.LogLevel

Nilai enumerasi untuk parameter level adalah sebagai berikut:

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

Unduh hasil

Hasil pengenalan ucapan non-real-time dihasilkan secara asinkron. Respons yang dikembalikan oleh event EVENT_FILE_TRANS_RESULT berisi transcription_url. Unduh teks pengenalan dalam format JSON dari URL ini. URL ini memiliki masa berlaku. Unduh hasilnya segera.

​Panduan cepat

​Langkah pemanggilan

​Mode sinkron

​Mode asinkron

​Parameter permintaan

​Parameter koneksi dan kontrol

​Parameter efek pengenalan ucapan

​Antarmuka utama

​NativeNui

​initializeFileTrans

​setParams

​startFileTranscriber

​queryFileTranscriber

​cancelFileTranscriber

​release

​GetVersion

​INativeFileTransCallback

​onFileTransEventCallback

​Constants.NuiEvent

​Tipe tambahan

​Constants.LogLevel

​Unduh hasil