Claude Architect · درس

نمط مضاد: تحليل النص لاكتشاف الاكتمال

لماذا يُعدّ البحث عن 'done' في المخرجات هشًا وخاطئًا

الدرس 3 من 413 خطوة

نمط مضاد: تحليل النص لاكتشاف الاكتمال درس مجاني في Claude Architect على CoddyKit. هذا هو الدرس 3 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Claude Architect، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Claude Architect 4 دروس في المجموع.

الفخ

تبنون وكيلًا. يشغّل الأدوات، ويفكّر، ويرد. والآن تحتاجون إلى معرفة متى انتهى. من الاختصارات المغرية: فحص نص النموذج بحثًا عن كلمة مثل done أو finished أو complete، ثم إيقاف الحلقة عند العثور عليها.

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

كيف تعمل حلقة الوكيل فعلًا

يقود حلقة الوكيل حقل واحد في الاستجابة: stop_reason. والحلقة بسيطة وحتمية:

أرسلوا الطلب (مع سجل الرسائل الكامل في كل دورة).
افحصوا stop_reason.
إذا كانت قيمته tool_use، فشغّلوا الأدوات، وأضيفوا النتائج إلى السجل، وكرروا العملية.
إذا كانت قيمته end_turn، فقد اكتملت المهمة. أوقفوا الحلقة.

يخبركم النموذج نفسه، عبر البيانات الوصفية المنظمة، بما إذا كان يريد المتابعة أو قد انتهى. ولا يتعين عليكم التخمين بقراءة النثر.

while True:
    response = client.messages.create(
        model="claude-opus-4-8",
        max_tokens=16000,
        tools=tools,
        messages=messages,
    )
    if response.stop_reason == "end_turn":
        break  # complete
    # else: tool_use -> run tools, append results, loop

أسباب الإيقاف الأربعة

أنهوا الحلقة عند الإشارة، لا عند الكلمات. يعيد Claude أحد أسباب الإيقاف الأربعة:

end_turn — أنهى Claude المهمة بصورة طبيعية. اكتملت المهمة.
tool_use — يريد Claude تشغيل أداة؛ شغّلوها وتابعوا الحلقة.
max_tokens — اقتُطع الناتج بسبب حد الرموز.
stop_sequence — جرى الوصول إلى تسلسل إيقاف مُعد مسبقًا.

كل سبب منها واضح ولا يلتبس، ويمكن للآلة قراءته. قارنوا ذلك بفحص النص الحر، حيث يعتمد المعنى بالكامل على الطريقة التي صاغ بها النموذج عبارته في هذه المرة.

لماذا يُعد فحص النص هشًا

اللغة الطبيعية ليست بروتوكولًا للتحكم. يمكن للمهمة المكتملة نفسها أن تنتهي باثنتي عشرة طريقة مختلفة:

«All done!»
«That completes the migration.»
«I've finished the analysis.»
«Everything is in place now.»

سيتطابق فحصكم للكلمة done مع العبارة الأولى، وربما الثانية، وسيفوّت الباقي بصمت. ولن تتوقف الحلقة. وستستهلكون الرموز والوقت، أو تصلون إلى حد صلب، في مهمة كانت قد اكتملت قبل دورات.

# ANTI-PATTERN: brittle keyword scan
if "done" in response_text.lower():
    break  # misses "finished", "complete", "all set"...

الإيجابيات الكاذبة أسوأ

إن تفويت الإشارة يهدر الموارد. أما الإخفاق المعاكس فهو أخطر: التوقف مبكرًا جدًا.

لنفترض أن المستخدم طلب من Claude «التحقق مما إذا كان النشر قد اكتمل». قد يرد Claude في منتصف التحقيق قائلًا: «دعوني أتحقق من اكتمال النشر قبل أن أتابع». سيرى الفاحص لديكم done وينهي الحلقة — متخليًا عن المهمة في منتصفها، قبل تشغيل أي أداة أو إنتاج أي إجابة.

يستخدم النموذج كلمات مثل done في سياق المحادثة. ولا يستطيع تطابق الكلمات التمييز بين السرد وإشارة الاكتمال الحقيقية. أما stop_reason فيستطيع ذلك.

النموذج لا يحتفظ بأي حالة

