الوكيل الذي يعمل خمس دقائق يستطيع تجاهل الفشل. أما الذي يعمل خمس ساعات فسيواجه انتهاء مهلة، و429، وبثًّا منقطعًا، وعلى الأرجح إعادة تشغيل. معظم الأدلة عن الوكلاء طويلي التشغيل تروّج لمحرّك سير عمل، وقد لا تحتاج إليه. يتناول هذا المقال خمس عادات تُبقي حلقة وكيل بسيطة حيّة لساعات، مع شيفرة لـOpenAI Python SDK.
ما الذي ينكسر حين يعمل الوكيل لساعات؟
| الفشل | كيف يبدو | العادة التي تعالجه |
|---|---|---|
| استدعاء عالق أو بطيء | لا رد لدقائق | مهلة لكل استدعاء، والبث |
| حد المعدّل أو الحمل الزائد | 429، 5xx | إعادة محاولة محدودة بتأخير متزايد |
| بث منقطع | ينتهي الاتصال قبل [DONE] |
اعتبره غير مكتمل وأعد الاستدعاء |
| أثر جانبي مكرّر | تعمل الأداة مرتين بعد إعادة المحاولة | مفاتيح عدم التكرار |
| انهيار العملية أو نشر جديد | يعود الوكيل إلى الخطوة 1 | نقطة حفظ لكل خطوة |
1. كم يُسمح للاستدعاء أن يستغرق؟
يقول ملف README في OpenAI Python SDK إن مهلة الطلبات تنتهي افتراضيًا بعد 10 دقائق، وإن أخطاء معيّنة يُعاد محاولتها مرتين. في الوكيل، حدّد القيمتين بنفسك، كي لا يتغيّر السلوك دون علمك:
client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"],
timeout=300, max_retries=4)
اختر المهلة بناءً على البيانات. سجّل مدة كل استدعاء ليوم كامل، ثم اضبط المهلة أعلى بكثير من أبطأ استدعاء ناجح. الأوامر الكبيرة تتأخر أكثر في البدء، ونماذج الاستدلال المنطقي تفكّر قبل أن تكتب. فبسرعة نحو 100 رمز في الثانية تستغرق 8,000 رمز (توكن) إخراج أكثر من دقيقة وحدها. وأضِف ميزانية زمنية منفصلة لكل مهمة كي لا تستمر حلقة لا تتوقف طوال الليل.
2. لماذا تستخدم البث في وكيل طويل التشغيل؟
يمنحك البث إشارة أثناء عمل النموذج. فبدونه يبدو الاستدعاء البطيء والاتصال الميت متشابهين حتى تنتهي المهلة. ومعه ترى الأجزاء تصل، وتحصل أيضًا على استهلاك الرموز في الجزء الأخير.
قواعد البث لدى BroadNet: اقرأ حتى السطر الحرفي data: [DONE]. إذا أُغلق الاتصال قبله فالإجابة غير مكتملة. سجّل X-Request-ID، ثم قرّر هل ترسل طلبًا جديدًا. الدليل الكامل للبث.
def call_streaming(messages, tools=None):
parts, done = [], False
stream = client.chat.completions.create(
model="broadnet/glm-5.3", messages=messages, tools=tools, stream=True,
stream_options={"include_usage": True}, max_tokens=8000)
for chunk in stream:
if chunk.choices and chunk.choices[0].finish_reason:
done = True
if chunk.choices and chunk.choices[0].delta.content:
parts.append(chunk.choices[0].delta.content)
if not done:
raise IncompleteStream() # retry the whole call
return "".join(parts)
هذا المخطط يجمع النص فقط. إذا كنت تبثّ استدعاءات الأدوات، فاجمع delta.tool_calls حسب الفهرس أيضًا.
3. ما الذي يجب إعادة محاولته؟
يعيد الـSDK بالفعل محاولة أخطاء الاتصال و408 و409 و429 و5xx. أضِف إعادة محاولة خاصة بك فوقه فقط لما لا يراه، مثل البث غير المكتمل:
- أعد المحاولة: أخطاء الاتصال، و429، و5xx، والبث غير المكتمل. استخدم التأخير الأسّي المتزايد مع عشوائية وسقف، مثلًا 4 محاولات.
- أصلح ولا تُعِد المحاولة: 400 و401 و402 و403 و413 و422. هذه تفشل بالطريقة نفسها كل مرة. راجع رموز الأخطاء ومتى تعيد المحاولة.
- خصّص ميزانية لإعادة المحاولة لكل مهمة، لا لكل استدعاء فقط. عشر خطوات تعيد كل منها المحاولة أربع مرات تعني أربعين استدعاءً إضافيًا.
- انتقل إلى مزود بديل حين تنفد المحاولات. إذا كان يجب أن يصمد التشغيل أمام انقطاع لدى المزود، فحوّل أخطاء الاتصال و5xx و429 الخاصة بحد المعدّل إلى مزود ثانٍ. ويعرض مقال التحويل التلقائي بين مزودي LLM API شيفرة العميل وقاطع دائرة.
في الدفع حسب الاستخدام، كل إعادة محاولة استدلال جديد يُحاسَب مرة أخرى. ومفتاح الدفع حسب الاستخدام يسمح أيضًا بـ30 طلب في الدقيقة و4 طلبات متزامنة، لذا تصطدم موجات إعادة المحاولة بـحد المعدّل بسرعة؛ وتبيّن حاسبة حدود المعدّل الهامش المتاح لوكيلك. ويشرح مقال التعامل مع 429 التأخير المتزايد بالتفصيل. وفي الخطة غير المحدودة لا تكلّف إعادة المحاولة شيئًا إضافيًا، لكنها تشغل خانة الطلب الوحيدة في الجلسة أثناء تنفيذها.
4. كيف تجعل استدعاءات الأدوات غير قابلة للتكرار؟
استدعاء النموذج بلا آثار جانبية. أما استدعاء الأداة فقد تكون له آثار. إذا انهار الوكيل بعد تنفيذ send_invoice وقبل حفظ الخطوة، فسيرسلها الوكيل مرة أخرى بعد إعادة تشغيله.
امنح كل استدعاء ذي أثر جانبي مفتاح عدم تكرار مشتقًّا من المهمة والخطوة، وتحقّق منه قبل التنفيذ، وتخطَّ الاستدعاء إذا كان مسجَّلًا بالفعل:
def run_side_effect(task_id, step, call, store):
key = f"{task_id}:{step}:{call.id}"
if store.done(key):
return store.result(key) # already ran: return the saved result
result = execute(call) # pass key to the API if it supports one
store.save(key, result)
return result
كثير من واجهات الدفع والمراسلة تقبل ترويسة لمفتاح عدم التكرار. مرّر مفتاحك إليها حين تقبله.
5. كيف تحفظ نقاط استئناف للوكيل؟
احفظ بعد كل خطوة مكتملة: قائمة الرسائل، ورقم الخطوة، ومفاتيح الآثار الجانبية. وعند البدء، حمّل أحدث نقطة حفظ إن وُجدت.
def save_checkpoint(path, step, messages):
tmp = path + ".tmp"
with open(tmp, "w") as f:
json.dump({"step": step, "messages": messages}, f)
os.replace(tmp, path) # atomic on the same filesystem
الكتابة إلى ملف مؤقت ثم إعادة تسميته تعني أن الانهيار أثناء الكتابة لا يترك أبدًا نقطة حفظ ناقصة. وفي الجلسات الطويلة جدًا، احفظ أيضًا ملخّصًا: استبدل الأدوار القديمة بملخّص قصير كي لا يعيد الوكيل المستأنَف تحميل تاريخ ضخم. هذا يُبقيك داخل نافذة السياق، حتى مع 1,048,576 رمزًا في DeepSeek V4.1 Flash.
قائمة تحقق قبل تشغيل طوال الليل
- المهلة و
max_retriesمحدّدتان صراحةً في العميل. - البث مفعّل مع
include_usage، والبث غير المكتمل يُعاد. - ميزانية لإعادة المحاولة لكل مهمة، وحد زمني.
- مفاتيح عدم تكرار على كل أداة تكتب أو ترسل أو تدفع.
- نقطة حفظ بعد كل خطوة، تُكتب بشكل ذرّي.
- سجلات فيها رقم الخطوة والمدة والرموز و
X-Request-ID.
إذا كنت تشغّل عدة وكلاء جنبًا إلى جنب، فاقرأ تشغيل وكلاء برمجة متوازين بسعر ثابت وتكلفة أنظمة الوكلاء المتعددين.
أين يأتي دور BroadNet Inference؟
تستخدم BroadNet Inference بث chat completions القياسي، وتعيد ترويسة X-Request-ID يمكنك تسجيلها، وتوثّق الأخطاء التي يُعاد محاولتها، فتعمل الأنماط أعلاه كما هي مكتوبة. وللوكلاء الذين يعملون طوال اليوم، تزيل الخطط غير المحدودة عدّاد الرموز على DeepSeek V4.1 Flash مقابل $60 شهريًا لكل جلسة، ما يجعل إعادة المحاولة مجانية. ضع في حسبانك أن ساعة الشهاب (Meteor) تنتهي بعد ساعة من الشراء، وأسبوع المدار (Orbit) بعد سبعة أيام، لذا يجب أن تنتهي المهمة الطويلة داخل المدة أو تنتقل إلى جلسة البدر (Full Moon) المتجددة. الخطط متاحة على inference.broadnet.ai/plans.
