ژرفا — خودآموز یادگیری عمیق و مهندسی هوش مصنوعی (متوسط)

فصل ۲ از ۱۰

پیشرفت ترم
۰٪

در این فصل چه یاد می‌گیری#

فصلِ قبل خروجی متن بود و تو خواندی‌اش. برنامه‌ات نمی‌تواند متن بخواند. برای اینکه کدت کاری بکند — رزروی ثبت کند، فرمی پر کند، سطری در پایگاه داده بنویسد — به dict نیاز دارد با کلیدهای معلوم و مقدارهای از نوعِ درست.

در این فصل از مدل JSON می‌خواهیم و سه بار می‌شماریم. اول: از ۴۰ پاسخ، ۱۶ تا اصلاً json.loads را می‌شکنند. دوم: بعد از باز کردنِ بسته‌بندی، این عدد به ۷ می‌رسد. سوم — و ناخوشایندترینش: وقتی محتوا را هم بسنجیم، باز هم فقط ۱۶ تا سالم‌اند. ۱۷ تای دیگر قالبشان بی‌عیب است و قانونِ کتابخانه را نقض می‌کنند.

بعد سه لایه دفاع می‌سازیم و همان عدد را به ۴۰ از ۴۰ می‌رسانیم — و می‌شماریم چقدر خرجِ اضافه داشت.

یک قالبِ سوراخ‌دار که فقط قطعه‌های درست‌شکل از آن رد می‌شوند

آخر این فصل می‌توانی:

  • از مدل خروجیِ ساختارمند بخواهی و بسته‌بندی‌اش را باز کنی
  • با pydantic هم نوع و هم قانونِ کاری را اعتبارسنجی کنی
  • یک حلقهٔ تصحیح بنویسی که خطا را به مدل برمی‌گرداند
  • بگویی چرا schemaی کوچک‌تر خروجیِ سالم‌تری می‌دهد — با عدد

قبل از شروع#

از فصل ۱: chat، reset_calls، و اینکه پرسش آخرین سطرِ پیامِ کاربر است.

از سرنخ ترمِ ۱: try/except و dict. از سرنخ ترمِ ۵ فصل ۲: class — pydantic رویش سوار است.

📓 نوت‌بوک: نوت‌بوک این فصل را در Colab باز کن — همهٔ کدهای این فصل آماده و به‌ترتیب داخلش هست.

۱. چرا متن کافی نیست#

REQUESTS = [
    "سلام، عضو دانشجویی‌ام و می‌خواهم ۳ جلد کتاب را ۲۱ روز امانت بگیرم",
    "من عضو عادی هستم، ۲ جلد برای ۱۴ روز لطفاً",
    "عضویت پژوهشی دارم و ۸ جلد را ۳۰ روز می‌خواهم",
    "عضو عادی‌ام، دو جلد برای دو هفته می‌خواهم",
]

for text in REQUESTS:
    numbers = re.findall(r"\d+", to_ascii_digits(text))
    print(f"{str(numbers):<12} ← {text[:44]}")
['3', '21']  ← سلام، عضو دانشجویی‌ام و می‌خواهم ۳ جلد کتاب 
['2', '14']  ← من عضو عادی هستم، ۲ جلد برای ۱۴ روز لطفاً
['8', '30']  ← عضویت پژوهشی دارم و ۸ جلد را ۳۰ روز می‌خواهم
[]           ← عضو عادی‌ام، دو جلد برای دو هفته می‌خواهم

سه تا از چهار تا کار کرد. چهارمی «دو جلد برای دو هفته» است و هیچ رقمی ندارد — پس عبارتِ منظمِ ما دستِ خالی برمی‌گردد.

می‌شود عبارتِ منظم را بزرگ‌تر کرد: «دو» و «سه» و «هفته» و «ماه» را هم بشناسد. بعد «یکی‌دو تا» می‌آید. بعد «تا آخرِ ترم». این مسابقه‌ای است که هیچ‌وقت نمی‌بری — و دقیقاً همان جایی است که مدلِ زبانی به کار می‌آید: زبانِ آزاد را می‌فهمد.

پس معامله روشن است: مدل زبان را می‌فهمد، ولی خروجی‌اش هم زبان است. کارِ ما این است که از دهانِ چیزی که زبان تولید می‌کند، داده‌ای با قالبِ تضمین‌شده بیرون بکشیم.

۲. از مدل JSON بخواه#

