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 yang tidak sensitif terhadap latensi.
Untuk menggunakan konsol, lihat panduan konsol.
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
-
China daratan:
https://dashscope.aliyuncs.com/compatible-mode/v1 -
Internasional:
https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
-
Model Studio telah merilis domain khusus ruang kerja untuk wilayah Singapura. Domain khusus baru ini memberikan performa lebih unggul dan stabilitas lebih tinggi untuk permintaan inferensi. Kami merekomendasikan migrasi ke domain baru:
-
Singapura: dari
https://dashscope-intl.aliyuncs.comkehttps://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
{WorkspaceId} adalah ID ruang kerja Anda, yang dapat ditemukan di halaman Detail Ruang Kerja pada konsol Model Studio. Domain lama tetap berfungsi penuh.
Cakupan
Singapura
Model yang didukung: qwen-max, qwen-plus, qwen-flash, qwen-turbo.
China (Beijing)
Model yang didukung:
-
Model generasi teks: Versi stabil dan beberapa versi
latestQwen-Max, Qwen-Plus, Qwen-Flash, dan Qwen-Long. Seri QwQ (qwq-plus) serta beberapa model pihak ketiga (deepseek-r1, deepseek-v3.2, deepseek-v3) juga didukung. -
Model multimodal: Versi stabil dan beberapa versi
latestQwen-VL-Max, Qwen-VL-Plus, dan Qwen-VL-Flash. Model Qwen-OCR juga didukung. -
Model penyematan teks: text-embedding-v4.
-
Dalam skenario pemrosesan batch, jumlah maksimum token konteks per permintaan adalah 256 K untuk
qwen3.7-max,qwen3.7-plus,qwen3.6-plus,qwen3.5-plus, danqwen3.5-flash. -
Beberapa model mendukung mode thinking. Mengaktifkan mode ini menghasilkan
tokenthinking dan meningkatkan biaya. -
Model seri
qwen3.7,qwen3.6, danqwen3.5memiliki mode thinking aktif secara default. Jika Anda menggunakan model hybrid thinking, Anda harus secara eksplisit mengatur parameterenable_thinking. Atur parameter ini ketrueuntuk mengaktifkan mode ataufalseuntuk menonaktifkannya. -
Dalam badan permintaan JSONL,
enable_thinkingadalah parameter tingkat atas daribodydan harus ditempatkan pada level yang sama denganmodel. Jangan letakkan di dalamextra_body.
Mulai
Sebelum memproses tugas formal, uji dengan batch-test-model. Model uji ini melewati inferensi dan mengembalikan respons sukses tetap, memungkinkan Anda memverifikasi rantai panggilan API dan format data Anda.
Batasan batch-test-model:
-
File uji Anda harus memenuhi Persyaratan file masukan. 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 masukan
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?"}]}}
Model multimodal (misalnya, qwen-vl-plus) mendukung URL file dan input Base64:
{"custom_id":"image-url","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-vl-plus","messages":[{"role":"user","content":[{"type":"image_url","image_url":{"url":"https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg"}},{"type":"text","text":"Describe this image."}]}]}}
{"custom_id":"image-base64","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-vl-plus","messages":[{"role":"user","content":[{"type":"image_url","image_url":{"url":"data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEA8ADwAAD..."}},{"type":"text","text":"Describe this image."}]}]}}
Langkah 2: Jalankan kode
Pilih potongan kode untuk bahasa pemrograman Anda. Simpan di direktori yang sama dengan file masukan Anda dan jalankan. Kode ini menangani seluruh alur kerja: unggah, buat tugas, periksa status, dan unduh hasil.
Untuk menyesuaikan jalur file atau parameter lainnya, ubah kode sesuai kebutuhan.
Gunakan kembali ID file yang ada: ID yang dikembalikan setelah mengunggah file (misalnya, file-batch-xxx) dapat digunakan kembali. Jika konten masukan tetap sama, lewati pengunggahan ulang dan langsung buat tugas dengan ID yang ada:
batch = client.batches.create(
input_file_id="file-batch-xxx", # Gunakan kembali ID file yang ada, tidak perlu mengunggah ulang
endpoint="/v1/chat/completions",
completion_window="24h"
)
Anda dapat mengambil ID file historis melalui API client.files.list(purpose="batch") untuk menanyakan ID file Batch yang diunggah.
Langkah 3: Verifikasi hasil uji
Setelah tugas berhasil, file hasil result.jsonl 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 masukan
-
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.
Skenario 1: Obrolan teks
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?"}]}}
Skenario 2: Pemahaman gambar dan video
Model multimodal (misalnya, qwen-vl-plus) mendukung URL file dan input Base64.
{"custom_id":"image-url","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-vl-plus","messages":[{"role":"user","content":[{"type":"image_url","image_url":{"url":"https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg"}},{"type":"text","text":"Describe this image."}]}]}}
{"custom_id":"image-base64","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-vl-plus","messages":[{"role":"user","content":[{"type":"image_url","image_url":{"url":"data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEA8ADwAAD..."}},{"type":"text","text":"Describe this image."}]}]}}
{"custom_id":"video-url","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-vl-plus","messages":[{"role":"user","content":[{"type":"video","video":"https://example.com/video.mp4"},{"type":"text","text":"Describe this video."}]}]}}
{"custom_id":"video-base64","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-vl-plus","messages":[{"role":"user","content":[{"type":"video","video":["data:image/jpeg;base64,{frame1}","data:image/jpeg;base64,{frame2}","data:image/jpeg;base64,{frame3}"]},{"type":"text","text":"Describe this video."}]}]}}
{"custom_id":"multi-image-url","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-vl-plus","messages":[{"role":"user","content":[{"type":"image_url","image_url":{"url":"https://example.com/image1.jpg"}},{"type":"image_url","image_url":{"url":"https://example.com/image2.jpg"}},{"type":"text","text":"Compare these two images."}]}]}}
{"custom_id":"multi-image-base64","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-vl-plus","messages":[{"role":"user","content":[{"type":"image_url","image_url":{"url":"data:image/jpeg;base64,{image1_base64}"}},{"type":"image_url","image_url":{"url":"data:image/jpeg;base64,{image2_base64}"}},{"type":"text","text":"Compare these two images."}]}]}}
String Base64 dalam contoh di atas dipotong. Hasilkan encoding lengkap menggunakan kode Python di bawah ini.
Untuk detail lengkap (termasuk batas file, jenis MIME, dan metode encoding), lihat Kirim file lokal (encoding Base64 atau jalur file).
1. Ubah file masukan
-
Dalam file
test_model.jsonl, atur parametermodelke model target dan atur fieldurl:Jenis model
url
Model generasi teks/model multimodal
/v1/chat/completionsModel penyematan teks
/v1/embeddings -
Atau gunakan "alat pembuat batch JSONL" di atas untuk menghasilkan file baru untuk tugas formal. Pastikan field
modeldanurlbenar.
2. Ubah kode Getting Started
-
Ubah jalur file masukan ke nama file Anda.
-
Atur parameter endpoint agar sesuai dengan field url dalam file masukan Anda.
3. Jalankan kode dan tunggu hasil
Saat tugas selesai, hasil permintaan yang berhasil disimpan ke file lokal result.jsonl. Jika ada permintaan yang gagal, detail kesalahan disimpan ke file error.jsonl.
-
Hasil yang berhasil (
output_file_id): Setiap baris sesuai dengan satu permintaan yang berhasil dan mencakupcustom_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! Hangzhou West Lake is a famous scenic spot in China, located in the western part of Hangzhou City, Zhejiang Province, hence the name \"West Lake\". It is one of China's top ten scenic spots and a World Cultural Heritage site (listed by UNESCO in 2011). It is renowned worldwide 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, covering an area of approximately 6.39 square kilometers, shaped like a ruyi scepter with rippling blue waters. The lake is naturally or artificially divided into multiple water areas by Solitary Hill, Bai Causeway, Su Causeway, and Yanggong Causeway, forming a layout of \"one mountain, two pagodas, three islands, and three causeways\".\n\nMain attractions include the following:\n- **Spring Dawn at Su Causeway**: During the Northern Song Dynasty, the great literary figure Su Dongpo, while serving as the prefect of Hangzhou, led 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, this is where the reunion scene from the Legend of the White Snake took place. After snowfall in winter, it is particularly famous for its silver-white appearance.\n- **Leifeng Pagoda at Sunset**: Leifeng Pagoda glows golden under the setting sun and was once one of the \"Ten Scenes of West Lake\".\n- **Three Pools Mirroring the Moon**: On Xiaoyingzhou Island in the lake, there are three stone pagodas. During the Mid-Autumn Festival, lanterns can be lit inside the pagodas, creating a harmonious interplay of moonlight, lamplight, and lake reflections.\n- **Autumn Moon over Calm Lake**: Located at the western end of Bai Causeway, it is an excellent spot for viewing the moon over the lake.\n- **Viewing Fish at Flower Harbor**: Known for viewing flowers and fish, with peonies and koi complementing each other beautifully in the garden.\n\n### II. Cultural History\nWest Lake not only boasts beautiful scenery but also carries rich historical and cultural significance:\n- Since the Tang and Song dynasties, numerous literati such as Bai Juyi, Su Dongpo, Lin Bu, and Yang Wanli have left poems here.\n- Bai Juyi oversaw the construction of \"Bai Causeway\" and dredged West Lake, benefiting the local people.\n- Around West Lake are many historical sites, including Yuewang Temple (commemorating national hero Yue Fei), Lingyin Temple (a millennium-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 Symbolism\nWest Lake is regarded as a representative of \"paradise on earth\" and a model of traditional Chinese landscape aesthetics. It embodies the philosophical concept of \"harmony between heaven and humanity\" by integrating natural beauty with cultural depth. Many poems, paintings, and operas feature West Lake, making it an important symbol of Chinese culture.\n\n### IV. Travel Recommendations\n- Best visiting seasons: Spring (March-May) for peach blossoms and willows, Autumn (September-November) for clear skies and cool weather.\n- Recommended ways: Walking, cycling (along the lakeside greenway), or boating on the lake.\n- Local cuisine: West Lake vinegar fish, Longjing shrimp, Dongpo pork, pian'erchuan noodles.\n\nIn summary, Hangzhou West Lake is not just a natural wonder but also a living cultural museum worth exploring in detail. If you ever visit Hangzhou, don't miss this earthly paradise that is \"equally charming in light or heavy makeup\"."}}],"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":"The spring breeze brushes green willows,\nNight rain nourishes red flowers.\nBird songs fill the forest,\nMountains and rivers share the same beauty."}}],"object":"chat.completion"}},"error":null} -
Detail kegagalan (
error_file_id): Berisi informasi tentang permintaan yang gagal dengan nomor baris dan alasan kesalahan. Lihat Kode kesalahan 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
2. Buat tugas batch
3. Tanyakan dan kelola tugas batch
4. Unduh file hasil Batch
Fitur lanjutan
Atur notifikasi penyelesaian
Untuk tugas berjalan lama, gunakan notifikasi asinkron daripada polling untuk mengurangi konsumsi sumber daya.
Notifikasi penyelesaian hanya didukung di wilayah Beijing.
-
Callback: Tentukan URL yang dapat diakses publik saat membuat tugas.
-
Antrian pesan EventBridge: Terintegrasi mendalam dengan ekosistem Alibaba Cloud. Tidak memerlukan IP publik.
Metode 1: Callback
Metode 2: Antrian pesan EventBridge
Produksi
-
Manajemen file
-
Secara berkala, hapus file yang tidak diperlukan menggunakan OpenAI File delete API untuk menghindari tercapainya batas penyimpanan (10.000 file atau 100 GB).
-
Simpan file berukuran besar di OSS alih-alih mengunggahnya secara langsung.
-
-
Pemantauan tugas
-
Gunakan notifikasi asinkron Callback atau EventBridge.
-
Jika polling diperlukan, atur interval lebih dari 1 menit dan gunakan strategi exponential backoff.
-
-
Penanganan kesalahan
-
Implementasikan penanganan untuk kesalahan jaringan, kesalahan API, dan pengecualian lainnya.
-
Unduh dan analisis detail kesalahan dari
error_file_id. -
Untuk kode kesalahan umum, lihat Kode kesalahan.
-
-
Optimasi biaya
-
Konsolidasikan tugas kecil menjadi satu batch.
-
Atur
completion_windowsecara tepat untuk memungkinkan fleksibilitas penjadwalan yang lebih besar.
-
Alat utilitas
CSV ke JSONL
Hasil JSONL ke CSV
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 masukan dan keluaran 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 ditagih.
-
Permintaan yang gagal karena kesalahan parsing file, kegagalan eksekusi tugas, atau kesalahan tingkat baris tidak dikenai biaya.
-
Untuk tugas yang dibatalkan, permintaan yang berhasil diselesaikan sebelum pembatalan tetap ditagih secara normal.
-
-
Inferensi batch adalah item penagihan terpisah. Mendukung rencana penghematan dan paket sumber daya, 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 aktif secara default. Mode ini menghasilkan token thinking tambahan, yang ditagih dengan harga token keluaran dan meningkatkan biaya. Untuk mengontrol biaya, atur parameter `enable_thinking` berdasarkan kompleksitas tugas. Untuk informasi lebih lanjut, lihat Deep thinking.
Kode kesalahan
Jika permintaan gagal dan mengembalikan pesan kesalahan, lihat Kode kesalahan untuk solusinya.
FAQ
-
Bagaimana memilih antara Batch Chat dan Batch File?
Gunakan Batch File saat Anda perlu memproses file besar yang berisi banyak permintaan secara asinkron. Gunakan Batch Chat saat 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 saat 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.