كيف تستخدم OpenAI Batch API

بحلول نهاية هذا الدليل، ستكون قادرًا على استدعاء Batch API الخاص بـ OpenAI لتشغيل آلاف طلبات النماذج كوظيفة غير متزامنة واحدة واستعادة كل نتيجة بخصم 50%. ستقوم بتجميع مطالباتك في ملف JSONL، وتقديم دفعة واحدة، والاستعلام عنها حتى تنتهي، وتنزيل المخرجات، ثم اختبار كل خطوة في Apidog قبل ربطها بالإنتاج. إذا كان عملك أكثر تفاعلية، فإن المسار المتزامن (synchronous) هو الأنسب، ويمكنك اختبار ChatGPT API باستخدام Apidog بدلاً من ذلك.

ما هو Batch API ومتى يجب استخدامه

Batch API هو نقطة نهاية غير متزامنة لكميات كبيرة من استدعاءات النماذج التي يمكن أن تتسامح مع التأخير. بدلاً من طلب HTTP واحد لكل مطالبة، تقوم بتجميع العديد من الطلبات في ملف JSONL واحد، وتقديمه كوظيفة واحدة، وتستعلم عن اكتماله. يقوم OpenAI بتشغيل المهمة خارج أوقات الذروة ويعيد كل نتيجة في ملف إخراج.

تحصل على فائدتين ملموستين. أولاً، خصم ثابت بنسبة 50% على رموز الإدخال والإخراج مقارنةً بالواجهة البرمجية المتزامنة (synchronous API). ثانيًا، إنتاجية أعلى، حيث تستخدم مهام الدفعات مجمعًا منفصلاً لحدود المعدل ولا تتنافس مع حركة المرور المباشرة الخاصة بك. المقايضة هي زمن الوصول (latency). يلتزم OpenAI بالانتهاء في غضون 24 ساعة؛ تنتهي العديد من المهام في وقت أقرب، لكن لا يمكنك الاعتماد على ذلك.

استخدم معالجة الدُفعات عندما يكون العمل غير متصل بالإنترنت وبكميات كبيرة:

تصنيف أو وسم سجلات متراكمة
توليد تضمينات (embeddings) لمجموعة نصوص كاملة
توليد المحتوى بكميات كبيرة (أوصاف المنتجات، ملخصات، ترجمات)
تشغيل مجموعات التقييم أو مقارنات النماذج على مجموعة بيانات

تخطاها لأي شيء ينتظره المستخدم. واجهات المستخدم للمحادثة (Chat UIs)، والإكمال التلقائي، والوكلاء المباشرون يحتاجون إلى نقاط النهاية المتزامنة. إذا كنت تقوم بإنشاء العديد من تكوينات النماذج أو الوكلاء دفعة واحدة، فإن معالجة الدُفعات تتناسب جيدًا مع عبء العمل هذا؛ راجع دليلنا حول توليد أكثر من 100 تكوين وكيل باستخدام معالجة الدُفعات.

ما تحتاجه قبل البدء

تتضمن العملية بأكملها نقطتي نهاية، /v1/files و /v1/batches، وأربع خطوات. إليك الشكل العام قبل أن نلقي نظرة على الاستدعاءات.

الخطوة	نقطة النهاية (Endpoint)	ماذا يحدث
1. الرفع	`POST /v1/files`	أرسل ملف `.jsonl` الخاص بك مع `purpose: "batch"`، وستستقبل معرّف الملف
2. الإنشاء	`POST /v1/batches`	أرسل معرّف الملف مع نقطة نهاية ونافذة اكتمال
3. الاستعلام	`GET /v1/batches/{id}`	تحقق من `status` حتى يصبح `completed`
4. الاسترجاع	`GET /v1/files/{id}/content`	نزّل النتائج عبر `output_file_id`

للمتابعة، تحتاج إلى مفتاح OpenAI API تم تصديره كـ OPENAI_API_KEY، وملف JSONL للطلبات، وأداة لتشغيل والاستعراض للطلبات. تُرجع كل خطوة كائنًا يمكنك التحقق منه، مما يجعل دورة الحياة بأكملها سهلة الاختبار.

الخطوة 1: بناء وتحميل ملف JSONL

مدخلاتك هي ملف JSONL حيث يمثل كل سطر طلبًا واحدًا مستقلاً. يحتاج كل سطر إلى أربعة حقول: custom_id تختاره (حتى تتمكن من مطابقة النتائج مع المدخلات)، وmethod (POST)، وurl (نقطة النهاية المستهدفة مثل /v1/chat/completions)، وbody يحمل معلمات الطلب الفعلية.

{"custom_id": "req-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4.1-mini", "messages": [{"role": "user", "content": "Classify the sentiment of: 'shipping was slow but the product is great'"}]}}
{"custom_id": "req-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4.1-mini", "messages": [{"role": "user", "content": "Classify the sentiment of: 'returned it the same day'"}]}}

