Topik ini menjelaskan parameter dan antarmuka Python SDK untuk model pengenalan ucapan real-time Qwen-Audio-ASR-Streaming.
Prasyarat
Mulai cepat
Kelas Recognition menyediakan antarmuka untuk panggilan non-streaming maupun streaming dua arah. Pilih metode panggilan yang sesuai dengan kebutuhan Anda:
- Panggilan non-streaming: Mengenali file lokal dan mengembalikan hasil lengkap dalam satu respons. Cocok untuk memproses audio yang telah direkam sebelumnya.
- Panggilan streaming dua arah: Mengenali aliran audio secara langsung dan menghasilkan hasil secara real-time. Aliran audio dapat berasal dari perangkat eksternal seperti mikrofon atau dibaca dari file lokal. Cocok untuk skenario yang memerlukan umpan balik segera.
- Panggilan non-streaming
- Panggilan streaming dua arah
Kirim satu tugas pengenalan ucapan real-time dan dapatkan hasil pengenalan secara sinkron dengan memasukkan file lokal.Buat instans dari kelas Recognition, ikat Parameter permintaan, lalu panggil
call untuk menjalankan pengenalan atau terjemahan dan mendapatkan Hasil pengenalan (RecognitionResult) akhir.Parameter permintaan
Atur parameter permintaan melalui konstruktor (init) dari kelas Recognition.
| Parameter | Tipe | Wajib | Deskripsi |
|---|---|---|---|
model | str | Ya | Nama model. |
sample_rate | int | Ya | Laju sampel dalam Hz. Semua laju sampel didukung. |
format | str | Ya | Format audio.Nilai valid:
|
keep_dialect | bool | Tidak | Hanya berlaku untuk qwen-audio-3.1-asr-flash-streaming.false, yang mentranskripsikan dialek menjadi bahasa Mandarin standar. Tetapkan ke true untuk mempertahankan ungkapan dialek. Teruskan sebagai argumen kata kunci dengan nama yang sama. |
vad_model | str | Tidak | Hanya berlaku untuk qwen-audio-3.1-asr-flash-streaming.near_meeting_16k (jarak dekat) atau far_field_meeting_16k (jarak jauh, default). Teruskan sebagai argumen kata kunci dengan nama yang sama. |
vocabulary_id | str | Tidak | ID daftar kata kunci panas yang telah dikompilasi sebelumnya.Hasilkan ID ini terlebih dahulu dengan memanggil API pembuatan daftar kata kunci panas. Masukkan ID ini selama pengenalan untuk menggunakan kata-kata 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 kunci panas yang telah dikompilasi. |
vocabulary | dict | Tidak | Kata kunci panas instan.Diteruskan sebagai pasangan kunci-nilai, di mana kunci adalah teks kata kunci (string) dan nilai adalah bobot kata kunci (integer). Tidak perlu membuat daftar kata kunci 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 kunci super panas, yang sangat meningkatkan recall, tetapi jumlah kata kunci super panas tidak boleh melebihi 50.Cocok untuk optimasi kata kunci panas sementara pada tingkat sesi.Jika dikonfigurasi bersama dengan kata kunci panas yang telah dikompilasi, hanya kata kunci panas instan yang berlaku. Untuk detail penggunaan, lihat Kata kunci panas instan.Contoh: |
semantic_punctuation_enabled | bool | Tidak | Apakah segmentasi semantik diaktifkan.Default: False.
|
max_sentence_silence | int | Tidak | Ambang batas keheningan VAD untuk segmentasi, dalam ms. Ketika keheningan setelah segmen ucapan melebihi ambang batas ini, sistem menentukan bahwa kalimat telah berakhir. Saat semantic_punctuation_enabled diatur ke true, parameter ini tidak digunakan sebagai kriteria untuk mengembalikan sentence_end, tetapi pengaturannya terlalu rendah dapat memengaruhi performa pengenalan.Nilai default: 1300.Nilai valid: [200, 6000]. |
multi_threshold_mode_enabled | bool | Tidak | Apakah mode multi-ambang batas diaktifkan. Saat diaktifkan, mencegah segmentasi VAD menghasilkan segmen yang terlalu panjang.Default: False. |
punctuation_prediction_enabled | bool | Tidak | Apakah tanda baca ditambahkan secara otomatis ke hasil pengenalan:
|
heartbeat | bool | Tidak | Apakah paket heartbeat diaktifkan.Default: False.
|
language_hints | list[str] | Tidak | Bahasa audio yang akan dikenali. Tidak ada nilai default; jika tidak diatur, 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
|
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:
|
special_word_filter | str | Tidak | Menentukan kata sensitif yang akan diproses selama pengenalan ucapan, dan mendukung pengaturan metode pemrosesan berbeda untuk kata sensitif berbeda. Untuk detailnya, lihat Penyaringan kata sensitif. |
callback | RecognitionCallback | Tidak | Antarmuka callback (RecognitionCallback). |
call atau start dari instans Recognition.
| Parameter | Tipe | Wajib | Deskripsi |
|---|---|---|---|
raw_input | dict | Tidak | Objek input yang digunakan untuk meneruskan konteks percakapan. Peningkatan konteks meningkatkan akurasi pengenalan untuk istilah spesifik domain. Untuk penggunaan, lihat Mulai cepat.Dict harus mencakup kunci context yang nilainya adalah daftar pesan (list[dict]). Setiap pesan berisi bidang berikut:
Field ini memerlukan SDK versi 1.25.23 atau lebih baru. raw_input ke metode start atau call dari instans Recognition: |
Antarmuka utama
Kelas Recognition
Impor Recognition dengan from dashscope.audio.asr import *.
| Metode anggota | Signature metode | Deskripsi |
|---|---|---|
call | Panggilan non-streaming berbasis file lokal. Metode ini memblokir thread saat ini hingga semua audio dibaca, dan memerlukan izin baca pada file.Hasil pengenalan dikembalikan sebagai objek RecognitionResult. | |
start | Memulai pengenalan ucapan.Pengenalan real-time streaming berbasis callback. Metode ini tidak memblokir thread saat ini. Gunakan bersama dengan send_audio_frame dan stop. | |
send_audio_frame | Mendorong audio. Pastikan setiap frame audio yang didorong tidak terlalu besar atau terlalu kecil: sekitar 100 ms per frame, antara 1 KB hingga 16 KB.Hasil pengenalan diperoleh melalui metode on_event dari Antarmuka callback (RecognitionCallback). | |
stop | Menghentikan pengenalan ucapan. Memblokir hingga server selesai mengenali semua audio yang diterima, lalu mengakhiri tugas. | |
get_last_request_id | Mendapatkan request_id. Tersedia setelah konstruktor dipanggil (objek dibuat). | |
get_first_package_delay | Mendapatkan delay paket pertama: latensi dari pengiriman paket audio pertama hingga menerima hasil pengenalan pertama. Gunakan setelah tugas selesai. | |
get_last_package_delay | Mendapatkan delay paket terakhir: waktu dari pengiriman perintah stop hingga menerima hasil pengenalan terakhir. Gunakan setelah tugas selesai. | |
get_response | Mendapatkan pesan terakhir. Gunakan untuk mengambil error kegagalan tugas. |
Antarmuka callback (RecognitionCallback)
Selama panggilan streaming dua arah, server mengembalikan informasi proses utama dan data ke klien melalui callback. Implementasikan metode callback untuk menangani informasi dan data yang dikembalikan oleh server.
| Metode | Parameter | Nilai kembalian | Deskripsi |
|---|---|---|---|
None | None | Dipanggil segera setelah koneksi ke server terbentuk. | |
result: Hasil pengenalan (RecognitionResult) | None | Dipanggil saat server memiliki respons. | |
None | None | Dipanggil setelah semua hasil pengenalan dikembalikan. | |
result: Hasil pengenalan (RecognitionResult) | None | Dipanggil saat terjadi error. | |
None | None | Dipanggil setelah server menutup koneksi. |
Respons
Hasil pengenalan (RecognitionResult)
RecognitionResult merepresentasikan hasil dari satu pengenalan real-time dalam panggilan streaming dua arah, atau hasil dari panggilan non-streaming.
| Metode anggota | Signature metode | Deskripsi |
|---|---|---|
get_sentence | Mendapatkan kalimat yang dikenali saat ini dan informasi timestamp-nya. Callback mengembalikan satu kalimat, sehingga metode ini mengembalikan Dict[str, Any].Untuk detailnya, lihat Kalimat (Sentence). | |
get_request_id | Mendapatkan request_id dari permintaan. | |
is_sentence_end | Menentukan apakah kalimat yang diberikan telah berakhir. Metode ini memeriksa apakah field end_time dalam sentence bernilai None: end_time yang tidak None menunjukkan bahwa kalimat telah berakhir. Panggil sebagai RecognitionResult.is_sentence_end(sentence), di mana sentence adalah dict kalimat tunggal yang dikembalikan oleh get_sentence(), bukan field boolean pada instans Sentence. |
Informasi kalimat (Sentence)
Anggota kelas Sentence adalah sebagai berikut:
| Parameter | Tipe | Deskripsi |
|---|---|---|
begin_time | int | Waktu mulai kalimat, dalam ms. |
end_time | int | Waktu akhir kalimat, dalam ms. |
text | str | Teks yang dikenali. |
words | Daftar Informasi timestamp tingkat kata (Word) | Informasi timestamp tingkat kata. |
Informasi timestamp tingkat kata (Word)
Anggota kelas Word adalah sebagai berikut:
| Parameter | Tipe | Deskripsi |
|---|---|---|
begin_time | int | Waktu mulai kata, dalam ms. |
end_time | int | Waktu akhir kata, dalam ms. |
text | str | Kata tersebut. |
punctuation | str | Tanda baca. |
Kode error
Jika Anda mengalami error, lihat Kode error untuk troubleshooting.
Jika masalah berlanjut, bergabunglah dengan komunitas developer untuk melaporkan masalah Anda dan sertakan Request ID untuk investigasi lebih lanjut.
FAQ
Fitur
T: Bagaimana cara menjaga koneksi tetap aktif selama periode diam yang panjang?
Atur parameter permintaan heartbeat ke true, dan terus kirim audio diam ke server.
Audio diam adalah konten dalam file audio atau aliran yang tidak mengandung sinyal suara. Anda dapat menghasilkan audio diam dengan beberapa cara, seperti 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 FFmpeg. Untuk penggunaan lebih lanjut, lihat situs resmi FFmpeg.
T: Bagaimana cara mengenali file lokal (rekaman)?
Ada dua cara untuk mengenali file lokal:
-
Teruskan path file lokal secara langsung: Cara ini hanya mengembalikan hasil lengkap setelah pengenalan selesai, sehingga tidak cocok untuk skenario yang memerlukan umpan balik segera.
Lihat Panggilan non-streaming, dan teruskan path file ke metode
calldari kelas Recognition untuk mengenali rekaman secara langsung. -
Konversi file lokal ke aliran biner untuk pengenalan: Cara ini mengenali file sambil mengalirkan hasil, sehingga cocok untuk skenario yang memerlukan umpan balik segera.
Lihat Panggilan streaming dua arah, dan kirim aliran biner ke server untuk pengenalan melalui metode
send_audio_framedari kelas Recognition.
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, tambahkan kata kunci panas kustom untuk meningkatkan pengenalan istilah tertentu.