Panduan ini menjelaskan cara menggunakan SDK HarmonyOS pengenalan ucapan non-real-time Qwen-Audio-ASR-Filetrans untuk mengubah ucapan menjadi teks.
Mulai cepat
- Mendapatkan kunci API: Mendapatkan kunci API. Demi keamanan, kami menyarankan untuk mengonfigurasi kunci API sebagai variabel lingkungan.
- Unduh SDK dan jalankan kode sampel:
- Unduh paket SDK terbaru.
- Ekstrak paket TAR. Dapatkan SDK format HAR dari direktori
neonuidan tambahkan ke dependensi proyek Anda. Untuk integrasi C++, dapatkan pustaka dinamis dan file header darinative/libsdannative/includedalam paket TAR. - Buka proyek di DevEco Studio. Kode sampel terletak di
DashFunAsrFileTranscriberPage.ets. Ganti kunci API untuk mencoba fitur ini.
Langkah pemanggilan
Mode sinkron
- Inisialisasi SDK.
- Konfigurasikan parameter berdasarkan kebutuhan bisnis Anda.
- Panggil
startFileTranscriberuntuk memulai tugas pengenalan denganasync_requestdiatur kefalse. - Di antarmuka
onFileTransEventCallback, dengarkan peristiwaEVENT_FILE_TRANS_RESULTuntuk mendapatkan hasil pengenalan akhir. - Panggil
releaseuntuk melepaskan sumber daya SDK.
Mode asinkron
- Inisialisasi SDK.
- Konfigurasikan parameter berdasarkan kebutuhan bisnis Anda.
- Panggil
startFileTranscriberuntuk memulai tugas pengenalan denganasync_requestdiatur ketrue. - Panggil
queryFileTranscriberuntuk menanyakan kemajuan atau hasil pengenalan. - Di antarmuka
onFileTransEventCallback, dengarkan peristiwaEVENT_FILE_TRANS_QUERY_RESULTuntuk mendapatkan hasil kueri saat ini. - Di antarmuka
onFileTransEventCallback, dengarkan peristiwaEVENT_FILE_TRANS_RESULTuntuk mendapatkan hasil pengenalan akhir. - Panggil
releaseuntuk 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 mencakup semua parameter. Tambahkan parameter sesuai kebutuhan:
| Parameter | Tipe | Wajib | Deskripsi |
|---|---|---|---|
url | string | Ya | Titik akhir. Nilai ini tetap wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription. 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 non-real-time, nilai ini tetap "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 berlaku hanya jika Anda mengatur save_log ke true saat memanggil initializeFileTrans. Dalam hal ini, Anda harus menentukan jalur file log. Jika tidak, akan terjadi kesalahan. Maksimum dua file log dipertahankan secara lokal. |
max_log_file_size | number | Tidak | Mengatur ukuran maksimum file log dalam byte. Parameter ini berlaku hanya 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:
| Parameter | Tipe | Wajib | Deskripsi |
|---|---|---|---|
file_urls | array[string] | Ya | Daftar URL untuk file audio atau video yang akan ditranskripsi. HTTP dan HTTPS didukung. Satu permintaan hanya mendukung 1 URL. Untuk persyaratan input seperti format audio yang didukung serta batas ukuran dan durasi file, lihat Spesifikasi audio. Jika file audio disimpan di Alibaba Cloud OSS, RESTful API mendukung URL sementara dengan prefiks oss://, namun SDK tidak mendukungnya.- Jika URL publik OSS sementara tidak dapat diakses, atur header permintaan X-DashScope-OssResourceResolve ke enable. Metode ini tidak disarankan. SDK tidak mendukung pengonfigurasian header permintaan. |
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 dalam Parameter koneksi dan kontrol adalah kunci API 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 | Nama model. |
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. Untuk informasi selengkapnya, lihat Pemfilteran kata sensitif. |
nls_config.channel_id | array[integer] | Tidak | Menentukan indeks trek audio yang akan dikenali dalam file audio multitrack. Indeks dimulai dari 0. Misalnya, [0] mengenali trek pertama, dan [0, 1] mengenali trek pertama dan kedua. Jika diabaikan, trek pertama yang diproses.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 waktu habis. speaker_id, lihat Deskripsi hasil pengenalan. |
nls_config.speaker_count | integer | Tidak | Ini memberikan nilai referensi untuk jumlah pembicara. Nilai yang valid adalah bilangan bulat dari 2 hingga 100. 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. Tidak ada nilai default. |
nls_config.vocabulary_id | string | Tidak | ID daftar hotword yang telah dikompilasi sebelumnya. Buat daftar hotword terlebih dahulu dan teruskan ID-nya selama pengenalan untuk menggunakan hotword dalam daftar tersebut. Ini cocok ketika kosakata sudah diketahui dan relatif stabil serta kosakata yang sama perlu digunakan kembali di berbagai permintaan. Untuk informasi selengkapnya, lihat Hotword yang telah dikompilasi sebelumnya. |
nls_config.language_hints | array[string] | Tidak | Menentukan kode bahasa untuk audio yang akan dikenali. Jika bahasa tidak dapat ditentukan sebelumnya, abaikan parameter ini dan model akan mendeteksi bahasa secara otomatis. Anda dapat menetapkan hingga 4 nilai. Jika lebih, hanya 4 nilai pertama yang berlaku.
Klik untuk melihat kode bahasa yang didukung
|
nls_config.parameters | object | Tidak | Mengonfigurasi parameter tambahan sebagai objek JSON. |
Antarmuka utama
NativeNui
initializeFileTrans
Menginisialisasi instans SDK transkripsi ucapan. Jangan menginisialisasi instans lagi sebelum Anda memanggil release.
Berbeda dengan pengenalan ucapan real-time, transkripsi file audio non-real-time harus menggunakan
initializeFileTrans dan meneruskan callback INativeFileTransCallback alih-alih menggunakan initialize.| Parameter | Tipe | Deskripsi |
|---|---|---|
callback | INativeFileTransCallback | Implementasi antarmuka callback data dan peristiwa 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 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. |
setParams
Mengatur atau memperbarui hanya parameter nls_config. Jika semua parameter disediakan dalam startFileTranscriber, Anda tidak perlu memanggil metode ini.
Tanda tangan metode
| Parameter | Tipe | Deskripsi |
|---|---|---|
params | string | Parameter nls_config dalam Parameter efek pengenalan ucapan. Parameter di luar nls_config tidak dapat diatur menggunakan metode ini. Contoh: { "nls_config": { "model":"qwen-audio-3.0-asr-flash-filetrans", "diarization_enabled": false } } |
startFileTranscriber
Memulai pengenalan.
Tanda tangan metode
| Parameter | Tipe | Deskripsi |
|---|---|---|
params | string | Parameter efek pengenalan ucapan. Contoh: { "file_urls": [ "{YOUR_AUDIO_URL}" ], "async_request": false, "nls_config": { "model":"qwen-audio-3.0-asr-flash-filetrans", "diarization_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 panggilan berhasil, dekode buffer untuk mendapatkan task_id tugas. |
queryFileTranscriber
Mengkueri status dan hasil tugas asinkron saat ini. Setelah panggilan berhasil, hasil dikembalikan oleh peristiwa EVENT_FILE_TRANS_QUERY_RESULT dalam callback onFileTransEventCallback.
Tanda tangan metode
| Parameter | Tipe | Deskripsi |
|---|---|---|
task_id | string | ID tugas yang akan dikueri, diperoleh dari buffer yang ditulis oleh startFileTranscriber. |
cancelFileTranscriber
Segera membatalkan tugas saat ini.
Tanda tangan metode
| Parameter | Tipe | Deskripsi |
|---|---|---|
task_id | string | ID tugas yang akan dibatalkan. |
release
Melepaskan semua sumber daya internal SDK. Setelah metode ini dipanggil, instans SDK menjadi tidak tersedia. Untuk menggunakannya lagi, panggil initializeFileTrans untuk menginisialisasi ulang.
Tanda tangan metode
GetVersion
Mendapatkan informasi versi SDK saat ini.
Tanda tangan metode
INativeFileTransCallback
Mendefinisikan callback untuk peristiwa transkripsi file dan hasil pengenalan.
onFileTransEventCallback
Mendengarkan peristiwa transkripsi file dan memperoleh hasil pengenalan ucapan.
Tanda tangan metode
| Parameter | Tipe | Deskripsi |
|---|---|---|
event | Constants.NuiEvent | Peristiwa 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
Jenis peristiwa HarmonyOS SDK didefinisikan oleh enumerasi Constants.NuiEvent. Peristiwa berikut berlaku untuk transkripsi file audio:
| Peristiwa | 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 kesalahan selama pengenalan ucapan. |
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. |
Mengunduh hasil
Hasil pengenalan ucapan non-real-time dihasilkan secara asinkron. Respons yang dikembalikan oleh peristiwa EVENT_FILE_TRANS_RESULT berisi transcription_url. Unduh teks pengenalan dalam format JSON dari URL ini. URL memiliki masa berlaku. Segera unduh hasilnya.