يجب أن يكون custom_id فريدًا داخل الملف. تعود النتائج بترتيب غير مضمون، لذا فإن هذا المعرّف هو كيفية إعادة ربط كل استجابة بسطرها الأصلي. يمكن أن تحتوي الدفعة الواحدة على ما يصل إلى 50,000 طلب ويمكن أن يصل حجم الملف إلى 200 ميجابايت.

ارفعه إلى Files API مع الغرض batch:

curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="batch" \
  -F file="@requests.jsonl"

تحمل الاستجابة معرّف ملف id (شيء مثل file-abc123). هذا هو input_file_id الخاص بك للخطوة التالية.

الخطوة 2: إنشاء الدفعة

الآن أنشئ المهمة. تمرر input_file_id، وendpoint الذي تستهدفه، وcompletion_window. حاليًا، يقبل completion_window قيمة واحدة، وهي "24h".

curl https://api.openai.com/v1/batches \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "file-abc123",
    "endpoint": "/v1/chat/completions",
    "completion_window": "24h",
    "metadata": {"job": "sentiment-backfill"}
  }'

يجب أن يتطابق حقل endpoint مع url المستخدم داخل سطور JSONL الخاصة بك. تتضمن الأهداف المدعومة /v1/chat/completions، و/v1/responses، و/v1/embeddings، و/v1/completions، و/v1/moderations، وغيرها. يحمل الكائن الاختياري metadata ما يصل إلى 16 زوجًا من المفتاح والقيمة، وهو مفيد لتصنيف المهام التي ستحتاج إلى تصفيتها لاحقًا.

يعيد الاستدعاء كائن دفعة. الحقول التي ستهتم بها أكثر:

{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "input_file_id": "file-abc123",
  "completion_window": "24h",
  "status": "validating",
  "output_file_id": null,
  "error_file_id": null,
  "request_counts": { "total": 0, "completed": 0, "failed": 0 },
  "created_at": 1733452800,
  "metadata": { "job": "sentiment-backfill" }
}

الخطوة 3: الاستعلام عن حالة الدفعة

تبدأ الدفعة الجديدة بحالة validating. ومن هناك تنتقل عبر مجموعة من الحالات الموثقة. استعلم عن GET /v1/batches/{batch_id} واقرأ حقل status.

الحالة (Status)	المعنى
`validating`	يتم التحقق من ملف الإدخال قبل بدء التشغيل
`in_progress`	تتم معالجة الطلبات
`finalizing`	انتهى التشغيل ويتم إعداد ملف الإخراج
`completed`	اكتمل؛ النتائج جاهزة للتنزيل
`failed`	فشل التحقق؛ لم يتم تشغيل أي شيء
`expired`	انتهت نافذة الـ 24 ساعة قبل اكتمال جميع الطلبات
`cancelling` / `cancelled`	لقد طلبت الإلغاء

يوفر لك الكائن request_counts (total، completed، failed) تقدمًا مباشرًا بينما تكون الحالة in_progress. لا يوجد webhook للانتظار عليه هنا، لذا فإن الاستعلام على فترات معقولة (كل بضع دقائق، وليس كل ثانية) هو النمط الصحيح. يمكنك أيضًا إلغاء مهمة قيد التشغيل باستخدام POST /v1/batches/{batch_id}/cancel إذا قمت بتقديمها عن طريق الخطأ.

الخطوة 4: استرجاع المخرجات

عندما تكون status هي completed، يحمل كائن الدفعة output_file_id. نزّل محتويات هذا الملف عبر Files API:

curl https://api.openai.com/v1/files/file-output456/content \
  -H "Authorization: Bearer $OPENAI_API_KEY" > results.jsonl

المخرجات هي JSONL مرة أخرى، سطر واحد لكل طلب. يعكس كل سطر custom_id الذي قمت بتعيينه، بالإضافة إلى كائن response يحتوي على رمز الحالة والجسم. تظهر أي طلبات بها أخطاء في الملف المشار إليه بواسطة error_file_id، لذا تحقق من كلاهما. طابق النتائج مع المدخلات بناءً على custom_id، وليس على ترتيب السطور.

ضع في اعتبارك مقايضات التكلفة والنافذة الزمنية

الحساب بسيط: توفر 50% على الرموز وتوافق على مهلة تصل إلى 24 ساعة. بالنسبة لملء بيانات متأخرة لمرة واحدة أو مهمة ليلية، هذا خيار سهل. لكن بالنسبة لميزة في المسار الحرج لمنتجك، فهو ليس كذلك.

بعض الملاحظات العملية:

