Topik ini menjelaskan parameter dan antarmuka Java SDK untuk pengenalan ucapan real-time Qwen-Audio-ASR-Message.
Prasyarat
Mulai cepat
Kelas Recognition menyediakan antarmuka untuk panggilan sinkron maupun panggilan streaming dua arah. Pilih pendekatan yang sesuai dengan kebutuhan Anda:
- Panggilan sinkron: mengenali file lokal dan mengembalikan hasil lengkap sekaligus. Paling cocok untuk memproses audio yang telah direkam sebelumnya.
- Panggilan streaming dua arah: mengenali aliran audio secara langsung dan mengembalikan hasil secara real time. Aliran audio dapat berasal dari perangkat eksternal seperti mikrofon atau dibaca dari file lokal. Paling cocok untuk skenario yang memerlukan umpan balik segera.
- Panggilan sinkron
- Panggilan streaming dua arah: berbasis callback
- Panggilan streaming dua arah: berbasis Flowable
Kirim satu tugas pengenalan ucapan real-time dan dapatkan hasil pengenalan secara sinkron dengan memasukkan file lokal. Panggilan ini akan memblokir hingga hasil dikembalikan.Buat instans Kelas Recognition, lalu panggil metode
call untuk mengikat parameter permintaan dan file yang akan dikenali. Metode ini melakukan pengenalan dan mengembalikan hasil akhir.Panggilan konkurensi tinggi
SDK Java DashScope menggunakan pooling koneksi OkHttp3 untuk mengurangi overhead pembentukan koneksi berulang. Untuk detailnya, lihat Praktik terbaik konkurensi tinggi.
Parameter permintaan
Gunakan metode berantai RecognitionParam untuk mengonfigurasi model, laju sampel, format audio, dan parameter lainnya. Masukkan objek parameter yang telah dikonfigurasi ke metode call/streamCall dari Kelas Recognition.
| Parameter | Tipe | Wajib | Deskripsi |
|---|---|---|---|
model | String | Ya | Nama model. |
sampleRate | Integer | Ya | Laju sampel dalam Hz. Hanya 16000 yang didukung. |
format | String | Ya | Format audio.Nilai valid:
|
keep_dialect | boolean | Tidak | Default: false, yang mentranskripsikan dialek menjadi bahasa Mandarin standar. Tetapkan ke true untuk mempertahankan ungkapan dialek. Tetapkan dengan .parameter("keep_dialect", value). |
vad_model | String | Tidak | Model VAD: near_meeting_16k (jarak dekat) atau far_field_meeting_16k (jarak jauh, default). Tetapkan dengan .parameter("vad_model", value). |
disfluency_removal_enabled | boolean | Tidak | Menentukan apakah kata pengisi difilter dan teks keluaran dirapikan. Default: false. Tetapkan ke true untuk mengaktifkan. Tetapkan dengan .parameter("disfluency_removal_enabled", value). |
intermediate_result_enabled | boolean | Tidak | Menentukan apakah hasil streaming sementara dikembalikan. Default: false. Tetapkan ke true untuk menerimanya. Tetapkan dengan .parameter("intermediate_result_enabled", value). |
vocabularyId | String | Tidak | ID daftar kata panas yang telah dikompilasi sebelumnya.Hasilkan ID ini terlebih dahulu dengan memanggil API pembuatan daftar kata panas. Masukkan ID ini selama pengenalan untuk menggunakan kata-kata panas dalam daftar tersebut.Cocok untuk skenario di mana kosakata diketahui dan relatif stabil, serta Anda perlu menggunakan kembali daftar kata yang sama di berbagai permintaan.Untuk detail penggunaan, lihat Kata panas yang telah dikompilasi. |
vocabulary | Map<String, Integer> | Tidak | Kata panas instan.Diberikan sebagai pasangan kunci-nilai, di mana kunci adalah teks kata panas (string) dan nilai adalah bobot kata panas (integer). Tidak perlu membuat daftar kata panas terlebih dahulu. Bobot berkisar antara [1, 5] atau diatur ke 50: nilai dalam [1, 5] membuat model lebih cenderung mengeluarkan kata tersebut seiring peningkatan nilainya; nilai 50 menunjukkan kata panas super, yang sangat meningkatkan recall, tetapi jumlah kata panas super tidak boleh melebihi 50.Cocok untuk optimasi kata panas sementara pada tingkat sesi.Jika dikonfigurasi bersama kata panas yang telah dikompilasi, hanya kata panas instan yang berlaku. Untuk detail penggunaan, lihat Kata panas instan.Atur vocabulary melalui metode parameter atau metode parameters dari instans RecognitionParam: |
max_sentence_silence | Integer | Tidak | Ambang keheningan VAD untuk segmentasi, dalam milidetik. Kalimat dianggap selesai jika keheningan setelah ucapan melebihi ambang ini. Default: 1300. Rentang valid: [200, 6000]. |
heartbeat | boolean | Tidak | Apakah paket heartbeat diaktifkan.Nilai default: false.
Untuk menggunakan bidang ini, versi SDK harus 2.19.1 atau lebih baru. heartbeat melalui metode parameter atau metode parameters dari instans RecognitionParam: |
speech_noise_threshold | float | Tidak | Ambang batas untuk membedakan ucapan dari kebisingan, digunakan untuk menyesuaikan sensitivitas Voice Activity Detection (VAD).Nilai valid: [-1.0, 1.0].Deskripsi nilai:
speech_noise_threshold melalui metode parameter atau metode parameters dari instans RecognitionParam: |
input | Map<String, Object> | Tidak | Objek input yang memasukkan konteks percakapan. Konteks membantu pengenalan dan meningkatkan akurasi pengenalan istilah khusus. Untuk penggunaan, lihat Mulai cepat.Map harus berisi kunci context yang nilainya adalah array pesan bertipe List<Map<String, Object>>. Setiap pesan berisi bidang berikut:
Untuk menggunakan bidang ini, versi SDK harus 2.22.23 atau lebih baru. input melalui metode input dari instans RecognitionParam: |
apiKey | String | Tidak | Kunci API Anda. |
Antarmuka utama
Kelas Recognition
Impor Recognition dengan import com.alibaba.dashscope.audio.asr.recognition.Recognition;. Antarmuka utamanya sebagai berikut:
| Antarmuka/Metode | Parameter | Nilai kembali | Deskripsi |
|---|---|---|---|
| Tidak ada | Pengenalan real-time streaming berbasis callback. Metode ini tidak memblokir thread saat ini. | |
| Hasil pengenalan. | Pengenalan non-streaming file lokal. Metode ini memblokir thread saat ini hingga seluruh file audio dibaca. File harus dapat dibaca. | |
| Flowable<RecognitionResult> | Pengenalan real-time streaming berbasis Flowable. | |
| Tidak ada | Mengirim audio. Pertahankan ukuran setiap chunk audio yang dikirim dalam batas wajar. Ukuran chunk yang direkomendasikan berisi sekitar 100 ms audio dan berukuran 1 KB hingga 16 KB.Hasil pengenalan dikirim melalui metode onEvent dari Antarmuka callback (ResultCallback). | |
| Tidak ada | Tidak ada | Menghentikan pengenalan real-time.Metode ini memblokir thread saat ini hingga callback ResultCallback memanggil onComplete atau onError. | |
| code: Kode penutupan WebSocket.reason: Alasan penutupan.Untuk panduan mengatur dua parameter ini, lihat Protokol WebSocket. | true | Setelah tugas berakhir, selalu tutup koneksi WebSocket, baik terjadi kesalahan maupun tidak, untuk menghindari kebocoran koneksi. Untuk menggunakan kembali koneksi demi efisiensi yang lebih baik, lihat Optimalkan pengenalan ucapan real-time Paraformer untuk konkurensi tinggi. | |
| Tidak ada | requestId | Mendapatkan requestId tugas saat ini. Tersedia setelah tugas baru dimulai dengan call atau streamingCall.Metode ini tersedia hanya di versi SDK 2.18.0 dan lebih baru. | |
| Tidak ada | Latensi paket pertama. | Mendapatkan latensi paket pertama, yaitu penundaan dari pengiriman paket audio pertama hingga menerima hasil pengenalan pertama. Gunakan setelah tugas selesai. Metode ini tersedia hanya di versi SDK 2.18.0 dan lebih baru. | |
| Tidak ada | Latensi paket terakhir. | Mendapatkan latensi paket terakhir, yaitu waktu dari pengiriman perintah stop hingga menerima hasil pengenalan akhir. Gunakan setelah tugas selesai.Metode ini tersedia hanya di versi SDK 2.18.0 dan lebih baru. |
Antarmuka callback (ResultCallback)
Selama panggilan streaming dua arah, server mengembalikan informasi dan data proses penting ke klien melalui callback. Implementasikan metode callback untuk menangani informasi atau data yang dikembalikan oleh server.
Implementasikan metode callback dengan memperluas kelas abstrak ResultCallback. Saat memperluas kelas ini, Anda dapat mengatur tipe generik ke RecognitionResult. RecognitionResult membungkus struktur data yang dikembalikan oleh server.
Karena Java mendukung penggunaan kembali koneksi, tidak ada onClose atau onOpen.
| Antarmuka/Metode | Parameter | Nilai kembali | Deskripsi |
|---|---|---|---|
result: Hasil pengenalan real-time (RecognitionResult) | Tidak ada | Dipanggil ketika server mengirim respons. | |
| Tidak ada | Tidak ada | Dipanggil setelah tugas selesai. | |
e: Informasi pengecualian. | Tidak ada | Dipanggil ketika terjadi pengecualian. |
Respons
Hasil pengenalan real-time (RecognitionResult)
RecognitionResult merepresentasikan hasil dari satu pengenalan real-time.
| Antarmuka/Metode | Parameter | Nilai kembali | Deskripsi |
|---|---|---|---|
| Tidak ada | requestId | Mendapatkan requestId. | |
| Tidak ada | Apakah kalimat lengkap telah terbentuk, yaitu apakah batas kalimat terdeteksi. | Menentukan apakah kalimat yang diberikan telah berakhir. | |
| Tidak ada | Informasi kalimat (Sentence) | Mendapatkan informasi kalimat, termasuk timestamp dan teks. |
Informasi kalimat (Sentence)
| Antarmuka/Metode | Parameter | Nilai kembali | Deskripsi |
|---|---|---|---|
| Tidak ada | Waktu mulai kalimat, dalam ms. | Mengembalikan waktu mulai kalimat. | |
| Tidak ada | Waktu akhir kalimat, dalam ms. | Mengembalikan waktu akhir kalimat. | |
| Tidak ada | Teks yang dikenali. | Mengembalikan teks yang dikenali. | |
| Tidak ada | Daftar objek Informasi timestamp tingkat kata (Word). | Mengembalikan informasi timestamp tingkat kata. |
Informasi timestamp tingkat kata (Word)
| Antarmuka/Metode | Parameter | Nilai kembali | Deskripsi |
|---|---|---|---|
| Tidak ada | Waktu mulai kata, dalam ms. | Mengembalikan waktu mulai kata. | |
| Tidak ada | Waktu akhir kata, dalam ms. | Mengembalikan waktu akhir kata. | |
| Tidak ada | Kata. | Mengembalikan kata yang dikenali. | |
| Tidak ada | Tanda baca. | Mengembalikan tanda baca. |
Kode kesalahan
Jika Anda mengalami kesalahan, lihat Kode kesalahan untuk troubleshooting.
Jika masalah berlanjut, bergabunglah dengan komunitas developer untuk melaporkan masalah Anda dan berikan Request ID untuk investigasi lebih lanjut.
FAQ
Fitur
T: Bagaimana cara menjaga koneksi ke server tetap aktif selama periode diam yang panjang?
Atur parameter permintaan heartbeat ke true, dan terus kirim audio diam ke server.
Audio diam adalah audio yang tidak mengandung sinyal suara dalam file atau aliran data. Anda dapat menghasilkan audio diam dengan beberapa cara, misalnya dengan menggunakan perangkat lunak pengeditan audio seperti Audacity atau Adobe Audition, atau alat command-line seperti FFmpeg.
T: Bagaimana cara mengonversi audio ke format yang didukung?
Gunakan alat FFmpeg. Untuk penggunaan lebih lanjut, lihat situs resmi FFmpeg.
T: Bagaimana cara mengenali file lokal (rekaman)?
Ada dua cara untuk mengenali file lokal:
-
Masukkan path file lokal secara langsung: pendekatan ini hanya mengembalikan hasil pengenalan lengkap setelah pengenalan selesai, sehingga tidak cocok untuk skenario yang memerlukan umpan balik segera.
Lihat Panggilan sinkron, dan masukkan path file ke metode
calldari Kelas Recognition untuk mengenali rekaman secara langsung. -
Konversi file lokal ke aliran biner untuk pengenalan: pendekatan ini mengenali file dan mengalirkan hasil secara bersamaan, yang cocok untuk skenario yang memerlukan umpan balik segera.
- Lihat Panggilan streaming dua arah: berbasis callback, dan kirim aliran biner ke server untuk pengenalan melalui metode
sendAudioFramedari Kelas Recognition. - Lihat Panggilan streaming dua arah: berbasis Flowable, dan kirim aliran biner ke server untuk pengenalan melalui metode
streamCalldari Kelas Recognition.
- Lihat Panggilan streaming dua arah: berbasis callback, dan kirim aliran biner ke server untuk pengenalan melalui metode
Troubleshooting
T: Mengapa ucapan tidak dapat dikenali (tidak ada hasil pengenalan)?
-
Periksa bahwa format audio (
format) dan laju sampel (sampleRate/sample_rate) dalam parameter permintaan benar dan memenuhi batasan parameter. Kesalahan umum meliputi:- File audio memiliki ekstensi .wav tetapi sebenarnya dalam format MP3, sedangkan parameter permintaan
formatdiatur ke mp3 (pengaturan parameter salah). - Laju sampel audio adalah 3600 Hz, tetapi parameter permintaan
sampleRate/sample_ratediatur ke 48000 (pengaturan parameter salah).
- File audio memiliki ekstensi .wav tetapi sebenarnya dalam format MP3, sedangkan parameter permintaan
- Jika tidak ada masalah yang ditemukan dari pemeriksaan di atas, konfigurasikan kata panas khusus untuk meningkatkan pengenalan istilah tertentu.