Siapkan audio, gunakan kembali koneksi, kelola konkurensi Java dan tugas asinkron, serta tangani kesalahan dalam aplikasi pengenalan ucapan.
Menyiapkan audio input
Periksa format, sample rate, kanal, dan durasi input berdasarkan spesifikasi audio model tujuan.
- Utamakan kualitas perekaman dan kurangi kebisingan serta gema. Sebelum mengaktifkan peredam bising atau AEC, bandingkan hasil pengenalan sebelum dan sesudah pemrosesan pada kumpulan audio representatif yang sama dengan transkripsi manual.
- Untuk audio telepon 8 kHz, pilih model dan sample rate yang sesuai.
- Pilih model yang mendukung bahasa dan dialek audio.
- Jika pengenalan istilah khusus kurang akurat, atur hotword atau peningkatan konteks sesuai Meningkatkan akurasi pengenalan.
Periksa dan proses audio
Periksa dan proses audio
- Memeriksa format audio
- Mengonversi encoding dan sample rate
- Memotong audio
- Mengekstrak audio dari video
Gunakan FFprobe untuk memeriksa format kontainer, codec, sample rate, dan kanal:
Pilih metode input file
Metode input file bergantung pada API. Misalnya, Qwen-Audio-ASR-Flash mendukung URL file audio dan Base64 Data URI. Encode audio lokal sebagai Base64 Data URI untuk mengirimkannya secara langsung. Untuk contoh encoding dan pemanggilan, lihat HTTP API Flash.
Saat mengirim file melalui URL, pastikan layanan pengenalan dapat mengunduh audio selama pemrosesan tugas. Periksa izin, masa berlaku URL, dan akses dari jaringan publik.
Untuk produksi, simpan file di penyimpanan stabil seperti OSS dan kirimkan URL-nya. Gunakan kembali file yang telah diunggah dalam pemrosesan batch untuk mengurangi unggahan berulang. Sebelum memakai fitur unggah file lokal SDK, periksa batas antarmuka tersebut. Mekanisme file sementara dan ketentuannya dijelaskan di Mendapatkan URL file sementara.
Mengelola tugas dan koneksi real-time
Protokol run-task / finish-task pada Qwen-Audio-ASR-Message, Qwen-Audio-ASR-Streaming, Fun-ASR-Realtime, dan Paraformer mendukung penggunaan ulang koneksi secara berurutan:
- Kirim
run-taskdengantask_idunik. Tunggutask-startedsebelum mengirim audio. - Setelah mengirim audio, kirim
finish-taskdengantask_idyang sama. - Tunggu peristiwa
task-finisheddari server untuk memastikan penyelesaian. - Mulai tugas berikutnya pada koneksi yang sama dengan
task_idbaru. Jangan jalankan beberapa tugas secara bersamaan pada satu koneksi.
Menangani koneksi idle dan gagal
- Koneksi ditutup otomatis jika tidak ada tugas baru selama sekitar 60 detik setelah penyelesaian. Buat koneksi baru setelah periode idle yang panjang.
- Setelah tugas gagal, jaringan terputus, atau terjadi kesalahan protokol, tutup koneksi lama dan buat objek baru. Invalidasikan objek pool, jangan kembalikan sebagai objek yang siap digunakan.
- Tutup pool dan koneksinya saat aplikasi keluar atau berhenti menyediakan pengenalan.
Menangani keheningan panjang dalam tugas
Jika tugas yang berjalan perlu menerima audio hening secara terus-menerus, atur heartbeat=true sesuai API dan terus kirim data hening dengan encoding yang diperlukan. Kelola koneksi idle setelah tugas selesai sesuai bagian sebelumnya. Untuk parameter model, lihat referensi berikut.
Peristiwa klien Message | Peristiwa klien Streaming | Peristiwa klien Fun-ASR | Peristiwa klien Paraformer
Mengonfigurasi konkurensi Java
Berikan satu objek Recognition secara eksklusif untuk setiap tugas yang berjalan, lalu kembalikan hanya setelah berhasil selesai. Contoh berikut mengelola objek melalui Commons Pool 2. Buat pool sekali dan gunakan kembali di antara panggilan.
Menambahkan dependensi
Selesaikan Mendapatkan API key dan Menginstal SDK terlebih dahulu. Contoh lengkap di bagian ini memerlukan DashScope Java SDK 2.18.0 atau yang lebih baru. Konfigurasi dependensi ini menggunakan DashScope Java SDK 2.23.2 dan Commons Pool 2.12.0:
- Maven
- Gradle
Membedakan kapasitas koneksi, objek, dan permintaan
SDK membaca tiga variabel lingkungan DASHSCOPE_ berikut. Atur sebelum proses dimulai. Kode contoh dalam dokumen ini membaca RECOGNITION_OBJECTPOOL_SIZE.
| Variabel lingkungan | Default | Fungsi |
|---|---|---|
DASHSCOPE_CONNECTION_POOL_SIZE | 32 | Koneksi HTTP idle yang dipertahankan klien OkHttp bersama milik SDK. |
DASHSCOPE_MAXIMUM_ASYNC_REQUESTS | 32 | Kapasitas penjadwalan konkuren untuk permintaan asinkron SDK. Permintaan di atas kapasitas menunggu jadwal. |
DASHSCOPE_MAXIMUM_ASYNC_REQUESTS_PER_HOST | 32 | Kapasitas penjadwalan permintaan asinkron per host. |
RECOGNITION_OBJECTPOOL_SIZE | 500 | Jumlah total objek pengenalan dalam contoh ini, dikendalikan oleh maxTotal Commons Pool. |
Konkurensi adalah jumlah tugas yang berjalan bersamaan; RPS adalah jumlah permintaan per detik. Atur thread pekerja dan kapasitas pool objek berdasarkan konkurensi aplikasi, lalu kontrol frekuensi mulai tugas sesuai Batas laju model.
Referensi konfigurasi Paraformer
Referensi konfigurasi Paraformer
Nilai berikut menjadi referensi perencanaan kapasitas aplikasi pengenalan real-time Paraformer. Konkurensi per server berarti jumlah tugas yang berjalan bersamaan. Server hanya menjalankan aplikasi pengenalan tersebut.
- Untuk kapasitas koneksi HTTP idle, mulai dari setidaknya dua kali konkurensi puncak, lalu sesuaikan.
- Awalnya, samakan kapasitas penjadwalan asinkron total dan per host dengan kapasitas koneksi tersebut, lalu sesuaikan berdasarkan antrean yang diamati.
- Untuk pool objek pengenalan, mulai dari 1,5 hingga 2 kali konkurensi puncak. Kapasitas default 500 merupakan konfigurasi aplikasi contoh.
| Server Alibaba Cloud | Referensi konkurensi tugas | Kapasitas pool pengenalan | Kapasitas koneksi HTTP idle |
|---|---|---|---|
| 4 vCPU, 8 GiB | 100 | 500 | 2000 |
| 8 vCPU, 16 GiB | 200 | 500 | 2000 |
| 16 vCPU, 32 GiB | 400 | 500 | 2000 |
Pengaturan ini berlaku untuk server khusus aplikasi pengenalan real-time Paraformer. Sesuaikan kapasitas dengan laju pengiriman audio, sumber daya klien, dan beban aplikasi. Untuk batas API model, lihat Batas laju.
Menerapkan pool objek pengenalan
Gunakan siklus hidup berikut. Saat maxTotal tercapai dan tidak ada objek idle, borrowObject pada contoh ini menunggu objek dikembalikan. Objek dibuat sesuai kebutuhan, dan koneksi WebSocket dibentuk saat permintaan pengenalan dimulai.
- Pinjam objek
Recognition, mulai pengenalan, dan kirim audio. - Kirim perintah akhir dan tunggu konfirmasi. Untuk panggilan asinkron, periksa juga callback kesalahan.
- Setelah berhasil, panggil
returnObjectagar objek dapat digunakan kembali. - Saat gagal atau terhenti, panggil
invalidateObject.destroyObjectpada factory akan menutup koneksi. - Setelah semua tugas selesai, tutup pool untuk melepas koneksi yang dimiliki objek idle.
RecognitionPoolExample.java. Siapkan asr-example.pcm berisi PCM mono, 16 kHz, 16-bit, atur DASHSCOPE_API_KEY, lalu ganti workspace dan alamat dengan konfigurasi region tujuan (lihat Endpoint). Contoh ini memakai tiga thread pekerja untuk memproses sembilan tugas.
Melakukan pemanasan dan mengukur latensi
Lakukan pemanasan dengan mengirim permintaan pengenalan yang sebenarnya untuk membentuk koneksi WebSocket yang dapat digunakan kembali oleh tugas berikutnya.
- Sebelum pengukuran, kirim permintaan pada tingkat konkurensi produksi. Satu hingga dua menit dapat menjadi acuan awal, lalu sesuaikan dengan beban.
- Pastikan koneksi yang dapat dipakai kembali sudah ada sebelum mengukur kondisi stabil. Pisahkan data cold start dari operasi stabil.
- Koneksi dapat ditutup saat aplikasi idle dan perlu dibuat lagi. Lakukan pemanasan ulang bila diperlukan sebelum pengukuran baru.
Mengelola pekerjaan transkripsi asinkron
Untuk transkripsi batch dengan konkurensi tinggi, utamakan callback penyelesaian tugas agar permintaan polling berkurang. Untuk konfigurasi callback dan format peristiwa, lihat Mengonfigurasi callback tugas asinkron.
Saat menerima notifikasi penyelesaian, gunakan data.task_id untuk mengidentifikasi tugas bisnis dan periksa data.task_status. Jika tugas berhasil tetapi notifikasi tidak memuat hasil yang diperlukan, kueri hasil melalui API HTTP model terkait, lalu unduh dan simpan file transkripsi.
Kontrol laju pengiriman, kueri, dan unggah
- Pengiriman tugas: Kontrol frekuensi pengiriman sesuai Batas laju model tujuan.
- Kueri status: API kueri memiliki batas default 20 QPS, yang dapat dinaikkan hingga 100 QPS (hubungi account manager Alibaba Cloud untuk meminta peningkatan), per akun utama Alibaba Cloud, termasuk pengguna RAM-nya. Untuk polling, mulai dengan interval 2 hingga 5 detik dan sesuaikan dengan jumlah tugas agar total laju kueri tetap dalam batas. Untuk kueri, kueri batch, dan pembatalan tugas, lihat Mengelola tugas asinkron.
- Unggah file sementara: API kredensial unggah file dibatasi hingga 100 QPS per akun utama Alibaba Cloud dan model. Batas ini tidak dapat dinaikkan. Gunakan penyimpanan stabil seperti OSS untuk produksi dan beban dengan konkurensi tinggi. Untuk prosedur dan batas unggah sementara, lihat Mendapatkan URL file sementara.
Segera menyimpan hasil pengenalan
Segera unduh dan simpan file hasil setelah tugas berhasil. Misalnya, transcription_url pada HTTP API Qwen-Audio-ASR-Filetrans berlaku selama 24 jam. Unduh dan simpan hasil secara permanen sebelum URL kedaluwarsa.
- Jika respons berisi array
results, periksa setiapsubtask_statussebelum mengunduh JSON transkripsi untuk file yang berhasil. Simpan stempel waktu, informasi pembicara, dan bidang lain yang diperlukan aplikasi. - Simpan pemetaan tugas ke file dan status akhir. Jika unduhan gagal, pertahankan catatan tugas dan coba kembali selama URL masih berlaku.
Menangani kesalahan dan percobaan ulang
Tentukan apakah perlu mencoba kembali berdasarkan jenis kesalahan. Catat ID permintaan, ID tugas, model, region, dan tahap kegagalan untuk membedakan masalah input atau izin dari kegagalan layanan sementara.
| Masalah | Tindakan |
|---|---|
| Kesalahan file input atau parameter | Periksa URL, encoding, sample rate, channel, dan rentang parameter. Perbaiki sebelum mengirim ulang. |
| Kesalahan autentikasi atau endpoint | Periksa API key, workspace, dan region endpoint, lalu perbaiki sesuai pesan kesalahan. |
| Pembatasan laju | Kurangi frekuensi permintaan atau awal tugas, dan ikuti Batas laju. Hindari loop percobaan ulang langsung. |
| Timeout jaringan, gangguan, atau kesalahan server sementara (5xx) | Untuk kegagalan kueri atau unduhan, gunakan retry dengan backoff serta batas jumlah percobaan dan total waktu tunggu. Setelah pengiriman asinkron mengalami timeout, kueri status tugas jika task_id telah diterima. Jika belum, tentukan pengiriman ulang sesuai toleransi aplikasi terhadap pemrosesan dan biaya duplikat. |
| Kegagalan tugas asinkron atau pemrosesan file | Simpan kesalahan tingkat tugas dan file, identifikasi penyebabnya, lalu tentukan apakah input harus diperbaiki atau dikirim ulang. |
Dokumentasi terkait
- Integrasi dasar: Pengenalan ucapan real-time dan Pengenalan ucapan non-real-time.
- Kualitas pengenalan: Meningkatkan akurasi pengenalan.
- Tugas asinkron: Mengonfigurasi callback tugas asinkron dan Mengelola tugas asinkron.