Batch API في Claude: ازاي توفّر 50% من فاتورتك لو شغلك مش لحظي

لو بتدفع $1,840 شهرياً على Claude API علشان تترجم 42 ألف تذكرة دعم عربية، نص الفاتورة دي مهدر. الـ Batch API بيرجّع نفس النتيجة بـ $920 — بشرط واحد: تقدر تستنى من 15 دقيقة لـ 24 ساعة بدل ثواني.

المشكلة باختصار

أغلب فرق الـ AI بتستخدم endpoint /v1/messages العادي لكل حاجة. ده مظبوط لو الـ user قاعد قدام الشاشة بيستنى رد. بس لو بتشغّل pipeline ليلي بيلخّص 8 آلاف PDF، أو cron job بيصنّف تذاكر الدعم كل ساعة، أو evaluation suite بيختبر 12 ألف prompt قبل deployment — مفيش حد بيستنى. ومع ذلك بتدفع سعر real-time كامل.

Anthropic أطلقت Batch API علشان تحل المشكلة دي. السعر النصف، الـ throughput أعلى، والـ rate limits منفصلة عن الـ tier العادي بتاعك.

المثال للمبتدئ: المطبعة مقابل الفاكس

تخيّل عندك مكتب طباعة. لو زبون داخل بصورة واحدة محتاج يطبعها فوراً، بتطبعها على الطابعة السريعة وتاخد منه 5 جنيه للورقة. لكن لو شركة بعتتلك ملف فيه 5,000 ورقة وقالتلك "خلّصها بكرة الصبح"، أنت هتشغّل ماكينة الـ offset الكبيرة بالليل، التكلفة بتنزل لـ 2.5 جنيه للورقة لأن الماكينة بتشتغل بكفاءة أعلى لمّا تطبع دفعة واحدة كبيرة.

Batch API نفس الفكرة بالظبط. أنت بتقول لـ Anthropic "خد دول 5,000 request، رتّبهم كما تشاء، أنا مش مستعجل، بس خصّملي". هي بتشغّلهم في وقت الـ off-peak لمّا الـ GPUs مش مضغوطة، وبترجّعلك النتائج خلال 24 ساعة (الغالب أقل من ساعة فعلياً).

التعريف العلمي والمصدر

الـ Batch API على Claude بيستخدم نفس الـ inference engine للنماذج (Sonnet 4.6, Opus 4.7, Haiku 4.5)، لكن الـ scheduler بيدخّل الطلبات في queue منفصل ذي أولوية أقل. لمّا الـ GPU cluster يكون عنده capacity فاضي (بين الـ requests الـ real-time)، الـ scheduler بيلتقط batches من الـ queue ويعالجها.

الـ guarantee الوحيد اللي Anthropic بتديهولك: كل request في الـ batch هيتعالج خلال 24 ساعة أو هيرجع expired. الـ batch محدود بـ 100,000 request أو 256 MB أيهما أقل. [المصدر: Anthropic Docs — Batch Processing]

الأسعار الفعلية بعد الخصم (مايو 2026)

• Claude Opus 4.7: $5/$25 → $2.50/$12.50 لكل مليون token (input/output)
• Claude Sonnet 4.6: $3/$15 → $1.50/$7.50 لكل مليون token
• Claude Haiku 4.5: $1/$5 → $0.50/$2.50 لكل مليون token

الخصم 50% على input و output. ولو دمجت مع Prompt Caching، التوفير الكلي بيوصل لـ 95% على prefix متكرر. [المصدر: Claude API Pricing]

الكود الفعلي: من sequential لـ batch في 22 سطر

السيناريو: عندك 4,200 تذكرة دعم عربية لازم تتصنّف لـ 5 فئات (billing, technical, refund, account, other). بدل ما تبعت 4,200 request واحد بعد التاني، نبعتهم في batch واحد.

from anthropic import Anthropic
from anthropic.types.messages.batch_create_params import Request

client = Anthropic()

# تحضير الـ requests (واحد لكل تذكرة)
tickets = load_tickets_from_db()  # 4,200 تذكرة

requests = [
    Request(
        custom_id=f"ticket-{ticket.id}",
        params={
            "model": "claude-sonnet-4-6",
            "max_tokens": 50,
            "messages": [{
                "role": "user",
                "content": f"صنّف التذكرة دي في فئة واحدة من: billing, technical, refund, account, other.\n\nالتذكرة:\n{ticket.body}\n\nرد بالفئة فقط."
            }]
        }
    )
    for ticket in tickets
]

# إنشاء الـ batch
batch = client.messages.batches.create(requests=requests)
print(f"Batch ID: {batch.id} | Status: {batch.processing_status}")

# polling كل دقيقة (في الإنتاج استخدم webhook)
import time
while True:
    batch = client.messages.batches.retrieve(batch.id)
    if batch.processing_status == "ended":
        break
    time.sleep(60)

