Pemrosesan batch
Pemrosesan batch adalah pendekatan yang ampuh untuk menangani volume permintaan yang besar secara efisien. Alih-alih memproses permintaan satu per satu dengan respons langsung, pemrosesan batch memungkinkan Anda mengirimkan beberapa permintaan sekaligus untuk diproses secara asinkron. Pola ini sangat berguna ketika:
- Anda perlu memproses volume data yang besar
- Respons langsung tidak diperlukan
- Anda ingin mengoptimalkan efisiensi biaya
- Anda menjalankan evaluasi atau analisis skala besar
API Message Batches adalah implementasi pertama kami untuk pola ini.
API Message Batches
API Message Batches adalah cara yang ampuh dan hemat biaya untuk memproses volume besar permintaan Messages secara asinkron. Pendekatan ini sangat cocok untuk tugas yang tidak memerlukan respons langsung, dengan sebagian besar batch selesai dalam waktu kurang dari 1 jam sambil mengurangi biaya hingga 50% dan meningkatkan throughput.
Anda dapat menjelajahi referensi API secara langsung, selain panduan ini.
Cara kerja API Message Batches
Ketika Anda mengirim permintaan ke API Message Batches:
- 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 selesai untuk semua permintaan.
Ini sangat berguna untuk operasi massal yang tidak memerlukan hasil langsung, seperti:
- Evaluasi skala besar: Proses ribuan kasus uji secara efisien.
- Moderasi konten: Analisis volume besar konten buatan pengguna secara asinkron.
- Analisis data: Hasilkan wawasan atau ringkasan untuk kumpulan data besar.
- Pembuatan konten massal: Buat jumlah teks yang besar untuk berbagai tujuan (misalnya, deskripsi produk, ringkasan artikel).
Batasan batch
- Message Batch dibatasi hingga 100.000 permintaan Message atau ukuran 256 MB, mana yang tercapai lebih dulu.
- Kami memproses setiap batch secepat mungkin, dengan sebagian besar batch selesai dalam waktu 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 waktu 24 jam.
- Hasil batch tersedia selama 29 hari setelah pembuatan. Setelah itu, Anda masih dapat melihat Batch, tetapi hasilnya tidak 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 rate berlaku untuk permintaan HTTP API Batches dan jumlah permintaan dalam batch yang menunggu untuk diproses. Lihat batas rate API Message Batches. Selain itu, kami mungkin 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 melebihi batas pengeluaran yang dikonfigurasi untuk Workspace Anda.
Model yang didukung
API Message Batches saat ini mendukung:
- Claude Opus 4 (
claude-opus-4-20250514
) - Claude Sonnet 4 (
claude-sonnet-4-20250514
) - Claude Sonnet 3.7 (
claude-3-7-sonnet-20250219
) - Claude Sonnet 3.5 (
claude-3-5-sonnet-20240620
danclaude-3-5-sonnet-20241022
) - Claude Haiku 3.5 (
claude-3-5-haiku-20241022
) - Claude Haiku 3 (
claude-3-haiku-20240307
) - Claude Opus 3 (
claude-3-opus-20240229
)
Apa yang dapat dibatch
Permintaan apa pun yang dapat Anda buat ke API Messages dapat disertakan dalam batch. Ini termasuk:
- Vision
- Penggunaan alat
- Pesan sistem
- Percakapan multi-giliran
- Fitur beta apa pun
Karena setiap permintaan dalam batch diproses secara independen, Anda dapat mencampur berbagai jenis permintaan dalam satu batch.
Harga
API Batches menawarkan penghematan biaya yang signifikan. Semua penggunaan dikenakan biaya 50% dari harga API standar.
Model | Batch input | Batch output |
---|---|---|
Claude Opus 4 | $7.50 / MTok | $37.50 / MTok |
Claude Sonnet 4 | $1.50 / MTok | $7.50 / MTok |
Claude Sonnet 3.7 | $1.50 / MTok | $7.50 / MTok |
Claude Sonnet 3.5 | $1.50 / MTok | $7.50 / MTok |
Claude Haiku 3.5 | $0.40 / MTok | $2 / MTok |
Claude Opus 3 | $7.50 / MTok | $37.50 / MTok |
Claude Haiku 3 | $0.125 / MTok | $0.625 / MTok |
Cara menggunakan API Message Batches
Persiapkan dan buat batch Anda
Message Batch terdiri dari daftar permintaan untuk membuat Message. Bentuk permintaan individu terdiri dari:
custom_id
unik untuk mengidentifikasi permintaan Messages- Objek
params
dengan parameter API Messages standar
Anda dapat membuat batch dengan memasukkan daftar ini ke dalam parameter requests
:
Dalam contoh ini, dua permintaan terpisah dibatch bersama untuk pemrosesan asinkron. Setiap permintaan memiliki custom_id
unik dan berisi parameter standar yang akan Anda gunakan untuk panggilan API Messages.
Uji permintaan batch Anda dengan API Messages
Validasi objek params
untuk setiap permintaan pesan dilakukan secara asinkron, dan kesalahan validasi dikembalikan ketika pemrosesan seluruh batch telah selesai. Anda dapat memastikan bahwa Anda membangun input dengan benar dengan memverifikasi bentuk permintaan Anda dengan API Messages terlebih dahulu.
Ketika batch pertama kali dibuat, respons akan memiliki status pemrosesan in_progress
.
Melacak batch Anda
Bidang processing_status
Message Batch menunjukkan tahap pemrosesan batch. Dimulai sebagai in_progress
, kemudian diperbarui menjadi ended
setelah semua permintaan dalam batch selesai diproses, dan hasilnya siap. Anda dapat memantau status batch Anda dengan mengunjungi Console, atau menggunakan endpoint pengambilan:
Anda dapat melakukan polling endpoint ini untuk mengetahui kapan pemrosesan telah selesai.
Mengambil hasil batch
Setelah pemrosesan batch selesai, 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 yang 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. |
Anda akan melihat gambaran umum hasil Anda dengan request_counts
batch, yang menunjukkan berapa banyak permintaan yang mencapai keempat 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 mengalirkan hasil daripada mengunduhnya sekaligus.
Hasilnya akan dalam format .jsonl
, di mana setiap baris adalah objek JSON yang valid yang mewakili hasil dari satu permintaan dalam Message Batch. Untuk setiap hasil yang dialirkan, Anda dapat melakukan sesuatu yang berbeda tergantung pada custom_id
dan jenis hasilnya. Berikut adalah contoh kumpulan hasil:
Jika hasil Anda memiliki kesalahan, result.error
akan diatur ke bentuk kesalahan standar kami.
Hasil batch mungkin tidak cocok dengan urutan input
Hasil batch dapat dikembalikan dalam urutan apa pun, dan mungkin tidak cocok dengan urutan permintaan saat batch dibuat. Dalam contoh di atas, hasil untuk permintaan batch kedua dikembalikan sebelum yang pertama. Untuk mencocokkan hasil dengan benar dengan permintaan yang sesuai, selalu gunakan bidang custom_id
.
Menggunakan caching prompt dengan Message Batches
API Message Batches mendukung caching prompt, memungkinkan Anda untuk berpotensi mengurangi biaya dan waktu pemrosesan untuk permintaan batch. Diskon harga dari caching prompt 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 hits disediakan dengan upaya terbaik. Pengguna biasanya mengalami tingkat cache hit mulai dari 30% hingga 98%, tergantung pada pola lalu lintas mereka.
Untuk memaksimalkan kemungkinan cache hits dalam permintaan batch Anda:
- Sertakan blok
cache_control
yang identik di setiap permintaan Message dalam batch Anda - Pertahankan aliran permintaan yang stabil untuk mencegah entri cache kedaluwarsa setelah masa pakai 5 menit
- Strukturkan permintaan Anda untuk berbagi sebanyak mungkin konten yang di-cache
Contoh implementasi caching prompt dalam batch:
Dalam contoh ini, kedua permintaan dalam batch menyertakan pesan sistem yang identik dan teks lengkap Pride and Prejudice yang ditandai dengan cache_control
untuk meningkatkan kemungkinan cache hits.
Praktik terbaik untuk batching yang efektif
Untuk mendapatkan hasil maksimal dari API Batches:
- Pantau status pemrosesan batch secara teratur dan implementasikan logika percobaan ulang yang sesuai untuk permintaan yang gagal.
- Gunakan nilai
custom_id
yang bermakna untuk memudahkan pencocokan hasil dengan permintaan, karena urutan tidak dijamin. - Pertimbangkan untuk memecah kumpulan data yang sangat besar menjadi beberapa batch untuk pengelolaan yang lebih baik.
- Lakukan uji coba bentuk permintaan tunggal dengan API Messages untuk menghindari kesalahan validasi.
Pemecahan masalah umum
Jika mengalami perilaku yang tidak terduga:
- Verifikasi bahwa ukuran total permintaan batch tidak melebihi 256 MB. Jika ukuran permintaan terlalu besar, Anda mungkin mendapatkan kesalahan 413
request_too_large
. - Periksa bahwa Anda menggunakan model yang didukung untuk semua permintaan dalam batch.
- Pastikan setiap permintaan dalam batch memiliki
custom_id
yang unik. - Pastikan bahwa kurang dari 29 hari sejak waktu batch
created_at
(bukan pemrosesanended_at
). Jika lebih dari 29 hari telah berlalu, hasil tidak akan lagi dapat dilihat. - Konfirmasi bahwa batch belum dibatalkan.
Perhatikan bahwa kegagalan satu permintaan dalam batch tidak memengaruhi pemrosesan permintaan lain.
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.