- Anda perlu memproses volume data yang besar
- Respons langsung tidak diperlukan
- Anda ingin mengoptimalkan efisiensi biaya
- Anda menjalankan evaluasi atau analisis skala besar
Message Batches API
Message Batches API adalah cara yang kuat dan hemat biaya untuk memproses volume besar permintaan Messages secara asinkron. Pendekatan ini sangat cocok untuk tugas-tugas yang tidak memerlukan respons langsung, dengan sebagian besar batch selesai dalam waktu kurang dari 1 jam sambil mengurangi biaya sebesar 50% dan meningkatkan throughput. Anda dapat menjelajahi referensi API secara langsung, selain panduan ini.Cara kerja Message Batches API
Ketika Anda mengirim permintaan ke Message Batches API:- Sistem membuat Message Batch baru dengan permintaan Messages yang disediakan.
- Batch kemudian diproses secara asinkron, dengan setiap permintaan ditangani secara independen.
- Anda dapat melakukan polling untuk status batch dan mengambil hasil ketika pemrosesan telah berakhir untuk semua permintaan.
- Evaluasi skala besar: Memproses ribuan kasus uji secara efisien.
- Moderasi konten: Menganalisis volume besar konten yang dibuat pengguna secara asinkron.
- Analisis data: Menghasilkan wawasan atau ringkasan untuk dataset besar.
- Generasi konten massal: Membuat sejumlah besar teks untuk berbagai tujuan (misalnya, deskripsi produk, ringkasan artikel).
Batasan batch
- Message Batch dibatasi hingga 100.000 permintaan Message atau 256 MB dalam ukuran, mana yang tercapai lebih dulu.
- Kami memproses setiap batch secepat mungkin, dengan sebagian besar batch selesai dalam 1 jam. Anda akan dapat mengakses hasil batch ketika semua pesan telah selesai atau setelah 24 jam, mana yang lebih dulu. Batch akan kedaluwarsa jika pemrosesan tidak selesai dalam 24 jam.
- Hasil batch tersedia selama 29 hari setelah pembuatan. Setelah itu, Anda masih dapat melihat Batch, tetapi hasilnya tidak akan lagi tersedia untuk diunduh.
- Batch dibatasi pada Workspace. Anda dapat melihat semua batch—dan hasilnya—yang dibuat dalam Workspace tempat kunci API Anda berada.
- Batas laju berlaku untuk permintaan HTTP Batches API dan jumlah permintaan dalam batch yang menunggu untuk diproses. Lihat batas laju Message Batches API. Selain itu, kami dapat memperlambat pemrosesan berdasarkan permintaan saat ini dan volume permintaan Anda. Dalam hal itu, Anda mungkin melihat lebih banyak permintaan kedaluwarsa setelah 24 jam.
- Karena throughput tinggi dan pemrosesan bersamaan, batch mungkin sedikit melampaui batas pengeluaran yang dikonfigurasi Workspace Anda.
Model yang didukung
Semua model aktif mendukung Message Batches API.Apa yang dapat di-batch
Setiap permintaan yang dapat Anda buat ke Messages API dapat disertakan dalam batch. Ini termasuk:- Vision
- Penggunaan tool
- Pesan sistem
- Percakapan multi-turn
- Fitur beta apa pun
Karena batch dapat memakan waktu lebih dari 5 menit untuk diproses, pertimbangkan menggunakan durasi cache 1 jam dengan prompt caching untuk tingkat hit cache yang lebih baik saat memproses batch dengan konteks bersama.
Harga
Batches API menawarkan penghematan biaya yang signifikan. Semua penggunaan dikenakan biaya 50% dari harga API standar.| Model | Batch input | Batch output |
|---|---|---|
| Claude Opus 4.1 | $7.50 / MTok | $37.50 / MTok |
| Claude Opus 4 | $7.50 / MTok | $37.50 / MTok |
| Claude Sonnet 4.5 | $1.50 / MTok | $7.50 / MTok |
| Claude Sonnet 4 | $1.50 / MTok | $7.50 / MTok |
| Claude Sonnet 3.7 (deprecated) | $1.50 / MTok | $7.50 / MTok |
| Claude Haiku 4.5 | $0.50 / MTok | $2.50 / MTok |
| Claude Haiku 3.5 | $0.40 / MTok | $2 / MTok |
| Claude Opus 3 (deprecated) | $7.50 / MTok | $37.50 / MTok |
| Claude Haiku 3 | $0.125 / MTok | $0.625 / MTok |
Cara menggunakan Message Batches API
Persiapkan dan buat batch Anda
Message Batch terdiri dari daftar permintaan untuk membuat Message. Bentuk permintaan individual terdiri dari:custom_idunik untuk mengidentifikasi permintaan Messages- Objek
paramsdengan parameter Messages API standar
requests:
custom_id unik dan berisi parameter standar yang akan Anda gunakan untuk panggilan Messages API.
Uji permintaan batch Anda dengan Messages APIValidasi objek
params untuk setiap permintaan pesan dilakukan secara asinkron, dan kesalahan validasi dikembalikan ketika pemrosesan seluruh batch telah berakhir. Anda dapat memastikan bahwa Anda membangun input dengan benar dengan memverifikasi bentuk permintaan Anda dengan Messages API terlebih dahulu.in_progress.
JSON
Melacak batch Anda
Fieldprocessing_status Message Batch menunjukkan tahap pemrosesan batch. Dimulai sebagai in_progress, kemudian diperbarui menjadi ended setelah semua permintaan dalam batch selesai diproses, dan hasil siap. Anda dapat memantau status batch Anda dengan mengunjungi Console, atau menggunakan endpoint pengambilan:
Mengambil hasil batch
Setelah pemrosesan batch berakhir, setiap permintaan Messages dalam batch akan memiliki hasil. Ada 4 jenis hasil:| Jenis Hasil | Deskripsi |
|---|---|
succeeded | Permintaan berhasil. Termasuk hasil pesan. |
errored | Permintaan mengalami kesalahan dan pesan tidak dibuat. Kemungkinan kesalahan termasuk permintaan tidak valid dan kesalahan server internal. Anda tidak akan ditagih untuk permintaan ini. |
canceled | Pengguna membatalkan batch sebelum permintaan ini dapat dikirim ke model. Anda tidak akan ditagih untuk permintaan ini. |
expired | Batch mencapai kedaluwarsa 24 jam sebelum permintaan ini dapat dikirim ke model. Anda tidak akan ditagih untuk permintaan ini. |
request_counts batch, yang menunjukkan berapa banyak permintaan yang mencapai masing-masing dari empat status ini.
Hasil batch tersedia untuk diunduh di properti results_url pada Message Batch, dan jika izin organisasi memungkinkan, di Console. Karena ukuran hasil yang berpotensi besar, disarankan untuk streaming hasil kembali daripada mengunduh semuanya sekaligus.
.jsonl, di mana setiap baris adalah objek JSON yang valid yang mewakili hasil dari satu permintaan dalam Message Batch. Untuk setiap hasil yang di-stream, Anda dapat melakukan sesuatu yang berbeda tergantung pada custom_id dan jenis hasilnya. Berikut adalah contoh set hasil:
.jsonl file
result.error akan diatur ke bentuk kesalahan standar kami.
Hasil batch mungkin tidak sesuai urutan inputHasil batch dapat dikembalikan dalam urutan apa pun, dan mungkin tidak sesuai dengan urutan permintaan ketika batch dibuat. Dalam contoh di atas, hasil untuk permintaan batch kedua dikembalikan sebelum yang pertama. Untuk mencocokkan hasil dengan permintaan yang sesuai dengan benar, selalu gunakan field
custom_id.Menggunakan prompt caching dengan Message Batches
Message Batches API mendukung prompt caching, memungkinkan Anda berpotensi mengurangi biaya dan waktu pemrosesan untuk permintaan batch. Diskon harga dari prompt caching dan Message Batches dapat ditumpuk, memberikan penghematan biaya yang lebih besar ketika kedua fitur digunakan bersama. Namun, karena permintaan batch diproses secara asinkron dan bersamaan, cache hit disediakan berdasarkan upaya terbaik. Pengguna biasanya mengalami tingkat cache hit mulai dari 30% hingga 98%, tergantung pada pola lalu lintas mereka. Untuk memaksimalkan kemungkinan cache hit dalam permintaan batch Anda:- Sertakan blok
cache_controlyang identik dalam setiap permintaan Message dalam batch Anda - Pertahankan aliran permintaan yang stabil untuk mencegah entri cache kedaluwarsa setelah masa hidup 5 menit mereka
- Strukturkan permintaan Anda untuk berbagi sebanyak mungkin konten yang di-cache
cache_control untuk meningkatkan kemungkinan cache hit.
Praktik terbaik untuk batching yang efektif
Untuk mendapatkan hasil maksimal dari Batches API:- Pantau status pemrosesan batch secara teratur dan implementasikan logika retry yang sesuai untuk permintaan yang gagal.
- Gunakan nilai
custom_idyang bermakna untuk dengan mudah mencocokkan hasil dengan permintaan, karena urutan tidak dijamin. - Pertimbangkan untuk memecah dataset yang sangat besar menjadi beberapa batch untuk kemudahan pengelolaan yang lebih baik.
- Lakukan dry run bentuk permintaan tunggal dengan Messages API untuk menghindari kesalahan validasi.
Mengatasi masalah umum
Jika mengalami perilaku yang tidak terduga:- Verifikasi bahwa total ukuran permintaan batch tidak melebihi 256 MB. Jika ukuran permintaan terlalu besar, Anda mungkin mendapat kesalahan 413
request_too_large. - Periksa bahwa Anda menggunakan model yang didukung untuk semua permintaan dalam batch.
- Pastikan setiap permintaan dalam batch memiliki
custom_idyang unik. - Pastikan bahwa telah kurang dari 29 hari sejak waktu
created_atbatch (bukanended_atpemrosesan). Jika lebih dari 29 hari telah berlalu, hasil tidak akan lagi dapat dilihat. - Konfirmasi bahwa batch belum dibatalkan.
Penyimpanan dan privasi batch
- Isolasi workspace: Batch diisolasi dalam Workspace tempat mereka dibuat. Mereka hanya dapat diakses oleh kunci API yang terkait dengan Workspace tersebut, atau pengguna dengan izin untuk melihat batch Workspace di Console.
- Ketersediaan hasil: Hasil batch tersedia selama 29 hari setelah batch dibuat, memberikan waktu yang cukup untuk pengambilan dan pemrosesan.
FAQ
Berapa lama waktu yang dibutuhkan untuk memproses batch?
Berapa lama waktu yang dibutuhkan untuk memproses batch?
Batch mungkin membutuhkan waktu hingga 24 jam untuk pemrosesan, tetapi banyak yang akan selesai lebih cepat. Waktu pemrosesan aktual tergantung pada ukuran batch, permintaan saat ini, dan volume permintaan Anda. Ada kemungkinan batch kedaluwarsa dan tidak selesai dalam 24 jam.
Apakah Batches API tersedia untuk semua model?
Apakah Batches API tersedia untuk semua model?
Lihat di atas untuk daftar model yang didukung.
Bisakah saya menggunakan Message Batches API dengan fitur API lainnya?
Bisakah saya menggunakan Message Batches API dengan fitur API lainnya?
Ya, Message Batches API mendukung semua fitur yang tersedia di Messages API, termasuk fitur beta. Namun, streaming tidak didukung untuk permintaan batch.
Bagaimana Message Batches API mempengaruhi harga?
Bagaimana Message Batches API mempengaruhi harga?
Message Batches API menawarkan diskon 50% pada semua penggunaan dibandingkan dengan harga API standar. Ini berlaku untuk token input, token output, dan token khusus apa pun. Untuk informasi lebih lanjut tentang harga, kunjungi halaman harga kami.
Bisakah saya memperbarui batch setelah dikirimkan?
Bisakah saya memperbarui batch setelah dikirimkan?
Tidak, setelah batch dikirimkan, batch tidak dapat dimodifikasi. Jika Anda perlu membuat perubahan, Anda harus membatalkan batch saat ini dan mengirimkan yang baru. Perhatikan bahwa pembatalan mungkin tidak berlaku segera.
Apakah ada batas laju Message Batches API dan apakah mereka berinteraksi dengan batas laju Messages API?
Apakah ada batas laju Message Batches API dan apakah mereka berinteraksi dengan batas laju Messages API?
Message Batches API memiliki batas laju berbasis permintaan HTTP selain batas pada jumlah permintaan yang perlu diproses. Lihat batas laju Message Batches API. Penggunaan Batches API tidak mempengaruhi batas laju di Messages API.
Bagaimana cara menangani kesalahan dalam permintaan batch saya?
Bagaimana cara menangani kesalahan dalam permintaan batch saya?
Ketika Anda mengambil hasil, setiap permintaan akan memiliki field
result yang menunjukkan apakah itu succeeded, errored, canceled, atau expired. Untuk hasil errored, informasi kesalahan tambahan akan disediakan. Lihat objek respons kesalahan di referensi API.Bagaimana Message Batches API menangani privasi dan pemisahan data?
Bagaimana Message Batches API menangani privasi dan pemisahan data?
Message Batches API dirancang dengan langkah-langkah privasi dan pemisahan data yang kuat:
- Batch dan hasilnya diisolasi dalam Workspace tempat mereka dibuat. Ini berarti mereka hanya dapat diakses oleh kunci API dari Workspace yang sama.
- Setiap permintaan dalam batch diproses secara independen, tanpa kebocoran data antar permintaan.
- Hasil hanya tersedia untuk waktu terbatas (29 hari), dan mengikuti kebijakan retensi data kami.
- Mengunduh hasil batch di Console dapat dinonaktifkan pada tingkat organisasi atau per workspace.
Bisakah saya menggunakan prompt caching di Message Batches API?
Bisakah saya menggunakan prompt caching di Message Batches API?
Ya, dimungkinkan untuk menggunakan prompt caching dengan Message Batches API. Namun, karena permintaan batch asinkron dapat diproses secara bersamaan dan dalam urutan apa pun, cache hit disediakan berdasarkan upaya terbaik.