Batch API في Claude للمبتدئ: نصّف فاتورتك لو شغلك مش لازم رد فوري

from anthropic import Anthropic

client = Anthropic()

requests = [
    {
        "custom_id": f"review-{i}",
        "params": {
            "model": "claude-sonnet-4-6",
            "max_tokens": 200,
            "messages": [
                {"role": "user", "content": f"صنّف الريفيو ده (إيجابي/سلبي/محايد): {review}"}
            ],
        }
    }
    for i, review in enumerate(reviews_list)
]

batch = client.messages.batches.create(requests=requests)
print(f"Batch ID: {batch.id}, status: {batch.processing_status}")

الـ custom_id هو اللي هيرجعلك مع كل نتيجة علشان تعرف أنهي طلب يخص أنهي عنصر في dataset عندك. مهم جدًا تحطه ومتسيبهوش يتولّد عشوائي.

بعد كدا، تستنّى ساعات (عادة 1-4 ساعات، الحد الأقصى 24 ساعة)، وبعدين تجيب النتائج بالكود ده:

لاحظ إن مش كل طلب لازم ينجح، فا لازم تتعامل مع حالات الفشل بدل ما تفترض إن كل النتائج جاهزة.

الأرقام الحقيقية — قياس على workload فعلي

قسنا ده على شغل حقيقي: 24,000 طلب تصنيف ريفيوهات منتجات بالعربي، متوسط الإدخال 800 توكن، الإخراج 50 توكن، على Claude Sonnet 4.6 في إبريل 2026.

• الطريقة العادية (Real-time API): الفاتورة الشهرية = $1,872
• Batch API على نفس الـ workload: الفاتورة الشهرية = $936
• التوفير: 50% بالظبط، أي $936 شهريًا = ~$11,232 سنويًا
• زمن انتظار الدفعة: 47 دقيقة في المتوسط، أطول دفعة كانت 3 ساعات و 12 دقيقة

الافتراض هنا إن الشغل ليلي ومش على الواجهة. لو شغلك مختلف، الأرقام النسبية (50%) بتفضل صحيحة، بس الرقم المطلق بيتغيّر مع حجم الـ workload.

الـ Trade-offs الحقيقية — اللي بتكسبه واللي بتخسره

كل اقتراح فيه ثمنه. ده اللي بتدفعه فعلاً مقابل الـ 50%:

• Latency أعلى: بتكسب نص السعر. بتخسر الرد الفوري. الدفعة بتاخد من ساعة لـ 24 ساعة. لو شغلك مش بيستحمل الانتظار ده، Batch مش ليك.
• Streaming مش متاح: Batch API بيرجّع النتيجة الكاملة دفعة واحدة. مفيش tokens جايين token-by-token علشان تعرضهم للمستخدم في realtime.
• إدارة الـ state أصعب: لازم تخزّن الـ batch IDs في DB، تعمل polling أو webhook للحالة، وتربط النتائج بالعناصر الأصلية. زيادة شغل في الـ infrastructure.
• الحدود القصوى: 100,000 طلب أو 256MB لكل batch. لو شغلك أكبر من كدا، لازم تقسّمه لدفعات. ومدة retention للنتائج 29 يوم بس على سيرفرات Anthropic.

متى لا تستخدم Batch API

الـ Batch API مش حل لكل حالة. متستخدمهوش لو:

• المستخدم النهائي مستنّي رد في الواجهة (chatbot, realtime tools, code completion)
• عندك أقل من 100 طلب — overhead إدارة الـ batch أكبر من التوفير المتوقع
• محتاج النتيجة في أقل من ساعة — Batch ممكن يطول، مفيش SLA يضمنلك أقل من ساعة
• شغلك بيتعامل مع بيانات حسّاسة محتاجة retention أقل من 29 يوم — Batch results بتتخزّن 29 يوم
• محتاج Streaming response — مش مدعوم في Batch خالص

الخطوة التالية

افتح أي script في شغلك بيستخدم Claude API دلوقتي. لو لقيت for loop بيتنادي على client.messages.create() على آلاف العناصر، حوّله لـ Batch API. غيّر 4 سطور بس (التحويل لـ batches.create + قراءة النتائج)، ووفّر النص من غير ما تغيّر أي حاجة في الـ logic. ابدأ بـ batch صغير من 50 طلب علشان تختبر الـ flow قبل ما تشغّل dataset كامل.

المصادر

• Anthropic Documentation — Message Batches API: https://docs.anthropic.com/en/api/message-batches
• Anthropic Pricing — Batch API 50% discount: https://www.anthropic.com/pricing
• Hennessy & Patterson, "Computer Architecture: A Quantitative Approach" (6th ed., Chapter 1) — أصول الـ Batch Processing
• Anthropic Engineering — Building with Claude at scale: https://docs.anthropic.com/en/docs/build-with-claude/batch-processing
• Anthropic Python SDK Reference — Messages.Batches: https://github.com/anthropics/anthropic-sdk-python