Alibaba Cloud Model Studio menyediakan API File Batch yang kompatibel dengan OpenAI. API ini memungkinkan Anda mengirimkan tugas batch melalui file. Sistem memproses tugas tersebut secara asinkron dan mengembalikan hasil setelah tugas selesai atau waktu tunggu maksimum tercapai. Biayanya 50% dari panggilan real-time, sehingga ideal untuk layanan seperti analitik data dan evaluasi model yang memerlukan pemrosesan skala besar namun tidak sensitif terhadap latensi.
Untuk melakukan operasi ini di konsol, lihat Inferensi batch.
Alur kerja
Prasyarat
Anda dapat memanggil API File Batch menggunakan SDK OpenAI untuk Python atau Node.js, atau melalui panggilan API HTTP.
-
Dapatkan Kunci API: Dapatkan dan konfigurasikan Kunci API sebagai variabel lingkungan
-
Instal SDK (opsional): Jika menggunakan SDK untuk melakukan panggilan, instal SDK OpenAI.
-
Titik akhir server
-
Tiongkok daratan:
https://dashscope.aliyuncs.com/compatible-mode/v1 -
Internasional:
https://dashscope-intl.aliyuncs.com/compatible-mode/v1
-
Ketersediaan
Internasional
Dalam mode penyebaran internasional, baik titik akhir maupun penyimpanan data berlokasi di Wilayah Singapura. Sumber daya komputasi inferensi model dijadwalkan secara dinamis di seluruh wilayah global, kecuali Tiongkok daratan.
Model yang didukung: qwen-max, qwen-plus, qwen-flash, qwen-turbo.
Tiongkok daratan
Dalam mode penyebaran Tiongkok daratan, baik titik akhir maupun penyimpanan data berlokasi di Wilayah Beijing. Sumber daya komputasi inferensi model hanya tersedia di Tiongkok daratan.
Model yang didukung:
Model generasi teks: Versi stabil Qwen-Max, Plus, Flash, dan Long, serta beberapa versi
latest. Seri QwQ (qwq-plus) dan beberapa model pihak ketiga (deepseek-r1, deepseek-v3) juga didukung.Model multimodal: Versi stabil Qwen-VL-Max, Plus, dan Flash, ditambah beberapa versi
latest. Model Qwen-OCR juga didukung.Model text embedding: text-embedding-v4.
Beberapa model mendukung mode pemikiran. Saat diaktifkan, mode ini menghasilkan
tokenpemikiran dan meningkatkan biaya.Seri
qwen3.5(sepertiqwen3.5-plusdanqwen3.5-flash) mengaktifkan mode pemikiran secara default. Saat menggunakan model hybrid-thinking, atur eksplisit parameterenable_thinking(trueataufalse).
Mulai
Sebelum memproses tugas formal, Anda dapat menggunakan model uji batch-test-model untuk melakukan pengujian tertutup end-to-end guna memverifikasi bahwa rantai panggilan API dan format data sudah benar.
Batasan model uji (batch-test-model):
-
File uji harus memenuhi persyaratan file input. Ukuran file tidak boleh melebihi 1 MB, dan jumlah baris tidak boleh melebihi 100.
-
Batas konkurensi: Jumlah maksimum tugas paralel adalah 2.
-
Biaya: Model uji tidak dikenakan biaya inferensi model.
Langkah 1: Siapkan file input
Siapkan file bernama test_model.jsonl dengan konten berikut:
{"custom_id":"1","method":"POST","url":"/v1/chat/ds-test","body":{"model":"batch-test-model","messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"Hello! How can I help you?"}]}}
{"custom_id":"2","method":"POST","url":"/v1/chat/ds-test","body":{"model":"batch-test-model","messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"What is 2+2?"}]}}
Langkah 2: Jalankan kode
Pilih kode contoh untuk bahasa pemrograman Anda, simpan di direktori yang sama dengan file input, lalu jalankan. Kode ini menyelesaikan seluruh proses mengunggah file, membuat tugas, memeriksa status secara berkala, dan mengunduh hasil.
Untuk menyesuaikan path file atau parameter lainnya, Anda dapat memodifikasi kode sesuai kebutuhan.
Langkah 3: Verifikasi hasil uji
Setelah tugas berhasil selesai, file hasil result.jsonl akan berisi respons tetap {"content":"This is a test result."}:
{"id":"a2b1ae25-21f4-4d9a-8634-99a29926486c","custom_id":"1","response":{"status_code":200,"request_id":"a2b1ae25-21f4-4d9a-8634-99a29926486c","body":{"created":1743562621,"usage":{"completion_tokens":6,"prompt_tokens":20,"total_tokens":26},"model":"batch-test-model","id":"chatcmpl-bca7295b-67c3-4b1f-8239-d78323bb669f","choices":[{"finish_reason":"stop","index":0,"message":{"content":"This is a test result."}}],"object":"chat.completion"}},"error":null}
{"id":"39b74f09-a902-434f-b9ea-2aaaeebc59e0","custom_id":"2","response":{"status_code":200,"request_id":"39b74f09-a902-434f-b9ea-2aaaeebc59e0","body":{"created":1743562621,"usage":{"completion_tokens":6,"prompt_tokens":20,"total_tokens":26},"model":"batch-test-model","id":"chatcmpl-1e32a8ba-2b69-4dc4-be42-e2897eac9e84","choices":[{"finish_reason":"stop","index":0,"message":{"content":"This is a test result."}}],"object":"chat.completion"}},"error":null}
Jalankan tugas formal
Persyaratan file input
-
Format: JSONL dengan encoding UTF-8 (satu objek JSON independen per baris)
-
Batas ukuran: Satu file dapat berisi hingga 50.000 permintaan dan tidak boleh lebih besar dari 500 MB.
-
Batas baris: Setiap objek JSON tidak boleh melebihi 6 MB dan tidak boleh melebihi panjang konteks model.
-
Persyaratan konsistensi: Semua permintaan dalam file yang sama harus menggunakan model dan mode pemikiran yang sama (jika berlaku).
-
Pengenal unik: Setiap permintaan harus menyertakan field `custom_id` yang unik dalam file tersebut. Ini digunakan untuk mencocokkan hasil.
Contoh konten file:
{"custom_id":"1","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-plus","messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"Hello!"}]}}
{"custom_id":"2","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-plus","messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"What is 2+2?"}]}}Alat pembuatan batch JSONL
Gunakan alat ini untuk menghasilkan file JSONL dengan cepat.
1. Modifikasi File Input
-
Anda dapat langsung memodifikasi file
test_model.jsonlyang digunakan untuk pengujian. Atur parameter model ke model produksi yang ingin Anda gunakan, dan atur field url.Jenis Model
URL
Model Generasi Teks/Multimodal
/v1/chat/completionsModel Text Embedding
/v1/embeddings -
Atau, Anda dapat menggunakan Alat Pembuatan Batch JSONL untuk menghasilkan file baru untuk tugas produksi. Pastikan field
modeldanurlsudah benar.
2. Modifikasi Kode QuickStart
-
Ubah path file input ke nama file Anda.
-
Modifikasi nilai parameter endpoint agar sesuai dengan field url dalam file input.
3. Jalankan Kode dan Tunggu Hasil
Setelah tugas berhasil, hasil permintaan yang berhasil disimpan di file lokal result.jsonl. Jika beberapa permintaan gagal, detail error disimpan di file error.jsonl.
-
Hasil yang berhasil (
output_file_id): Setiap baris merepresentasikan permintaan yang berhasil dan berisicustom_iddanresponse.{"id":"3a5c39d5-3981-4e4c-97f2-e0e821893f03","custom_id":"req-001","response":{"status_code":200,"request_id":"3a5c39d5-3981-4e4c-97f2-e0e821893f03","body":{"created":1768306034,"usage":{"completion_tokens":654,"prompt_tokens":14,"total_tokens":668},"model":"qwen-plus","id":"chatcmpl-3a5c39d5-3981-4e4c-97f2-e0e821893f03","choices":[{"finish_reason":"stop","index":0,"message":{"role":"assistant","content":"Hello! West Lake in Hangzhou is a famous scenic area in China, located in the western part of Hangzhou, Zhejiang Province, hence its name 'West Lake'. It is one of China's top ten scenic spots and a World Cultural Heritage site (listed in UNESCO's World Heritage List in 2011), renowned for its beautiful natural scenery and profound cultural heritage.\n\n### I. Natural Landscape\nWest Lake is surrounded by mountains on three sides and borders the city on one side. Its surface area is about 6.39 square kilometers, shaped like a Ruyi scepter, with shimmering blue waters. The lake is divided into multiple water areas by natural or artificial features such as Gushan Mountain, Bai Causeway, Su Causeway, and Yanggong Causeway, forming a pattern of 'one mountain, two pagodas, three islands, and three causeways'.\n\nMajor attractions include the following:\n- **Spring Dawn at Su Causeway**: During the Northern Song Dynasty, the great literati Su Dongpo, while serving as the governor of Hangzhou, oversaw the dredging of West Lake and used the excavated silt to build a causeway, later named 'Su Causeway'. In spring, peach blossoms and willows create a picturesque scene.\n- **Lingering Snow on Broken Bridge**: Located at the eastern end of Bai Causeway, it is the setting for the 'Broken Bridge Reunion' in the Legend of the White Snake. It is especially famous for its silver-clad appearance after a winter snowfall.\n- **Leifeng Pagoda in the Sunset**: Leifeng Pagoda, gleaming golden under the setting sun, was once one of the 'Ten Scenes of West Lake'.\n- **Three Ponds Mirroring the Moon**: Three stone pagodas on Xiaoyingzhou Island in the lake. During the Mid-Autumn Festival, lights can be lit inside the pagodas, creating a beautiful interplay of moonlight, lamplight, and lake reflections.\n- **Autumn Moon Over the Calm Lake**: Located at the western end of Bai Causeway, it is an excellent spot to admire the moon over the lake.\n- **Viewing Fish at Flower Pond**: Known for appreciating flowers and viewing fish, with peonies and koi complementing each other in the garden.\n\n### II. Human History\nWest Lake is not only beautiful but also carries a rich historical and cultural legacy:\n- Since the Tang and Song dynasties, many literati such as Bai Juyi, Su Dongpo, Lin Bu, and Yang Wanli have left poems here.\n- Bai Juyi once oversaw the construction of 'Bai Causeway' and dredged West Lake, benefiting the local people.\n- There are many historical sites around West Lake, such as Yue Fei Temple (commemorating national hero Yue Fei), Lingyin Temple (a thousand-year-old Buddhist temple), Liuhe Pagoda, and Longjing Village (the origin of Longjing tea, one of China's top ten famous teas).\n\n### III. Cultural Symbol\nWest Lake is hailed as a representative of 'heaven on earth' and a model of traditional Chinese landscape aesthetics. It integrates natural beauty with humanistic beauty, embodying the philosophical idea of 'unity of heaven and humanity'. Many poems, paintings, and operas feature West Lake as their theme, making it an important symbol of Chinese culture.\n\n### IV. Travel Tips\n- Best seasons to visit: Spring (March-May) with blooming peach blossoms and green willows, and Autumn (September-November) with clear skies and crisp air.\n- Recommended ways to explore: Walking, cycling (around the lake's greenway), and boating on the lake.\n- Local delicacies: West Lake Fish in Vinegar Gravy, Longjing Shrimp, Dongpo Pork, Pian'er Chuan noodles, etc.\n\nIn summary, Hangzhou West Lake is not only a natural beauty but also a living cultural museum, worth savoring. If you have the chance to visit Hangzhou, do not miss this 'heaven on earth' that is 'always beautiful, whether lightly or heavily adorned'."}}],"object":"chat.completion"}},"error":null} {"id":"628312ba-172c-457d-ba7f-3e5462cc6899","custom_id":"req-002","response":{"status_code":200,"request_id":"628312ba-172c-457d-ba7f-3e5462cc6899","body":{"created":1768306035,"usage":{"completion_tokens":25,"prompt_tokens":18,"total_tokens":43},"model":"qwen-plus","id":"chatcmpl-628312ba-172c-457d-ba7f-3e5462cc6899","choices":[{"finish_reason":"stop","index":0,"message":{"role":"assistant","content":"Spring breeze brushes green willows,\nNight rain moistens red flowers.\nBirds chirp amidst the forest,\nMountains and rivers are everywhere the same."}}],"object":"chat.completion"}},"error":null} -
Detail kegagalan (
error_file_id): Berisi informasi baris permintaan dan alasan error untuk setiap permintaan yang gagal. Untuk informasi troubleshooting, lihat Kode Kesalahan.
Prosedur
Alur kerja API Batch terdiri dari empat langkah: mengunggah file, membuat tugas Batch, memeriksa status tugas, dan mengunduh hasil.
1. Unggah File
2. Buat Tugas Batch
3. Kueri dan Kelola Tugas Batch
4. Unduh File Hasil Batch
Fitur lanjutan
Konfigurasi notifikasi penyelesaian tugas
Untuk pekerjaan berdurasi panjang, polling bisa menjadi boros sumber daya. Kami menyarankan Anda menggunakan notifikasi asinkron sebagai gantinya. Dengan notifikasi asinkron, sistem secara otomatis memberi tahu Anda ketika pekerjaan selesai.
-
Callback: Tentukan URL yang dapat diakses publik saat Anda membuat pekerjaan.
-
Antrian pesan EventBridge: Metode ini terintegrasi dengan ekosistem Alibaba Cloud dan tidak memerlukan alamat IP publik.
Metode 1: Callback
Metode 2: Antrian pesan EventBridge
Mulai Produksi
-
Manajemen File
-
Secara berkala panggil API Penghapusan File OpenAI untuk menghapus file yang tidak perlu dan menghindari mencapai batas penyimpanan file (10.000 file atau 100 GB).
-
Untuk file besar, simpan di Alibaba Cloud OSS.
-
-
Pemantauan Tugas
-
Lebih disukai pesan notifikasi asinkron Callback atau EventBridge.
-
Gunakan interval polling lebih dari 1 menit dan terapkan kebijakan backoff eksponensial.
-
-
Penanganan Error
-
Implementasikan mekanisme penanganan exception komprehensif yang mencakup error jaringan, error API, dan exception lainnya.
-
Unduh dan analisis detail error yang terkait dengan
error_file_id. -
Untuk solusi kode error umum, lihat Pesan Error.
-
-
Optimasi Biaya
-
Gabungkan tugas kecil menjadi satu batch.
-
Atur parameter
completion_windowuntuk meningkatkan fleksibilitas penjadwalan.
-
Utilitas
CSV ke JSONL
Hasil JSONL ke CSV
Batas Laju Antarmuka
|
Antarmuka |
Batas Laju (tingkat Akun Alibaba Cloud) |
|
Buat tugas |
1000 permintaan/menit, maksimum 1000 tugas konkuren |
|
Kueri tugas |
1000 permintaan/menit |
|
Kueri daftar tugas |
100 permintaan/menit |
|
Batalkan tugas |
1000 permintaan/menit |
Informasi Penagihan
Harga satuan: Token input dan output untuk semua permintaan yang berhasil dikenakan 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 pekerjaan yang ditagih.
Permintaan yang gagal karena error parsing file, kegagalan eksekusi pekerjaan, atau error tingkat baris tidak dikenakan biaya.
Untuk pekerjaan yang dibatalkan, permintaan yang berhasil diselesaikan sebelum pembatalan tetap ditagih secara normal.
Inferensi batch adalah item penagihan terpisah. Tidak memenuhi syarat untuk diskon, seperti langganan (Savings Plan) 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 pemikiran yang diaktifkan secara default. Mode ini menghasilkan token pemikiran tambahan, yang ditagih dengan harga token output dan meningkatkan biaya. Untuk mengontrol biaya, atur parameter `enable_thinking` berdasarkan kompleksitas tugas. Untuk informasi lebih lanjut, lihat Pemikiran mendalam.
Kode kesalahan
Jika panggilan gagal dan mengembalikan pesan error, lihat Pesan error untuk menyelesaikan masalah.
FAQ
-
Kapan saya harus menggunakan Batch Chat atau Batch File?
Gunakan Batch File untuk memproses satu file besar yang berisi banyak permintaan, terutama ketika Anda dapat mengambil file hasil secara asinkron. Gunakan Batch Chat ketika logika aplikasi Anda memerlukan pengiriman volume tinggi permintaan percakapan terpisah secara konkuren melalui panggilan API sinkron.
-
Bagaimana penagihan panggilan Batch File? Apakah saya perlu membeli paket terpisah?
Batch adalah metode pemanggilan yang menggunakan model bayar sesuai penggunaan. Anda ditagih berdasarkan penggunaan token dari permintaan yang berhasil dalam pekerjaan Anda. Tidak diperlukan pembelian paket terpisah.
-
Apakah pekerjaan Batch File yang dikirim dieksekusi sesuai urutan pengiriman?
Tidak. Backend menggunakan mekanisme penjadwalan dinamis. Sistem menjadwalkan eksekusi pekerjaan berdasarkan beban sumber daya komputasi secara keseluruhan saat ini, sehingga urutan eksekusi tidak dijamin. Ketika sumber daya terbatas, startup dan eksekusi pekerjaan mungkin tertunda.
-
Berapa lama waktu yang dibutuhkan pekerjaan Batch File yang dikirim untuk selesai?
Waktu eksekusi tergantung pada alokasi sumber daya sistem dan ukuran pekerjaan Anda. Jika pekerjaan tidak selesai dalam completion_window yang Anda atur, statusnya berubah menjadi expired. Pada titik itu, permintaan yang belum diproses tidak dieksekusi dan tidak dikenakan biaya.
Rekomendasi: Untuk skenario dengan persyaratan real-time ketat untuk inferensi model, gunakan panggilan real-time. Untuk skenario yang memproses data skala besar dan dapat mentolerir beberapa latensi, gunakan panggilan Batch.