Parameter dan antarmuka Python SDK untuk pengenalan ucapan real-time Paraformer.
Prasyarat
Daftar model
| paraformer-realtime-v2 | paraformer-realtime-8k-v2 | |
|---|---|---|
| Skema penggunaan | Streaming langsung, rapat, dan skenario serupa | Pengenalan audio 8 kHz dalam skenario seperti layanan pelanggan telepon dan pesan suara |
| Laju sampel | Apa saja | 8kHz |
| Bahasa | Bahasa Tionghoa (termasuk Mandarin dan berbagai dialek), Inggris, Jepang, Korea, Jerman, Prancis, RusiaDialek Tionghoa yang didukung: Shanghainese, Wu, Minnan, Timur Laut, Gansu, Guizhou, Henan, Hubei, Hunan, Jiangxi, Ningxia, Shanxi, Shaanxi, Shandong, Sichuan, Tianjin, Yunnan, Kanton | Tionghoa |
| Prediksi tanda baca | Didukung secara default. Tidak perlu konfigurasi. | Didukung secara default. Tidak perlu konfigurasi. |
| Inverse Text Normalization (ITN) | Didukung secara default. Tidak perlu konfigurasi. | Didukung secara default. Tidak perlu konfigurasi. |
| Kosakata kustom | Lihat Kustomisasi hotword | Lihat Kustomisasi hotword |
| Tentukan bahasa pengenalan | Tentukan bahasa menggunakan parameter language_hints. | Tidak didukung |
| Pengenalan emosi | Tidak didukung |
Klik untuk melihat penggunaan Pengenalan emosi memiliki batasan berikut:
emo_tag dan emo_confidence pada informasi kalimat tunggal (Sentence). |
Mulai cepat
Sumber daya inti (client.audio.asr) menyediakan antarmuka panggilan non-streaming dan streaming dua arah. Pilih metode pemanggilan yang sesuai berdasarkan kebutuhan aktual Anda:
- Panggilan non-streaming (
recognize_file): mengenali file lokal; SDK otomatis mengirim audio secara bertahap dan menggerakkan tugas hingga selesai. Cocok untuk memproses audio yang telah direkam sebelumnya. - Panggilan streaming dua arah: dapat langsung mengenali aliran audio dan mengeluarkan hasil secara real-time. Aliran audio dapat berasal dari perangkat eksternal (seperti mikrofon) atau dibaca dari file lokal. Cocok untuk skenario yang membutuhkan umpan balik segera.
Panggilan non-streaming
Kirim satu tugas transkripsi ucapan real-time dan dapatkan hasil transkripsi secara sinkron (blocking) dengan memasukkan file lokal.
Panggil metode recognize_file dari sumber daya inti (client.audio.asr) untuk mengikat parameter permintaan dan meneruskan path file lokal, lalu iterasi event server untuk mendapatkan hasil pengenalan (RecognitionResult).
Klik untuk melihat contoh lengkap
Klik untuk melihat contoh lengkap
recognize_file menghasilkan event server (Dict[str, Any]) satu per satu: jenis event berada di event['header']['event'], teks pengenalan berada di event['payload']['output']['sentence'] (sentence_end bernilai true berarti kalimat telah selesai; begin_time / end_time adalah timestamp, words adalah timestamp per kata — bidang lainnya lihat Informasi kalimat (Sentence)). Event heartbeat dan teks kosong tetap dihasilkan, dapat diabaikan sesuai kebutuhan.Pada sesi streaming dua arah, selain events(), Anda juga dapat menggunakan results() untuk hanya iterasi frame hasil pengenalan (mengembalikan hasil pengenalan (RecognitionResult) bertipe, frame heartbeat telah difilter); lihat penjelasan metode get_sentence untuk detailnya.Panggilan streaming dua arah
Kirim satu tugas transkripsi ucapan real-time dan keluarkan hasil pengenalan real-time secara streaming dengan cara mengiterasi event.
-
Mulai pengenalan ucapan streaming
Panggil metode
recognizedari sumber daya inti (client.audio.asr) untuk membuat sesi pengenalan dan mengikat parameter permintaan; masuki kontekswith(otomatis memanggil metodestartuntuk membuat koneksi dan mengirim tugas) untuk memulai pengenalan ucapan streaming. -
Streaming
Panggil metode
send_audio_framemilik sesi dalam loop untuk mengirim aliran audio biner yang dibaca dari file lokal atau perangkat (seperti mikrofon) ke server secara bertahap. Pengiriman dan penerimaan harus berjalan konkuren: thread penerima mengiterasi event server melalui iterasi event (events()/results()), mengembalikan hasil pengenalan ke klien secara real-time. Disarankan durasi audio yang dikirim setiap kali sekitar 100 milidetik, dengan ukuran data dijaga antara 1 KB hingga 16 KB. -
Akhiri pemrosesan
Panggil metode
stopmilik sesi untuk mengakhiri pengenalan ucapan. Metode ini hanya memberi tahu server bahwa input telah selesai; thread penerima perlu terus mengonsumsievents()hingga eventtask-finisheduntuk mendapatkan hasil pengenalan terakhir beserta statistiknya. Error pada lapisan ws akan dilempar sebagai pengecualianDashScopeError, yang dapat ditangkap dengan try/except di sisi pengirim/penerima.
Klik untuk melihat contoh lengkap
Klik untuk melihat contoh lengkap
Panggilan konkuren
Dalam Python, karena adanya Global Interpreter Lock (GIL), hanya satu thread yang dapat menjalankan kode Python pada satu waktu (meskipun beberapa library berorientasi performa mungkin menghilangkan batasan ini). Jika Anda ingin memanfaatkan sumber daya komputasi komputer multi-inti secara lebih baik, kami merekomendasikan penggunaan multiprocessing atau concurrent.futures.ProcessPoolExecutor. Multithreading dapat meningkatkan latensi panggilan SDK secara signifikan dalam kondisi konkurensi tinggi.
Parameter permintaan
Parameter permintaan diatur melalui metode recognize/recognize_file dari sumber daya inti (client.audio.asr): model, format, sample_rate, vocabulary_id, disfluency_removal_enabled adalah parameter bernama; parameter lainnya (seperti language_hints, semantic_punctuation_enabled) diteruskan melalui dictionary parameters.
Parameter | Type | Default | Wajib | Deskripsi |
|---|---|---|---|---|
model | str | - | Ya | Model yang digunakan untuk pengenalan ucapan real-time. Untuk informasi lebih lanjut, lihat Daftar Model. |
sample_rate | int | - | Ya | Atur laju sampel (dalam Hz) audio yang akan dikenali. Bervariasi berdasarkan model:
|
format | str | - | Ya | Atur format audio yang akan dikenali. Format audio yang didukung: pcm, wav, mp3, opus, speex, aac, amr. opus/speex: Harus menggunakan enkapsulasi Ogg. wav: Harus dikodekan dengan PCM. amr: Hanya tipe AMR-NB yang didukung. |
vocabulary_id | str | - | Tidak | Atur ID hot word. Jika tidak diatur, hot word tidak akan berlaku. Gunakan field ini untuk mengatur ID hot word untuk model v2 dan yang lebih baru. Pada sesi pengenalan ucapan saat ini, informasi hot word yang sesuai dengan ID hot word ini akan diterapkan. Untuk penggunaan detail, lihat Hotword kustom. |
disfluency_removal_enabled | bool | False | Tidak | Atur apakah akan menyaring kata pengisi:
|
language_hints | list[str] | ["zh", "en"] | Tidak | Atur kode bahasa untuk pengenalan. Jika Anda tidak dapat menentukan bahasa sebelumnya, Anda dapat membiarkannya tidak diatur dan model akan secara otomatis mendeteksi bahasa. Kode bahasa yang saat ini didukung:
Parameter ini hanya berlaku untuk model multibahasa. Untuk informasi lebih lanjut, lihat Daftar model. |
semantic_punctuation_enabled | bool | False | Tidak | Atur apakah akan mengaktifkan segmentasi semantik. Dinonaktifkan secara default.
Segmentasi semantik memberikan akurasi lebih tinggi dan cocok untuk skenario transkripsi rapat. Segmentasi VAD (Voice Activity Detection) memiliki latensi lebih rendah dan cocok untuk skenario interaktif. Dengan menyesuaikan parameter Parameter ini hanya berlaku ketika model adalah v2 atau yang lebih baru. |
max_sentence_silence | int | 800 | Tidak | Atur ambang batas durasi diam (dalam ms) untuk segmentasi VAD (Voice Activity Detection). Ketika durasi diam setelah segmen ucapan melebihi ambang batas ini, sistem menentukan bahwa kalimat telah berakhir. Rentang parameter adalah 200 ms hingga 6000 ms, dengan nilai default 800 ms. Parameter ini hanya berlaku ketika parameter |
multi_threshold_mode_enabled | bool | False | Tidak | Ketika sakelar ini diaktifkan (true), mencegah segmentasi VAD memotong kalimat yang terlalu panjang. Dinonaktifkan secara default. Parameter ini hanya berlaku ketika parameter |
punctuation_prediction_enabled | bool | True | Tidak | Atur apakah akan secara otomatis menambahkan tanda baca dalam hasil pengenalan:
Parameter ini hanya berlaku ketika model adalah v2 atau yang lebih baru. |
heartbeat | bool | False | Tidak | Ketika Anda perlu mempertahankan koneksi panjang dengan server, gunakan sakelar ini untuk mengontrol perilaku:
Parameter ini hanya berlaku ketika model adalah v2 atau yang lebih baru. Field ini diperkenalkan sejak SDK 1.23.1, dan telah disertakan pada versi 2.0.1 ke atas. |
inverse_text_normalization_enabled | bool | True | Tidak | Atur apakah akan mengaktifkan ITN (Inverse Text Normalization). Diaktifkan secara default (true). Ketika diaktifkan, angka Tionghoa dikonversi menjadi angka Arab. Parameter ini hanya berlaku ketika model adalah v2 atau yang lebih baru. |
Referensi API
Sumber daya inti (client.audio.asr)
Kemampuan pengenalan ucapan real-time terpasang pada resource client.audio.asr: recognize membuat sesi pengenalan streaming dua arah (Recognition), recognize_file mengenali file lokal sekali jalan.
| Metode anggota | Signature metode | Deskripsi |
|---|---|---|
| recognize | Membuat sesi pengenalan streaming dua arah; saat memasuki konteks with, start otomatis dipanggil untuk membuat koneksi dan mengirim tugas.Pengiriman audio dan konsumsi event harus berjalan konkuren (gunakan bersama send_audio_frame, events()/results(), dan stop). | |
| recognize_file | Panggilan non-streaming berbasis file lokal: otomatis mengirim audio secara bertahap dan menggerakkan tugas hingga selesai, menghasilkan event server satu per satu. Metode ini memerlukan izin baca pada file yang dikenali. | |
| start | Memulai pengenalan ucapan: membuat koneksi, mengirim tugas, dan menunggu task-started. Otomatis dipanggil saat memasuki konteks with; audio hanya dapat dikirim setelah startup berhasil. | |
| send_audio_frame | Mendorong aliran audio. Aliran audio yang didorong setiap kali tidak boleh terlalu besar atau terlalu kecil; disarankan durasi audio per paket sekitar 100 ms dengan ukuran antara 1KB~16KB.Hasil pengenalan diperoleh melalui iterasi event (events()/results()). | |
| stop | Menghentikan pengenalan ucapan: hanya memberi tahu server bahwa input telah selesai; thread penerima perlu terus mengonsumsi events() hingga event task-finished. | |
| events / results | Mengiterasi event server: events() menghasilkan dict event mentah (teks pengenalan berada di payload.output.sentence); results() hanya menghasilkan frame hasil pengenalan, mengembalikan objek bertipe Hasil pengenalan (RecognitionResult) (frame heartbeat telah difilter). | |
| close | Menutup sesi pengenalan. Otomatis dipanggil saat keluar dari konteks with. | |
| request_id / first_package_delay / last_package_delay | Mendapatkan request_id, delay paket pertama (latensi dari pengiriman paket audio pertama hingga diterimanya hasil pengenalan pertama) dan delay paket terakhir (waktu dari pengiriman perintah stop hingga hasil pengenalan terakhir diterima). Gunakan setelah tugas selesai; masih dapat dibaca setelah sesi ditutup. |
Iterasi event (events()/results())
Saat panggilan streaming dua arah, server mengembalikan informasi proses utama dan data ke klien melalui event. Anda perlu mengiterasi events() (dict event mentah) atau results() (frame hasil pengenalan bertipe) milik sesi pada thread penerima, untuk memproses informasi atau data yang dikembalikan server.
Klik untuk melihat contoh
Klik untuk melihat contoh
| Event/metode iterasi | Konten yang dihasilkan | Nilai kembalian | Deskripsi |
|---|---|---|---|
event task-started | Tidak ada | Dibaca secara internal oleh start(), disimpan di last_response saat startup kembali, dan tidak dihasilkan lagi oleh events(). | |
event: dict event server | Iterator | Menghasilkan event ketika server membalas. Hasil pengenalan berada di payload.output.sentence, dapat berupa heartbeat atau event teks kosong; aplikasi dapat mengabaikannya sesuai kebutuhan. Harus dikonsumsi terus-menerus oleh satu thread penerima, jangan membuat beberapa pembaca secara konkuren. | |
result: Hasil pengenalan (RecognitionResult) | Iterator | Hanya menghasilkan frame hasil pengenalan (frame heartbeat telah difilter); iterasi berakhir setelah semua hasil pengenalan dikembalikan. | |
pengecualian DashScopeError | Tidak ada | Saat terjadi pengecualian, dilempar di thread pengirim/penerima; dapat ditangkap dengan try/except. | |
event task-finished | Tidak ada | Dihasilkan oleh events() setelah server menyelesaikan seluruh pengenalan, lalu iterasi berakhir; event ini tetap harus dibaca setelah mengirim stop(). |
Hasil respons
Hasil pengenalan (RecognitionResult)
RecognitionResult merepresentasikan satu frame hasil pengenalan yang dihasilkan oleh iterasi results() milik sesi (dapat digunakan baik pada panggilan streaming dua arah maupun panggilan non-streaming; events() menghasilkan dict event mentah — jika membutuhkan tampilan bertipe ini, gunakan results()).
| Metode anggota | Signature metode | Deskripsi |
|---|---|---|
| get_sentence | Mendapatkan kalimat yang saat ini dikenali beserta informasi timestamp-nya; metode ini mengembalikan tipe Dict[str, Any] (informasi kalimat tunggal).Untuk informasi lebih lanjut, lihat Sentence. | |
| request_id | request_id permintaan yang sesuai dengan event saat ini. | |
| is_sentence_end | Menentukan apakah kalimat saat ini telah berakhir (bernilai True jika kalimat membawa end_time). |
Sentence (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 | Informasi timestamp kata. | |
emo_tag | str | Emosi kalimat saat ini:
Pengenalan emosi memiliki batasan berikut:
|
emo_confidence | float | Tingkat kepercayaan emosi yang dikenali untuk kalimat saat ini. Nilainya berkisar dari 0,0 hingga 1,0. Nilai yang lebih besar menunjukkan tingkat kepercayaan yang lebih tinggi. Pengenalan emosi memiliki batasan berikut:
|
Informasi timestamp 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. |