بالنسبة للمطورين الذين يعملون مع نماذج اللغة الكبيرة (LLMs)، غالبًا ما تكون التكلفة وزمن الاستجابة (Latency) العائقين الرئيسيين عند معالجة مجموعات البيانات الكبيرة. سواء كنت تولّد أوصافًا للمنتجات لموقع تجارة إلكترونية يحتوي على ملايين العناصر، أو تلخّص آلاف تذاكر الدعم، أو تجري تحليل المشاعر على السجلات التاريخية، فإن إجراء استدعاءات API فردية لكل عنصر غير فعال ومكلف.
هنا يأتي دور واجهة برمجة التطبيقات الدفعية (Batch API) من OpenAI. تتيح لك هذه الميزة إرسال كميات كبيرة من الطلبات غير العاجلة إلى OpenAI بخصم كبير. من خلال تجميع الطلبات في مهمة واحدة تُعالج بشكل غير متزامن (Asynchronously)، يمكنك تقليل تكاليف رموز الإدخال والإخراج (Tokens) بنسبة تصل إلى 50% مقارنةً باستدعاءات API الفورية. في هذا الدليل، سنستكشف كيفية تنفيذ واجهة برمجة التطبيقات الدفعية بفعالية للمعالجة واسعة النطاق للبيانات.
لماذا تستخدم واجهة برمجة التطبيقات الدفعية (Batch API)؟
الميزة الأساسية لواجهة برمجة التطبيقات الدفعية هي كفاءة التكلفة. تقدم OpenAI خصمًا بنسبة 50% على جميع الرموز المستخدمة في الطلبات الدفعية. ومع ذلك، يأتي هذا مع تنازلات:
- معالجة غير متزامنة: لا يمكنك توقع ردود فورية. عادةً ما تكتمل المهام خلال 24 ساعة.
- عدم وجود تفاعل فوري: ليست مناسبة للروبوتات الدردشية أو التطبيقات التي تتطلب ملاحظات فورية من المستخدم.
- حجم دفعة ثابت: يجب عليك إعداد جميع الطلبات مسبقًا قبل الإرسال.
إذا كان استخدامك يتضمن التحليلات غير المتصلة، أو توليد المحتوى، أو تسمية البيانات، فإن واجهة برمجة التطبيقات الدفعية هي الخيار المثالي.
الخطوة 1: جهّز ملف JSONL الخاص بك
الخطوة الأولى في أي مهمة دفعية هي إنشاء ملف JSON Lines (JSONL). يمثل كل سطر في هذا الملف طلب API واحدًا. يجب أن يتطابق الهيكل مع تنسيق طلبات OpenAI API القياسية، بما في ذلك `custom_id` فريد للتتبع.
import json
def create_batch_file(data_points, output_filename="batch_input.jsonl"):
"""
يولّد ملف JSONL لواجهة برمجة التطبيقات الدفعية من OpenAI.
Args:
data_points: قائمة من النصوص المراد معالجتها.
output_filename: اسم ملف JSONL الناتج.
"""
with open(output_filename, 'w') as f:
for i, text in enumerate(data_points):
request = {
"custom_id": f"request-{i}",
"method": "POST",
"url": "/v1/chat/completions",
"body": {
"model": "gpt-4o",
"messages": [
{
"role": "user",
"content": f"Summarize the following text in one sentence: {text}"
}
],
"max_tokens": 100
}
}
f.write(json.dumps(request) + '\n')
print(f"تم إنشاء ملف الدفعة '{output_filename}' بنجاح.")
# مثال على الاستخدام
sample_data = [
"The quick brown fox jumps over the lazy dog.",
"Python is a high-level programming language known for its readability.",
"Machine learning is a subset of artificial intelligence."
]
create_batch_file(sample_data)الخطوة 2: ارفع الملف وأنشئ مهمة الدفعة
بمجرد جاهزية ملف JSONL، تحتاج إلى رفعه إلى OpenAI وبدء مهمة الدفعة باستخدام SDK بلغة Python.
from openai import OpenAI
import time
client = OpenAI() # يتم قراءة مفتاح API من متغير البيئة
# 1. ارفع الملف
file_response = client.files.create(
file=open("batch_input.jsonl", "rb"),
purpose="batch"
)
file_id = file_response.id
print(f"تم رفع الملف بالمعرّف: {file_id}")
# 2. أنشئ مهمة الدفعة
batch = client.batches.create(
input_file_id=file_id,
endpoint="/v1/chat/completions",
completion_window="24h"
)
batch_id = batch.id
print(f"تم إنشاء مهمة الدفعة بالمعرّف: {batch_id}")الخطوة 3: استطلع حالة الاكتمال
بما أن مهمة الدفعة غير متزامنة، يجب عليك استطلاع الحالة حتى تكتمل. اعتمادًا على حجم المهمة، قد يستغرق ذلك عدة ساعات. بالنسبة لأنظمة الإنتاج، يُوصى بتنفيذ مهمة cron أو نظام إشعارات قائم على Webhook بدلاً من الحجب داخل السكربت.
def poll_batch_status(batch_id, client, interval=60):
"""
يستطلع حالة مهمة الدفعة حتى تكتمل أو تفشل.
"""
while True:
batch = client.batches.retrieve(batch_id=batch_id)
status = batch.status
print(f"الحالة الحالية: {status}")
if status in ["completed", "failed", "expired", "cancelled"]:
return batch
time.sleep(interval)
# انتظر الاكتمال
final_batch = poll_batch_status(batch_id, client, interval=300) # تحقق كل 5 دقائقالخطوة 4: استرجع النتائج ومعالجتها
بمجرد تحديد الدفعة على أنها `completed` (مكتملة)، يمكنك تنزيل ملف الإخراج. يحتوي هذا الملف على الردود المقابلة لكل `custom_id` من ملف الإدخال.
def download_and_process_results(batch_id, client):
"""
ينزّل ملف إخراج الدفعة ويحلل النتائج.
"""
# استرجع معرّف ملف الإخراج
output_file_id = client.batches.retrieve(batch_id).output_file_id
if output_file_id is None:
raise ValueError("لم يتم العثور على ملف إخراج. قد تكون المهمة فشلت.")
# استرجع محتوى الملف
file_content = client.files.content(output_file_id)
# حلل محتوى JSONL
results = []
for line in file_content.splitlines():
if line.strip():
data = json.loads(line)
# استخرج المحتوى من الاستجابة
response_content = data.get('response', {}).get('body', {}).get('choices', [{}])[0].get('message', {}).get('content', '')
results.append({
'id': data.get('custom_id'),
'summary': response_content
})
return results
# عالج النتائج
results = download_and_process_results(batch_id, client)
for r in results:
print(f"{r['id']}: {r['summary']}")أفضل الممارسات للمعالجة الدفعية
- التعامل مع الأخطاء بسلاسة: قد تفشل بعض الطلبات بسبب انتهاكات سياسة المحتوى أو مشاكل التنسيق. تحقق دائمًا من حقل `error` في أسطر JSONL الناتجة.
- تقسيم مجموعات البيانات الكبيرة: على الرغم من عدم وجود حد صارم، إلا أن الملفات الكبيرة جدًا قد يصعب تصحيح أخطائها. فكّر في تقسيم ملايين الصفوف إلى دفعات من 10,000 إلى 50,000 لإدارة أسهل.
- تحكم في إصدارات الموجهات (Prompts): بما أن مهام الدفعة تستغرق وقتًا للتشغيل، تأكد من أن قالب الموجه مستقر. إذا كنت بحاجة إلى تغيير الموجه، يجب عليك إنشاء ملف جديد ومهمة دفعة جديدة.
- راقب التكاليف: استخدم لوحة تحكم OpenAI لتتبع استخدام الرموز والتكاليف لكل مهمة دفعة للتأكد من أنك تعظم التوفير.
الخلاصة
تُعد واجهة برمجة التطبيقات الدفعية من OpenAI أداة قوية للمطورين الذين يسعون إلى توسيع نطاق تطبيقات الذكاء الاصطناعي الخاصة بهم دون زيادة التكاليف بشكل خطي. من خلال الاستفادة من المعالجة غير المتزامنة، يمكنك التعامل مع تحديات البيانات واسعة النطاق التي ستكون باهظة التكلفة أو بطيئة للغاية مع استدعاءات API الفورية. مع استمرار تطور تطبيقات نماذج اللغة الكبيرة، سيصبح إتقان المعالجة الدفعية مهارة حاسمة لبناء أنظمة ذكاء اصطناعي فعالة وكفؤة من حيث التكلفة.
ابدأ صغيرًا بمجموعة بيانات اختبار، وتحقق من نتائجك، ثم قم بالتوسع. يجعل الخصم بنسبة 50% واجهة برمجة التطبيقات الدفعية جزءًا لا غنى عنه في أي مجموعة تطوير جادة لنماذج اللغة الكبيرة.