كيفية تصحيح أخطاء وكيل ذكاء اصطناعي في الإنتاج (دليل ميداني)

جدول المحتويات

محدّث يونيو 2026.

الخلاصة: تصحيح أخطاء وكيل ذكاء اصطناعي في الإنتاج يتعلق في معظمه بعزل الطبقة التي فشلت — الموجِّه، أو استدعاء الأداة، أو مُخرَج النموذج، أو التنسيق. أسجّل كل خطوة بمعرّف تتبّع، وأعيد تشغيل المدخلات نفسها بالضبط، ثم أقسّم انطلاقًا من هناك. في وكلائي، نحو 70% مما يبدو “خطأ ذكاء اصطناعي” يتبيّن أنه سباكة: نتيجة أداة مشوّهة، أو مدخل مقتطع، أو استثناء ابتُلِع بصمت.

قراءة المُشغّل: أُشغّل أكثر من 100 وكيل في الإنتاج — تدفقات حجز لـ Pickleland، وخطوط أنابيب محتوى، ومُصنّفات صندوق وارد. تتعطّل كما يتعطّل أي برنامج، إضافة إلى بضع طرق جديدة. هذا هو الدليل الميداني الذي كنت أتمنى لو امتلكته: كيف تجد الطبقة المعطلة دون التحديق في جدار من الرموز (tokens).

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

اجعل كل تشغيلة قابلة للتتبّع قبل أن تصحّح أي شيء

لا يمكنك تصحيح ما لا تستطيع رؤيته. أعلى شيء ذي قيمة يمكنك فعله — قبل ظهور أي خطأ محدد — هو إرفاق معرّف تتبّع بكل تشغيلة للوكيل وتسجيل كل خطوة يخطوها.

“الخطوة” هي أي شيء يعبر حدًّا: المُحفِّز الوارد، وكل استدعاء للنموذج (مع مصفوفة الرسائل الكاملة)، وكل استدعاء أداة (مع الوسائط)، وكل نتيجة أداة، والمُخرَج النهائي. سجّلها كـ JSON منظَّم مُفهرَس بمعرّف التتبّع.

function logStep(traceId: string, step: string, payload: unknown) {
  console.log(JSON.stringify({
    traceId,
    step,            // "trigger" | "model_call" | "tool_call" | "tool_result" | "output"
    ts: Date.now(),
    payload,
  }));
}

على Cloudflare Workers أرسلها إلى طابور وإلى جدول؛ ومحليًّا تذهب إلى stdout. القاعدة مطلقة: إذا لم تُسجَّل خطوة، فهي لم تحدث بقدر ما يتعلق الأمر بالتصحيح. هذا يعكس الأدوات التي أصفها في حزمة الوكلاء التي أستخدمها — معرّف التتبّع هو العمود الفقري الذي يتعلّق به كل شيء آخر.

اعزل الطبقة: الموجِّه أو الأداة أو النموذج أو التنسيق

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

1. طبقة المدخلات (المتهم الأكثر شيوعًا)

اسحب مصفوفة messages نفسها بالضبط التي دخلت في استدعاء النموذج الفاشل. ليست إعادة بناء — بل الحمولة الحرفية من السجل. ثم اقرأها كما يقرأها غريب. نصف أخطائي من نوع “تجاهل النموذج التعليمات” هي في الواقع:

• نتيجة أداة عادت كـ "[object Object]" لأن شيئًا ما حُوّل إلى نص بشكل خاطئ.
• مدخل مقتطع في منتصف الجملة لأنه فجّر نافذة السياق وقطعه تقطيع ساذج.
• متغيّر أُدرِج كـ undefined وسمّم الموجِّه بصمت.

إذا كان المدخل خاطئًا، فقد أدى النموذج عمله بإتقان على قمامة. أصلح السباكة.

2. طبقة الأدوات

إذا بدا المدخل نظيفًا، تحقق مما إذا كانت أداة قد أعادت خطأً عامله الوكيل على أنه نجاح. كلاسيكية: واجهة برمجية تُعيد 200 مع متن { "error": "rate limited" }، وغلاف أداتك لا يفحص المتن، فيتصرّف الوكيل بثقة بناءً على رسالة خطأ. سجّل نتائج الأدوات خامًا وتحقّق من بنيتها.

3. طبقة النموذج

فقط بعد استبعاد 1 و2 أشكّ في النموذج. وحتى عندها، “خطأ النموذج” يعني عادةً “موجّهي غامض.” خذ المدخل الفاشل نفسه بالضبط، وضعه في سكربت لمرة واحدة مقابل النموذج ودرجة الحرارة نفسيهما، وانظر هل يتكرر. إن تكرّر، فالإصلاح هو عمل على الموجِّه أو تقييم أكثر إحكامًا، وليس استبدالًا محمومًا للنموذج.

4. طبقة التنسيق

إذا كانت خطوة واحدة سليمة بمعزل لكن التشغيلة متعددة الخطوات تفشل، فالخطأ في التسليم — حالة مفقودة بين الخطوات، أو حالة سباق، أو إعادة محاولة أعادت تنفيذ إجراء غير عديم الأثر التراكمي (non-idempotent). هذه هي الأشدّ خبثًا، وأغطّي أنماطها في أنماط تنسيق الوكلاء المتعددين.

أعد إنتاج اللاحتمية بدلًا من مصارعتها

الشيء الذي يجعل الوكلاء يبدون مستعصين على التصحيح هو اللاحتمية: المدخل نفسه يُنتج مُخرَجات مختلفة عبر التشغيلات. يمكنك ترويضها.

أولًا، ثبّت ما تستطيع. اضبط temperature: 0 أثناء التصحيح. لن يجعل Claude حتميًّا تمامًا، لكنه يُضيّق التباين بشكل حاد كي تميّز خطأً حقيقيًّا من ضوضاء العيّنات.