SCHEMA_HINT = """از پیامِ کاربر یک درخواستِ امانت دربیاور.
خروجی را فقط به شکل JSON بده، با دقیقاً همین سه کلید:
  tier  : یکی از «عادی» یا «دانشجویی» یا «پژوهشی»
  count : تعدادِ جلد، عددِ صحیح
  days  : مدتِ امانت به روز، عددِ صحیح
هیچ توضیحی ننویس."""


def ask(text, correction=""):
    messages = [{"role": "system", "content": SCHEMA_HINT},
                {"role": "user", "content": text}]
    if correction:
        messages.append({"role": "user", "content": correction})
    return chat(messages)["text"]


reset_calls()
print(repr(ask(REQUESTS[0])))
'{"tier": "طلایی", "count": 3, "days": 21}'

همین اولین پاسخ، درسِ کلِ فصل را در خودش دارد.

JSONش بی‌عیب است. json.loads بی‌صدا قبولش می‌کند. count و days هم دقیقاً همان‌اند که کاربر گفت. و tier مقداری است که در کتابخانهٔ نوردانه اصلاً وجود ندارد.

«خروجی JSON بود» یعنی هیچ. قالبِ درست فقط می‌گوید پرانتزها بسته شده‌اند.

💡 نکته: آن repr را عمداً گذاشتیم. print(raw) متن را رندرشده نشان می‌دهد و کاراکترهای کنترلی و فاصله‌های اضافه را پنهان می‌کند؛ repr همه‌چیز را لو می‌دهد. هر وقت داری خروجیِ خامِ یک مدل را اشکال‌یابی می‌کنی، repr بزن.

۳. چهل بار، نه یک بار#

import json


def parses(text):
    try:
        json.loads(text)
        return True
    except json.JSONDecodeError:
        return False


reset_calls()
answers = [ask(REQUESTS[i % 3]) for i in range(40)]

broken = [a for a in answers if not parses(a)]
print("از ۴۰ پاسخ،", len(broken), "تا json.loads را می‌شکنند")
for sample in sorted(set(broken))[:3]:
    print("   ", repr(sample)[:74])
از ۴۰ پاسخ، 16 تا json.loads را می‌شکنند
    '```json\n{"tier": "دانشجویی", "count": 3, "days": 21}\n```'
    '```json\n{"tier": "عادی", "count": 2, "days": 14}\n```'
    '```json\n{"tier": "پژوهشی", "count": 8, "days": 30}\n```'

✅ چک کن: اگر عددت صفر درآمد، SCHEMA_HINT را عوض کرده‌ای و کلمهٔ JSON از متن افتاده — بدل به همان کلمه نگاه می‌کند تا بفهمد باید JSON بدهد. اگر خیلی بزرگ‌تر از ۱۶ شد، reset_calls() را قبلِ حلقه فراموش کرده‌ای.

یک تماسِ موفق چیزی را ثابت نمی‌کند. خرابیِ مدل احتمالی است، نه قطعی — پس با یک نمونه پیدایش نمی‌کنی. چهل تا بزن و بشمار. این عادت، نصفِ این ترم است.

۱۶ از ۴۰. و سه نمونهٔ بالا همگی یک بیماری دارند: مدل JSON را داخلِ حصارِ markdown بسته‌بندی کرده. برایش طبیعی است — میلیاردها بار دیده که کد در markdown این‌طور نوشته می‌شود.

try:
    json.loads(broken[0])
except json.JSONDecodeError as error:
    print(type(error).__name__, "→", error)
JSONDecodeError → Expecting value: line 1 column 27 (char 26)

🔧 اگر کار نکرد: Expecting value تقریباً همیشه یعنی متنِ اضافه قبل یا بعدِ JSON هست — حصار، یک «بفرمایید:»، یا یک جملهٔ توضیحی. Expecting ',' delimiter یعنی خودِ JSON خراب است. و Extra data یعنی دو شیء پشتِ‌سرِ‌هم آمده. متنِ خطا دقیقاً می‌گوید در کدام نویسه گیر کرده؛ همان اطرافش را چاپ کن.

۴. لایهٔ اول: بسته‌بندی را باز کن#

FENCE_RE = re.compile(r"^\s*```(?:json)?\s*|\s*```\s*$")


def extract_json(text):
    """بسته‌بندی را باز می‌کند: حصارِ markdown و ارقامِ فارسی."""
    return to_ascii_digits(FENCE_RE.sub("", text.strip()))


still_broken = [a for a in answers if not parses(extract_json(a))]
print("بعد از تمیزکاری:", len(still_broken), "تا هنوز می‌شکنند")
print("نمونه:", repr(still_broken[0]))
بعد از تمیزکاری: 7 تا هنوز می‌شکنند
نمونه: '{"tier": "دانشجویی", "count": 3, "days": 21,}'

