Panduan ini menjelaskan cara menggunakan SDK HarmonyOS pengenalan ucapan non-real-time Qwen-Audio-3.x-ASR-Flash-Filetrans/Fun-ASR untuk mengubah ucapan menjadi teks.
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 DashFunAsrFileTranscriberPage.ets. Ganti kunci API untuk mencoba fitur ini.
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:
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).
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:
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.
URL sementara berlaku selama 48 jam dan tidak dapat digunakan setelah kedaluwarsa. Jangan gunakan URL sementara di lingkungan produksi.
Antarmuka kredensial unggahan file dibatasi hingga 100 QPS dan tidak dapat diskalakan keluar. Jangan menggunakannya di lingkungan produksi, skenario konkurensi tinggi, atau uji beban.
Di lingkungan produksi, gunakan penyimpanan stabil seperti Alibaba Cloud OSS untuk memastikan ketersediaan file jangka panjang dan menghindari pembatasan.
- 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.
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.
Setiap trek yang ditentukan ditagih secara terpisah. Misalnya, [0, 1] untuk satu file menimbulkan 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 waktu habis.
Parameter ini berlaku hanya ketika diarization pembicara diaktifkan dengan mengatur diarization_enabled ke true.
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. Model Qwen-Audio-3.0-ASR-Flash-Filetrans mendukung hingga 4 nilai. Jika lebih dari 4 nilai ditentukan, hanya 4 pertama yang berlaku. Model Fun-ASR hanya mendukung 1 nilai. Jika beberapa nilai ditentukan, hanya nilai pertama yang berlaku. Kode bahasa yang didukung: - qwen-audio-3.0-asr-flash-filetrans, fun-asr, fun-asr-2025-11-07, fun-asr-mtl, dan fun-asr-mtl-2025-08-25: - zh: Cina - en: Inggris - ja: Jepang - ko: Korea - vi: Vietnam - th: Thai - id: Indonesia - ms: Melayu - tl: Filipina - hi: Hindi - ar: Arab - fr: Prancis - de: Jerman - es: Spanyol - pt: Portugis - ru: Rusia - it: Italia - nl: Belanda - sv: Swedia - da: Denmark - fi: Finlandia - no: Norwegia - el: Yunani - pl: Polandia - cs: Ceko - hu: Hungaria - ro: Rumania - bg: Bulgaria - hr: Kroasia - sk: Slovakia - fun-asr-2025-08-25: - zh: Cina - en: Inggris.
nls_config.parameters
object
Tidak
Mengonfigurasi parameter tambahan sebagai objek JSON.
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.
Antarmuka ini memblokir thread pemanggil. Panggil dari thread non-UI.
Tanda tangan metode
Copy
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 peristiwa transkripsi file.
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.
Mengatur atau memperbarui hanya parameter nls_config. Jika semua parameter disediakan dalam startFileTranscriber, Anda tidak perlu memanggil metode ini.
Tanda tangan metode
Copy
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 menggunakan metode ini. Contoh: { "nls_config": { "model":"qwen-audio-3.0-asr-flash-filetrans", "diarization_enabled": false } }
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.
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
Copy
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.
Melepaskan semua sumber daya internal SDK. Setelah metode ini dipanggil, instans SDK menjadi tidak tersedia. Untuk menggunakannya lagi, panggil initializeFileTrans untuk menginisialisasi ulang.
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.
