تناسب Batch API في OpenAI الأعمال التي يمكن انتظار نتائجها، مثل تصنيف مجموعة بيانات أو تشغيل اختبارات تقييم، بدل إرسال كل طلب وانتظار رده فورًا. وللتحضير لاستخدامها في عام 2027، افهم أولًا طريقة تجهيز الملف وربط النتائج بالطلبات والتعامل مع انتهاء المهلة. يعرض هذا الدليل الإمكانات الموثقة عند المراجعة في 27 أكتوبر 2026، ولا يفترض نماذج أو أسعارًا جديدة لعام 2027.
متى تختار المعالجة على دفعات؟
توفر الخدمة خصمًا بنسبة 50% مقارنة بالواجهات المتزامنة، مع مجموعة منفصلة من حدود الاستخدام ونافذة معالجة مقدارها 24 ساعة. لكنها ليست بديلًا مناسبًا لمحادثة تنتظر إجابة فورية، ولا تدعم بث الردود أثناء توليدها. تحقق من أن النموذج الذي تختاره يدعم Batch؛ فالدعم ليس شاملًا لكل النماذج.
تجهيز ملف الطلبات دون فقدان الربط
- أنشئ ملفًا بصيغة JSONL، بحيث يحتوي كل سطر على طلب مستقل، لا مصفوفة واحدة تضم جميع الطلبات.
- ضع لكل طلب قيمة فريدة في الحقل
custom_idلتستطيع ربط نتيجته ببياناته الأصلية لاحقًا. - حدد طريقة الطلب ومساره ومحتواه، مع استخدام معاملات الواجهة المستهدفة داخل
body. احرص على تطابق المسارات مع الواجهة التي تختارها للدفعة. - اجعل الطلبات داخل ملف الإدخال لنموذج واحد. ثم ارفع الملف باستخدام Files API مع تعيين الغرض
purposeإلىbatch. - أنشئ الدفعة باستخدام
input_file_idللملف المرفوع وendpointالمناسب. نافذة الإكمال المدعومة حاليًا هي24h.
الحد لكل دفعة هو 50 ألف طلب، وحجم ملف الإدخال حتى 200 ميجابايت. ولدفعات embeddings حد إضافي: 50 ألف مُدخل تضمين عبر جميع طلبات الدفعة. وتوجد أيضًا حدود للرموز المدخلة المنتظرة لكل نموذج؛ فلا تخلط بين حد الملف وحدود حسابك.
قراءة الحالة واسترجاع النتائج
تبدأ الدفعة بحالة validating لفحص الملف، وقد تصبح failed إذا فشل التحقق. ثم تشير in_progress إلى التنفيذ، وfinalizing إلى تجهيز النتائج، وcompleted إلى جاهزيتها.
استرجع ملف النتائج الناجحة عبر output_file_id، وافحص ملف الأخطاء عبر error_file_id. لا تعتمد على ترتيب الأسطر: قد يختلف ترتيب النتائج عن ترتيب الإدخال، ولذلك يكون الربط بواسطة custom_id. نزّل النتائج واحفظها ضمن خطة احتفاظ واضحة، وراجع سياسة انتهاء ملفات الإخراج والأخطاء إذا ضبطتها عند إنشاء الدفعة.
انتهاء المهلة والإلغاء والتكلفة
إذا انتهت النافذة دون اكتمال العمل، تصبح الحالة expired وتلغى الطلبات غير المنفذة، بينما تبقى نتائج الطلبات المكتملة متاحة وتُحتسب تكلفتها. والإلغاء اليدوي قد يمر بحالة cancelling حتى عشر دقائق قبل cancelled؛ وهو لا يجعل العمل المكتمل مجانيًا.
قبل إعادة المحاولة، طابق النتائج والأخطاء مع معرفات الإدخال حتى لا تعيد معالجة الطلبات الناجحة. ولا تفترض انطباق عدم الاحتفاظ بالبيانات على Batch لمجرد تفعيله للمؤسسة؛ راجع سياسة الاحتفاظ قبل رفع بيانات حساسة.