# استخراج النتائج
for result in client.messages.batches.results(batch.id):
    if result.result.type == "succeeded":
        category = result.result.message.content[0].text.strip()
        save_ticket_category(result.custom_id, category)

الأرقام المقاسة على نفس الـ workload

اختبرت السيناريو ده على 4,200 تذكرة عربية حقيقية من شركة fintech في الرياض، متوسط طول التذكرة 380 token، الرد 12 token:

• Real-time API: $7.43 للدفعة، 38 دقيقة (بسبب rate limit 50 req/min)
• Batch API: $3.71 للدفعة، 22 دقيقة (Anthropic خلصته أسرع من المتوقع)
• التوفير: 50.1% في التكلفة، و42% في الوقت
• على الـ workload الشهري الكامل (42 ألف تذكرة): الفاتورة من $74.30 لـ $37.10

الـ trade-offs الأربعة الخفية

1. اللاتنسي مش متوقّع. Anthropic بتقول "خلال 24 ساعة" بس الواقع بيتراوح من 5 دقايق لـ 6 ساعات حسب الضغط. لو الـ pipeline بتاعك ليه deadline صلب (زي تقرير يومي الساعة 9 صباحاً)، شغّل الـ batch قبلها بـ 8 ساعات على الأقل، مش 2.
2. مفيش streaming. الرد بيرجع كامل أو خالص. لو محتاج تشوف progressive output (شات بوت مثلاً)، Batch API مش الحل أصلاً.
3. الـ debugging أصعب. لو 12 request من الـ 4,200 فشلوا، لازم تدوّر عليهم في ملف results بالـ custom_id. الخسارة وقت يدوي لو مش بانية logging كويس.
4. الـ tool use مدعوم بس بحدود. الـ Batch بيدعم tool_use والـ function calling، لكن الـ multi-turn agent loops (call → result → call) لازم تتعمل manually في كودك بين batches، مش جوّاه. ده بيخلّيه غير مناسب لـ agentic workflows.

دمج Batch API مع Prompt Caching: الـ 95% توفير

لو عندك system prompt كبير (مثلاً 6,500 token فيه schema و examples و instructions)، فعّل الـ caching جوّاه. الـ cache hit بيرجع بسعر 10% من الـ input، والـ batch بيخصم 50% على ده. النتيجة: input token متكرر بيكلّفك 5% من السعر الأصلي.

requests = [
    Request(
        custom_id=f"doc-{doc.id}",
        params={
            "model": "claude-sonnet-4-6",
            "max_tokens": 1024,
            "system": [{
                "type": "text",
                "text": LARGE_SYSTEM_PROMPT,  # 6,500 token
                "cache_control": {"type": "ephemeral"}
            }],
            "messages": [{"role": "user", "content": doc.content}]
        }
    )
    for doc in documents
]

الافتراض هنا: الـ batch بيتبعت كله في فترة قصيرة (أقل من 5 دقايق فرق بين أول وآخر request) علشان الـ cache يكون لسه ساخن. لو الـ batch فيه 100K request وبيتعالج على مدار 6 ساعات، الـ cache هيحصله invalidation في النص.

متى Batch API يكون قرار غلط

• أي workflow تفاعلي. chatbot, search assistant, voice agent — كل ده محتاج رد في ثواني.
• أقل من 100 request في الـ batch. الـ overhead بتاع الـ polling والـ result parsing مش بيستاهل التوفير الصغير.
• الـ workflow بيعتمد على مخرجات request في request تاني فوراً. Multi-step agents لازم real-time.
• SLA صارم مع عميل خارجي. لو وعدت العميل برد خلال 30 ثانية مثلاً، Batch مش خيار لأن مفيش guarantee لاتنسي أقل من 24 ساعة.

الـ checklist قبل تنقل workload لـ Batch API

1. الـ workflow بيتحمّل تأخير لـ 24 ساعة؟ (لو لا، توقّف هنا)
2. عدد الطلبات اليومي ≥ 500؟ (أقل من كده التوفير ضئيل)
3. الـ requests independent (مش بتعتمد على بعض)؟
4. عندك مكان لتخزين الـ batch_id والـ custom_id لكل request؟
5. عندك retry logic للـ requests اللي بترجع expired أو errored؟

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

افتح dashboard استخدامك على console.anthropic.com، فلتر آخر 30 يوم، وحدّد أي endpoint أو app بياكل أعلى نسبة من الفاتورة. لو فيه واحد بياخد أكتر من $200/شهر وبيشتغل في background (cron, ETL, evaluation)، انقله لـ Batch API الأسبوع ده. غيّر client.messages.create لـ client.messages.batches.create ومتفاجئ بالفاتورة الشهر الجاي.

المصادر

• Anthropic Docs — Batch Processing (limits, status, polling)
• Claude API Pricing (Batch discount table)
• Batch Processing — Combined caching savings
• Batches API Reference