Alibaba Cloud Model Studio menyediakan OpenAI-compatible Batch File API yang memungkinkan pengiriman permintaan secara massal melalui file. Sistem memproses permintaan tersebut secara asinkron dan mengembalikan hasil ketika semua permintaan selesai atau waktu tunggu maksimum tercapai. Biayanya hanya 50% dari panggilan real-time, sehingga ideal untuk analitik data, evaluasi model, dan beban kerja skala besar lainnya di mana latensi tidak kritis.
Alur kerja
Prasyarat
Anda dapat memanggil Batch File API melalui OpenAI SDK (Python, Node.js) atau HTTP API.
- Dapatkan Kunci API: Dapatkan dan konfigurasikan Kunci API Model Studio Anda sebagai variabel lingkungan
- Instal SDK (opsional): Instal OpenAI SDK jika Anda berencana menggunakannya.
-
Titik akhir layanan
- North China 2 (Beijing):
https://dashscope.aliyuncs.com/compatible-mode/v1 - Singapura:
https://dashscope-intl.aliyuncs.com/compatible-mode/v1
- North China 2 (Beijing):
Cakupan
- Singapura
- Tiongkok (Beijing)
Mulai
Sebelum memproses tugas formal, uji dengan batch-test-model. Model uji ini melewati inferensi dan mengembalikan respons sukses tetap, sehingga Anda dapat memverifikasi rantai panggilan API dan format data Anda.
- File uji Anda harus memenuhi Persyaratan file input. Ukuran maksimum: 1 MB. Jumlah baris maksimum: 100.
- Batas konkurensi: Maksimal 2 tugas paralel.
- Biaya: Model uji tidak dikenakan biaya inferensi model.
Langkah 1: Siapkan file input
Siapkan file bernama test_model.jsonl dengan konten berikut:
Langkah 2: Jalankan kode
Pilih potongan kode sesuai bahasa pemrograman Anda. Simpan di direktori yang sama dengan file input Anda dan jalankan. Kode ini menangani seluruh alur kerja: unggah, buat tugas, periksa status, dan unduh hasil.
Untuk menyesuaikan jalur file atau parameter lainnya, modifikasi kode sesuai kebutuhan.
file-batch-xxx) dapat digunakan kembali. Jika konten input tetap sama, lewati pengunggahan ulang dan langsung buat tugas dengan ID yang ada:client.files.list(purpose="batch") untuk menanyakan ID file Batch yang telah diunggah.Kode contoh
Kode contoh
Langkah 3: Verifikasi hasil uji
Setelah tugas berhasil, file hasil result.jsonl berisi respons tetap {"content":"This is a test result."}:
Jalankan tugas formal
Persyaratan file input
- Format: JSONL berkode UTF-8 (satu objek JSON independen per baris).
- Batas ukuran: Maksimum 50.000 permintaan per file, maksimum 500 MB.
- Batas baris: Setiap objek JSON tidak boleh melebihi 6 MB dan harus sesuai dalam jendela konteks model.
- Konsistensi: Semua permintaan dalam file yang sama harus menggunakan model yang sama dan mode thinking yang sama (jika berlaku).
- Pengenal unik: Setiap permintaan harus menyertakan field custom_id unik dalam file tersebut. Field ini digunakan untuk mencocokkan permintaan dengan hasil.
String Base64 dalam contoh di atas dipotong. Hasilkan encoding lengkap menggunakan kode Python di bawah ini.
Kirim string berkode Base64 (menggunakan gambar sebagai contoh)
Kirim string berkode Base64 (menggunakan gambar sebagai contoh)
- Konversi file lokal ke encoding Base64:
-
Buat format Data URL:
data:[MIME_type];base64,{base64_image};- Ganti
MIME_typedengan jenis media aktual. Harus sesuai dengan nilaiMIME Type(misalnya,image/jpeg,image/png); base64_imageadalah string Base64 yang dihasilkan pada langkah sebelumnya.
- Ganti
1. Modifikasi file input
-
Dalam file
test_model.jsonl, atur parametermodelke model target dan atur fieldurl:Jenis model
url
Model generasi teks/model multimodal
/v1/chat/completionsModel text embedding
/v1/embeddings -
Atau gunakan "Alat pembuatan batch JSONL" di atas untuk membuat file baru untuk tugas formal. Pastikan field
modeldanurlbenar.
2. Ubah kode Getting Started
- Ubah jalur file input ke nama file Anda.
- Atur parameter endpoint agar sesuai dengan field url dalam file input Anda.
3. Jalankan kode dan tunggu hasil
Ketika tugas selesai, hasil permintaan yang berhasil disimpan ke file result.jsonl lokal. Jika ada permintaan yang gagal, detail error disimpan ke file error.jsonl.
- Hasil yang berhasil (
output_file_id): Setiap baris sesuai dengan satu permintaan yang berhasil dan mencakupcustom_iddanresponse.
- Detail kegagalan (
error_file_id): Berisi informasi tentang permintaan yang gagal dengan nomor baris dan alasan error. Lihat Kode error untuk troubleshooting.
Prosedur detail
Alur kerja Batch API terdiri dari empat langkah: unggah file, buat tugas, tanyakan status tugas, dan unduh hasil.
1. Unggah file
1. Unggah file
file_id.Saat mengunggah file, parameterpurposeharusbatch.
file-batch-xxx) dapat digunakan kembali. Jika konten input tetap sama, lewati pengunggahan ulang dan langsung buat tugas dengan ID yang ada:client.files.list(purpose="batch") untuk menanyakan ID file Batch yang telah diunggah.- OpenAI Python SDK
- OpenAI Node.js SDK
- Java (HTTP)
- curl (HTTP)
Contoh permintaan
Contoh respons
2. Buat tugas batch
2. Buat tugas batch
- OpenAI Python SDK
- OpenAI Node.js SDK
- Java (HTTP)
- curl (HTTP)
Contoh permintaan
Parameter input
Field | Tipe | Metode | Wajib | Deskripsi |
|---|---|---|---|---|
input_file_id | String | Body | Ya | ID file input. Gunakan ID file yang dikembalikan oleh API Siapkan dan unggah file, seperti |
endpoint | String | Body | Ya | Jalur akses API. Harus sesuai dengan field url dalam file input.
|
completion_window | String | Body | Ya | Waktu tunggu maksimum. Rentang: 24h-336h, hanya bilangan bulat. Unit: "h" atau "d" (misalnya, "24h" atau "14d"). |
metadata | Map | Body | Tidak | Metadata tambahan untuk tugas, ditentukan sebagai pasangan kunci-nilai. |
metadata.ds_name | String | Body | Tidak | Nama tugas. Contoh: Panjang maksimum: 100 karakter. Jika ditentukan beberapa kali, nilai terakhir yang berlaku. |
metadata.ds_description | String | Body | Tidak | Deskripsi tugas. Contoh: Panjang maksimum: 200 karakter. Jika ditentukan beberapa kali, nilai terakhir yang berlaku. |
Contoh respons
Parameter respons
Field | Type | Deskripsi |
|---|---|---|
id | String | ID tugas batch. |
object | String | Nilai tetap: |
endpoint | String | Jalur akses API. |
errors | Map | Informasi error. |
input_file_id | String | ID file input . |
completion_window | String | Waktu tunggu maksimum. Rentang: 24h-336h, hanya bilangan bulat. Unit: "h" atau "d" (misalnya, "24h" atau "14d"). |
status | String | Status tugas: validating, failed, in_progress, finalizing, completed, expired, cancelling, cancelled. |
output_file_id | String | ID file untuk hasil permintaan yang berhasil. |
error_file_id | String | ID file untuk hasil permintaan yang gagal. |
created_at | Integer | Timestamp Unix (detik) saat tugas dibuat. |
in_progress_at | Integer | Timestamp Unix (detik) saat tugas mulai diproses. |
expires_at | Integer | Timestamp Unix (detik) saat tugas mulai timeout. |
finalizing_at | Integer | Timestamp Unix (detik) saat tugas terakhir dimulai. |
completed_at | Integer | Timestamp Unix (detik) saat tugas selesai. |
failed_at | Integer | Timestamp Unix (detik) saat tugas gagal. |
expired_at | Integer | Timestamp Unix (detik) saat tugas kedaluwarsa. |
cancelling_at | Integer | Timestamp Unix (detik) saat tugas memasuki status cancelling. |
cancelled_at | Integer | Timestamp Unix (detik) saat tugas dibatalkan. |
request_counts | Map | Jumlah permintaan berdasarkan status. |
metadata | Map | Metadata tambahan sebagai pasangan kunci-nilai. |
metadata.ds_name | String | Nama tugas. |
metadata.ds_description | String | Deskripsi tugas. |
3. Tanyakan dan kelola tugas batch
3. Tanyakan dan kelola tugas batch
Tanyakan status tugas tertentu
Tanyakan status tugas tertentu
- OpenAI Python SDK
- OpenAI Node.js SDK
- Java (HTTP)
- curl (HTTP)
Contoh permintaan
Contoh respons
Permintaan yang berhasil mengembalikan informasi detail tugas batch. Berikut adalah contoh respons untuk tugas dengan status completed:Field | Tipe | Deskripsi |
|---|---|---|
id | String | ID tugas batch. |
status | String | Status tugas. Nilai yang mungkin:
|
output_file_id | String | ID file output yang berisi hasil yang berhasil. Dihasilkan setelah tugas selesai. |
error_file_id | String | ID file error yang berisi detail permintaan yang gagal. Dihasilkan setelah tugas selesai jika ada permintaan yang gagal. |
request_counts | Object | Statistik jumlah permintaan yang berisi total, completed, dan failed. |
Tanyakan daftar tugas
Tanyakan daftar tugas
batches.list() untuk mengambil daftar tugas batch. Gunakan pagination untuk mengambil daftar tugas lengkap.- OpenAI Python SDK
- OpenAI Node.js SDK
- Java (HTTP)
- curl (HTTP)
Contoh permintaan
Parameter input
Field | Tipe | Metode | Wajib | Deskripsi |
|---|---|---|---|---|
after | String | Kueri | Tidak | Kursor untuk pagination. Atur ini ke ID tugas terakhir dari halaman sebelumnya. |
limit | Integer | Kueri | Tidak | Jumlah tugas per halaman. Rentang: [1, 100]. Default: 20. |
ds_name | String | Kueri | Tidak | Pencocokan fuzzy berdasarkan nama tugas. |
input_file_ids | String | Kueri | Tidak | Filter berdasarkan ID file. Tentukan beberapa ID yang dipisahkan koma (maksimal 20). |
status | String | Kueri | Tidak | Filter berdasarkan status tugas. Tentukan beberapa status yang dipisahkan koma. |
create_after | String | Kueri | Tidak | Filter tugas yang dibuat setelah waktu ini. Format: |
create_before | String | Kueri | Tidak | Filter tugas yang dibuat sebelum waktu ini. Format: |
Contoh respons
Parameter respons
Field | Tipe | Deskripsi |
|---|---|---|
object | String | Jenis objek. Nilai tetap: list. |
data | Array | Array objek tugas batch. Lihat parameter respons untuk membuat tugas batch. |
first_id | String | ID tugas batch pertama pada halaman saat ini. |
last_id | String | ID tugas batch terakhir pada halaman saat ini. |
has_more | Boolean | Apakah halaman tambahan tersedia. |
Batalkan tugas batch
Batalkan tugas batch
- OpenAI Python SDK
- OpenAI Node.js SDK
- Java (HTTP)
- curl (HTTP)
Contoh permintaan
Contoh respons
Setelah Anda berhasil membatalkan tugas, API mengembalikan informasi detail tugas batch. Berikut adalah contoh respons untuk tugas dengan status cancelling:Setelah Anda membatalkan tugas, status pertama kali berubah menjadicancellingsementara sistem menunggu permintaan yang sedang dieksekusi selesai. Status akhirnya berubah menjadicancelled. Hasil dari permintaan yang berhasil diselesaikan tetap disimpan dalam file output.
4. Unduh file hasil Batch
4. Unduh file hasil Batch
file_id-nya diawali dengan file-batch_output.- OpenAI Python SDK
- OpenAI Node.js SDK
- Java (HTTP)
- curl (HTTP)
content untuk mengambil konten file hasil tugas batch dan gunakan metode write_to_file untuk menyimpannya secara lokal.Contoh permintaan
Contoh respons
Contoh respons
Contoh respons tunggal:Parameter respons
Field | Tipe | Deskripsi |
|---|---|---|
id | String | ID permintaan. |
custom_id | String | Pengenal permintaan yang ditentukan pengguna. |
response | Object | Hasil permintaan. |
status_code | Integer | Kode status HTTP. 200 menunjukkan sukses. |
request_id | String | ID unik yang dihasilkan server untuk permintaan ini. |
completion_tokens | Integer | Jumlah token dalam respons yang dihasilkan model. |
prompt_tokens | Integer | Jumlah token dalam konten input ( |
total_tokens | Integer | Total jumlah token yang digunakan oleh permintaan ini. |
model | String | Nama model yang digunakan untuk permintaan ini. |
error | Object | Objek error. Mengembalikan |
error.code | String | Informasi baris error dan alasannya. Lihat Kode error untuk troubleshooting. |
error.message | String | Pesan error. |
Fitur lanjutan
Atur notifikasi penyelesaian
Untuk tugas berjalan lama, gunakan notifikasi asinkron alih-alih polling untuk mengurangi konsumsi sumber daya.
- Callback: Tentukan URL yang dapat diakses publik saat membuat tugas.
- Antrian pesan EventBridge: Terintegrasi erat dengan ekosistem Alibaba Cloud. Tidak memerlukan IP publik.
Metode 1: Callback
Metode 1: Callback
metadata. Setelah tugas selesai, sistem mengirim permintaan POST yang berisi status tugas ke URL yang ditentukan:- OpenAI Python SDK
- curl (HTTP)
Metode 2: Antrian pesan EventBridge
Metode 2: Antrian pesan EventBridge
- Sumber event (Source):
acs.dashscope - Jenis event (Type):
dashscope:System:BatchTaskFinish
Mulai produksi
-
Manajemen file
- Hapus file yang tidak diperlukan secara berkala menggunakan OpenAI File delete API untuk menghindari mencapai batas penyimpanan (10.000 file atau 100 GB).
- Simpan file besar di OSS alih-alih mengunggah langsung.
-
Pemantauan tugas
- Gunakan notifikasi asinkron Callback atau EventBridge.
- Jika polling diperlukan, atur interval lebih dari 1 menit dan gunakan strategi backoff eksponensial.
-
Penanganan error
- Implementasikan penanganan untuk error jaringan, error API, dan exception lainnya.
- Unduh dan analisis detail error dari
error_file_id. - Untuk kode error umum, lihat Kode error.
-
Optimasi biaya
- Gabungkan tugas kecil menjadi satu batch.
- Atur
completion_windowsecara tepat untuk memungkinkan fleksibilitas penjadwalan yang lebih besar.
Alat utilitas
CSV ke JSONL
CSV ke JSONL
Untuk menyesuaikan jalur file atau parameter lainnya, modifikasi kode sesuai kebutuhan.
Hasil JSONL ke CSV
Hasil JSONL ke CSV
result.jsonl menjadi result.csv untuk analisis di Excel.Untuk menyesuaikan jalur file atau parameter lainnya, modifikasi kode sesuai kebutuhan.
- Gunakan editor teks (seperti Sublime Text) untuk mengonversi encoding file CSV ke GBK, lalu buka di Excel.
- Atau, buat file Excel baru dan tentukan encoding UTF-8 saat mengimpor data.
Batas laju
API | Batas laju (per Akun Alibaba Cloud) |
|---|---|
Buat tugas | 1.000 panggilan/menit; maksimal 1.000 tugas konkuren |
Tanyakan tugas | 1.000 panggilan/menit |
Tanyakan daftar tugas | 100 panggilan/menit |
Batalkan tugas | 1.000 panggilan/menit |
Penagihan
- Harga satuan: Token input dan output untuk semua permintaan yang berhasil dikenai biaya sebesar 50% dari harga inferensi real-time untuk model yang sesuai. Untuk informasi lebih lanjut, lihat Daftar model.
-
Lingkup penagihan:
- Hanya permintaan yang berhasil dieksekusi dalam tugas yang dikenai biaya.
- Permintaan yang gagal karena error parsing file, kegagalan eksekusi tugas, atau error tingkat baris tidak dikenai biaya.
- Untuk tugas yang dibatalkan, permintaan yang berhasil diselesaikan sebelum pembatalan tetap dikenai biaya seperti biasa.
- Inferensi batch adalah item penagihan terpisah. Mendukung rencana penghematan AI universal, tetapi tidak mendukung diskon seperti langganan (rencana penghematan lainnya) atau kuota gratis untuk pengguna baru. Juga tidak mendukung fitur seperti cache konteks.
- Beberapa model, seperti qwen3.5-plus dan qwen3.5-flash, memiliki mode thinking yang diaktifkan secara default. Mode ini menghasilkan token thinking tambahan, yang dikenai biaya sesuai harga token output dan meningkatkan biaya. Untuk mengontrol biaya, atur parameter
enable_thinkingberdasarkan kompleksitas tugas. Untuk informasi lebih lanjut, lihat Deep thinking.
Kode error
Jika permintaan gagal dan mengembalikan pesan error, lihat Kode error untuk solusinya.
FAQ
- Bagaimana cara memilih antara Batch Chat dan Batch File? Gunakan Batch File ketika Anda perlu memproses file besar yang berisi banyak permintaan secara asinkron. Gunakan Batch Chat ketika logika bisnis Anda memerlukan pengiriman banyak permintaan obrolan independen secara sinkron dengan konkurensi tinggi.
- Bagaimana penagihan API Batch File? Apakah saya perlu membeli paket terpisah? Batch menggunakan penagihan bayar sesuai penggunaan berdasarkan token yang dikonsumsi oleh permintaan yang berhasil. Tidak diperlukan paket sumber daya terpisah.
- Apakah file batch yang dikirim dieksekusi secara berurutan? Tidak. Sistem menggunakan penjadwalan dinamis berdasarkan beban komputasi dan tidak menjamin urutan eksekusi. Tugas mungkin tertunda ketika sumber daya terbatas.
- Berapa lama waktu yang dibutuhkan untuk menyelesaikan file batch yang dikirim? Waktu eksekusi tergantung pada sumber daya sistem dan skala tugas. Jika tugas tidak selesai dalam completion_window, tugas tersebut kedaluwarsa. Permintaan yang tidak diproses dalam tugas yang kedaluwarsa tidak dieksekusi dan tidak dikenai biaya. Rekomendasi skenario: Gunakan panggilan real-time untuk skenario yang memerlukan inferensi model real-time ketat. Gunakan panggilan batch untuk skenario pemrosesan data skala besar yang dapat mentolerir penundaan.