مستوى المقال: للمبتدئ

لو عندك 30,000 سؤال محتاج تجاوبهم بـ Claude لكن مش لازم رد في ثواني، انت بتدفع تمن real-time غصب عنك. Batch API بياخد نفس الشغل، يشغّله في الخلفية، ويرجّعهولك خلال 24 ساعة بنص السعر بالظبط.

Batch API في Claude — وفّر النص بسطرين كود

الفكرة بسيطة: انت بترسل ملف فيه آلاف الطلبات مرة واحدة، Anthropic تشتغل عليهم في الخلفية، ولمّا يخلصوا بترجع تأخد النتائج. وبكدا بتاخد منك نص السعر فقط، لأنك مش مزاحم الـ traffic الفوري.

قبل التعريف العلمي — تخيّل المغسلة في حيّك

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

Batch API نفس الفكرة بالظبط، بس مع طلبات الذكاء الاصطناعي. لو شغلك مش لازم يرد في 5 ثواني، انت بتدفع ضعف اللي محتاج تدفعه فعلاً.

التعريف العلمي للـ Batch Processing

الـ Batch Processing مفهوم قديم في علوم الحاسب، اتعرّف لأول مرة في ستينات القرن الماضي مع نظم IBM System/360 (المرجع: Hennessy & Patterson, "Computer Architecture: A Quantitative Approach"). الفكرة العلمية: تجميع المهام في دفعات بيقلّل overhead الجدولة على الـ scheduler، وبيسمح للـ infrastructure إنها تجدول الشغل في فترات الـ off-peak، فبتطلع كفاءة استخدام أعلى (utilization) مقابل latency أعلى.

في سياق LLMs، Anthropic بتستفيد من ده بإن طلبات Batch بتتجدول لمّا تكون السيرفرات أقل ضغط، فتقدر تخصم 50% من السعر من غير ما تأثّر على الـ traffic الفوري للمستخدمين الآخرين (المرجع الرسمي: Anthropic Message Batches API).

المشكلة باختصار — مين فعلاً محتاج Batch API

لو عندك أي حالة من الحالات دي في شغلك، انت بتدفع زيادة من غير سبب:

• تصنيف 50,000 ريفيو منتج كل ليلة لتحديد المشاعر (sentiment analysis)
• توليد ملخصات لـ 5,000 مقال أسبوعيًا في موقع إخباري
• تقييم 12,000 زوج سؤال/جواب في dataset تدريب
• توليد عناوين SEO لـ 80,000 صفحة في موقع e-commerce
• ترجمة 20,000 وصف منتج من إنجليزي لعربي

كل واحدة من دول مش محتاجة رد في الثواني. والفلوس الزيادة بتترجم لآلاف الدولارات شهريًا بتروح لمنفعة وهمية اسمها "السرعة" انت أصلاً مش بتستخدمها.

الكود الشغّال — Batch API في 14 سطر Python

ده الـ workflow كامل. أول حاجة، انت بتجهّز قائمة الطلبات وبتبعتهم لـ batches.create:

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 ساعة)، وبعدين تجيب النتائج بالكود ده:

batch_status = client.messages.batches.retrieve(batch.id)

if batch_status.processing_status == "ended":
    results = client.messages.batches.results(batch.id)
    for line in results:
        custom_id = line.custom_id
        if line.result.type == "succeeded":
            response = line.result.message.content[0].text
            print(f"{custom_id}: {response}")
        else:
            print(f"{custom_id}: FAILED — {line.result.type}")

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

الأرقام الحقيقية — قياس على 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