إنتقل إلى المحتوى الرئيسي

المخرجات المنظَّمة

متوسط
What you'll learn
  • اشرح لماذا تتفوّق المخرجات المفروضة بمخطّط على مطالبة النموذج بإنتاج JSON والأمل بالأفضل
  • قدّم مخطّط JSON Schema وحلّل الاستجابة إلى كائن مُصنَّف بنوع (Pydantic / Zod)
  • ميِّز المخرجات المنظَّمة عن استخدام الأدوات بحسب النيّة، لا بحسب الآلية
  • طبّق النصائح الأربع للحصول على مخطّطات محكمة وموثوقة
  • اختر الأداة الصحيحة بقاعدة إرشادية من سؤال واحد

عندما تغذّي مخرجات Claude برمجيات أخرى، فأنت بحاجة إلى بنية موثوقة — JSON صالح يطابق شكلًا معروفًا، في كل مرة. لا تعتمد على "ردّ بصيغة JSON" وتأمل خيرًا؛ استخدم دعم المخرجات المنظَّمة في المنصّة.

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

الطريقة الموثوقة​

قدّم مخطّط JSON Schema للمخرجات ودع الواجهة البرمجية/SDK تفرضه، ثم حلّله إلى كائن مُصنَّف بنوع (مثل Pydantic في Python، أو Zod في TypeScript). تمنحك مساعِدات التحليل في SDK نتيجة مُصنَّفة بنوع بدلًا من سلسلة نصية عليك أن تطبّق عليها JSON.parse وتتحقّق منها بنفسك.

Guided walkthrough1 of 3
  1. صُغ المخرجات التي تحتاجها على هيئة مخطّط JSON Schema — في Python عبر Pydantic BaseModel، وفي TypeScript عبر مخطّط Zod.
# Conceptual shape — see the official docs for the current API surface.
from pydantic import BaseModel

class Ticket(BaseModel):
    title: str
    priority: str   # "low" | "medium" | "high"
    tags: list[str]

# Request the model to return data conforming to Ticket's JSON schema,
# then parse the response into a Ticket instance.

أتريد طلبًا ملموسًا تكيّفه؟ إليك شكل ما تُسلّمه للنموذج — استبدل النموذج بمخطّطك الخاص.

اطلب مخرجات مطابقة للمخطّط

Return the data conforming to this JSON Schema:

{
"title": "string",
"priority": "low | medium | high",
"tags": ["string"]
}

Do not include any prose outside the JSON.

لماذا لا نطلب JSON عبر المطالبة فحسب؟​

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

Watch out
  • JSON المطلوب بالمطالبة ينجح في العروض التوضيحية وينهار في الإنتاج: لا يظهر الخلل إلا حين يحلّله نظام لاحق.
  • ثلاثة انحرافات كلاسيكية احذرها: نصّ شارد حول JSON، أو فاصلة زائدة في النهاية، أو حقل مطلوب مفقود.

المخرجات المنظَّمة مقابل استخدام الأدوات​

كلتا الميزتين تُسلّمان النموذج مخطّط JSON Schema، لذا تبدوان متشابهتين — والناس يختارون الخطأ. الفرق في النيّة، لا في الآلية:

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

قاعدة سريعة للإرشاد:

إذا كان JSON هو المُخرَج المطلوب، فاستخدم المخرجات المنظَّمة. وإذا كان JSON هو النموذج يطلب من شيفرتك أن تفعل شيئًا، فهذا استخدام للأدوات. غالبًا ما يستخدم الوكلاء كليهما: الأدوات للتنفيذ، والمخرجات المنظَّمة لإعادة نتيجة نهائية نظيفة.

نصائح​

Pro tip
  • اجعل المخطّطات محكمة — استخدم القيم المُعدَّدة (enums) للخيارات الثابتة؛ وعلّم الحقول المطلوبة.
  • صِف الحقول — أوصاف الحقول توجّه النموذج كأنها مطالبات مصغّرة.
  • تحقّق على أي حال عند الحدود — التحليل الدفاعي تأمين رخيص.
  • لمهام الاستخراج، تتفوّق المخرجات المنظَّمة + مخطّط واضح على النصّ الحرّ في كل مرة.
Key takeaways
  • سلّم الواجهة البرمجية/SDK مخطّط JSON Schema وحلّل إلى كائن مُصنَّف بنوع — لا تعتمد على المطالبة والأمل.
  • مطالبة النموذج بإنتاج JSON قد تنحرف (نصّ شارد، فاصلة زائدة، حقل مفقود)؛ فرض المخطّط يزيل هذه الفئة من الأخطاء.
  • تختلف المخرجات المنظَّمة عن استخدام الأدوات بحسب النيّة: JSON هو الإجابة مقابل JSON يطلب إجراءً.
  • المخطّطات المحكمة، والحقول الموصوفة، والتحقّق عند الحدود تجعل الاستخراج والتصنيف موثوقَين.

ثبّت المصطلحات​

اضغط Enter أو مفتاح المسافة لقلب البطاقة. استخدم مفتاحي السهمين الأيسر والأيمن للتنقل بين البطاقات.تم إظهار المصطلح.
1 / 5

اختبر نفسك

0/4
  1. ما الطريقة الموثوقة للحصول على JSON منظَّم من Claude؟
  2. لماذا تكون مطالبة النموذج بإنتاج JSON محفوفة بالمخاطر بمجرد اعتماد نظام لاحق عليها؟
  3. ما الذي يميّز المخرجات المنظَّمة عن استخدام الأدوات فعليًّا؟
  4. أيٌّ ممّا يلي نصيحة سليمة لتصميم المخطّطات؟

التالي​