Topik ini menjelaskan parameter dan detail antarmuka SDK Java untuk pengenalan ucapan non-real-time Paraformer.
Prasyarat
Mulai cepat
Kelas inti (Transcription) menyediakan antarmuka untuk mengirimkan tugas secara asinkron, menunggu secara sinkron hingga tugas selesai, dan mengkueri hasil tugas secara asinkron. Anda dapat menggunakan dua metode pemanggilan berikut untuk pengenalan ucapan non-real-time:
- Kirim asinkron + tunggu sinkron: Setelah mengirimkan tugas, thread saat ini diblokir hingga tugas selesai dan hasil pengenalan diperoleh.
- Kirim asinkron + kueri asinkron: Setelah mengirimkan tugas, Anda dapat mengkueri hasil tugas kapan saja dengan memanggil antarmuka kueri.
Kirim asinkron + tunggu sinkron
- Konfigurasikan Parameter permintaan.
- Buat instans Kelas inti (Transcription).
-
Panggil metode
asyncCalldari Kelas inti (Transcription) untuk mengirimkan tugas secara asinkron.- Layanan transkripsi file memproses tugas yang dikirim melalui API berdasarkan prinsip best-effort. Setelah dikirim, tugas masuk ke status antrian (
PENDING). Waktu antrian bergantung pada panjang antrian dan durasi file serta tidak dapat diprediksi 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 prinsip best-effort. Setelah dikirim, tugas masuk ke status antrian (
-
Panggil metode
waitdari Kelas inti (Transcription) untuk menunggu secara sinkron hingga tugas selesai. Status tugas mencakupPENDING,RUNNING,SUCCEEDED, danFAILED. Saat tugas berada dalam statusPENDINGatauRUNNING, antarmukawaitdiblokir. Saat tugas berada dalam statusSUCCEEDEDatauFAILED, antarmukawaittidak lagi diblokir dan mengembalikan hasil tugas.waitmengembalikan Hasil tugas (TranscriptionResult).
Klik untuk melihat contoh lengkap
Klik untuk melihat contoh lengkap
Kirim asinkron + kueri asinkron
- Konfigurasikan Parameter permintaan.
- Buat instans Kelas inti (Transcription).
-
Panggil metode
asyncCalldari Kelas inti (Transcription) untuk mengirimkan tugas secara asinkron.- Layanan transkripsi file memproses tugas yang dikirim melalui API berdasarkan prinsip best-effort. Setelah dikirim, tugas masuk ke status antrian (
PENDING). Waktu antrian bergantung pada panjang antrian dan durasi file serta tidak dapat diprediksi 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 prinsip best-effort. Setelah dikirim, tugas masuk ke status antrian (
-
Lakukan loop dengan memanggil metode
fetchdari Kelas inti (Transcription) hingga Anda memperoleh hasil tugas akhir. Saat status tugas adalahSUCCEEDEDatauFAILED, hentikan polling dan proses hasilnya.fetchmengembalikan Hasil tugas (TranscriptionResult).
Klik untuk melihat contoh lengkap
Klik untuk melihat contoh lengkap
Parameter permintaan
Parameter permintaan dikonfigurasi melalui metode berantai dari TranscriptionParam.
Klik untuk melihat contoh
Klik untuk melihat contoh
| Parameter | Tipe | Bawaan | Wajib | Deskripsi |
|---|---|---|---|---|
| model | String | Ya | Menentukan nama model Paraformer untuk transkripsi file audio/video. Lihat Model yang didukung. | |
| fileUrls | List<String> | Ya | Daftar URL file audio/video untuk transkripsi. Mendukung protokol HTTP/HTTPS. Hanya satu URL yang didukung per permintaan.Jika file audio disimpan di Alibaba Cloud OSS, SDK tidak mendukung URL sementara dengan awalan oss://. | |
| vocabularyId | String | Tidak | ID hot word terbaru. Mendukung model seri v2 terbaru dengan konfigurasi bahasa. Hot word yang terkait dengan ID ini berlaku untuk pengenalan ucapan ini. Dinonaktifkan secara bawaan. Untuk petunjuk penggunaan, lihat Hotword kustom. | |
| channelId | List<Integer> | [0] | Tidak | Menentukan indeks track audio yang akan dikenali dalam file audio multi-track. Indeks dimulai dari 0. Misalnya, [0] berarti mengenali track pertama, dan [0, 1] berarti mengenali track pertama dan kedua secara simultan. Jika parameter ini dihilangkan, hanya track pertama yang diproses secara bawaan. |
| disfluencyRemovalEnabled | Boolean | false | Tidak | Menyaring kata pengisi. Dinonaktifkan secara bawaan. |
| timestampAlignmentEnabled | Boolean | false | Tidak | Apakah akan mengaktifkan fitur penyelarasan timestamp. Dinonaktifkan secara bawaan. |
| specialWordFilter | String | Tidak | Menentukan kata sensitif yang akan diproses selama pengenalan ucapan dan mendukung pengaturan metode pemrosesan berbeda untuk kata sensitif 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 | String[] | ["zh", "en"] | Tidak | Menentukan kode bahasa dari ucapan yang akan dikenali.Parameter ini hanya berlaku untuk model paraformer-v2.Kode bahasa yang didukung:
language_hints perlu diatur melalui metode parameter atau metode parameters dari instans TranscriptionParam: |
| diarizationEnabled | Boolean | false | Tidak | Diarisasi pembicara otomatis. Dinonaktifkan secara bawaan.Hanya berlaku untuk audio mono. Audio multi-channel tidak mendukung diarisasi pembicara.Saat fitur ini diaktifkan, hasil pengenalan akan menyertakan bidang speaker_id untuk membedakan pembicara 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. |
| speakerCount | Integer | Tidak | Nilai referensi untuk jumlah pembicara. Nilai yang valid: bilangan bulat dari 2 hingga 100 (inklusif).Berlaku saat diarisasi pembicara diaktifkan (diarizationEnabled diatur ke true).Secara bawaan, sistem secara otomatis menentukan jumlah pembicara. Jika parameter ini dikonfigurasi, parameter ini hanya berfungsi sebagai petunjuk bagi algoritma untuk mencoba menghasilkan jumlah pembicara yang ditentukan, tetapi jumlah pastinya tidak dijamin. | |
| apiKey | String | Tidak | Kunci API. Jika Kunci API sudah dikonfigurasi dalam variabel lingkungan, Anda tidak perlu mengaturnya dalam kode. Jika tidak, Anda harus mengaturnya dalam kode. |
Respons
Hasil tugas (TranscriptionResult)
TranscriptionResult membungkus hasil tugas saat ini.
| Antarmuka/Metode | Parameter | Nilai kembali | Deskripsi |
|---|---|---|---|
| Tidak ada | requestId | Mendapatkan requestId. | |
| Tidak ada | taskId | Mendapatkan taskId. | |
| Tidak ada | TaskStatus, status tugas | Mendapatkan status tugas.TaskStatus adalah kelas enum. Anda hanya perlu fokus pada empat status berikut: PENDING, RUNNING, SUCCEEDED, dan FAILED.Saat tugas berisi beberapa subtugas, selama ada satu subtugas yang berhasil, status tugas keseluruhan ditandai sebagai SUCCEEDED. Anda perlu memeriksa bidang subtask_status untuk menentukan hasil setiap subtugas. | |
| Tidak ada | Hasil subtugas (TranscriptionTaskResult) | Mendapatkan Hasil subtugas (TranscriptionTaskResult).Setiap tugas mengenali satu atau beberapa file audio. File audio berbeda diproses dalam subtugas berbeda, sehingga setiap tugas berkorespondensi dengan satu atau beberapa subtugas. | |
| Tidak ada | Hasil tugas dalam format JSON | Mendapatkan hasil tugas.Hasilnya dalam format JSON. Jika Anda menggunakan antarmuka getOutput untuk mendapatkan hasil tugas, Anda perlu menguraikannya sendiri.
Klik untuk melihat contoh JSON Contoh normal code" adalah kode kesalahan dan "message" adalah pesan kesalahan. Kedua bidang ini hanya muncul dalam skenario error. Anda dapat menggunakannya untuk troubleshooting dengan merujuk ke Kode kesalahan. |
Hasil subtugas (TranscriptionTaskResult)
TranscriptionTaskResult membungkus hasil subtugas. Satu subtugas mengenali satu file audio.
| Antarmuka/Metode | Parameter | Nilai kembali | Deskripsi |
|---|---|---|---|
| Tidak ada | URL file audio yang dikenali | Mendapatkan URL file audio yang dikenali. | |
| Tidak ada | URL hasil pengenalan | Mendapatkan URL hasil pengenalan. URL ini berlaku selama 24 jam. Setelah kedaluwarsa, Anda tidak dapat mengkueri tugas atau mengunduh hasil melalui URL yang sebelumnya diberikan.Hasil pengenalan disimpan sebagai file JSON. Anda dapat mengunduh file tersebut melalui URL di atas atau langsung membaca isinya melalui permintaan HTTP.Untuk makna setiap bidang dalam data JSON, lihat Deskripsi hasil pengenalan. | |
| Tidak ada | TaskStatus, status subtugas | Mendapatkan status subtugas.TaskStatus adalah kelas enum. Anda hanya perlu fokus pada empat status berikut: PENDING, RUNNING, SUCCEEDED, dan FAILED. | |
| Tidak ada | Informasi penting selama eksekusi tugas, yang mungkin kosong | Mendapatkan informasi penting selama eksekusi tugas.Saat tugas gagal, Anda dapat memeriksa konten ini untuk menganalisis penyebabnya. |
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 file sumber. |
channels | array[integer] | Informasi indeks track audio file sumber. Mengembalikan [0] untuk audio mono, [0, 1] untuk audio dual-track, dan seterusnya. |
original_sampling_rate | integer | Frekuensi sampling (Hz) audio dalam file sumber. |
original_duration | integer | Durasi audio asli (ms) file sumber. |
channel_id | integer | Indeks track audio dari hasil transkripsi, dimulai dari 0. |
content_duration | integer | Durasi (ms) konten yang diidentifikasi sebagai ucapan dalam track audio. Layanan model pengenalan ucapan Paraformer hanya mentranskripsi dan mengukur konten yang diidentifikasi sebagai ucapan dalam track 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 terjadi sedikit 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 mulai (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 berbeda. Bidang ini hanya ditampilkan dalam hasil pengenalan saat diarisasi pembicara diaktifkan. |
punctuation | string | Tanda baca yang diprediksi setelah kata (jika ada). |
Antarmuka utama
Kelas parameter kueri tugas (TranscriptionQueryParam)
TranscriptionQueryParam digunakan saat menunggu tugas selesai (memanggil metode wait dari Transcription) atau mengkueri hasil tugas (memanggil metode fetch dari Transcription).
Buat instans TranscriptionQueryParam melalui metode statis FromTranscriptionParam.
Klik untuk melihat contoh
Klik untuk melihat contoh
| Antarmuka/Metode | Parameter | Nilai kembali | Deskripsi |
|---|---|---|---|
| Instans TranscriptionQueryParam | Membuat instans TranscriptionQueryParam. |
Kelas inti (Transcription)
Transcription dapat diimpor dengan "import com.alibaba.dashscope.audio.asr.transcription.*;". Antarmuka utamanya adalah sebagai berikut:
| Antarmuka/Metode | Parameter | Nilai kembali | Deskripsi |
|---|---|---|---|
param: Parameter pengenalan ucapan, instans TranscriptionParam | Hasil tugas (TranscriptionResult) | Mengirimkan tugas pengenalan ucapan secara asinkron. | |
queryParam: Instans TranscriptionQueryParam | Hasil tugas (TranscriptionResult) | Memblokir thread saat ini hingga tugas asinkron selesai (status tugas adalah SUCCEEDED atau FAILED). | |
queryParam: Instans TranscriptionQueryParam | Hasil tugas (TranscriptionResult) | Mengkueri hasil tugas saat ini secara asinkron. |
Kode kesalahan
Jika Anda mengalami kesalahan, lihat Kode kesalahan untuk troubleshooting.
Jika masalah berlanjut, bergabunglah dengan komunitas developer untuk melaporkan masalah dan memberikan Request ID untuk investigasi lebih lanjut.
Saat tugas berisi beberapa subtugas, selama ada satu subtugas yang berhasil, status tugas keseluruhan ditandai sebagai SUCCEEDED. Anda perlu memeriksa bidang subtask_status untuk menentukan hasil setiap subtugas.
Contoh respons error:
Lebih banyak contoh
Untuk lebih banyak contoh, lihat GitHub.
FAQ
Pertanyaan fitur
T: Apakah mendukung audio terenkode Base64?
Tidak. Audio yang dienkripsi 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?
Umumnya, ikuti langkah-langkah berikut (ini memberikan pendekatan umum; spesifiknya bervariasi berdasarkan 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 ke akses 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 hasilkan 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 membutuhkan 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 merupakan alamat server ditambah jalur file (seperti
https://your-domain.com/audio/file.mp3).
- URL akses file biasanya merupakan 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 gunakan di lingkungan produksi.
- API untuk mendapatkan kredensial unggah dibatasi hingga 100 QPS dan tidak mendukung penskalaan keluar. Jangan gunakan 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 masuk ke status antrian (PENDING). Waktu antrian bergantung pada panjang antrian dan durasi file serta tidak dapat diprediksi secara tepat, tetapi biasanya selesai dalam beberapa menit. Harap tunggu dengan sabar. File audio yang lebih panjang memerlukan waktu pemrosesan lebih lama.
Troubleshooting
Jika Anda mengalami kesalahan kode, lakukan troubleshooting berdasarkan informasi di Kode kesalahan.
T: Apa yang harus dilakukan jika hasil pengenalan dan pemutaran audio tidak sinkron?
Atur Parameter permintaan timestampAlignmentEnabled ke true untuk mengaktifkan fitur penyelarasan timestamp, yang menyinkronkan hasil pengenalan dengan pemutaran audio.
T: Tidak dapat mendapatkan hasil setelah polling terus-menerus?
Ini mungkin karena pembatasan laju. Harap tunggu dengan sabar. Jika Anda membutuhkan 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 menyelesaikan masalah, Anda dapat menyesuaikan hot word untuk meningkatkan pengenalan kata-kata tertentu.