در این فصل چه یاد میگیری#
فصلِ قبل خروجی متن بود و تو خواندیاش. برنامهات نمیتواند متن بخواند. برای اینکه کدت کاری بکند — رزروی ثبت کند، فرمی پر کند، سطری در پایگاه داده بنویسد — به 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جامانده. ولی قانونی که به چند فیلد با هم بسته است، مثلِ «۸ جلد برای عضو عادی»، فقط با کدِ خودت گرفته میشود.
تمرینها
اول خودت فکر کن یا امتحان کن — بعد اینجا را باز کن.
در فصل بعد#
خروجیِ ساختارمند را گرفتیم، ولی هنوز مدل فقط حرف میزند. فصلِ بعد به آن اجازه میدهیم کار بخواهد: تابعهای تو را نام ببرد و ورودیشان را پیشنهاد بدهد. و همانجا مرزی را میکشیم که تمامِ ایمنیِ فصلِ ۹ رویش بنا میشود — مدل تصمیم میگیرد، کدِ تو اجرا میکند.
به آخر این فصل رسیدی!
اگر ساختی و جواب داد، این دکمه مال توست.