Claude Batch API: تشغيل المهام غير المتزامنة بنصف التكلفة

الإجابة السريعة: تعالج واجهة Claude Batch API طلبات Messages API بشكل غير متزامن بخصم 50% على كل من الرموز المُدخَلة والمُخرَجة. يمكنك إرسال ما يصل إلى 100,000 طلب (أو 256 ميجابايت) في استدعاء واحد، ثم الاستعلام بشكل دوري حتى انتهاء الدفعة، ثم قراءة النتائج المرتبطة بـ custom_id الخاص بك. تُكمل معظم الدفعات خلال ساعة، والحد الأقصى الصارم هو 24 ساعة.

جرّب Apidog اليوم

لديك 40,000 تذكرة دعم لتصنيفها، أو كتالوج منتجات لإعادة كتابته، أو شهر من النصوص المُفرَّغة لتلخيصه. لا شيء من هذا عاجل. ومع ذلك، تُحتسب كل واحدة من هذه الاستدعاءات بالسعر الكامل عندما ترسلها واحدة تلو الأخرى، وتقضي فترة الظهيرة في مراقبة إعادة المحاولات ضد حد المعدل الخاص بك.

وُجدت Claude Batch API تحديداً لهذا النوع من العمل. تُسلّم Anthropic قائمة من الطلبات، ثم تبتعد، وتعود إلى ملف من النتائج تكلفته نصف ما كانت ستكلفه نفس الاستدعاءات بشكل متزامن. لا قائمة انتظار لتشغيلها، ولا ضبط للتزامن، ولا منطق للتراجع.

يغطي هذا الدليل ما تفعله نقطة نهاية الدفعة، وكم تكلف، وكيفية إرسال مهمة وجمعها، وكيفية ترك وكيل البرمجة الخاص بك يختبر الأمر برمته باستخدام Apidog CLI قبل توجيهه إلى بيانات حقيقية.

ما هي Claude Batch API؟

Claude Batch API هي نقطة نهاية غير متزامنة على /v1/messages/batches تقبل العديد من طلبات Messages API في إرسال واحد وتعيد نتائجها بمجرد انتهاء المعالجة. تُقايض زمن الاستجابة مقابل خصم بنسبة 50%. توثّقها Anthropic تحت المعالجة الدفعية.

القيود التي تحتاج إلى التصميم حولها:

• الحجم: ما يصل إلى 100,000 طلب أو 256 ميجابايت لكل دفعة، أيهما تصل إليه أولاً.
• التوقيت: تكتمل معظم الدفعات خلال ساعة؛ و24 ساعة هي الحد الأقصى قبل انتهاء صلاحية الطلبات غير المكتملة.
• الاحتفاظ: تبقى النتائج متاحة لمدة 29 يوماً بعد إنشاء الدفعة.
• تكافؤ الميزات: تعمل الرؤية واستخدام الأدوات ومطالبات النظام والتخزين المؤقت للمطالبات جميعها داخل الدفعة.
• الترتيب: تعود النتائج بأي ترتيب، لذا تربطها بـ custom_id وليس بالموضع أبداً.

هذه النقطة الأخيرة هي التي تربك الناس. الدفعة عبارة عن كيس، وليست قائمة انتظار.

كم تكلف Claude Batch API

الخصم ثابت بنسبة 50% على كل من الرموز المُدخَلة والمُخرَجة، ويُطبَّق على أي نموذج يحدده كل طلب. يمكنك خلط النماذج داخل دفعة واحدة، حتى يتمكن مصنِّف رخيص وملخِّص مكلف من السير معاً.

اقرأ صفوف Haiku بعناية. يُسعَّر Haiku 5.5 حسب حجم المطالبة، لذا فإن مطالبة واحدة تتجاوز 100,000 رمز تُحتسب بخمسة أضعاف معدل المطالبة القصيرة، سواءً طُبِّق خصم الدفعة أم لا. قدِّر عمل Haiku ذا السياق الطويل بسعر $0.25 / $1.25، وليس $0.05 / $0.25. تحقق من صفحة أسعار Anthropic قبل بناء تقدير على هذه الأرقام، واقرأ تحليلنا حول أين يذهب إنفاق Claude API إذا كانت الفاتورة هي سبب وجودك هنا.

تتكدس الأسعار الدفعية أيضاً مع التخزين المؤقت للمطالبات، وهو المكان الذي توجد فيه التوفيرات الحقيقية. المزيد حول ذلك أدناه.

أرسل دفعتك الأولى

ثبّت Python SDK الرسمي وأنشئ قائمة من الطلبات. يحمل كل واحد منها custom_id تختاره أنت وكائن params يبدو تماماً مثل استدعاء messages.create() العادي.

import anthropic
from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request

client = anthropic.Anthropic()

tickets = [
    "Card declined three times, support chat timed out.",
    "Love the new dashboard, the export button is hidden though.",
    "Webhook stopped firing after the 2.4 upgrade.",
]

