الطلبات الدفعية في بايثون لواجهة برمجة تطبيقات LLM متوافقة مع OpenAI
لأعمال معالجة الدفعي بلغة Python، لا تحتاج إلى نقطة نهاية دفعي خاصة: تحتاج إلى مجموعة عمال تحترم حدود المعدل، وقاعدة إعادة محاولة لخطأ HTTP 429، وملف نتائج يمكنك استئنافه من حيث توقف. يبني هذا الدليل هذه العناصر الثلاثة باستخدام OpenAI SDK الموجه إلى Base URL الخاص بك.

نقاط رئيسية
- تمتلك واجهة برمجة التطبيقات طريقتين، إكمال المحادثات والنماذج، لذا يتم إجراء التجميع من جانبك باستخدام مجموعة من الطلبات المتزامنة.
- يسمح المفتاح الكامل بـ 8 طلبات متزامنة و300 في الدقيقة؛ ويسمح المفتاح التجريبي بـ 2 و60. قم بتعيين حجم المجموعة الخاص بك ليتناسب مع ذلك.
- أعد المحاولة عند ظهور 429 باستخدام رأس Retry-After، وتمييز حالة rate_limited عن التزامن.
- اكتب كل نتيجة في ملف JSONL بمجرد انتهائها حتى تكلف الأعطال دقائق، وليس التشغيل بأكمله.
كيف تعمل الدفعات هنا
نقطة النهاية متوافقة مع OpenAI وتعرض POST /v1/chat/completions وGET /v1/models. لا توجد نقطة نهاية منفصلة لتقديم المهام تأخذ ملفاً وتعيد النتيجة لاحقاً. لذلك، الدفعة عبارة عن حلقة تكرار على الطلبات العادية، تُنفَّذ بالتوازي، مع تطبيق الحدود المدمجة في الكود الخاص بك. هذا أبسط مما يبدو، ويعطيك النتائج بمجرد انتهائها بدلاً من انتظار النهاية.
الأرقام التي تحدد التصميم هي الحدود. المفتاح الكامل يسمح بـ 8 طلبات متزامنة و300 طلب في الدقيقة. مفتاح التجربة يسمح بـ 2 طلب متزامن و60 طلب في الدقيقة. الحد الأقصى لحجم طلب الجسم هو 8 MB. الطلب المتدفق يحتفظ بمكان التزامن الخاص به حتى ينتهي البث، لذا بالنسبة لعمل الدفعات، اترك البث المتدفق غير مفعّل.
لماذا لا نطلق كل شيء مرة واحدة؟ لأن الدفعة هي مشكلة في معدل الإرسال لها سقف، والسقف عليك أن تحترمه. الحلقة التي ترسل 5,000 طلب بأسرع ما يمكن أن يخلقها بايثون ستواجه جداراً من أخطاء 429، وتهدر الوقت في إعادة المحاولة، وتدفن الأخطاء المفيدة في الضوضاء. المجموعة التي تحتفظ بـ 8 طلبات كحد أقصى قيد التنفيذ تبقي الخط متحركاً بسرعة تسمح به الخدمة، وهو نفس الكود سواء كان لديك 50 سطراً أو 500,000. خطط لثلاثة أجزاء: مجموعة محدودة، قاعدة إعادة محاولة واحدة، وملف نتائج يُضاف إليه فقط.
معرف النموذج هو uncensored، المصادقة هي Authorization: Bearer <key>، وعنوان URL الأساسي هو https://api.unfilteredvideo.com/v1. إذا لم يكن لديك مفتاح بعد، فإن صفحة مفتاح API تحتوي على تجربة مجانية بقيمة $0.50 بنقرة واحدة.
التثبيت والإعداد
تحتاج إلى Python 3.9 أو أحدث وحزمة openai الرسمية. ضع المفتاح في متغير بيئة بدلاً من وضعه في السكربت.
pip install openai
export API_KEY="paste-your-key-here"
# quick check that the key and base URL work
curl https://api.unfilteredvideo.com/v1/models -H "Authorization: Bearer $API_KEY"
قائمة النماذج يجب أن تظهر uncensored. الآن جهز مدخلاتك كملف JSONL، كائن واحد لكل سطر يحتوي على المعرّف والنص للمعالجة. المعرّف هو ما يسمح لك بالاستئناف لاحقاً.
{"id": "r001", "text": "Summarise this product review in one sentence: ..."}
{"id": "r002", "text": "Summarise this product review in one sentence: ..."}
مجموعة خيوط تبقى ضمن الحدود
للمعظم من السكربتات، يُعد ThreadPoolExecutor أقصر طريق. عميل OpenAI آمن للمشاركة بين الخيوط، والعمل مرتبط بالشبكة، لذا فإن الخيوط مناسبة. اضبط حجم المجموعة ليكون مساوياً لحد التزامن الخاص بك، وليس أعلى: فالعمال الإضافيين فقط يجمعون أخطاء 429.
import json, os
from concurrent.futures import ThreadPoolExecutor, as_completed
from openai import OpenAI
client = OpenAI(api_key=os.environ["API_KEY"], base_url="https://api.unfilteredvideo.com/v1", max_retries=0)
MODEL = "uncensored"
WORKERS = 8 # use 2 on a trial key
def run_one(row):
resp = client.chat.completions.create(
model=MODEL,
temperature=0.2,
max_tokens=200,
messages=[{"role": "user", "content": row["text"]}],
)
return {
"id": row["id"],
"output": resp.choices[0].message.content,
"in": resp.usage.prompt_tokens,
"out": resp.usage.completion_tokens,
}
rows = [json.loads(line) for line in open("input.jsonl")]
with ThreadPoolExecutor(max_workers=WORKERS) as pool, open("output.jsonl", "a") as out:
futures = [pool.submit(run_one, r) for r in rows]
for f in as_completed(futures):
out.write(json.dumps(f.result()) + "\n")
out.flush()
هذه النسخة لا تحتوي على إعادة محاولة ولا استئناف، لذا فهي نقطة بداية. تم إنشاء العميل بـ max_retries=0 لأن الـ SDK يعيد المحاولة تلقائياً افتراضياً، وأنت تريد مكاناً واحداً يملك قاعدة إعادة المحاولة. القسمين التاليين يضيفان قاعدة إعادة المحاولة ومنطق الاستئناف.
معالجة أخطاء 429 بالطريقة الصحيحة
هناك ثلاثة أنواع من أخطاء 429 في هذا API، وتتطلب تفاعلات مختلفة قليلاً:
rate_limited: لقد أرسلت طلبات كثيرة جداً في الدقيقة. قلل السرعة. مجموعة بعدد أقل من العمال، أو إضافة تأخير قصير، تحل المشكلة.concurrency: كان هناك طلبات كثيرة جداً قيد التنفيذ في آن واحد. مجموعتك أكبر من حدك، أو لديك بث متدفق مفتوح نسيته.- إحمال مؤقت: خطأ 429 مع رأس
Retry-After: 5. لا يوجد خطأ في الكود الخاص بك. انتظر الوقت المحدد وحاول مرة أخرى.
دالة مساعدة لإعادة المحاولة تغطي الأنواع الثلاثة. تنتظر Retry-After عند وجودها، وإلا فإنها تستخدم استراتيجية تراجع أسي مع قليل من العشوائية. الطلبات الفاشلة والمرفوضة لا تُحسب، لذا فإن إعادة المحاولة مجانية.
import random, time
import openai
from openai import OpenAI
client = OpenAI(api_key=__import__("os").environ["API_KEY"], base_url="https://api.unfilteredvideo.com/v1", max_retries=0)
MODEL = "uncensored"
def call_with_retry(messages, attempts=6):
for n in range(attempts):
try:
return client.chat.completions.create(model=MODEL, messages=messages, max_tokens=200)
except openai.RateLimitError as e:
wait = e.response.headers.get("Retry-After")
delay = float(wait) if wait else min(60, 2 ** n) + random.random()
print("429", getattr(e, "code", None), "waiting", round(delay, 1), "s")
time.sleep(delay)
except (openai.APIConnectionError, openai.APITimeoutError):
time.sleep(min(30, 2 ** n))
raise RuntimeError("gave up after %d attempts" % attempts)
لا تعيد المحاولة بشكل أعمى على كل خطأ. خطأ 400 يعني أن طلبك خاطئ، على سبيل المثال جسم أكبر من 8 MB أو رسالة غير صالحة، وإرساله مرة أخرى سيفشل بنفس الطريقة. سجله مع معرف السطر وتجاوز.
نسخة غير متزامنة باستخدام قفل عدّاد
إذا كان سكريبتك يعمل بالفعل في حلقة أحداث، أو تريد تغذية خدمة ويب، فاستخدم AsyncOpenAI و asyncio.Semaphore الذي يحد من الطلبات النشطة. يلعب السيمافور دور حجم المجموعة.
import asyncio, json, os
from openai import AsyncOpenAI
client = AsyncOpenAI(api_key=os.environ["API_KEY"], base_url="https://api.unfilteredvideo.com/v1", max_retries=0)
MODEL = "uncensored"
sem = asyncio.Semaphore(8)
async def run_one(row, out):
async with sem:
resp = await client.chat.completions.create(
model=MODEL,
max_tokens=200,
messages=[{"role": "user", "content": row["text"]}],
)
out.write(json.dumps({"id": row["id"], "output": resp.choices[0].message.content}) + "\n")
out.flush()
async def main():
rows = [json.loads(l) for l in open("input.jsonl")]
with open("output.jsonl", "a") as out:
await asyncio.gather(*(run_one(r, out) for r in rows))
asyncio.run(main())
لفّ الاستدعاء بنفس منطق إعادة المحاكاة أعلاه، باستخدام await asyncio.sleep بدلاً من time.sleep. تحذير واحد: إنشاء gather مع عشرات الآلاف من المهام غير المتزامنة ينشئها جميعاً في وقت واحد. للمدخلات الكبيرة جداً، قم بمعالجة الملف على شرائح من بضعة آلاف من الصفوف.
جعل التشغيل قابلاً للاستئناف
تفشل المهام الطويلة بطرق مملة: يذهب الكمبيوتر المحمول إلى وضع السكون، ينقطع الاتصال، تضغط على Ctrl+C. لأن كل صف مكتمل يُضاف إلى output.jsonl مع معرفه، فإن الاستئناف يعني تخطي المعرفات التي لديك بالفعل.
import json, os
from openai import OpenAI
client = OpenAI(api_key=os.environ["API_KEY"], base_url="https://api.unfilteredvideo.com/v1")
MODEL = "uncensored"
def done_ids(path="output.jsonl"):
if not os.path.exists(path):
return set()
return {json.loads(line)["id"] for line in open(path) if line.strip()}
finished = done_ids()
todo = [r for r in map(json.loads, open("input.jsonl")) if r["id"] not in finished]
print(len(finished), "done,", len(todo), "to go")
أدخل todo إلى أي من مجموعتي الاتصال المذكورتين أعلاه. افتح ملف الإخراج بوضع الإضافة (append)، ولا تستخدم وضع الكتابة (write) مطلقًا، وإلا سيحذف إعادة التشغيل تقدمك. كما اكتب الأخطاء في ملف ثانٍ، errors.jsonl، حتى تتمكن من إعادة تشغيل الفشل فقط بعد قراءة سبب الفشل.
للحصول على ناتج قابل للتكرار عبر عمليات إعادة التشغيل، مرّر قيمة seed ثابتة مع قيمة temperature منخفضة. تُمرّر البذرة إلى النموذج مع top_p وstop والعقوبات.
اختبر على شريحة صغيرة أولاً
شغّل 20 صفًا قبل تشغيل 20,000. اختر صفوفًا تتضمن أسوأ حالاتك: أطول مدخل، واحد يحتوي على أحرف غريبة، وآخر فارغ. اقرأ المخرجات بالعين، تحقق من أن usage يتطابق مع تقدير التكلفة الخاص بك، وتأكد من أن مساعد إعادة المحاولة يتصرف بشكل صحيح عن طريق رفع عدد العمال مؤقتًا فوق حدك. يجب أن ترى خطأ 429 مع الكود concurrency في السجل، ثم انتظار، ثم إعادة محاولة ناجحة. من الأفضل رؤية ذلك على 20 صفًا بدلاً من اكتشافه عند الصف 9,000.
إذا كانت المهمة تحتاج إلى ناتج منظم، أضف وضع JSON مع response_format={"type": "json_object"}، صف المفاتيح في الموجّه، وشرّح كل رد داخل كتلة try. احسب فشل الشرح أثناء شريحة الاختبار. إذا كان المعدل أعلى من واحد أو اثنين في المئة، فهذا يعني عادةً أن الموجّه يحتاج إلى مخطط أكثر وضوحًا، وهو أرخص لإصلاحه الآن من إعادة التشغيل لاحقًا. الصفوف التي تفشل في الشرح تذهب إلى errors.jsonl مع معرفها، ويعاملها منطق الاستئناف على أنها غير مكتملة.
أخيرًا، اضبط مهلة زمنية للعميل تتناسب مع أطول إخراج متوقع. يقبل الـ SDK timeout=60 على مستوى العميل أو لكل طلب؛ وإلا فإن الطلب العالق الذي لا يعود سيحتل أحد الـ 8 منافذ لديك طالما هو موجود.
تحديد حجم المجموعة وتقدير الوقت
القدرة الاستيعابية محدودة بعاملين: القابلية للتوازي مقسومة على الوقت الذي يستغرقه الطلب الواحد، وحدّ الطلبات في الدقيقة. على المفتاح الكامل، الحد هو 300 طلب في الدقيقة، أي 5 طلبات في الثانية. إذا استغرق الطلب النموذجي 2 ثانية، فإن 8 عمال ينتجون 8 / 2 = 4 طلبات في الثانية، أو 240 طلبًا في الدقيقة، وهو أقل من الحد. إذا استغرق الطلب 1 ثانية، سيحاول 8 عمال تقديم 8 طلبات في الثانية ويصطدمون بالحد، لذا أضف تأخيرًا صغيرًا أو اقبل أخطاء 429 العرضية التي يمتصها مساعد إعادة المحاولة.
بمعدل 4 طلبات في الثانية، تستغرق 10,000 صفًا 2,500 ثانية، أي حوالي 42 دقيقة. على مفتاح تجريبي، مع طلبين متوازيين و60 في الدقيقة، يكون الحد الأقصى 1 في الثانية، لذا ستستغرق نفس 10,000 صفًا 10,000 ثانية، أي ما يقرب من ساعتين و47 دقيقة. في الممارسة العملية، سينفد رصيد التجربة بقيمة $0.50 قبل ذلك، مما يجعله مكانًا جيدًا لاختبار النص البرمجي على بضع مئات من الصفوف وليس مكانًا لتشغيل الإنتاج.
تكلفة الدفعة الكبيرة
التسعير هو $0.15 لكل مليون رمز إدخال و$0.50 لكل مليون رمز ناتج. خذ مهمة من نمط التصنيف: 50,000 صف، كل منها حوالي 200 رمز إدخال و100 رمز ناتج.
- الإدخال: 50,000 × 200 = 10,000,000 رمز، وهو ما يعادل 10 × $0.15 = $1.50.
- الناتج: 50,000 × 100 = 5,000,000 رمز، وهو ما يعادل 5 × $0.50 = $2.50.
- المجموع: $4.00، أو $0.00008 لكل صف.
يسجّل السكربت أعلاه in و out لكل صف، لذا يمكنك حساب نفس القيمة من تشغيلك الفعلي. يُظهر رأس الاستجابة X-Balance-USD أيضًا الرصيد المتبقي، و X-Request-Id هو ما يجب ذكره إذا طلبت المساعدة في صفحات docs أو الدعم.
الرصيد مسبق الدفع بشحنات كاملة بالدولار من $20 إلى $500، مع +5% من $50، و+10% من $100، و+15% من $200، مدفوع بالعملات المشفرة (USDT على TRC20 أو USDC على Base). لا ينتهي الرصيد أبدًا. يحتوي صفحة الأسعار على التفاصيل الكاملة. ملاحظة للبيانات الحساسة: لا تُستخدم الموجّهات للتدريب.
المزيد من الأدلة
أسئلة وأجوبة
هل يحتوي الـ API على نقطة نهاية للدفعة؟
لا. يعرض إكمالات الدردشة وقائمة النماذج. تقوم بالتجميع عن طريق تشغيل العديد من الطلبات العادية بشكل متزامن من كودك الخاص، ضمن 8 طلبات متزامنة و300 في الدقيقة على مفتاح كامل.
كم عدد الخيوط التي يجب أن أستخدمها؟
استخدم 8 عمال على مفتاح كامل و2 على مفتاح تجريبي، بما يتوافق مع حدود التزامن. سيؤدي المزيد من العمال فقط إلى إنتاج أخطاء 429 مع الرمز concurrency.
ماذا يجب أن أفعل عندما أحصل على خطأ HTTP 429؟
انتظر قيمة Retry-After إذا كانت الاستجابة تحتوي عليها، وإلا قم بتقليل معدل الإرسال لبضع ثوانٍ، ثم أعد المحاولة. الطلبات الفاشلة لا تُحسب تكلفة، لذا فإن إعادة المحاولة لا تكلف شيئًا.
هل يمكنني بث الاستجابات في مهمة دفعية؟
يمكنك ذلك، لكن لا ينبغي لك ذلك. يحمل الطلب المتدفق فتحة التزامن الخاصة به حتى ينتهي البث المتدفق، مما يقلل من الإنتاجية. اترك البث المتدفق غير مفعّل لأعمال الدفعات.
مفتاحك على بُعد نموذج واحد
أنشئ حساباً، وانسخ المفتاح، ثم غيّر الرابط الأساسي. هذه هي الإعدادات الكاملة.