ينطبق الخصم على رموز الإدخال والإخراج على حد سواء، عبر النماذج المدعومة.
نافذة الـ 24 ساعة هي حد أقصى، وليست هدفًا. خطط للأسوأ؛ إذا وصلت مهمة ما إلى حالة expired، فإن الطلبات التي اكتملت لا تزال تُحاسب وتُعاد، والبقية لا.
تستمد مهام الدُفعات من حد منفصل للرموز في قائمة الانتظار، لذا فإن دفعة كبيرة لن تستهلك حدود المعدل التي تعتمد عليها حركة المرور المباشرة الخاصة بك. إذا كنت تواجه قيودًا بالفعل، فإن دليلنا حول حدود معدل GPT API وكيفية اختبارها يغطي الجانب المتزامن.
الرموز بنصف السعر لا تزال تتراكم بكميات كبيرة. تتبع الإنفاق لكل مهمة باستخدام علامة metadata حتى تتمكن من تحديد التكلفة لاحقًا؛ إليك دليل إسناد التكلفة للإنفاق على OpenAI.

كيفية اختباره في Apidog

Batch API أكثر عرضة للأخطاء من استدعاء محادثة واحد، لأن أنماط الفشل تتوزع عبر الملفات وتنسيق JSONL وحلقة الاستعلام (polling loop). سطر غير صحيح في ملف يضم 50,000 طلب يؤدي إلى فشل التحميل بالكامل، ولن تعرف بذلك حتى يتم تشغيل التحقق. اختبار نقاط نهاية دورة الحياة قبل أتمتتها يوفر عليك هذه الرحلة الطويلة.

Apidog هي منصة API حيث يمكنك تشغيل كل خطوة كطلب، وربطها، والتحقق من الاستجابات. إنها تختبر وتحاكي نقاط النهاية؛ إنها ليست OpenAI SDK. الإعداد الواقعي يبدو كالتالي:

التحقق من شكل JSONL أولاً. قبل تحميل أي شيء، تأكد من أن كل سطر يحتوي على custom_id، وmethod، وurl، وbody، وأن body.model والرسائل موجودة. اكتشاف حقل مفقود محليًا أرخص من دفعة فاشلة.
تشغيل التحميل متعدد الأجزاء. أرسل POST /v1/files مع purpose=batch وملفك، ثم التقط الـ id العائد إلى متغير بيئة.
إنشاء الدفعة والتحقق من الكائن. قم بتشغيل POST /v1/batches، ثم تحقق من أن status هو validating وأن endpoint يطابق ما أرسلته. تتيح لك تأكيدات Apidog المرئية التحقق من تلك الحقول دون كتابة نصوص برمجية.
الاستعلام والاسترجاع. قم بضرب GET /v1/batches/{id} في حلقة، تحقق عندما تصبح status هي completed، ثم اسحب output_file_id ونزّل النتائج.
تدريب مسارات الإلغاء والخطأ. أرسل ملفًا معطلًا عمدًا وتأكد من حصولك على حالة failed، واختبر POST /v1/batches/{id}/cancel بحيث يكون معالجة الأخطاء حقيقية، وليست مفترضة.

نظرًا لأن ملف الإخراج يصل لاحقًا، يمكنك أيضًا إعداد واجهة برمجة تطبيقات وهمية (mock API) تُعيد كائن دفعة مكتملة عينة وملف نتائج مُعلب. يتيح لك ذلك بناء واختبار منطق الاسترجاع والتحليل الخاص بك دون انتظار مهمة حقيقية تستغرق 24 ساعة، ودون استهلاك الرموز أثناء التطوير. عندما يعمل فريقك وفقًا للمواصفات أولاً، يمكنك أيضًا إنشاء مجموعة اختبار مباشرة من مواصفات OpenAPI والحفاظ على نقاط نهاية الدفعات تحت تغطية الانحدار في CI.

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

كم يستغرق تنفيذ الدفعة في الواقع؟

تلتزم OpenAI بإكمال الدفعة في غضون 24 ساعة. في الممارسة العملية، تنتهي العديد من المهام بشكل أسرع، ولكن الضمان هو سقف الـ 24 ساعة، لذا ابنِ نظامك حول ذلك. إذا انتهت النافذة ولم يكتمل العمل، تنتقل الدفعة إلى حالة expired ويتم إرجاع الطلبات المكتملة فقط ويتم محاسبتك عليها.

ما هو الخصم الحقيقي، وهل يتراكم؟

يوفر Batch API خصمًا ثابتًا بنسبة 50% مقارنةً بنقاط النهاية المتزامنة، على رموز الإدخال والإخراج على حد سواء. إنه أكبر عامل منفرد لخفض التكلفة تقدمه OpenAI لأعباء العمل غير المتصلة بالإنترنت. إذا كنت تحاول إسناد هذا الإنفاق إلى ميزات أو مهام، فإن دليل إسناد التكلفة يوضح كيفية تقسيم ذلك.

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

تقوم بتعيين الهدف في كل من url في JSONL وحقل endpoint الخاص بالدفعة، ويجب أن يتطابقا. تتضمن الأهداف المدعومة /v1/chat/completions، و/v1/responses، و/v1/embeddings، و/v1/completions، و/v1/moderations، بالإضافة إلى نقاط نهاية الصور والفيديو. تحقق من الوثائق الحالية للحصول على القائمة الكاملة، حيث يضيف OpenAI إليها بمرور الوقت.

لماذا نتائجي غير مرتبة؟

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

الخلاصة

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

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

زر