Skip to main content

SDK Python pengenalan ucapan non-real-time Paraformer

Gunakan SDK Python Paraformer untuk mentranskripsikan file audio dan video melalui API DashScope.

Dokumen ini hanya berlaku untuk wilayah Tiongkok Daratan (Beijing). Untuk menggunakan model ini, Anda harus menggunakan API key dari wilayah Tiongkok Daratan (Beijing).
Alibaba Cloud Model Studio telah merilis domain khusus ruang kerja untuk wilayah Tiongkok (Beijing). Domain khusus baru ini memberikan performa lebih unggul dan stabilitas lebih tinggi untuk permintaan inferensi. Kami merekomendasikan migrasi dari dashscope.aliyuncs.com ke {WorkspaceId}.cn-beijing.maas.aliyuncs.com.Ganti {WorkspaceId} dengan Workspace ID aktual Anda. Domain yang ada tetap berfungsi penuh.
Panduan pengguna:Pengenalan ucapan non-real-time

Prasyarat

Anda telah mengaktifkan layanan dan mendapatkan API key. Harap konfigurasikan API key sebagai variabel lingkungan alih-alih melakukan hardcoding di kode Anda untuk mencegah risiko keamanan akibat kebocoran kode.
Ketika Anda perlu memberikan akses sementara kepada aplikasi atau pengguna pihak ketiga, atau ketika ingin mengontrol secara ketat operasi berisiko tinggi seperti mengakses atau menghapus data sensitif, kami merekomendasikan penggunaan token otentikasi sementara.Dibandingkan dengan API Key jangka panjang, token otentikasi sementara memiliki periode validitas singkat (60 detik) dan keamanan lebih tinggi, sehingga cocok untuk skenario pemanggilan sementara dan secara efektif mengurangi risiko kebocoran API Key.Penggunaan: Dalam kode Anda, ganti API Key yang awalnya digunakan untuk otentikasi dengan token otentikasi sementara yang diperoleh.

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

  1. 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.
  2. Panggil sumber daya inti (client.audio.asr) (jobs.wait, atau transcribe satu langkah) untuk menunggu secara sinkron hingga tugas selesai. Status tugas: PENDING, RUNNING, SUCCEEDED, FAILED. Panggilan wait diblokir selama status PENDING atau RUNNING. Ketika tugas mencapai status SUCCEEDED atau FAILED, wait tidak lagi memblokir dan mengembalikan hasil eksekusi tugas. jobs.wait mengembalikan Job status akhir (struktur lihat Parameter respons).
import os
import json
import dashscope

# Jika Anda belum mengonfigurasi API Key dalam variabel lingkungan, ganti baris berikut dengan API Key Anda: api_key="sk-xxx"
# Berikut adalah konfigurasi untuk wilayah Singapura. Saat memanggil, ganti "{WorkspaceId}" dengan ID ruang kerja Anda yang sebenarnya. Nilai region berbeda-beda untuk setiap wilayah.
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

# Kirim tugas pengenalan file rekaman dan tunggu secara sinkron hingga tugas selesai
job = client.audio.asr.transcribe(
    ['{YOUR_AUDIO_URL}'],
    model='paraformer-v2',
    parameters={'language_hints': ['zh', 'en']}  # "language_hints" hanya didukung oleh model paraformer-v2
)

print(json.dumps(job.model_dump(), indent=4, ensure_ascii=False))
print('transkripsi selesai!')

Pengiriman asinkron + polling asinkron

  1. 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.
  2. Lakukan polling sumber daya inti (client.audio.asr) (jobs.fetch) secara berulang hingga mendapatkan hasil akhir tugas. Berhenti polling ketika statusnya SUCCEEDED atau FAILED dan proses hasilnya. jobs.fetch mengembalikan Job (struktur lihat Parameter respons).