۱۶ شد ۷، با دو خط. حصار را برداشتیم و ارقامِ فارسی را به لاتین برگرداندیم — چون {"count": ۳} از نظرِ JSON اصلاً عدد نیست.

و آن هفت‌تا یک ویرگولِ اضافه دارند. این را هم می‌شد با یک عبارتِ منظم درست کرد. ولی نمی‌کنیم، و دلیلش مهم است:

  • حصار و ارقام مسئلهٔ بسته‌بندی‌اند — قالبِ داده درست است، فقط لباسِ اضافه پوشیده. برداشتنشان بی‌خطر و قطعی است.
  • ویرگولِ اضافه یعنی خودِ مدل نحو را شکسته. اگر امروز برایش وصله بگذاری، فردا پرانتزِ نبسته می‌آید و پس‌فردا نقلِ‌قولِ تک. هر وصله یک وصلهٔ بعدی می‌آورد و آخرش یک تحلیل‌گرِ JSONِ خانگیِ باگ‌دار داری.

قاعده: بسته‌بندی را باز کن، خرابیِ محتوا را دوباره بخواه. بخشِ ۶ همان «دوباره خواستن» است.

۵. لایهٔ دوم: schema که قانون را هم می‌داند#

from typing import Literal

from pydantic import BaseModel, Field, ValidationError, model_validator

LIMITS = {"عادی": (3, 14), "دانشجویی": (5, 21), "پژوهشی": (8, 30)}


class LoanRequest(BaseModel):
    tier: Literal["عادی", "دانشجویی", "پژوهشی"]
    count: int = Field(ge=1, le=8)
    days: int = Field(ge=1, le=30)

    @model_validator(mode="after")
    def within_tier(self):
        max_count, max_days = LIMITS[self.tier]
        if self.count > max_count:
            raise ValueError(f"عضو {self.tier} حداکثر {max_count} جلد می‌گیرد، نه {self.count}")
        if self.days > max_days:
            raise ValueError(f"مدتِ امانتِ عضو {self.tier} حداکثر {max_days} روز است")
        return self


print(LoanRequest(tier="دانشجویی", count=3, days=21))
tier='دانشجویی' count=3 days=21

این class سه لایه اعتبارسنجی در خودش دارد و هر سه لازم‌اند:

  • Literal — tier فقط یکی از این سه. «طلایی» همین‌جا می‌افتد.
  • Field(ge=..., le=...) — بازهٔ عددی. count=12 همین‌جا می‌افتد.
  • model_validator — قانونِ کاری، چیزی که فقط با دیدنِ همهٔ فیلدها معلوم می‌شود. «۸ جلد» به‌تنهایی معتبر است؛ «۸ جلد برای عضو عادی» نیست.

آن لایهٔ سوم است که این را از یک بررسیِ نوع به یک دروازهٔ واقعی تبدیل می‌کند. بیشترِ اشتباه‌های گران، نوعشان درست است.

🌱 ریشه‌اش کجاست: ایدهٔ «مجموعهٔ مقدارهای مجاز» همان دامنهای است که در ریشه ترمِ ۴ فصل ۱ دیدی: تابع روی هر ورودی‌ای تعریف نشده و دامنه‌اش بخشی از تعریفش است. Literal و ge/le دقیقاً دارند همان دامنه را در کد می‌نویسند.

۶. حالا هر ۴۰ تا را از دروازه رد کن#

syntax_bad = valid = invalid = 0
for answer in answers:
    try:
        data = json.loads(extract_json(answer))
    except json.JSONDecodeError:
        syntax_bad += 1
        continue
    try:
        LoanRequest(**data)
        valid += 1
    except ValidationError:
        invalid += 1

print("قالبِ خراب      :", syntax_bad)
print("قالبِ درست، محتوای غلط:", invalid)
print("سالم            :", valid, "از ۴۰")
قالبِ خراب      : 7
قالبِ درست، محتوای غلط: 17
سالم            : 16 از ۴۰

📏 اندازه بگیر: ۱۷ در برابرِ ۷. بیشترِ خرابی‌ها آن‌هایی نیستند که json.loads می‌گیردشان. بیش از دو برابرِ آن‌ها از تحلیلِ نحوی سالم رد می‌شوند و بعد در پایگاه داده‌ات می‌نشینند. اگر فقط try: json.loads(...) می‌نوشتی، حس می‌کردی ۳۳ از ۴۰ موفق بوده‌ای. این تفاوتِ «کد خطا نداد» با «کد درست کار کرد» است.

