بعض مهام LLM ليست محادثات. لديك 50,000 تذكرة دعم تحتاج إلى تصنيف، أو 200,000 وصف منتج تحتاج إلى ترجمة، أو مليون مراجعة تحتاج إلى تقييم. مزوّدون مثل OpenAI وAnthropic يبيعون Batch API لهذا الغرض. وكثير من واجهات API المتوافقة مع OpenAI، ومنها BroadNet Inference، لا تقدّمها. يشرح هذا المقال كيف تشغّل المهمة بنفسك: تحسب كم ستستغرق، وتكتب مشغّلًا يحترم الحدود، وتجعل إيقافه وإعادة تشغيله آمنين.
BroadRouter هو موقع BroadNet نفسها، لذا تستخدم الأرقام في الأمثلة حدود BroadNet المنشورة. والطريقة تعمل على أي API لإكمال المحادثات؛ ضع أرقام مزوّدك مكانها.
هل لدى BroadNet Inference واجهة Batch API؟
لا. يوثّق المرجع التقني، بتاريخ مراجعة 15 نوفمبر 2026، النقاط POST /v1/chat/completions وPOST /v1/audio/transcriptions وGET /v1/models (قائمة النماذج)، إضافة إلى نقاط نهاية الحساب تحت /portal/. لا توجد نقطة نهاية للدفعات أو لرفع الملفات، ولا خصم للدفعات. المهمة الكبيرة حلقة من الطلبات العادية.
وهذا ما تقدّمه Batch API المستضافة، لتعرف ما الذي تعيد بناءه:
| Batch API من OpenAI | Message Batches من Anthropic | مشغّلك الخاص | |
|---|---|---|---|
| السعر | خصم 50% عن الطلبات المتزامنة | خصم 50% | السعر العادي |
| مدة الإنجاز | خلال 24 ساعة | معظمها خلال ساعة؛ تنتهي صلاحيتها بعد 24 | تحددها حدود المعدل لديك |
| الحجم لكل دفعة | 50,000 طلب أو 200 MB | 100,000 طلب أو 256 MB | أي حجم |
| حدود المعدل | منفصلة عن حدود كل نموذج | تنطبق على الطلبات في الطابور | حدود مفتاحك |
| ترتيب النتائج | قد يختلف؛ طابِق على custom_id |
طابِق على custom_id |
تربط النتائج بالمعرّف بنفسك |
ثمة درسان ينتقلان إلى مشغّلك. كلا المزوّدين يُلزمك بوسم كل طلب بمعرّف، لأن النتائج لا تعود بالترتيب. ولا يَعِد أي منهما بإجابة خلال ثوانٍ. ويجب أن يعمل مشغّلك بالطريقة نفسها: معرّفات على كل شيء، وخطة تُقاس بالساعات.
إذا كان خصم 50% أهم لديك من مدة الإنجاز، وكانت النماذج التي تحتاجها متاحة هناك، فقد تكون Batch API المستضافة الأداة الأرخص. احسب تكلفة الخيارين بـحاسبة تكلفة LLM API قبل أن تبني.
كم ستستغرق المهمة؟
احسب ذلك قبل أن تكتب الشيفرة. حدّان يقيّدان الإنتاجية، والأبطأ منهما هو الذي يحكم:
- حد الطلبات الجارية ÷ زمن الاستجابة. مع 4 طلبات جارية وثانيتين لكل طلب، تستطيع إنهاء طلبين في الثانية.
- الطلبات في الدقيقة. بمعدل 30 في الدقيقة، تستطيع بدء 0.5 طلب في الثانية، مهما كان النموذج سريعًا.
يسمح مفتاح الدفع حسب الاستخدام لدى BroadNet بـ4 طلبات جارية و30 في الدقيقة. وبالقيم التي وردت في المرجع التقني حين راجعناه (30 طلبًا في الدقيقة و4 طلبات جارية، 2026-11-15)، يكون حد المعدل هو القيد الحاكم ما لم يستغرق كل طلب أكثر من 8 ثوانٍ، ويستخدم الجدول أدناه 30 طلبًا في الدقيقة:
| العناصر | عنصر واحد لكل طلب | 20 عنصرًا لكل طلب |
|---|---|---|
| 10,000 | 5.6 ساعة | 17 دقيقة |
| 100,000 | 2.3 يوم | 2.8 ساعة |
| 1,000,000 | 23 يومًا | 28 ساعة |
بمعدل 30 طلبًا في الدقيقة، يعالج المفتاح الواحد 1,800 طلب في الساعة، أو 43,200 يوميًا. وإعادات المحاولة تُحتسب أيضًا: كل 429 تتسبب فيه يستهلك خانة.
العمود الثاني هو أكبر رافعة. العناصر القصيرة، مثل المراجعات أو عناوين التذاكر، يمكن إرسالها من 10 إلى 50 في الطلب كقائمة مرقّمة، مع مصفوفة JSON في الرد. تحقّق من أن المصفوفة تحتوي مدخلًا واحدًا لكل عنصر، وأن كل مدخل يحمل رقمه. ويُظهر مقال تصنيف النصوص العربية هذا النمط. أما العناصر الطويلة فلا تُجمَّع: إذ يجب أن يتسع كل طلب في نافذة السياق للنموذج، وقد تنخفض الجودة مع طول القائمة. اختبر التجميع على 200 عنصر قبل أن تثق به.
لا توزّع مهمة واحدة على عدة مفاتيح لتتجاوز حدًا مفروضًا على كل مفتاح دون أن تسأل. تحظر سياسة الاستخدام المقبول لدى BroadNet التحايل على حدود المعدل أو التزامن أو الميزانية. إذا احتجت إلى المزيد، فاسأل BroadNet، أو استخدم جلسات الخطط أدناه. ويجري مخطِّط مهام الدفعات هذا الحساب لعدد عناصرك وزمن الاستجابة والحدود.
كيف يبدو المشغّل القابل للاستئناف؟
يقرأ هذا المشغّل items.jsonl (كائن {"id", "text"} واحد في كل سطر) ويُلحق سطر نتيجة واحدًا لكل عنصر بالملف results.jsonl. ولا يحتاج إلا إلى OpenAI Python SDK.
import asyncio, json, os, random, time
from openai import AsyncOpenAI, APIStatusError, APIConnectionError, APITimeoutError
client = AsyncOpenAI(base_url=os.environ.get("BASE_URL", "https://inference.broadnet.ai/v1"),
api_key=os.environ["BROADNET_API_KEY"],
max_retries=0, # we retry ourselves, with a cap we can see
timeout=120)
MODEL = os.environ.get("MODEL", "broadnet/deepseek-v4.1-flash")
IN_FLIGHT = int(os.environ.get("IN_FLIGHT", "4")) # PAYG key: 4 in flight. Plan: 1 per session.
RPM = int(os.environ.get("RPM", "30")) # PAYG key: 30 requests a minute
MAX_ATTEMPTS = 6
class Pacer:
"""Spaces request starts at least 60/RPM seconds apart, across all workers."""
def __init__(self, rpm):
self.gap, self.next, self.lock = 60 / rpm, 0.0, asyncio.Lock()
async def wait(self):
async with self.lock:
now = time.monotonic()
delay = max(0.0, self.next - now)
self.next = max(now, self.next) + self.gap
await asyncio.sleep(delay)
def retryable(e):
if isinstance(e, (APIConnectionError, APITimeoutError)):
return True
return isinstance(e, APIStatusError) and e.status_code in (429, 500, 502, 503, 504)
async def call(item, pacer):
for attempt in range(MAX_ATTEMPTS):
await pacer.wait() # every attempt counts against the rate limit
try:
r = await client.chat.completions.create(
model=MODEL, max_tokens=1500, reasoning_effort="low",
messages=[{"role": "system", "content": "Classify the review as positive, negative or mixed. Reply with one word."},
{"role": "user", "content": item["text"]}])
c = r.choices[0]
return {"id": item["id"], "ok": True, "finish_reason": c.finish_reason,
"output": c.message.content, "usage": r.usage.model_dump() if r.usage else None}
except Exception as e:
if not retryable(e) or attempt == MAX_ATTEMPTS - 1:
return {"id": item["id"], "ok": False, "error": repr(e)[:300]}
await asyncio.sleep(random.uniform(0, min(60, 2 ** attempt))) # full jitter, capped
async def run(in_path, out_path):
done = set()
if os.path.exists(out_path): # resume: skip ids that already succeeded
with open(out_path) as f:
done = {json.loads(l)["id"] for l in f if l.strip() and json.loads(l).get("ok")}
todo = [it for it in map(json.loads, open(in_path)) if it["id"] not in done]
print(f"{len(done)} done, {len(todo)} to go")
pacer, queue = Pacer(RPM), asyncio.Queue()
for it in todo:
queue.put_nowait(it)
with open(out_path, "a") as out:
async def worker():
while True:
try:
it = queue.get_nowait()
except asyncio.QueueEmpty:
return
res = await call(it, pacer)
out.write(json.dumps(res, ensure_ascii=False) + "\n")
out.flush() # one line per finished item = the checkpoint
await asyncio.gather(*(worker() for _ in range(IN_FLIGHT)))
if __name__ == "__main__":
import sys
asyncio.run(run(sys.argv[1], sys.argv[2]))
شغّله بالأمر python batch_run.py items.jsonl results.jsonl. اختبرنا هذا الملف نفسه على خادم محاكاة محلي يعيد أخطاء 429 عشوائية (8%) و500 (5%) ويرفض أي شيء يتجاوز 4 طلبات جارية أو 30 بداية في الدقيقة. انتهى 25 عنصرًا في 55 ثانية بـ28 طلبًا (3 إعادات محاولة)، ولم تتجاوز البدايات 30 في أي نافذة من 60 ثانية. ومع رفع حد المحاكاة إلى 300 في الدقيقة لتوفير الوقت، استُؤنف تشغيل من 120 عنصرًا أُوقف قسرًا بعد 10 ثوانٍ من 39 نتيجة محفوظة، وانتهى بـ120 معرّفًا فريدًا دون أي تكرار.
لماذا مجموعة عمّال لا asyncio.gather؟
يستخدم دليل خطأ 429 أداة semaphore حول asyncio.gather. وهذا مناسب لبضع مئات من الاستدعاءات. أما للمهمة الكبيرة، فمجموعة ثابتة من العمّال تسحب من طابور أفضل:
- الذاكرة. ينشئ
gatherمهمة لكل عنصر مسبقًا. أما مجموعة العمّال فلا تحمل إلا العناصر الجارية. - التزامن هو حجم المجموعة. أربعة عمّال لا يمكن أن يفتحوا خمسة طلبات أبدًا.
- النتائج تتدفق إلى القرص فور انتهائها، بأي ترتيب، مربوطة بالمعرّف.
يتولى Pacer الحد الثاني. فالـsemaphore وحده يمنعك من تجاوز 4 طلبات جارية، لكن إذا استغرق الطلب ثانية واحدة، فسيبدأ أربعة عمّال 240 طلبًا في الدقيقة ويصطدمون بـ429 في معظمها. أما الـpacer فيباعد بين البدايات بثانيتين، عبر كل العمّال، بما في ذلك إعادات المحاولة.
كيف تبقى إعادة المحاولة آمنة؟
لا تُعِد محاولة إلا ما يمكن أن ينجح في المرة الثانية:
| الرد | الإجراء |
|---|---|
| 429 | انتظر ثم أعد المحاولة؛ يقول توثيق BroadNet: “use response details and bounded backoff” (الترجمة: استخدم تفاصيل الرد وانتظارًا متزايدًا له حد أقصى) |
| 500، 502، 503، 504، انتهاء المهلة، الاتصالات المنقطعة | أعد المحاولة بانتظار أسّي متزايد له حد أقصى |
| 400، 422 | أصلح الطلب؛ إعادة المحاولة ترسل الخطأ نفسه |
| 401، 402، 403 | أوقف المهمة؛ المفتاح أو الرصيد أو السياسة يحتاج إلى مراجعة |
| 413 | اختصر العنصر |
يعطّل المشغّل إعادات المحاولة الخاصة بالـSDK (max_retries=0) لتكون هناك سياسة إعادة محاولة واحدة فقط، بحد أقصى ظاهر. والانتظار أسّي متزايد مع تذبذب كامل (full jitter)، بحد أقصى 60 ثانية، كي لا يعيد العمّال الذين فشلوا معًا المحاولة معًا. وبعد ست محاولات يُكتب العنصر بـ"ok": false وتمضي المهمة. عنصر واحد سيئ لا يوقف مليونًا أبدًا.
استدعاء النموذج بلا آثار جانبية، لذا فالتسليم هنا «مرة واحدة على الأقل»: إذا توقفت العملية في منتصف طلب، يُرسَل ذلك العنصر مجددًا عند إعادة التشغيل، وتدفع ثمنه مرتين. وهذا هو الهدر الوحيد. وإذا كانت المهمة تكتب أيضًا إلى نظام آخر، مثل التذاكر أو البريد الإلكتروني، فاجعل تلك الكتابة غير مكرِّرة بمعرّف العنصر، ونفّذها في مرور منفصل على results.jsonl. ويتناول مقال الوكلاء طويلي التشغيل الآثار الجانبية غير المكرِّرة بالتفصيل.
كيف تعمل نقاط الحفظ؟
ملف الإخراج هو نقطة الحفظ. كل عنصر منتهٍ سطر واحد مُفرَغ إلى القرص، فبعد انهيار أو نشر جديد أو Ctrl-C، يقرأ التشغيل التالي الملف، ويجمع المعرّفات التي لها "ok": true، ولا يضع في الطابور إلا الباقي. والعناصر التي فشلت سابقًا يُعاد محاولتها في التشغيل التالي، ويُلحق سطرها الجديد. وحين تقرأ النتائج، خذ آخر سطر لكل معرّف.
ثلاث عادات تجعل هذا يصمد لأيام:
- معرّفات ثابتة. استخدم مفتاحًا من قاعدة البيانات أو تجزئة (hash) للمدخل، لا رقم سطر يتغيّر حين يتغيّر ملف الإدخال.
- افحص
finish_reason. الرد المقطوع عندmax_tokensيكون"ok": trueلكنه بلا فائدة. يستدل DeepSeek V4.1 Flash وGLM 5.3 وQwen3.8 27B منطقيًا قبل أن تجيب، والاستدلال المنطقي يُحتسب ضمن max_tokens. يضبط المشغّلreasoning_effort="low"، وهي قيمة توثّقها BroadNet، ويترك 1,500 رمز. - سجّل الاستهلاك في كل سطر. جمع
usageمنresults.jsonlيعطيك فاتورة الرموز الفعلية لتقارنها بتقديرك.
كم يكلّف: الدفع حسب الاستخدام أم جلسة خطة؟
في الدفع حسب الاستخدام، التكلفة هي الرموز. خذ 100,000 مراجعة، بأمر نظام من 150 رمزًا، ومراجعة من 150 رمزًا (توكن)، و100 رمز إخراج مع استدلال منخفض. هذا 30 مليون رمز إدخال و10 ملايين رمز إخراج. على DeepSeek V4.1 Flash تكون التكلفة 30 × $0.175 + 10 × $0.52. أبقِ أمر النظام أولًا ومتطابقًا بايتًا ببايت، فيمكن أن تُحاسَب ملايينه الخمسة عشر بسعر الإدخال المخزّن مؤقتًا البالغ $0.0055 لكل مليون حيث يصيب التخزين المؤقت. وتُظهر أسطر usage عدد المرات التي أصاب فيها.
أما في الخطة، فالرموز مجانية والوقت هو التكلفة. جلسة خطة DeepSeek V4.1 Flash “runs one request at a time” (الترجمة: تشغّل طلبًا واحدًا في كل مرة)، لذا اضبط IN_FLIGHT=1 لكل جلسة. وإنتاجية الجلسة 86,400 ÷ عدد الثواني لكل عنصر، يوميًا. تذكر BroadNet أن السرعة المعتادة نحو 100 رمز في الثانية، لكن زمن الاستجابة لديك يعتمد على طول الأمر والاستدلال المنطقي، فقِسه على 50 عنصرًا. فإذا قست 3 ثوانٍ لكل عنصر، تعالج الجلسة الواحدة 28,800 يوميًا:
| المهمة | الجلسات | الوقت بمعدل 3 ثوانٍ/عنصر | الخطة |
|---|---|---|---|
| 100,000 عنصر | 1 | نحو 3.5 أيام | أسبوع واحد من المدار (Orbit)، $15 لكل جلسة |
| 100,000 عنصر | 4 | نحو 21 ساعة | أربعة أسابيع من المدار، أسبوع لكل جلسة؛ أو نحو 21 ساعة من الشهاب (Meteor) لكل جلسة بسعر $1 للساعة |
| 1,000,000 عنصر | 6 | نحو 6 أيام | ستة أسابيع من المدار |
تُقدَّم الخطط “best effort under fair use” (الترجمة: بأفضل جهد ضمن الاستخدام العادل)، ولا تنشر BroadNet حدًا للطلبات في الدقيقة لمفاتيح الخطط؛ ويعرض حسابك الحدود المطبّقة. اضبط RPM بناءً عليها، لا بالتخمين. ويشرح دليل تخطيط الجلسات كيف توزّع الجلسات على المفاتيح.
أين تقع BroadNet Inference من هذا؟
لا تملك BroadNet Inference واجهة Batch API، لذا فهي تناسب المهام الكبيرة حين تفضّل التحكم في المشغّل بنفسك ودفع أسعار الرموز العادية، أو تثبيت التكلفة بجلسات خطة DeepSeek V4.1 Flash. وللمهام الصغيرة بميزانية محدودة، يعمل Gemma 4 VL 26B بسعر $0.10 للإدخال و$0.22 للإخراج لكل مليون على الرصيد الأولي $5. ولا يُحتفظ بالأوامر والمخرجات بعد كل طلب. وإذا كانت مهمتك تحتمل الانتظار يومًا وكانت النماذج التي تحتاجها لدى مزوّد يقدّم خصم دفعات بنسبة 50%، فقد يكلّف ذلك أقل؛ قارن قبل أن تلتزم. الخطط والحدود في inference.broadnet.ai/plans.