ثانيًا، شغّلها N مرة. إذا تكرّر فشل مرة من كل 20 تشغيلة، فكرّر المدخل نفسه بالضبط 50 مرة والتقط كل مُخرَج. الآن لديك عيّنة، لا حكاية. خطأ يحدث 5% من الوقت هو خطأ حقيقي — تحتاج فقط إلى حجم لرؤيته.

for i in $(seq 1 50); do
  node replay.mjs --trace=abc123 >> runs.jsonl
done
# ثم عُدّ حالات الفشل
grep -c '"status":"fail"' runs.jsonl

ثالثًا، قارِن بين التشغيلات الناجحة والفاشلة. مع تثبيت درجة الحرارة والمدخل نفسه، فإن اختلافًا في المُخرَج يعني اختلافًا في المدخل لم تكتشفه بعد — طابع زمني في الموجِّه، أو نتيجة أداة تتغيّر، أو مستند مُسترجَع تغيّر.

ابنِ حزمة إعادة تشغيل كي تتوقف عن التصحيح في الإنتاج

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

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

حزمة إعادة تشغيل جيدة تتيح لك أيضًا التحوير وإعادة التشغيل: غيّر سطرًا واحدًا من موجِّه النظام، وأعد تشغيل الـ 50 تتبّعًا الفاشلة نفسها، وانظر كم منها ينجح الآن. هذا هو الجسر من التصحيح إلى التقييم — بمجرد أن يصبح لديك مجموعة من التتبّعات الفاشلة، يصبح لديك بداية مجموعة اختبار انحدار (regression suite).

راقب المقاييس التي تتنبأ فعلًا بالأعطال

بعض حالات الفشل لا تُطلق استثناءً أبدًا. يعمل الوكيل، ويُعيد شيئًا معقولًا، ويفعل الشيء الخطأ بصمت. لاصطياد تلك، تراقب مقاييس سلوكية، لا مجرد معدلات أخطاء:

• معدل نجاح استدعاءات الأداة لكل أداة. الانخفاض هنا كثيرًا ما يسبق فشلًا مرئيًّا.
• صلاحية مخطط المُخرَج — ما النسبة المئوية للمُخرَجات التي تُحلَّل مقابل البنية المتوقّعة. أتحقق من كل مُخرَج باستخدام Zod وأُطلق تنبيهًا عندما تنخفض الصلاحية.
• طول الحلقة — متوسط عدد الخطوات لكل تشغيلة. الارتفاع المفاجئ يعني عادةً أن الوكيل عالق في إعادة المحاولة.
• التكلفة لكل تشغيلة — حلقة جامحة تظهر كقفزة في التكلفة قبل أن تظهر كشكوى. (عندما تهمّ التكلفة، يستحق حساب Haiku مقابل Sonnet المعرفة.)

أتتبّع هذه كما أتتبّع كل شيء آخر — انظر كيف أقيس ما إذا كان وكيل الذكاء الاصطناعي يعمل فعلًا. المقياس الذي يصطاد فشلًا صامتًا يساوي عشرة تصطاد الفشل الصاخب.

قائمة الفرز في 5 دقائق

عندما يتعطّل وكيل وأنا تحت ضغط الوقت، أُنفّذ هذا بالترتيب:

1. احصل على معرّف التتبّع للتشغيلة الفاشلة.
2. اقرأ المدخل نفسه بالضبط للخطوة الفاشلة. هل هو جيّد التكوين؟ (يحلّ نحو 50% من الحالات هنا.)
3. افحص نتائج الأدوات في ذلك التتبّع بحثًا عن أخطاء متنكّرة في صورة نجاح.
4. أعد تشغيل الخطوة دون اتصال عند temperature: 0. هل تتكرر؟
5. إن تكرّرت، فهي مشكلة موجِّه/نموذج — أصلِح وأعد تشغيل مجموعة التتبّعات. وإن لم تتكرر، فهي لاحتمية أو خطأ حالة/تنسيق — كرّرها 50× لتوصيفها.

العزل المنضبط يتفوّق على الموجِّه البارع في كل مرة. النموذج نادرًا ما يكون المشكلة؛ النظام من حوله عادةً ما يكون كذلك.

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

كيف أُصحّح وكيل ذكاء اصطناعي يفشل أحيانًا فقط؟

التقط المدخل نفسه بالضبط من تتبّع مُسجَّل وأعد تشغيله أكثر من 50 مرة عند درجة حرارة 0. حالات الفشل المتقطّعة هي أخطاء حقيقية بمعدلات إطلاق منخفضة — الحجم يحوّل الحكاية إلى عيّنة قابلة لإعادة الإنتاج يمكنك مقارنتها وإصلاحها.

هل الخطأ عادةً في النموذج أم في شفرتي؟

في وكلائي في الإنتاج، نحو 70% من “أخطاء الذكاء الاصطناعي” الظاهرة هي سباكة: نتائج أدوات مشوّهة، أو مدخلات مقتطعة، أو استثناءات مبتلَعة، أو حالة مفقودة بين الخطوات. استبعد طبقتَي المدخل والأداة قبل أن تشكّ في النموذج.

ما الحد الأدنى من التسجيل الذي أحتاجه لتصحيح الوكلاء؟

معرّف تتبّع على كل تشغيلة، إضافة إلى سجلات منظَّمة للمُحفِّز، وكل استدعاء للنموذج (مصفوفة الرسائل الكاملة)، وكل استدعاء أداة ونتيجته الخام، والمُخرَج النهائي. إذا لم تُسجَّل خطوة، فلا يمكنك تصحيحها.

كيف أتوقف عن التصحيح مقابل الإنتاج المباشر؟

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