batch = client.messages.batches.create(
    requests=[
        Request(
            custom_id=f"ticket-{i}",
            params=MessageCreateParamsNonStreaming(
                model="claude-haiku-5-5",
                max_tokens=1024,
                output_config={"effort": "low"},
                messages=[{
                    "role": "user",
                    "content": f"Label this ticket billing, bug, or praise. One word.\n\n{text}",
                }],
            ),
        )
        for i, text in enumerate(tickets)
    ]
)

print(batch.id, batch.processing_status)

اجعل custom_id يحمل معنى. فمفتاح أساسي لقاعدة بيانات أو مسار ملف يوفر عليك عملية ربط لاحقة، وهو الشيء الوحيد الذي يربط النتيجة بمُدخلها.

إذا كنت تفضل HTTP الخام، فإن نفس الحمولة تذهب إلى POST https://api.anthropic.com/v1/messages/batches مع ترويسات x-api-key وanthropic-version الخاصة بك. يحتوي مرجع إنشاء دفعة رسائل على المخطط الكامل.

استعلم عن الدفعة واجمع النتائج

استرجع الدفعة حتى تقرأ processing_status القيمة ended، ثم بثّ النتائج. تحمل كل نتيجة custom_id الذي حددته وresult.type بقيمة succeeded أو errored أو canceled أو expired.

import time

while True:
    batch = client.messages.batches.retrieve(batch.id)
    if batch.processing_status == "ended":
        break
    print("still working:", batch.request_counts.processing)
    time.sleep(30)

labels, retry = {}, []
for result in client.messages.batches.results(batch.id):
    if result.result.type == "succeeded":
        msg = result.result.message
        labels[result.custom_id] = next(b.text for b in msg.content if b.type == "text")
    elif result.result.type == "errored":
        retry.append(result.custom_id)

print(f"{len(labels)} labeled, {len(retry)} need another pass")

تستحق أوضاع الفشل معالجة منفصلة. خطأ invalid_request يعني أن جسم الطلب كان خاطئاً، لذا أصلحه قبل إعادة الإرسال. أي شيء آخر هو من جانب الخادم ومن الآمن إعادة محاولته كما هو. نتيجة expired تعني أن النافذة البالغة 24 ساعة أُغلقت قبل تشغيل ذلك الطلب، فأعد إرساله أيضاً.

استعلم بمؤقت من 30 إلى 60 ثانية. فطرق نقطة نهاية الاسترجاع كل ثانية لا يجلب لك شيئاً ويُحتسب ضد حدود معدل Claude API الخاصة بك.

كدّس الأسعار الدفعية مع التخزين المؤقت للمطالبات

يأتي أكبر مكسب من الجمع بين الخصمين. إذا كانت كل مطالبة في دفعتك تشترك في بادئة طويلة — دليل أسلوب، تصنيف، عقد من 40 صفحة — ضع علامة على تلك البادئة بـ cache_control وأرسل نفس البادئة المعلَّمة على كل الطلبات العشرة آلاف.

shared_system = [
    {"type": "text", "text": "You are a support triage analyst."},
    {
        "type": "text",
        "text": taxonomy_document,          # thousands of tokens, identical every time
        "cache_control": {"type": "ephemeral"},
    },
]

ضع كتلة system تلك على كل Request في الدفعة. أي طلب تتطابق بادئته مع إدخال ذاكرة تخزين مؤقت حيّة بايتاً ببايت يُحتسب على تلك البادئة بأسعار قراءة الذاكرة المؤقتة، ويُطبَّق خصم الدفعة البالغ 50% على قراءات وكتابات الذاكرة المؤقتة على حد سواء. لا تضع ميزانية لمعدل إصابة مثالي: تعالج الدفعة طلباتها بشكل متزامن وليس بالترتيب، لذا فإن إصابات الذاكرة المؤقتة داخل دفعة واحدة هي بذل أفضل جهد. يغطي دليل التخزين المؤقت للمطالبات الخاص بـ Anthropic قواعد البادئة: أي بايت يتغير قبل نقطة التوقف الخاصة بك يُبطل كل شيء بعده، لذا أبقِ الطوابع الزمنية والنص الخاص بكل عنصر بعد الكتلة المخزنة مؤقتاً.

دع Claude Code يختبر نقطة النهاية باستخدام Apidog CLI

قبل أن تنفق المال على 100,000 طلب حي، تريد اختبار انحدار على دورة حياة الدفعة: الإنشاء، الاسترجاع، النتائج. كتابة ذلك يدوياً في واجهة رسومية بطيئة. دع وكيل البرمجة الخاص بك يقوم بذلك باستخدام Apidog CLI بدلاً من ذلك.

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install   # pick Claude Code when prompted

ثم مطالبة واحدة إلى Claude Code:

In Apidog project 4820193, create a test case for POST https://api.anthropic.com/v1/messages/batches
that submits two Haiku 5.5 requests with custom_id ticket-0 and ticket-1, asserts the response
has an id and processing_status, then polls GET /v1/messages/batches/{id} until processing_status
is ended. Run it against the anthropic-staging environment and summarize failures.