إليكم السبب الأعمق في كون فحص النص هو الطبقة الخاطئة. إن Claude API عديمة الحالة: فلا يحتفظ النموذج بأي ذاكرة بين الطلبات. وأنتم ترسلون المحادثة كاملة — system، وكل دورة سابقة من messages، ونتائج الأدوات — في كل استدعاء.

لذلك فإن سؤال «هل انتهى الوكيل؟» يتعلق بـ الحلقة التي تتحكمون بها، وتجيب عنه stop_reason المنظمة التي تعيدها الواجهة — وليس شيئًا ينبغي استنتاجه عكسيًا من النثر. إن مستوى التحكم (حلقتكم) ومستوى المحتوى (نص النموذج) منفصلان. أبقوا منطق الاكتمال في مستوى التحكم.

# Stateless: full history goes up every turn
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    system=system_prompt,
    tools=tools,
    messages=messages,  # ENTIRE history, every call
)
messages.append({"role": "assistant", "content": response.content})

فحص الإنهاء الصحيح

قودوا الحلقة اعتمادًا على stop_reason وحدها. عندما تكون القيمة tool_use، شغّلوا الأدوات المطلوبة وأضيفوا نتائجها إلى السجل باستخدام tool_use_id المطابق. وعندما تكون end_turn، تكونون قد انتهيتم.

يعمل هذا بغض النظر عن صياغة Claude لرسالته النهائية — سواء قال «All set» أو «Finished» أو لم يقل شيئًا على الإطلاق. فالقرار تتخذه بيانات وصفية يمكنكم الوثوق بها، لا مطابقة سلاسل نصية تحتاجون إلى مراقبتها باستمرار.

while True:
    response = client.messages.create(
        model="claude-opus-4-8", max_tokens=16000,
        tools=tools, messages=messages,
    )
    messages.append({"role": "assistant", "content": response.content})

    if response.stop_reason == "tool_use":
        results = run_tools(response.content)  # each with tool_use_id
        messages.append({"role": "user", "content": results})
        continue
    if response.stop_reason == "end_turn":
        break  # done -- no text parsing anywhere

القرارات يقودها النموذج

مبدأ معماري أساسي: في حلقة الوكيل، يقرر النموذج التدفق، ويظهر ذلك عبر stop_reason. لا تفرضون أن «بعد تشغيل 3 أدوات يجب أن تكون المهمة قد انتهت». إذ يشير Claude إلى حاجته إلى أداة أخرى وإلى انتهائه.

خصصوا التحكم المضمّن مسبقًا للأمور التي تحتاج إلى ضمان — أي ثابت حتمي تتطلبه أعمالكم. واكتشاف الاكتمال ليس من هذه الأمور؛ فالواجهة توفره أصلًا بصورة واضحة. إن إعادة تنفيذه بتحليل النص تستبدل إشارة موثوقة بتخمين.

حدود التكرار شبكة أمان

قد تقولون: «حسنًا، سأتوقف بعد N من التكرارات». تمهلوا: حد التكرار هو شبكة أمان، وليس آلية الإيقاف الأساسية. فهو موجود لوضع حد للحلقات الجامحة والحماية من الأخطاء — لا لتقرير اكتمال العمل.

إذا كانت حلقتكم تعتمد على الحد لكي تنتهي بصورة طبيعية، فأنتم تعانون المشكلة نفسها التي يسببها فحص النص: إذ تستبدلون الإشارة الحقيقية التي يقودها النموذج بقاعدة تقريبية اعتباطية. أنهوا الحلقة عند stop_reason أولًا؛ ودعوا الحد يتعامل فقط مع الحالة المرضية.

MAX_ITERS = 20  # safety net, NOT the primary stop
for _ in range(MAX_ITERS):
    response = client.messages.create(...)
    messages.append({"role": "assistant", "content": response.content})
    if response.stop_reason == "end_turn":
        break  # primary: model-driven
    # ... handle tool_use ...
else:
    log.warning("hit iteration cap -- investigate, don't trust as 'done'")

معالجة أسباب الإيقاف الأخرى

تفرّع الحلقة المتينة عند كل سبب من أسباب الإيقاف، وليس عند المسار المثالي فقط. وبوجه خاص، تعني max_tokens أن الاستجابة قد قُطعت — وهي ليست اكتمالًا. إن اعتبار دورة مقتطعة «منتهية» يؤدي بصمت إلى تسليم نصف إجابة.