بدلِ ما عمداً بدقالق‌تر از یک مدلِ خوبِ امروزی است تا هر شش نوع خرابی را در چهل تماس ببینی. با مدلِ واقعی این نسبت‌ها بهترند — ولی صفر نمی‌شوند، و کدی که فقط برای حالتِ خوب نوشته شده، دقیقاً همان‌جا می‌شکند.

try:
    LoanRequest(tier="دانشجویی", count=12, days=21)
except ValidationError as error:
    print(error)
1 validation error for LoanRequest
count
  Input should be less than or equal to 8 [type=less_than_equal, input_value=12, input_type=int]
    For further information visit https://errors.pydantic.dev/2.13/v/less_than_equal

پیامِ خطا سه چیز دارد: کدام فیلد، چه انتظاری، چه مقداری آمد. آن نشانیِ آخر شمارهٔ نسخهٔ pydantic را دارد، پس ممکن است پیشِ تو کمی فرق کند.

و همین پیام سرمایهٔ بخشِ بعد است: به‌جای اینکه خودمان حدس بزنیم مدل کجا را غلط کرده، عینِ این متن را به‌ش برمی‌گردانیم.

۷. لایهٔ سوم: حلقهٔ تصحیح#

def ask_valid(text, attempts=3):
    correction = ""
    for i in range(attempts):
        raw = ask(text, correction)
        try:
            data = json.loads(extract_json(raw))
        except json.JSONDecodeError as error:
            reason = f"JSON نامعتبر: {error}"
        else:
            try:
                return LoanRequest(**data), i + 1
            except ValidationError as error:
                reason = str(error).splitlines()[1].strip()
        correction = f"خطای اعتبارسنجی در خروجیِ قبلی: {reason}\nفقط JSON درست بده."
    return None, attempts


reset_calls()
obtained, tries = 0, []
for i in range(40):
    request, used = ask_valid(REQUESTS[i % 3])
    if request is not None:
        obtained += 1
        tries.append(used)

print("معتبر:", obtained, "از ۴۰")
print("توزیعِ تعدادِ تلاش:", {k: tries.count(k) for k in sorted(set(tries))})
print("تماس‌های واقعی:", _CALLS["n"], "برای ۴۰ درخواست")
معتبر: 40 از ۴۰
توزیعِ تعدادِ تلاش: {1: 15, 2: 25}
تماس‌های واقعی: 65 برای ۴۰ درخواست

۱۶ از ۴۰ شد ۴۰ از ۴۰. و هیچ‌کدام به تلاشِ سوم نرسید.

چرا روی مدلِ واقعی این کار می‌کند؟ چون خطا را دقیق برمی‌گردانیم. «درست بنویس» بی‌فایده است؛ «count باید حداکثر ۸ باشد و تو ۱۲ دادی» یک دستورِ اجراشدنی است. متنِ خطای pydantic را دور نریز — همان بهترین پرامپتِ تصحیح است. فقط بدان که این ۴۰ از ۴۰ چنین چیزی را اندازه نمی‌گیرد: بدلِ ما با دیدنِ عبارتِ «خطای اعتبارسنجی» خروجیِ سالم می‌دهد، هر پیامی که کنارش باشد. با پیامِ مبهمِ «خطای اعتبارسنجی. درست بنویس.» هم همان ۴۰ از ۴۰ با ۶۵ تماس درمی‌آید. ارزشِ پیامِ دقیق را فقط روی real_chat می‌شود سنجید.

📏 اندازه بگیر: ۶۵ تماس برای ۴۰ درخواست. یعنی حدودِ ۶۰٪ هزینهٔ بیشتر. این همان معاملهٔ فصلِ ۱ است با لباسِ تازه: اعتبار را با پول می‌خری. و همان‌جا هم راهِ ارزان‌تری وجود دارد — بخشِ بعد.

۸. ارزان‌ترین لایه: کمتر بخواه#

class NarrowRequest(BaseModel):
    tier: Literal["عادی", "دانشجویی", "پژوهشی"]
    count: int = Field(ge=1, le=8)


def days_for(tier):
    """تصمیمی که کدِ توست، نه مدل."""
    return LIMITS[tier][1]


narrow_ok = 0
for answer in answers:
    try:
        NarrowRequest(**json.loads(extract_json(answer)))
        narrow_ok += 1
    except (json.JSONDecodeError, ValidationError):
        pass

