Gunakan SDK Python Paraformer untuk mentranskripsikan file audio dan video melalui API DashScope.
Prasyarat
Mulai
Sumber daya inti (client.audio.asr) menyediakan antarmuka pengiriman tugas asinkron, penungguan sinkron hingga tugas selesai, dan polling hasil tugas secara asinkron (transcribe satu langkah / jobs.create+jobs.wait+jobs.fetch bertahap). Pengenalan ucapan non-real-time dapat dilakukan melalui dua cara pemanggilan berikut:
- Pengiriman asinkron + tunggu sinkron: Kirim tugas dan blokir thread saat ini hingga tugas selesai serta mendapatkan hasil pengenalan.
- Pengiriman asinkron + polling asinkron: Kirim tugas, lalu kapan pun dibutuhkan, panggil antarmuka polling untuk mendapatkan hasil eksekusi tugas.
Pengiriman asinkron + tunggu sinkron
-
Panggil sumber daya inti (
client.audio.asr) (jobs.create/transcribe) dan atur parameter permintaan.- Layanan transkripsi file memproses tugas yang dikirim melalui API berdasarkan upaya terbaik. Setelah dikirim, tugas memasuki status antrian (
PENDING). Waktu antrian bergantung pada panjang antrian dan durasi file serta tidak dapat diperkirakan secara tepat, tetapi biasanya selesai dalam beberapa menit. Setelah pemrosesan dimulai, pengenalan ucapan selesai dengan kecepatan ratusan kali lipat dari kecepatan real-time. - Setelah setiap tugas selesai, hasil pengenalan dan tautan unduh URL berlaku selama 24 jam. Setelah kedaluwarsa, Anda tidak dapat mengkueri tugas atau mengunduh hasil melalui URL yang sebelumnya diberikan.
- Layanan transkripsi file memproses tugas yang dikirim melalui API berdasarkan upaya terbaik. Setelah dikirim, tugas memasuki status antrian (
-
Panggil sumber daya inti (
client.audio.asr) (jobs.wait, atautranscribesatu langkah) untuk menunggu secara sinkron hingga tugas selesai. Status tugas:PENDING,RUNNING,SUCCEEDED,FAILED. Panggilanwaitdiblokir selama statusPENDINGatauRUNNING. Ketika tugas mencapai statusSUCCEEDEDatauFAILED,waittidak lagi memblokir dan mengembalikan hasil eksekusi tugas.jobs.waitmengembalikanJobstatus akhir (struktur lihat Parameter respons).
Klik untuk melihat contoh lengkap
Klik untuk melihat contoh lengkap
Pengiriman asinkron + polling asinkron
-
Panggil sumber daya inti (
client.audio.asr) (jobs.create/transcribe) dan atur parameter permintaan.- Layanan transkripsi file memproses tugas yang dikirim melalui API berdasarkan upaya terbaik. Setelah dikirim, tugas memasuki status antrian (
PENDING). Waktu antrian bergantung pada panjang antrian dan durasi file serta tidak dapat diperkirakan secara tepat, tetapi biasanya selesai dalam beberapa menit. Setelah pemrosesan dimulai, pengenalan ucapan selesai dengan kecepatan ratusan kali lipat dari kecepatan real-time. - Setelah setiap tugas selesai, hasil pengenalan dan tautan unduh URL berlaku selama 24 jam. Setelah kedaluwarsa, Anda tidak dapat mengkueri tugas atau mengunduh hasil melalui URL yang sebelumnya diberikan.
- Layanan transkripsi file memproses tugas yang dikirim melalui API berdasarkan upaya terbaik. Setelah dikirim, tugas memasuki status antrian (
-
Lakukan polling sumber daya inti (
client.audio.asr) (jobs.fetch) secara berulang hingga mendapatkan hasil akhir tugas. Berhenti polling ketika statusnyaSUCCEEDEDatauFAILEDdan proses hasilnya.jobs.fetchmengembalikanJob(struktur lihat Parameter respons).
Klik untuk melihat contoh lengkap
Klik untuk melihat contoh lengkap
Parameter permintaan
Parameter permintaan diatur melalui metode jobs.create/transcribe dari sumber daya inti (client.audio.asr).
| Parameter | Type | Default | Wajib | Deskripsi |
|---|---|---|---|---|
| model | str | Ya | Nama model untuk transkripsi file audio dan video Paraformer. Model yang didukung. | |
| file_urls | list[str] | Ya | Daftar URL untuk transkripsi file audio dan video. Protokol HTTP dan HTTPS didukung. Satu permintaan hanya mendukung 1 URL.Jika file audio disimpan di Alibaba Cloud OSS, SDK tidak mendukung URL sementara dengan awalan oss://. | |
| vocabulary_id | str | Tidak | ID kosakata kustom. Didukung untuk model seri v2; memerlukan konfigurasi bahasa. Dinonaktifkan secara default. Kosakata Kustom. | |
| channel_id | list[int] | [0] | Tidak | Menentukan indeks trek audio yang akan dikenali dalam file audio multi-trek. Indeks dimulai dari 0. Misalnya, [0] berarti mengenali trek pertama, dan [0, 1] berarti mengenali trek pertama dan kedua secara simultan. Jika parameter ini dihilangkan, hanya trek pertama yang diproses secara default. |
| disfluency_removal_enabled | bool | False | Tidak | Menyaring kata-kata pengisi. Dinonaktifkan secara default. |
| timestamp_alignment_enabled | bool | False | Tidak | Mengaktifkan penyelarasan timestamp. Dinonaktifkan secara default. |
| special_word_filter | str | Tidak | Menentukan kata sensitif yang akan diproses selama pengenalan ucapan dan mendukung pengaturan metode pemrosesan berbeda untuk kata sensitif yang berbeda.Jika parameter ini tidak diberikan, sistem menggunakan logika penyaringan kata sensitif bawaan, dan kata-kata yang cocok dengan daftar kata sensitif Alibaba Cloud Model Studio dalam hasil pengenalan akan diganti dengan * dengan panjang yang sama.Jika parameter ini diberikan, strategi pemrosesan kata sensitif berikut dapat diterapkan:
| |
| language_hints | list[str] | ["zh", "en"] | Tidak | Menentukan kode bahasa dari ucapan yang akan dikenali.Parameter ini hanya berlaku untuk model paraformer-v2.Kode bahasa yang didukung:
|
| diarization_enabled | bool | False | Tidak | Diarisasi pembicara otomatis. Dinonaktifkan secara default.Hanya berlaku untuk audio mono. Audio multi-channel tidak mendukung diarisasi pembicara.Ketika fitur ini diaktifkan, hasil pengenalan akan menyertakan bidang speaker_id untuk membedakan pembicara yang berbeda.Jika diarisasi pembicara diaktifkan, disarankan agar durasi audio tidak melebihi 2 jam, jika tidak pengenalan mungkin gagal atau timeout. speaker_id, lihat Deskripsi hasil pengenalan. |
| speaker_count | int | Tidak | Jumlah pembicara referensi. Bilangan bulat dari 2 hingga 100.Berlaku hanya ketika diarization_enabled bernilai true.Ditentukan secara otomatis secara default. Mengatur parameter ini membimbing algoritma tetapi tidak menjamin jumlah yang tepat. |
Tanggapan
Job
Job membungkus informasi dasar tugas (task_id dan status) serta hasil eksekusinya (results lihat Hasil pengenalan sub-tugas, task_metrics, usage). Job yang dikembalikan setelah jobs.create mengirim tugas hanya memuat task_id dan status; Job yang dikembalikan oleh jobs.fetch, jobs.wait (serta transcribe satu langkah) memuat hasil eksekusi tugas.
Klik untuk melihat contoh struktur Job
Klik untuk melihat contoh struktur Job
Job yang dikembalikan oleh metode jobs.create (tugas dalam status PENDING setelah dikirim):Job yang dikembalikan oleh jobs.fetch, jobs.wait (serta transcribe satu langkah):Parameter | Deskripsi |
|---|---|
request_id | ID yang dihasilkan sistem untuk mengidentifikasi pemanggilan ini. |
task_id | ID tugas. |
status | Status tugas. Keempat status tersebut adalah Ketika sebuah tugas berisi beberapa subtugas, jika ada subtugas yang berhasil, status seluruh tugas ditandai sebagai |
results | Hasil pengenalan sub-tugas; setiap item memuat |
subtask_status | Status sub-tugas. Keempat status tersebut adalah |
file_url | URL audio yang dikenali. |
transcription_url | URL yang sesuai dengan hasil pengenalan audio. Hasil pengenalan disimpan sebagai file JSON. Unduh file dari URL di |
usage | Informasi meteran, memuat |
subtask_status, code, dan message dalam results untuk menentukannya.
results (hasil pengenalan sub-tugas)
Array results sesuai dengan hasil pengenalan sub-tugas untuk setiap file audio dalam Job; setiap item memuat file_url, transcription_url, subtask_status; saat sub-tugas gagal, juga memuat code dan message.
Klik untuk melihat contoh struktur results
Klik untuk melihat contoh struktur results
- Status SUCCEEDED
- Status FAILED
Parameter | Deskripsi |
|---|---|
code | Kode kesalahan. Gunakan bersama bidang |
message | Pesan kesalahan. Gunakan bersama bidang |
subtask_status | Status sub-tugas. Keempat status tersebut adalah |
file_url | URL audio yang dikenali. |
transcription_url | URL yang sesuai dengan hasil pengenalan audio. Hasil pengenalan disimpan dalam format JSON di dalam sebuah file JSON. Unduh file dari URL di |
Deskripsi hasil pengenalan
Hasil pengenalan disimpan sebagai file JSON.
Klik untuk melihat contoh hasil pengenalan
Klik untuk melihat contoh hasil pengenalan
Parameter | Type | Deskripsi |
|---|---|---|
audio_format | string | Format audio dari file sumber. |
channels | array[integer] | Informasi indeks trek audio dari file sumber. Mengembalikan [0] untuk audio mono, [0, 1] untuk audio dual-trek, dan seterusnya. |
original_sampling_rate | integer | Frekuensi sampling (Hz) audio dalam file sumber. |
original_duration | integer | Durasi audio asli (ms) dari file sumber. |
channel_id | integer | Indeks trek audio dari hasil transkripsi, dimulai dari 0. |
content_duration | integer | Durasi (ms) konten yang diidentifikasi sebagai ucapan dalam trek audio. Layanan model pengenalan ucapan Paraformer hanya mentranskripsikan dan mengukur konten yang diidentifikasi sebagai ucapan dalam trek audio, dan menagih sesuai dengan itu. Konten non-ucapan tidak diukur maupun ditagih. Biasanya, durasi konten ucapan lebih pendek daripada durasi audio asli. Karena penentuan apakah konten ucapan ada dilakukan oleh model AI, mungkin terdapat beberapa penyimpangan dari situasi aktual. |
transcript | string | Hasil transkripsi ucapan tingkat paragraf. |
sentences | array | Hasil transkripsi ucapan tingkat kalimat. |
words | array | Hasil transkripsi ucapan tingkat kata. |
begin_time | integer | Timestamp awal (ms). |
end_time | integer | Timestamp akhir (ms). |
text | string | Hasil transkripsi ucapan. |
speaker_id | integer | Indeks pembicara saat ini, dimulai dari 0, digunakan untuk membedakan pembicara yang berbeda. Bidang ini hanya ditampilkan dalam hasil pengenalan ketika diarisasi pembicara diaktifkan. |
punctuation | string | Tanda baca yang diprediksi setelah kata (jika ada). |
Referensi API
Sumber daya inti (client.audio.asr)
Kemampuan pengenalan ucapan non-real-time terpasang pada resource client.audio.asr; dapat menyelesaikan pengiriman dan penungguan dalam satu langkah melalui client.audio.asr.transcribe, atau mengontrol secara bertahap melalui client.audio.asr.jobs.
| Metode anggota | Signature metode | Deskripsi |
|---|---|---|
| transcribe | Mengirim tugas pengenalan file rekaman dan memblokir thread saat ini hingga tugas selesai (status tugas SUCCEEDED atau FAILED).Metode ini mengembalikan Job; hasil transkripsi dibaca dari job.results (setiap item memuat transcription_url). | |
| jobs.create | Mengirim tugas pengenalan ucapan secara asinkron.Metode ini mengembalikan Job (job.task_id/job.status). | |
| jobs.wait | Memblokir thread saat ini hingga tugas asinkron selesai (polling dengan exponential backoff, total anggaran default 24 jam).Metode ini mengembalikan Job status akhir. | |
| jobs.fetch | Meminta hasil eksekusi tugas saat ini secara asinkron.Metode ini mengembalikan Job. |
Kode kesalahan
Jika Anda mengalami kesalahan, lihat Kode kesalahan untuk troubleshooting.
Jika masalah berlanjut, bergabunglah dengan komunitas developer untuk melaporkan masalah dan berikan Request ID untuk investigasi lebih lanjut.
Ketika sebuah tugas berisi beberapa subtugas, selama ada subtugas yang berhasil, status keseluruhan tugas ditandai sebagai SUCCEEDED. Anda perlu memeriksa bidang subtask_status untuk menentukan hasil setiap subtugas.
Contoh tanggapan kesalahan:
Contoh lainnya
Jelajahi lebih banyak contoh di GitHub.
FAQ
Fitur
T: Apakah mendukung audio yang diencode Base64?
Tidak. Audio yang diencode Base64 tidak didukung. Hanya audio yang dapat diakses melalui URL publik yang didukung. Aliran biner dan pengenalan file lokal langsung tidak didukung.
T: Bagaimana cara menyediakan file audio sebagai URL publik?
Secara umum, ikuti langkah-langkah berikut (ini memberikan pendekatan umum; spesifiknya bervariasi tergantung produk penyimpanan. Kami merekomendasikan mengunggah audio ke Alibaba Cloud OSS):
1. Pilih metode penyimpanan dan hosting
1. Pilih metode penyimpanan dan hosting
-
Layanan Penyimpanan Objek (direkomendasikan):
- Gunakan layanan penyimpanan objek penyedia cloud (seperti Alibaba Cloud OSS) untuk mengunggah file audio ke bucket dan mengaturnya agar dapat diakses publik.
- Keuntungan: Ketersediaan tinggi, dukungan akselerasi CDN, manajemen mudah.
-
server web:
- Tempatkan file audio di server web yang mendukung akses HTTP/HTTPS (seperti Nginx atau Apache).
- Keuntungan: Cocok untuk proyek kecil atau pengujian lokal.
-
Content Delivery Network (CDN):
- Host file audio di CDN dan akses melalui URL yang disediakan CDN.
- Keuntungan: Pengiriman file dipercepat, cocok untuk skenario konkurensi tinggi.
2. Unggah file audio
2. Unggah file audio
-
Layanan Penyimpanan Objek:
- Login ke konsol penyedia cloud dan buat bucket.
- Unggah file audio dan atur izin file ke "baca publik" atau buat tautan akses sementara.
-
server web:
- Tempatkan file audio di direktori yang ditentukan server (seperti
/var/www/html/audio/). - Pastikan file dapat diakses melalui HTTP/HTTPS.
- Tempatkan file audio di direktori yang ditentukan server (seperti
3. Hasilkan URL publik
3. Hasilkan URL publik
-
Layanan Penyimpanan Objek:
- Setelah diunggah, sistem secara otomatis menghasilkan URL akses publik (biasanya dalam format
https://<bucket-name>.<region>.aliyuncs.com/<file-name>). - Jika Anda memerlukan domain yang lebih ramah pengguna, Anda dapat mengikat domain kustom dan mengaktifkan HTTPS.
- Setelah diunggah, sistem secara otomatis menghasilkan URL akses publik (biasanya dalam format
-
server web:
- URL akses file biasanya alamat server ditambah jalur file (seperti
https://your-domain.com/audio/file.mp3).
- URL akses file biasanya alamat server ditambah jalur file (seperti
-
CDN:
- Setelah mengonfigurasi akselerasi CDN, gunakan URL yang disediakan CDN (seperti
https://cdn.your-domain.com/audio/file.mp3).
- Setelah mengonfigurasi akselerasi CDN, gunakan URL yang disediakan CDN (seperti
4. Verifikasi aksesibilitas URL
4. Verifikasi aksesibilitas URL
- Buka URL di browser dan periksa apakah file audio dapat diputar.
- Gunakan alat (seperti
curlatau Postman) untuk memverifikasi apakah URL mengembalikan respons HTTP yang benar (kode status 200).
oss:// tidak didukung.
Saat menggunakan RESTful API, jika file audio disimpan di Alibaba Cloud OSS, URL sementara dengan awalan oss:// didukung:
- URL sementara berlaku selama 48 jam dan tidak dapat digunakan setelah kedaluwarsa. Jangan menggunakannya di lingkungan produksi.
- API untuk mendapatkan kredensial unggah dibatasi hingga 100 QPS dan tidak mendukung penskalaan keluar. Jangan menggunakannya di lingkungan produksi, skenario konkurensi tinggi, atau skenario uji stres.
- Untuk lingkungan produksi, gunakan layanan penyimpanan stabil seperti OSS untuk memastikan ketersediaan file jangka panjang dan menghindari masalah pembatasan laju.
T: Berapa lama waktu yang dibutuhkan untuk mendapatkan hasil pengenalan?
Setelah dikirim, tugas memasuki status antrian (PENDING). Waktu antrian bergantung pada panjang antrian dan durasi file serta tidak dapat diperkirakan secara tepat, tetapi biasanya selesai dalam beberapa menit. Harap tunggu dengan sabar. File audio yang lebih panjang memerlukan waktu pemrosesan lebih lama.
Troubleshooting
Untuk kesalahan kode, lihat Kode kesalahan.
T: Apa yang harus saya lakukan jika hasil pengenalan tidak sinkron dengan pemutaran audio?
Atur parameter permintaan timestamp_alignment_enabled ke true untuk mengaktifkan kalibrasi timestamp, yang menyinkronkan hasil pengenalan dengan pemutaran ucapan.
T: Apa yang harus saya lakukan jika tugas mengembalikan kesalahan InvalidFile.DownloadFailed?
Periksa apakah URL file berisi spasi atau karakter non-ASCII lainnya (seperti karakter Tionghoa). Jika nama file menyertakan spasi (misalnya, my audio recording.mp4), ganti setiap spasi dengan %20 untuk mengencode nama file dalam URL sebelum meneruskannya ke parameter file_urls.
T: Tidak dapat mendapatkan hasil setelah polling terus-menerus?
Ini mungkin karena pembatasan laju. Harap tunggu dengan sabar. Jika Anda memerlukan ekspansi kapasitas, bergabunglah dengan komunitas developer untuk mengajukan permohonan.T: Mengapa tidak ada hasil pengenalan (tidak dapat mengenali ucapan)?
- Periksa apakah audio memenuhi persyaratan (format, frekuensi sampling).
- Jika Anda menggunakan model
paraformer-v2, periksa apakah pengaturanlanguage_hintssudah benar. - Jika tidak ada yang di atas yang menyelesaikan masalah, Anda dapat menyesuaikan hot word untuk meningkatkan pengenalan kata-kata tertentu.