يقرأ الوكيل مخطط الحمولة، ويتحقق من JSON الخاص به، ثم ينشئ الحالة ويشغلها:

apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file batch-case.json
apidog test-case create --project 4820193 --file batch-case.json
apidog run --test-case 77214 --project 4820193 -e 992301 -r cli,json

يبقى مفتاح API الخاص بك في متغير بيئة Apidog، لذا لا يصل أبداً إلى مطالبة أو مستودع. بدّل أداة الإبلاغ إلى -r junit وسيعمل نفس الأمر في CI عند كل دمج، وهو الإعداد الموجود في دليل خط أنابيب Apidog CLI الخاص بنا. إذا لم تكن قد وصّلت CLI بوكيلك بعد، فابدأ بـ استخدام Apidog CLI في Claude Code.

متى تكون الدفعة الخيار الخاطئ

بعض الأشياء أيضاً لا تنتقل. الوضع السريع غير متاح على Batch API، وتُرفض الاحتياطات من جانب الخادم هناك، وعلى Claude Opus 5.5 وClaude Sonnet 5.5 يُعيد tool_choice المفروض بقيمة any أو tool خطأ 400 داخل الدفعة تماماً كما يفعل في استدعاء عادي. استخدم tool_choice: auto مع strict: true بدلاً من ذلك.

إذا كنت تدير بنية تحتية متعددة المزودين، فإن نفس النمط موجود في أماكن أخرى: انظر OpenAI Batch API ووضع الدفعة في Gemini API. تختلف الأشكال، لكن الاقتصاديات لا تختلف.

الأسئلة الشائعة

ما هي Claude Batch API؟

إنها نقطة نهاية غير متزامنة تشغّل طلبات Messages API القياسية بكميات كبيرة بنسبة 50% من أسعار الرموز العادية. تُرسل قائمة من الطلبات بمعرّفاتك الخاصة، وتستعلم حتى انتهاء الدفعة، وتقرأ النتائج خلال 29 يوماً.

كم تكلف Claude Batch API؟

نصف السعر القياسي على كل من الإدخال والإخراج. على Claude Sonnet 5.5 يكون $1.00 لكل مليون رمز مُدخَل و$5.00 لكل مليون رمز مُخرَج، مقابل $2.00 و$10.00 بشكل متزامن.

كم تستغرق دفعة Claude؟

تكتمل معظم الدفعات خلال ساعة. الحد الأقصى هو 24 ساعة، وبعدها يُعيد أي طلب غير معالَج نتيجة expired، فأعد إرساله.

هل يمكنني استخدام التخزين المؤقت للمطالبات داخل الدفعة؟

نعم، والخصومات تتكدس. ضع علامة على بادئة مشتركة بـ cache_control، وكرر تلك البادئة المتطابقة عبر كل طلب، وتُحتسب القراءات المخزنة مؤقتاً بجزء صغير من سعر الإدخال فوق خصم الدفعة.

ماذا يحدث عندما يفشل طلب واحد في دفعة؟

يفشل ذلك الطلب فقط. تحمل نتيجته type: "errored" مع كائن خطأ؛ وكل شيء آخر يظل ناجحاً. تحتاج أخطاء التحقق إلى حمولة مُصلَحة، وأخطاء الخادم آمنة لإعادة المحاولة دون تغيير.

هل يمكنني إلغاء دفعة قيد التشغيل؟

نعم. ينقل client.messages.batches.cancel(batch_id) الدفعة إلى canceling. تحتفظ الطلبات المنتهية بالفعل بنتائجها؛ ويعود الباقي بـ canceled.

هل تدعم Batch API الأدوات والصور؟

نعم. تعمل كل ميزة في Messages API داخل الدفعة، بما في ذلك الرؤية وتعريفات الأدوات ومطالبات النظام. الاستثناءات هي الوضع السريع والاحتياطات من جانب الخادم واختيار الأدوات المفروض على نماذج 5.5.

الختام

المعالجة الدفعية هي ثاني أكبر توفير مجاني على Claude API بعد التخزين المؤقت للمطالبات، وهي لا تكلفك شيئاً في الجودة: نفس النماذج، نفس الميزات، نصف السعر، مدفوعة بزمن استجابة لم تكن تستخدمه على الأرجح. اربط نتائجك بـ custom_id، وخزّن البادئة المشتركة مؤقتاً، وتعامل مع expired كإعادة محاولة وليس كفشل.

اختبر دورة الحياة قبل توسيع نطاقها. ثبّت Apidog CLI، ووجّه وكيل البرمجة الخاص بك إلى نقاط نهاية الدفعة، وأبقِ حالة الاختبار المُولَّدة قيد التشغيل في CI حتى لا يفاجئك تغيير المخطط عند 100,000 طلب. تغطي الخطة المجانية 4 مستخدمين، ويمكنك تنزيل Apidog وتشغيل أول حالة في غضون دقائق قليلة.