print("schemaی سه‌کلیدی، بارِ اول:", valid, "از ۴۰")
print("schemaی دوکلیدی، بارِ اول:", narrow_ok, "از ۴۰")
print("نمونهٔ نهایی:", NarrowRequest(tier="پژوهشی", count=8), "→ days =", days_for("پژوهشی"))
schemaی سه‌کلیدی، بارِ اول: 16 از ۴۰
schemaی دوکلیدی، بارِ اول: 21 از ۴۰
نمونهٔ نهایی: tier='پژوهشی' count=8 → days = 30

یک کلید کمتر خواستیم و نرخِ موفقیتِ بارِ اول از ۱۶ به ۲۱ رفت — بدونِ هیچ تماسِ اضافه.

منطقش ساده است: days را اصلاً لازم نبود از مدل بپرسیم. مدتِ امانت از روی نوعِ عضویت درمی‌آید و در LIMITS نوشته شده. هر فیلدی که از مدل می‌خواهی، یک جای دیگر برای اشتباه کردن است.

📏 اندازه بگیر: قاعدهٔ عملی، و در کلِ ترم به کارت می‌آید: هر چیزی که کدت می‌تواند حساب کند، از مدل نخواه. مدل برای چیزی است که فقط او می‌تواند — فهمیدنِ «دو جلد برای دو هفته». حسابِ اینکه عضو دانشجویی چند روز فرصت دارد کارِ یک dict است، و dict هیچ‌وقت خیال‌بافی نمی‌کند.

و سه لایه را کنارِ هم بگذار:

لایه چه چیزی را می‌گیرد هزینه
کوچک کردنِ schema خطا را از اول کم می‌کند صفر
باز کردنِ بسته‌بندی حصار، ارقامِ فارسی، فاصله صفر
pydantic نوعِ غلط، بازهٔ غلط، قانونِ نقض‌شده ناچیز
حلقهٔ تصحیح باقیِ همه‌چیز تماسِ اضافه

به همین ترتیب هم به‌کارشان ببر: اول رایگان‌ها، آخر گران.

واژه‌های تازهٔ این فصل#

کلمه تلفظ به حروف فارسی یعنی چه
schema اسکیما توصیفِ رسمیِ شکلِ داده: چه کلیدهایی، از چه نوعی
structured output استراکچرد اوت‌پوت خروجیِ مدل با قالبِ ماشین‌خوان به‌جای متنِ آزاد
pydantic پایدنتیک کتابخانهٔ پایتون برای تعریف و اعتبارسنجیِ schema
ValidationError ولیدیشن ارور خطای pydantic وقتی داده با schema نمی‌خواند
Literal لیترال نوعی که فقط چند مقدارِ مشخص را مجاز می‌داند
repair loop ری‌پیر لوپ برگرداندنِ متنِ خطا به مدل و خواستنِ خروجیِ درست

🤖 از دستیارت بپرس: «سرویس‌های امروزی چه امکانی برای تضمینِ قالبِ خروجی دارند؟» (چیزهایی مثل response_schema و structured output را خواهی دید که قالب را در سمتِ سرویس اجباری می‌کنند.) بعد این را بپرس: «اگر سرویس قالب را تضمین کند، آیا دیگر به pydantic نیاز ندارم؟» — جوابِ درست نه است، ولی دلیلش ظریف‌تر از «قالب هیچ‌چیز را نمی‌گیرد» است. اگر enum، بازهٔ عددی و کلیدِ اجباری را هم در schema بگذاری، قالبِ تضمین‌شده خیلی از خرابی‌ها را می‌گیرد؛ هر ۱۷ موردِ این فصل هم از همین جنس‌اند: ۷ tier بیرون از فهرست، ۵ count بیرون از بازه و ۵ days جامانده. ولی قانونی که به چند فیلد با هم بسته است، مثلِ «۸ جلد برای عضو عادی»، فقط با کدِ خودت گرفته می‌شود.

تمرین‌ها

اول خودت فکر کن یا امتحان کن — بعد اینجا را باز کن.

در فصل بعد#

خروجیِ ساختارمند را گرفتیم، ولی هنوز مدل فقط حرف می‌زند. فصلِ بعد به آن اجازه می‌دهیم کار بخواهد: تابع‌های تو را نام ببرد و ورودی‌شان را پیشنهاد بدهد. و همان‌جا مرزی را می‌کشیم که تمامِ ایمنیِ فصلِ ۹ رویش بنا می‌شود — مدل تصمیم می‌گیرد، کدِ تو اجرا می‌کند.

به آخر این فصل رسیدی!

اگر ساختی و جواب داد، این دکمه مال توست.