سرفصل‌ها درس 138 از 250 · خروجی‌های ساختاریافته و فراخوانی تابع/ابزار
خروجی‌های ساختاریافته و فراخوانی تابع/ابزار

خروجی‌های محدود / اعمال‌شده بر اساس طرحواره

شما در درس‌های گذشته JSON مدل را به‌صورت دستی اعتبارسنجی کردید. روش‌های مدرن یک قدم جلوتر می‌روند: از تولید JSON نادرست توسط مدل جلوگیری می‌کنند. این رمزگشایی محدود (که به آن خروجی‌های ساختاریافته نیز گفته می‌شود) است. شما یک اسکیما به API می‌دهید و دیکودر تنها مجاز است توکن‌هایی را نمونه‌برداری کند که خروجی را مطابق آن اسکیما معتبر نگه می‌دارند. مدل عملاً نمی‌تواند فیلد از دست رفته یا مقدار با نوع اشتباه تولید کند.

با API به سبک OpenAI شما یک response_format با یک طرحواره JSON و 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"],
        },
    }},
)

در هر صورت، ارائه‌دهنده این محدودیت را اعمال می‌کند. اما رمزگشایی محدودشده همچنان نمی‌تواند قواعد کسب‌وکار شما را بررسی کند (آیا سن معقول است؟ آیا ارز از ارزهای پشتیبانی‌شده شماست؟)، و هر مدل یا گیت‌وی از آن پشتیبانی نمی‌کند. بنابراین شما به هر حال در سمت خود اعتبارسنجی را انجام می‌دهید. آن اعتبارسنج همان چیزی است که اکنون می‌سازید.

در سمت پایتون، استاندارد عملاً پذیرفته‌شده برای اعلام و اعتبارسنجی آن شکل، 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).

The schema یک dict است. هر مقدار یا یک رشته نام نوع ("int", "float", "str", "bool", "list", "dict") یا یک دیکت کوچک مشخصات مانند {"type": "int", "default": 0}. تابع شما یک dict نتیجه را بازمی‌گرداند {"ok": bool, "value": dict, "errors": list}:

  • اگر obj نیست dict، بازگردانید ok=False با یک خطای ریشه و یک value.
  • برای هر فیلد: اگر مفقود باشد و مشخصات دارای یک "default"، مقدار پیش‌فرض را پر کنید (گذرگاه اجبار/پیش‌فرض). اگر مقدار پیش‌فرض وجود نداشته باشد، خطایی ثبت کنید.
  • اگر موجود باشد، نوع آن را بررسی کنید. در صورت عدم تطابق، خطایی با نام فیلد ثبت کنید.
  • یک plain را اجباری کنید int تا یک float زمانی که یک عدد اعشاری (float) مورد نظر است (یعنی بدون افت و ایمن)، اما هیچ چیز دیگری را اجباری نکنید.
  • اگر خطایی وجود داشت، بازگردانید ok=False با داده‌های جمع‌آوری‌شده errors و یک value؛ در غیر این صورت بازگردانید ok=True با اعتبارسنجی‌شده value.

دام bool-is-int. در پایتون bool یک زیرکلاس از int، بنابراین isinstance(True, int) است True و JSON true را به Python رمزگشایی می‌کند True. یک بررسی نوع ساده‌لوحانه اجازه می‌دهد "age": true از یک عبور کند int field. Reject a 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": ...}. یک dict غیر را رد کنید obj، برای هر فیلد از دست رفته (بدون مقدار پیش‌فرض) یا با نوع نادرست خطایی ثبت کنید، در صورت وجود مقدار پیش‌فرض آن را پر کنید، یک مقدار ساده را اجبار کنید int تا float، و یک را رد می‌کند. bool که یک int یا float نیاز است (دام bool-is-int). بازگردان ok=True با اعتبارسنجی‌شده value فقط زمانی که هیچ خطایی وجود نداشته باشد.

مشکلی در این درس دیدید؟ گزارشش کنید · دربارهٔ این درس بپرسید

این تمرین به‌زودی باز می‌شود

درس پیش از آن را تمام کنید تا این یکی باز شود. کل دوره رایگان است، حساب کاربری لازم نیست، و می‌توانید همین الان این درس را بخوانید.