عندما ترون max_tokens، يكون الإصلاح هو رفع قيمة max_tokens أو التبديل إلى البث للمخرجات الكبيرة، ثم المتابعة — وليس الخروج من الحلقة أبدًا كما لو أن المهمة نجحت.

if response.stop_reason == "end_turn":
    break
elif response.stop_reason == "tool_use":
    messages.append({"role": "user", "content": run_tools(response.content)})
elif response.stop_reason == "max_tokens":
    # truncated, NOT complete -- raise cap or stream, then continue
    raise OutputTruncated("increase max_tokens or stream")

تحتاجون إلى علامة اكتمال منظمة؟ استخدموا أداة

قد ترغبون أحيانًا فعلًا في أن يبلغ النموذج عن نتيجة منظمة — مثل حالة أو درجة ثقة أو ملخص — عند انتهائه. ومع ذلك، لا يكمن الحل في تحليل النثر. امنحوا Claude أداة (أو JSON Schema عبر المخرجات المنظمة) ودعوه يصدر نتيجة مكتوبة بنوع محدد.

باستخدام tool_choice: "any" يمكنكم إجبار النموذج على استدعاء أي أداة، مما يضمن مخرجات منظمة بدلًا من نص حر. وتظل الحلقة تنتهي عند stop_reason؛ أما الأداة فتحمل الحكم المقروء آليًا. وتستبدل البنية مطابقة السلاسل النصية في كل موضع يهم.

tools = [{
    "name": "submit_result",
    "description": "Report the final task outcome.",
    "input_schema": {
        "type": "object",
        "properties": {
            "status": {"type": "string", "enum": ["success", "failed"]},
            "summary": {"type": "string"},
        },
        "required": ["status", "summary"],
    },
}]
# tool_choice={"type": "any"} forces a structured call, not prose

تحقق سريع

اختبروا حكمكم في قرار تصميم واقعي.

أجب عليها في الدرس التفاعلي

أهم النقاط

تعرفون الآن سبب كون فحص المخرجات بحثًا عن الاكتمال أداة غير مناسبة للمهمة:

أنهوا الحلقة عند stop_reason، وليس عند النص مطلقًا. end_turn = اكتمل؛ tool_use = شغّلوا الأدوات وتابعوا.
فحص النص هش في الاتجاهين — فهو يفوّت حالات الاكتمال الحقيقية (بسبب اختلاف الصياغة)، ويطلق إيجابيات كاذبة (بسبب الاستخدام الحواري لكلمة «done»).
الواجهة عديمة الحالة ويقودها النموذج. أرسلوا السجل الكامل في كل دورة؛ ودعوا الإشارة المنظمة، لا النثر، تقود الحلقة.
حدود التكرار شبكة أمان وليست الإيقاف الأساسي. تعاملوا مع max_tokens على أنه اقتطاع، لا نجاح.
هل تحتاجون إلى نتيجة منظمة؟ استخدموا أداة أو JSON Schema (وأجبروها باستخدام tool_choice: "any") — ولا تحللوا النص الحر مطلقًا.

البدء مجانًا

تعلم Python مع معلم ذكاء اصطناعي — مجانًا

اكتب وقم بتشغيل أكوادك الفعلية في المتصفح، واحصل على مساعدة فورية من معلم ذكاء اصطناعي متاح 24/7، واستمر من حيث توقفت على الويب أو في التطبيق.

الدورات: 26
الدروس: 104

ابدأ التعلم مجانًا عرض الدورة الكاملة

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

هل درس «نمط مضاد: تحليل النص لاكتشاف الاكتمال» مجاني؟

نعم — نص درس «نمط مضاد: تحليل النص لاكتشاف الاكتمال» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Claude Architect، انتقل إلى CoddyKit PRO. تتضمن دورة Claude Architect 4 دروس في المجموع.

ماذا ستتعلم في «نمط مضاد: تحليل النص لاكتشاف الاكتمال»؟

لماذا يُعدّ البحث عن 'done' في المخرجات هشًا وخاطئًا تتمرن على Claude Architect مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ Claude Architect؟

لا تُشترط خبرة سابقة. Claude Architect على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 3 من أصل 4.

كم من الوقت يستغرق درس «نمط مضاد: تحليل النص لاكتشاف الاكتمال»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس Claude Architect هذا؟

نعم. كل درس في Claude Architect يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

← العودة إلى Claude Architect