إدارة الدفعات

إرسال طلبات مجمعة غير متزامنة وفحص حالة تنفيذ الدفعة.

إرسال طلبات مجمعة غير متزامنة عبر نقاط نهاية النماذج المدعومة باستخدام واجهة برمجة تطبيقات Batch المتوافقة مع OpenAI.

POST/openai/v1/batches

جسم الطلب

الحقلالنوعمطلوبالوصف
input_file_idstringنعممعرف الملف الذي تم تحميله مع تعيين الغرض إلى batch.
endpointstringنعمنقطة النهاية المستهدفة (/v1/chat/completions أو /v1/completions أو /v1/responses أو /v1/embeddings).
completion_windowstringنعمنافذة الاكتمال، وهي ثابتة حالياً عند 24h.
metadataobjectلاأزواج مفتاح وقيمة اختيارية للتتبع والمتابعة.

يجب أن تكون ملفات الإدخال بتنسيق JSONL بترميز UTF-8 بما لا يتجاوز 50,000 عنصر وحجم ملف أقصاه 200 MiB. يجب أن يكون كل سطر في JSONL كائناً برمجياً صالحاً يحتوي على معرف فريد غير فارغ custom_id، وأسلوب method: "POST"، وعنوان url يطابق نقطة نهاية الدفعة endpoint، وكائن body (يحتوي على حقل model إلزامي للدفعات المدفوعة مسبقاً الصارمة). بالنسبة للدفعات المدفوعة مسبقاً، تتحقق البوابة من المجموع الاختباري للملف وسياسات التنفيذ قبل التمويل؛ وتُحجز مخصصات جميع العناصر بشكل ذري قبل الإرسال للمزود. في حال عدم كفاية الرصيد الإجمالي، يتم إرجاع HTTP 402 دون إرسال جزئي. لا يمكن تقسيم تكوينات المزود غير المتوافقة داخل الدفعة الواحدة، ولا يتم إجراء تجاوز فشل بين المزودين على مستوى العناصر.

دورة حياة الدفعة

GET/openai/v1/batches/{batch_id}
POST/openai/v1/batches/{batch_id}/cancel
  • validating: التحقق من صحة تنسيق ملف الإدخال وبناء جملة JSONL والالتزام بمخطط العناصر.
  • in_progress: توزيع العناصر إلى بيانات اعتماد المزود المحددة دون تجاوز الفشل بين المزودين.
  • finalizing: تجميع مخرجات الإكمال وتسجيل تسوية الاستخدام في دفتر الأستاذ.
  • completed: اكتمال المعالجة بنجاح وإنشاء output_file_id و error_file_id الاختياري.
  • failed: حالة فشل نهائية في حال فشل التحقق من صحة الملف أو تنسيق الدفعة بالكامل.
  • cancelling: إيقاف المعالجة بشكل آمن بناءً على الطلب والتحول إلى حالة الإلغاء.
  • cancelled: يشير إلى إيقاف تنفيذ الدفعة قبل اكتمالها النهائي. لا تثبت نتائج العناصر الفاشلة أو الملغاة أو المفقودة تكلفة صفرية من المزود؛ تحتفظ التسوية بالتمويل المحجوز للمطابقة مع سجلات المزود. الحالة المعتمدة في AnyInt هي cancelled.
  • expired: يتم تفعيلها عند تجاوز نافذة الاكتمال البالغة 24 ساعة؛ وتتطلب المعاملات غير المؤكدة تسوية بناءً على سجلات المزود ولا تعني تكلفة مزود صفرية.

قائمة الدفعات وتنزيل النتائج

GET/openai/v1/batches
  • عرض الدفعات: GET /openai/v1/batches يسرد مهام الدفعات النشطة والمؤرشفة للمؤسسة أو المشروع المصرح به.
  • تخزين الكائنات والتنزيل: قبول الملفات ذات الغرض batch وتشغيل عمليات الدفعات يتطلب تخزين كائنات مشتركاً (OBJECT_STORE_MODE). بعد الاكتمال، يمكن تنزيل ملفات مخرجات وأخطاء JSONL عبر واجهة الملفات في GET /openai/v1/files/{file_id}/content.

مسارات التوافق

  • تقبل البوابة /v1/batches للتوافق؛ يوصى باستخدام /openai/v1/batches للتكاملات الجديدة.