المنهج الدراسي الدرس 138 من 250 · المخرجات المهيكلة واستدعاء الوظائف/الأدوات
المخرجات المهيكلة واستدعاء الوظائف/الأدوات

مخرجات مقيدة / مفروضة بالمخطط

لقد قمت بالتحقق من ملف JSON الخاص بالنموذج يدويا في الدروس السابقة. الممارسة الحديثة تتقدم خطوة واحدة للأمام وهي منع النموذج من إصدار JSON سيء من الأساس. هذا هو constrained decoding (ويسمى أيضا structured outputs). أنت تقدم schema إلى API، ويُسمح للمُفكك فقط باختيار tokens تحافظ على صحة المخرجات وفقا لها. لا يمكن للنموذج حرفيا إنتاج حقل مفقود أو قيمة بنوع خاطئ.

باستخدام واجهة برمجة التطبيقات (API) بنمط OpenAI، تقوم بتمرير response_format مع JSON Schema و strict: true (للتوضيح فقط -> نحن لا نستدعي أي نموذج هنا):

resp = client.chat.completions.create(
    model="...",
    messages=[...],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {"name": {"type": "string"}, "age": {"type": "integer"}},
                "required": ["name", "age"],
            },
        },
    },
)

بقية هذا المسار تستدعي Anthropic، والتي تقدم نفس الضمان عبر output_config للحصول على استجابات JSON مضمونة و strict لاستخدام الأدوات بمدخلات مطابقة للمخطط:

resp = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[...],
    output_config={"format": {
        "type": "json_schema",
        "schema": {
            "type": "object",
            "properties": {"name": {"type": "string"}, "age": {"type": "integer"}},
            "required": ["name", "age"],
        },
    }},
)

في كلتا الحالتين يقوم المزود بعملية التقييد. لكن فك التشفير المقيد لا يزال لا يستطيع التحقق من قواعد العمل الخاصة بك (هل العمر منطقي؟ هل العملة هي التي تدعمها؟)، ولا يدعمها كل نموذج أو بوابة. لذا عليك التحقق من جانبك بغض النظر عن ذلك. هذا المقيّم هو ما تبنيه الآن.

على جانب Python، المعيار الفعلي لإعلان ذلك الشكل والتحقق منه هو Pydantic. تكتب صنف نموذج وتقوم المكتبة بالتحليل والتحويل والتحقق نيابةً عنك:

from pydantic import BaseModel

class Person(BaseModel):
    name: str
    age: int

record = Person.model_validate_json(text)   # raises if it does not fit

Pydantic غير متوفر في بيئة العمل هذه داخل المتصفح، لذا ستقوم ببناء الفكرة نفسها يدويا باستخدام المكتبة القياسية. هذا هو بالضبط ما تفعله هذه المكتبات في الخلفية، وهذا يجعل القواعد غير قابلة للتجاهل. أنت تكتب validate_against_schema(obj, schema).

الـ schema هو dict. كل قيمة هي إما سلسلة نصية لاسم النوع ("int", "float", "str", "bool", "list", "dict") أو dict مواصفات صغير مثل {"type": "int", "default": 0}. تعيد الدالة الخاصة بك dict نتيجة {"ok": bool, "value": dict, "errors": list}:

  • إذا لم يكن obj عبارة عن dict، أعد ok=False مع خطأ جذر واحد و value فارغ.
  • لكل حقل: إذا كان missing وهناك "default" في المواصفات، فاملأ القيمة الافتراضية (تمريرة coerce/default). إذا كان مفقودا بدون قيمة افتراضية، سجل خطأ.
  • إذا كان موجودا، تحقق من type الخاص به. في حال عدم التطابق، سجل خطأ يحدد اسم الحقل.
  • Coerce قيمة int بسيطة إلى float عندما يكون المطلوب float (وهذا آمن وبدون فقدان بيانات)، ولكن لا تقم بتحويل أي شيء آخر.
  • إذا كانت هناك أي أخطاء، أعد ok=False مع errors المجموعة و value فارغ؛ خلاف ذلك أعد ok=True مع value الذي تم التحقق منه.

فخ bool-is-int. في Python bool هو subclass من int، لذا isinstance(True, int) هو True و JSON true يتم فك تشفيره إلى Python True. فحص النوع البدائي سيسمح لـ "age": true بالمرور عبر حقل int. ارفض bool صراحة في أي مكان يتطلب فيه int أو float:

if expected is int and isinstance(value, bool):
    errors.append(field + ": expected int, got bool")

ابنِهِ بحيث يمر حمولتان مختلفتان جيدتا التكوين، حقل مفقود ونوع خاطئ يقع كل منهما في errors، قيمة افتراضية تملأ الفراغ، و int يتم تحويله إلى float، و bool خفي يتم رفضه حيث يكون الرقم مطلوبا.

دورك

اكتب validate_against_schema(obj, schema) ليعيد {"ok", "value", "errors"}. يقوم schema بربط كل حقل بسلسلة نصية لاسم النوع ("int"/"float"/"str"/"bool"/"list"/"dict") أو قاموس مواصفات {"type": ..., "default": ...}. ارفض obj غير القاموس، وسجل خطأ لكل حقل مفقود (بدون قيمة افتراضية) أو ذي نوع خاطئ، واملأ قيمة افتراضية عندما تكون معطاة، واجبر int بسيط على float، وارفض bool عندما يكون int أو float مطلوبا (فخ bool-is-int). أعد ok=True مع value الذي تم التحقق منه فقط عندما لا توجد أخطاء.

هل لاحظت مشكلة في هذا الدرس؟ أبلغ عنها · اسأل عن هذا الدرس

سيفتح هذا التمرين قريبا

أنهِ الدرس السابق ليفتح هذا الدرس. الدورة كاملة مجانية، ولا تحتاج إلى حساب، ويمكنك قراءة هذا الدرس الآن.