import os
import json
import dashscope
# Berikut adalah konfigurasi untuk wilayah Singapura. Saat memanggil, ganti "{WorkspaceId}" dengan ID ruang kerja Anda yang sebenarnya. Nilai region berbeda-beda untuk setiap wilayah.
client = dashscope.Client(
    # Jika Anda belum mengonfigurasi API Key dalam variabel lingkungan, ganti baris berikut dengan API Key Anda: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

# Kirim tugas pengenalan file rekaman
job = client.audio.asr.jobs.create(
    model='paraformer-v2',
    file_urls=['{YOUR_AUDIO_URL}'],
    parameters={'language_hints': ['zh', 'en']}  # "language_hints" hanya didukung oleh model paraformer-v2
)

# Lakukan polling tugas hingga mendapatkan hasil akhir
while True:
    if job.status == 'SUCCEEDED' or job.status == 'FAILED':
        break
    job = client.audio.asr.jobs.fetch(job.task_id)

print(json.dumps(job.model_dump(), indent=4, ensure_ascii=False))
print('transkripsi selesai!')

Parameter permintaan

Parameter permintaan diatur melalui metode jobs.create/transcribe dari sumber daya inti (client.audio.asr).
ParameterTypeDefaultWajibDeskripsi
modelstr
YaNama model untuk transkripsi file audio dan video Paraformer. Model yang didukung.
file_urlslist[str]
YaDaftar 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_idstr
TidakID kosakata kustom. Didukung untuk model seri v2; memerlukan konfigurasi bahasa. Dinonaktifkan secara default. Kosakata Kustom.
channel_idlist[int][0]TidakMenentukan 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.
Setiap trek yang ditentukan ditagih secara independen. Misalnya, meminta [0, 1] untuk satu file menghasilkan dua tagihan terpisah.
disfluency_removal_enabledboolFalseTidakMenyaring kata-kata pengisi. Dinonaktifkan secara default.
timestamp_alignment_enabledboolFalseTidakMengaktifkan penyelarasan timestamp. Dinonaktifkan secara default.
special_word_filterstr
TidakMenentukan 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:
  • Ganti dengan *: Ganti kata sensitif yang cocok dengan * dengan panjang yang sama.
  • Filter langsung: Hapus sepenuhnya kata sensitif yang cocok dari hasil pengenalan.
Nilai parameter ini harus berupa string JSON dengan struktur berikut:
{
  "filter_with_signed": {
    "word_list": ["test"]
  },
  "filter_with_empty": {
    "word_list": ["start", "happen"]
  },
  "system_reserved_filter": true
}
Deskripsi bidang JSON:
  • filter_with_signed
    • Tipe: Object.
    • Wajib: Tidak.
    • Deskripsi: Mengonfigurasi daftar kata sensitif yang akan diganti dengan *. Kata yang cocok dalam hasil pengenalan akan diganti dengan * dengan panjang yang sama.
    • Contoh: Menggunakan JSON di atas, hasil pengenalan ucapan untuk "Help me test this code" akan menjadi "Help me **** this code".
    • Bidang internal:
      • word_list: Array string yang mencantumkan kata sensitif yang akan diganti.
  • filter_with_empty
    • Tipe: Object.
    • Wajib: Tidak.
    • Deskripsi: Mengonfigurasi daftar kata sensitif yang akan dihapus (difilter) dari hasil pengenalan. Kata yang cocok akan dihapus sepenuhnya.
    • Contoh: Menggunakan JSON di atas, hasil pengenalan ucapan untuk "The game is about to start, right?" akan menjadi "The game is about to, right?".
    • Bidang internal:
      • word_list: Array string yang mencantumkan kata sensitif yang akan dihapus sepenuhnya (difilter).
  • system_reserved_filter
    • Tipe: Boolean.
    • Wajib: Tidak.
    • Default: true.
    • Deskripsi: Apakah akan mengaktifkan aturan kata sensitif bawaan sistem. Ketika diatur ke true, logika penyaringan kata sensitif bawaan sistem juga diaktifkan, dan kata-kata yang cocok dengan daftar kata sensitif Alibaba Cloud Model Studio dalam hasil pengenalan akan diganti dengan * dengan panjang yang sama.
language_hintslist[str]["zh", "en"]TidakMenentukan kode bahasa dari ucapan yang akan dikenali.Parameter ini hanya berlaku untuk model paraformer-v2.Kode bahasa yang didukung:
  • zh: Bahasa Tiongkok
  • en: Bahasa Inggris
  • ja: Bahasa Jepang
  • yue: Bahasa Kanton
  • ko: Bahasa Korea
  • de: Bahasa Jerman
  • fr: Bahasa Prancis
  • ru: Bahasa Rusia
diarization_enabledboolFalseTidakDiarisasi 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.
Untuk contoh speaker_id, lihat Deskripsi hasil pengenalan.
speaker_countint
TidakJumlah 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.
Contoh Job yang dikembalikan oleh metode jobs.create (tugas dalam status PENDING setelah dikirim):
{
    "request_id":"251aceab-a6aa-9fc4-b7f7-0cc6d3e2a9f3",
    "task_id":"7d0a58a3-1dbe-4de9-8cff-5f48213128b0",
    "status":"PENDING"
}
Contoh Job yang dikembalikan oleh jobs.fetch, jobs.wait (serta transcribe satu langkah):
{
    "request_id":"251aceab-a6aa-9fc4-b7f7-0cc6d3e2a9f3",
    "task_id":"7d0a58a3-1dbe-4de9-8cff-5f48213128b0",
    "status":"PENDING",
    "task_metrics":{
        "TOTAL":1,
        "SUCCEEDED":0,
        "FAILED":0
    }
}
Parameter yang perlu diperhatikan:

Parameter

Deskripsi

request_id

ID yang dihasilkan sistem untuk mengidentifikasi pemanggilan ini.

task_id

ID tugas.

status

Status tugas.

Keempat status tersebut adalah PENDING, RUNNING, SUCCEEDED, dan FAILED.

Ketika sebuah tugas berisi beberapa subtugas, jika ada subtugas yang berhasil, status seluruh tugas ditandai sebagai SUCCEEDED. Periksa bidang subtask_status untuk menentukan hasil setiap subtugas tertentu.

results

Hasil pengenalan sub-tugas; setiap item memuat file_url, transcription_url, subtask_status; lihat Hasil pengenalan sub-tugas.

subtask_status

Status sub-tugas.

Keempat status tersebut adalah PENDING, RUNNING, SUCCEEDED, dan FAILED.

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 transcription_url atau baca isinya melalui permintaan HTTP. Untuk detail konten file JSON, lihat Deskripsi hasil pengenalan.

usage

Informasi meteran, memuat duration (durasi audio, dalam detik).

Saat pemanggilan gagal, Python SDK akan melempar pengecualian DashScopeError; kode error, kode status HTTP, pesan error, dan ID permintaan dapat diperoleh melalui e.code/e.status_code/e.message/e.request_id. Kegagalan sub-tugas tidak melempar pengecualian; periksa 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.
  • Status SUCCEEDED
  • Status FAILED
{
    "file_url":"{YOUR_AUDIO_URL}",
    "transcription_url":"https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/paraformer-v2/20250213/17%3A59/70e737cc-bf8c-418b-b0c8-83fab192a0fa-1.json?Expires=1739527168&OSSAccessKeyId=YOUR_ACCESS_KEY_ID&Signature=YOUR_SIGNATURE",
    "subtask_status":"SUCCEEDED"
}
Parameter yang perlu diperhatikan:

Parameter

Deskripsi

code

Kode kesalahan. Gunakan bersama bidang message dan rujuk Kode kesalahan untuk troubleshooting.

message

Pesan kesalahan. Gunakan bersama bidang code dan rujuk Kode kesalahan untuk troubleshooting.

subtask_status

Status sub-tugas.

Keempat status tersebut adalah PENDING, RUNNING, SUCCEEDED, dan FAILED.

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 transcription_url atau baca isinya melalui permintaan HTTP. Untuk detail konten file JSON, lihat Deskripsi hasil pengenalan.

Deskripsi hasil pengenalan

Hasil pengenalan disimpan sebagai file JSON.
{
    "file_url":"{YOUR_AUDIO_URL}",
    "properties":{
        "audio_format":"pcm_s16le",
        "channels":[
            0
        ],
        "original_sampling_rate":16000,
        "original_duration_in_milliseconds":3834
    },
    "transcripts":[
        {
            "channel_id":0,
            "content_duration_in_milliseconds":3720,
            "text":"Hello world, this is the Alibaba speech laboratory.",
            "sentences":[
                {
                    "begin_time":100,
                    "end_time":3820,
                    "text":"Hello world, this is the Alibaba speech laboratory.",
                    "sentence_id":1,
                    "speaker_id":0, //Bidang ini hanya ditampilkan ketika diarisasi pembicara otomatis diaktifkan
                    "words":[
                        {
                            "begin_time":100,
                            "end_time":596,
                            "text":"Hello ",
                            "punctuation":""
                        },
                        {
                            "begin_time":596,
                            "end_time":844,
                            "text":"world",
                            "punctuation":", "
                        }
                        // Konten lainnya dihilangkan di sini
                    ]
                }
            ]
        }
    ]
}
Parameter utama adalah sebagai berikut:

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 anggotaSignature metodeDeskripsi
transcribe
def transcribe(self,
               file_urls: List[str],
               *,
               model: str = "paraformer-v2",
               parameters: Dict = None,
               phrase_id: str = None,
               timeout: float = ...,
               ...) -> Job
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
def create(self,
           *,
           model: str,
           file_urls: List[str],
           parameters: Dict = None,
           phrase_id: str = None,
           ...) -> Job
Mengirim tugas pengenalan ucapan secara asinkron.Metode ini mengembalikan Job (job.task_id/job.status).
jobs.wait
def wait(self,
         task: Union[str, Job],
         poll_interval: float = 1,
         timeout: float = 86400,
         ...) -> Job
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
def fetch(self,
          task_id: str,
          ...) -> Job
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:
{
    "task_id": "7bac899c-06ec-4a79-8875-xxxxxxxxxxxx",
    "task_status": "SUCCEEDED",
    "submit_time": "2024-12-16 16:30:59.170",
    "scheduled_time": "2024-12-16 16:30:59.204",
    "end_time": "2024-12-16 16:31:02.375",
    "results": [
        {
            "file_url": "{YOUR_AUDIO_URL}",
            "code": "InvalidFile.DownloadFailed",
            "message": "File audio tidak dapat diunduh.",
            "subtask_status": "FAILED"
        }
    ],
    "task_metrics": {
        "TOTAL": 1,
        "SUCCEEDED": 0,
        "FAILED": 1
    }
}

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):
Sebagai contoh:
  • 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.
Unggah file audio berdasarkan metode penyimpanan/hosting yang Anda pilih, misalnya:
  • 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.
Sebagai contoh:
  • 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.
  • server web:
    • URL akses file biasanya alamat server ditambah jalur file (seperti https://your-domain.com/audio/file.mp3).
  • CDN:
    • Setelah mengonfigurasi akselerasi CDN, gunakan URL yang disediakan CDN (seperti https://cdn.your-domain.com/audio/file.mp3).
Di lingkungan jaringan publik, pastikan URL yang dihasilkan dapat diakses, misalnya:
  • Buka URL di browser dan periksa apakah file audio dapat diputar.
  • Gunakan alat (seperti curl atau Postman) untuk memverifikasi apakah URL mengembalikan respons HTTP yang benar (kode status 200).
Saat menggunakan SDK, jika file audio disimpan di Alibaba Cloud OSS, URL sementara dengan awalan 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 pengaturan language_hints sudah benar.
  • Jika tidak ada yang di atas yang menyelesaikan masalah, Anda dapat menyesuaikan hot word untuk meningkatkan pengenalan kata-kata tertentu.

Pertanyaan lainnya

Kunjungi halaman QA di GitHub.