واجهة Batch API لنماذج LLM: 50 ألف طلب بخصم يصل إلى 50% وثلاث فئات من الأخطاء

ما دامت طلبات LLM بالعشرات أو المئات، تتصرف واجهة API المتزامنة بشكل لائق: ترسل طلبًا وتتلقى ردًا. لكن حين تحتاج إلى معالجة 50 ألف عقد أو بطاقة منتج، تصطدم سريعًا بحدود TPM وRPM، وتبدأ الطلبات ذات السياق الطويل بالفشل حتى قبل بدء التوليد. لمثل هذه المهام تقدّم OpenAI وAnthropic وGoogle وضع الدفعات، أي Batch API. تجمع كل المهام في ملف واحد، وترسله إلى المزوّد، وتنتظر حتى 24 ساعة، لكنك تدفع أقل.

كيف يعمل الطابور

خلف كلمة «باتش» البسيطة تقف ثلاثة مستويات من القيود.

المستوى الأول هو الحزمة نفسها. إنها ملف JSONL يحتوي كل سطر فيه على custom_id وmethod وurl وbody يتضمن النموذج والرسائل. في جوهره هو طلب عادي إلى Chat Completions معبّأ في سطر واحد. يُرفع الملف عبر Files API مع purpose بقيمة «batch»، ثم تُنشأ المهمة. لا تعود النتائج بالترتيب الذي أرسلتها به، لذلك يعمل custom_id عمليًا كمفتاح أساسي: به تطابق الرد مع السجل الأصلي.

المستوى الثاني هو مجموعة الرموز المنتظرة (enqueued). لا يُحتسب الحد بحسب الملفات، بل بحسب الحجم الإجمالي للرموز في جميع الحزم غير المكتملة. إذا دفعت حزمة جديدة المؤسسة فوق السقف، تعيد API الخطأ token_limit_exceeded وترفض إنشاء المهمة. لدى OpenAI يعتمد السقف على الـ tier: كلما ارتفع، أمكن إبقاء عدد أكبر من الرموز في الطابور.

المستوى الثالث هو نافذة الإكمال. الأربع والعشرون ساعة هي اتفاقية مستوى خدمة (SLA) وليست توقعًا. عمليًا تنتهي الحزم في الغالب خلال بضع ساعات، وتكتب Anthropic أن معظم الدفعات تكون جاهزة في أقل من ساعة. لكن ينبغي الاعتماد على أسوأ الحالات. المعامل completion_window يقبل حاليًا القيمة «24h» فقط.

أين ينكسر خط المعالجة

يقسّم كاتب المقال الأصلي الأخطاء إلى أربع فئات، والفخاخ هنا ليست بسيطة.

قبل إنشاء الحزمة. فاصلة زائدة في JSONL، أو تكرار custom_id أو إغفاله، أو endpoint خاطئ. بحسب الكاتب، لا تتحقق Anthropic من معاملات الطلبات إلا بعد اكتمال الحزمة كلها: يمكنك إرسال 100 ألف سطر، وانتظار ساعة، ثم اكتشاف أن في ثلاثة منها قيمة max_tokens خاطئة. لذلك تحققوا من الملف محليًا قبل رفعه: حلّلوا كل سطر، وافحصوا تفرّد custom_id ووجود model وmessages. ونماذج Pydantic مناسبة لذلك أيضًا.

على مستوى الطابور. الخطأ الرئيسي هنا هو token_limit_exceeded. يُعالَج بحساب الرموز قبل الإرسال وبطابور خاص بك في جانب التطبيق. إذا لم تتسع الميزانية، فانتظروا اكتمال الحزم السابقة أو أعيدوا المحاولة مع backoff أسّي: 30 ثم 60 ثم 120 ثانية وهكذا.

داخل الحزمة. هذه هي الفئة الأكثر مكرًا. تكون الحزمة completed، لكن في الملف المُصدَّر بعض الأسطر succeeded وبعضها errored وبعضها expired. إذا اكتفى الكود بقراءة content وكتابته في قاعدة البيانات، تضيع الأسطر الإشكالية بصمت. لدى Anthropic تبقى عدّادات errored وcanceled وexpired في request_counts صفرية حتى تكتمل الحزمة كلها، فلا يمكن تقدير حجم الفشل مسبقًا. المخطط المعقول يعتمد ثلاث سلال: invalid_request يُصلَح ويُعاد إرساله، وأخطاء الخادم تُعاد مع تأخير، وexpired تذهب إلى حزمة جديدة لأن النافذة أُغلقت بالفعل.

عند الاستعلام عن الحالة. إذا استعلمتم عن الحالة كل خمس ثوانٍ، فقد تتلقون 429 على الاستعلام نفسه. ستقرأ الحلقة الساذجة ذلك على أنه «الحزمة غير جاهزة»، بينما اصطدمتم في الواقع بحد المعدّل (rate limit) على القراءة. للحزم التي تصل إلى ألف سطر استعلموا مرة كل 30 ثانية، وللكبيرة مرة كل 2–5 دقائق. وإذا ظلت الحزمة معلّقة أكثر من بضع ساعات، فتحققوا من أنها لم تعلق في مرحلة validating.

كم تكلّف فعلًا

الخصم بنسبة 50% سقف وليس ضمانًا. الرقم النهائي يعتمد على عدد الطلبات التي انتهت إلى expired، وعدد ما اضطررتم إلى إعادة إرساله، وعلى استخدام تخزين موجّه النظام المؤقت. في السيناريو الجيد يكون التوفير أعلى حتى، لأن cached-input أرخص أيضًا. وفي السيناريو السيئ تدفعون مرتين مقابل الأسطر نفسها. وثمة تفصيل مهم آخر: لدى OpenAI عند إلغاء الحزمة تُلغى الطلبات غير المكتملة، أما الطلبات المنفّذة فعلًا فتُحاسَب.

وتجدر الإشارة بشكل منفصل إلى أن النص الأصلي مكتوب جزئيًا بنَفَس إعلاني: يقترح الكاتب بوابة Bothub المتوافقة مع OpenAI مع الدفع ببطاقة روسية وتوفير معلن بنسبة 45%. فكرة نقطة النهاية المتوافقة عملية، لكن شروط أي وسيط وموثوقيته ينبغي التحقق منها بنفسكم، لا بالاعتماد على رابط إحالة.

ماذا نفعل عمليًا

الباتش عقد مختلف: تحصلون على خصم ومجموعة حدود منفصلة، لكنكم تتحمّلون مسؤولية تحليل النتائج. إذا كنتم تبنون معالجة جماعية للمستندات أو التصنيف أو الوسم، فضمّنوا في خط المعالجة عدة أمور:

• تحققًا محليًا من JSONL قبل الإرسال؛
• حساب الرموز وسيمافور على حد enqueued؛
• تحليل الملف المُصدَّر بحسب نوع النتيجة وإعادة إرسال الأسطر الفاشلة فقط؛
• استعلامًا دوريًا (polling) مع backoff وتسجيل created_at.

والقاعدة الأهم: لا تعيدوا إرسال حزمة كاملة بسبب ثلاثة أسطر فاشلة، لأنكم دفعتم بالفعل مقابل الناجحة.