# فصل ۰۴ — خروجیِ ساختارمند: از متن به داده

<div dir="rtl">

# فصل ۰۴ — خروجیِ ساختارمند: از متن به داده

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

مدل جواب می‌دهد، ولی جوابش **متنِ آزاد** است و برنامه‌ات نمی‌تواند رویش حساب کند. راهِ حل این است که از مدل بخواهی جوابش را در قالبِ `JSON` بدهد. ولی نکتهٔ اصلیِ این فصل قسمتِ دوم است: **مدل گاهی قالب را رعایت نمی‌کند**، و برنامه‌ای که این را در نظر نگیرد در اولین موردِ واقعی می‌شکند. پس یاد می‌گیری خروجی را استخراج کنی، **اعتبارسنجی** کنی، و وقتی خراب بود کارِ درست را بکنی.

![یک قالبِ فلزی با شکافِ مشخص که فقط قطعه‌های هم‌شکل از آن رد می‌شوند و بقیه کنار می‌افتند](/lesson-assets/t4-s04-structured-output/prompt/01-image-shape-gate.png)

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

- از مدل خروجیِ `JSON` بخواهی و از متنِ خام استخراجش کنی
- خروجی را در برابرِ یک `schema` اعتبارسنجی کنی
- بگویی چرا اعتبارسنجی اجباری است، نه اختیاری
- حلقهٔ «بگیر، بسنج، دوباره بخواه» را بنویسی

## قبل از شروع

**از فصل ۳:** فراخوانیِ API و اینکه پاسخ یک `dict` تودرتوست.

**از ترمِ ۱ فصل ۸:** `try`/`except` و اینکه فقط خطای پیش‌بینی‌شده را باید گرفت.

> 📓 **نوت‌بوک:** [نوت‌بوک این فصل را در Colab باز کن](/notebooks/sarnakh/term-4-pretrained-models/session-04-structured-output.ipynb) — همهٔ کدهای این فصل آماده و به‌ترتیب داخلش هست.

> 💡 **نکته:** این فصل عمداً **بدونِ فراخوانیِ زنده** کار می‌کند. سه پاسخِ **واقعی** را که از یک مدل گرفته‌ایم به‌عنوان متغیر گذاشته‌ایم و همهٔ کارِ فصل روی همان‌هاست. دلیلش این است که منطقِ اعتبارسنجی باید **قابلِ تکرار و قابلِ تست** باشد — و همان کاری است که در یک پروژهٔ واقعی هم می‌کنی: پاسخ‌های نمونه را ذخیره می‌کنی و منطقت را رویشان می‌سنجی.

## ۱. چرا متنِ آزاد کافی نیست

فرض کن از مدل می‌پرسی «موضوعِ این جمله چیست؟» و جواب می‌گیری: «به‌نظر می‌رسد این جمله دربارهٔ آشپزی باشد.»

برای یک انسان عالی است. برای برنامه‌ات فاجعه: باید متن را بگردی، دنبالِ کلمه‌ها بگردی، و امیدوار باشی مدل دفعهٔ بعد هم همین‌طور بنویسد. **مدل قطعی نیست و همین جمله را فردا جورِ دیگری می‌نویسد.**

راهِ حل: **از مدل بخواه در قالبِ مشخصی جواب بدهد.** یک پرامپتِ خوب برای این کار سه چیز دارد — قالبِ دقیق، فهرستِ مقادیرِ مجاز، و تأکید بر اینکه چیزِ اضافه ننویسد:

</div>

```text
موضوع این جمله را تشخیص بده و فقط یک JSON برگردان، بدون هیچ توضیح اضافه.
قالب دقیق:
{"topic": "<یکی از: سفر، آشپزی، برنامه‌نویسی، سلامت>", "confidence": <عددی بین 0 و 1>, "keywords": ["<کلمه>", "..."]}

جمله: پیاز را با حرارت ملایم سرخ کن تا شیرینی‌اش دربیاید.
```

<div dir="rtl">

## ۲. سه پاسخِ واقعی

این سه پاسخ **واقعاً** از یک مدل گرفته شده‌اند و هر سه حالتِ رایج را نشان می‌دهند:

</div>

```python
answer_clean = '{"topic": "آشپزی", "confidence": 0.92, "keywords": ["پیاز", "سرخ کردن"]}'

# سه بک‌تیک را به‌جای تایپِ مستقیم می‌سازیم تا داخلِ رشته دردسر درست نکند
BACKTICKS = "`" * 3
answer_fenced = BACKTICKS + 'json\n{"topic": "سفر", "confidence": 0.88, "keywords": ["بلیت"]}\n' + BACKTICKS

answer_prose = "موضوع این جمله آشپزی است."

for name, raw in [("تمیز", answer_clean), ("داخل بلوک", answer_fenced), ("متن آزاد", answer_prose)]:
    print(name, "->", repr(raw[:40]))
```

<div dir="rtl">

</div>

```text
تمیز -> '{"topic": "آشپزی", "confidence": 0.92, "'
داخل بلوک -> '```json\n{"topic": "سفر", "confidence": 0'
متن آزاد -> 'موضوع این جمله آشپزی است.'
```

<div dir="rtl">

با `repr` چاپ کردیم تا `\n` را **ببینی**؛ با `print` ساده پنهان می‌شد. همین عادت در اشکال‌زداییِ خروجیِ مدل بارها به‌کارت می‌آید.

حالتِ دوم بسیار رایج است: مدل `JSON` را داخلِ یک بلوکِ کدِ markdown می‌پیچد، چون در دادهٔ آموزشی‌اش این‌طور دیده. حالتِ سوم یعنی مدل دستور را کاملاً نادیده گرفته.

**هر سه را باید پیش‌بینی کنی.** این نه بدعملکردیِ مدل است و نه چیزی که با پرامپتِ بهتر کاملاً حل شود — **ذاتِ کارکردن با خروجیِ غیرقطعی است.**

## ۳. استخراج

</div>

```python
import json

def extract_json(text):
    """JSON را از پاسخ بیرون می‌کشد، حتی اگر داخل بلوک کد markdown پیچیده شده باشد."""
    text = text.strip()
    if text.startswith("```"):
        lines = [line for line in text.split("\n") if not line.strip().startswith("```")]
        text = "\n".join(lines).strip()
    return json.loads(text)

print(extract_json(answer_clean))
print(extract_json(answer_fenced))
```

<div dir="rtl">

</div>

```text
{'topic': 'آشپزی', 'confidence': 0.92, 'keywords': ['پیاز', 'سرخ کردن']}
{'topic': 'سفر', 'confidence': 0.88, 'keywords': ['بلیت']}
```

<div dir="rtl">

`json.loads` متنِ `JSON` را به `dict` پایتون تبدیل می‌کند — همان `dict` آشنای ترمِ ۱، حالا از یک منبعِ خارجی.

آن چند خطِ اولِ تابع فقط بلوکِ markdown را برمی‌دارند. ساده است، ولی **بدونش نیمی از پاسخ‌های واقعی می‌شکنند.**

و یک نکتهٔ نحویِ کوچک که اولین بار گیج‌کننده است: **`"\n".join(lines)`** یعنی «این فهرست از خط‌ها را با `\n` به هم بچسبان». برخلافِ چیزی که انتظار می‌رود، **جداکننده صاحبِ متد است و فهرست آرگومان** — یعنی `join` را روی همان رشته‌ای صدا می‌زنی که قرار است **بین** عنصرها بنشیند. این دقیقاً عکسِ `split()` ترمِ ۱ فصلِ ۳ است: `split` متن را به فهرست می‌شکند، `join` فهرست را به متن برمی‌گرداند.

و حالتِ سوم:

</div>

```python
try:
    extract_json(answer_prose)
except json.JSONDecodeError as error:
    print("JSONDecodeError:", str(error)[:50])
```

<div dir="rtl">

</div>

```text
JSONDecodeError: Expecting value: line 1 column 1 (char 0)
```

<div dir="rtl">

> ✅ **چک کن:** دو خروجیِ اول باید `dict` باشند و سومی خطا بدهد. اگر سومی خطا نداد، یعنی `try` را طوری نوشته‌ای که خطا را می‌بلعد — و آن دقیقاً همان `except`ِ گشادِ ترمِ ۱ فصلِ ۸ است.

## ۴. اعتبارسنجی: `JSON` معتبر بودن کافی نیست

اینجا مهم‌ترین بخشِ فصل است. یک `JSON` می‌تواند کاملاً معتبر باشد و در عینِ حال **کاملاً غلط**:

</div>

```python
ALLOWED_TOPICS = {"سفر", "آشپزی", "برنامه‌نویسی", "سلامت"}

def validate(data):
    """فهرستِ مشکلات را برمی‌گرداند. فهرستِ خالی یعنی سالم."""
    problems = []
    topic = data.get("topic")
    if not isinstance(topic, str) or topic not in ALLOWED_TOPICS:
        problems.append("topic نامعتبر")
    confidence = data.get("confidence")
    if not isinstance(confidence, (int, float)) or not 0 <= confidence <= 1:
        problems.append("confidence خارج از بازه")
    if not isinstance(data.get("keywords"), list):
        problems.append("keywords باید فهرست باشد")
    return problems

print("پاسخ سالم:", validate(extract_json(answer_clean)))
print("پاسخ خراب:", validate({"topic": "ورزش", "confidence": 1.4, "keywords": "دو"}))
```

<div dir="rtl">

</div>

```text
پاسخ سالم: []
پاسخ خراب: ['topic نامعتبر', 'confidence خارج از بازه', 'keywords باید فهرست باشد']
```

<div dir="rtl">

`isinstance(x, str)` می‌پرسد «آیا `x` رشته است؟» — همان کاری که `type()` در ترمِ ۱ فصلِ ۲ می‌کرد، فقط به شکلی که در `if` تمیزتر می‌نشیند.

پاسخِ دوم یک `JSON` **کاملاً معتبر** است — `json.loads` بی‌هیچ اعتراضی می‌خواندش. ولی سه مشکل دارد:

- `"ورزش"` جزوِ چهار موضوعِ مجاز نیست. مدل موضوعی ساخته که وجود ندارد.
- `1.4` به‌عنوان احتمال بی‌معناست.
- `keywords` باید فهرست باشد و متن آمده.

**پس دو لایهٔ کاملاً متفاوت داری و هر دو لازم‌اند:** `json.loads` می‌گوید «قالب درست است»، و `validate` می‌گوید «**محتوا** معنا دارد».

> 📏 **اندازه بگیر:** و لایهٔ سومی هم هست که هیچ کدی نمی‌گیردش: آن `confidence: 0.92` را مدل **از خودش ساخته**. هیچ ضمانتی نیست که با درستیِ واقعیِ جواب رابطه‌ای داشته باشد. **عددی را که مدل به‌عنوان اطمینانِ خودش می‌دهد، به‌عنوان احتمالِ درست بودن به‌کار نبر** — مگر اینکه خودت روی یک مجموعهٔ برچسب‌خورده سنجیده باشی که واقعاً هم‌راستاست. این یکی از رایج‌ترین اشتباه‌های سامانه‌های مبتنی بر LLM است.

## ۵. حلقهٔ «بگیر، بسنج، دوباره بخواه»

وقتی خروجی خراب است، سه گزینه داری و انتخابشان به کاربردت بستگی دارد:

</div>

| گزینه | کِی مناسب است |
|---|---|
| دوباره بخواه، با پیامِ خطا در پرامپت | معمولاً بهترین — مدل اغلب بارِ دوم درست می‌کند |
| مقدارِ پیش‌فرضِ امن برگردان | وقتی جوابِ ناقص بهتر از توقف است |
| صریح شکست بخور و به انسان بگو | وقتی جوابِ غلط پرهزینه‌تر از نبودِ جواب است |

<div dir="rtl">

</div>

```python
def parse_with_retry(raw_answers, max_attempts=3):
    """چند پاسخ را به‌ترتیب امتحان می‌کند و اولین پاسخِ سالم را برمی‌گرداند."""
    for attempt, raw in enumerate(raw_answers[:max_attempts], start=1):
        try:
            data = extract_json(raw)
        except json.JSONDecodeError:
            print(f"تلاش {attempt}: JSON معتبر نبود")
            continue
        problems = validate(data)
        if problems:
            print(f"تلاش {attempt}: {problems}")
            continue
        print(f"تلاش {attempt}: سالم")
        return data
    return None

result = parse_with_retry([answer_prose, '{"topic": "ورزش", "confidence": 2}', answer_clean])
print("نتیجه:", result)
```

<div dir="rtl">

</div>

```text
تلاش 1: JSON معتبر نبود
تلاش 2: ['topic نامعتبر', 'confidence خارج از بازه', 'keywords باید فهرست باشد']
تلاش 3: سالم
نتیجه: {'topic': 'آشپزی', 'confidence': 0.92, 'keywords': ['پیاز', 'سرخ کردن']}
```

<div dir="rtl">

در یک برنامهٔ واقعی، به‌جای فهرستِ آماده، در هر دور دوباره مدل را صدا می‌زنی و **پیامِ خطا را هم در پرامپت می‌گذاری**: «پاسخِ قبلی این مشکل را داشت: … . دوباره و فقط با قالبِ خواسته‌شده جواب بده.»

> ⚠️ **مواظب باش:** `max_attempts` را حتماً بگذار. بدونِ سقف، اگر مدل هرگز قالبِ درست ندهد، حلقه‌ات تا ابد می‌چرخد و **سهمیه‌ات را می‌سوزاند** — همان `while` بی‌پایانِ ترمِ ۱ فصلِ ۶، این بار با هزینهٔ واقعی. سه تلاش تقریباً همیشه کافی است؛ اگر سه بار نشد، مشکل از پرامپت است نه از شانس.

## ۶. یک خطای واقعی: `JSON` با گیومهٔ فارسی

</div>

```python-broken
json.loads('{"topic": «آشپزی»}')
```

<div dir="rtl">

</div>

```text
json.JSONDecodeError: Expecting value: line 1 column 11 (char 10)
```

<div dir="rtl">

مدل‌ها گاهی روی متنِ فارسی گیومهٔ فارسی (`«»`) به‌جای گیومهٔ `JSON` (`"`) می‌گذارند. `JSON` فقط گیومهٔ دوتاییِ استاندارد را می‌شناسد.

> 🔧 **اگر کار نکرد:** سه خرابیِ رایجِ دیگر که همه در پیامِ خطا شمارهٔ نویسه می‌دهند: ویرگولِ اضافه قبل از آکولادِ بسته، گیومهٔ تکی به‌جای دوتایی، و توضیحِ فارسی که مدل قبل یا بعد از `JSON` چسبانده. **هر بار خطا گرفتی، `repr(raw)` را چاپ کن و به همان شمارهٔ نویسه‌ای که خطا می‌گوید نگاه کن** — تقریباً همیشه مشکل دقیقاً همان‌جاست.

> 🤖 **از دستیارت بپرس:** «چه راه‌هایی وجود دارد که یک مدل زبانی JSON نامعتبر برگرداند؟ فقط فهرست کن.» برای هر مورد یک نمونهٔ متنی بساز و به `extract_json` بده. **هر کدام که تابعت را شکست، یک تستِ واقعی برای کدت است** — و همین‌جا داری بدونِ اینکه اسمش را بدانی، تست می‌نویسی. در ترمِ ۵ اسمش را هم یاد می‌گیری.

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

</div>

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| JSON | جِیسون | قالبِ استانداردِ تبادلِ داده؛ در پایتون به `dict` تبدیل می‌شود |
| schema | اسکیما | تعریفِ شکلِ مجازِ داده: کدام کلید، چه نوعی، چه بازه‌ای |
| validation | ولیدیشن | سنجشِ داده در برابرِ `schema` |
| retry | ری‌ترای | تلاشِ دوباره پس از شکست، با سقفِ مشخص |

<div dir="rtl">

## تمرین‌ها

قبل از تمرین، بدونِ نگاه به بالا جواب بده: یک `JSON` می‌تواند کاملاً معتبر باشد و در عینِ حال غلط. یک مثال بزن.

**تمرینِ اجباری:** تابعِ `validate` را کامل کن: چک کن که `keywords` بیش از پنج عضو نداشته باشد و هر عضوش رشته باشد. بعد پنج پاسخِ خرابِ متفاوت بساز که هرکدام **یک** قاعده را بشکنند و مطمئن شو تابع دقیقاً همان یکی را گزارش می‌کند، نه بیشتر و نه کمتر.

**تمرینِ ستاره‌دار ⭐:** تابعِ `extract_json` را مقاوم‌تر کن تا سه خرابیِ بخشِ ۶ را هم تحمل کند: گیومهٔ فارسی، ویرگولِ اضافه، و متنِ چسبیده قبل یا بعد از `JSON`. (راهنمایی: برای موردِ آخر، اولین `{` و آخرین `}` را پیدا کن و بینشان را بردار.) حالا این سؤال را جواب بده: **تا کجا باید خرابی را تحمل کرد و از کجا باید صریح شکست خورد؟** جوابت را با جدولِ بخشِ ۵ توجیه کن — و بدان که این سؤال جوابِ فنی ندارد، جوابِ مهندسی دارد.

## در فصل بعد

تا اینجا از مدل **جواب** گرفتی. فصلِ بعد کارِ متفاوتی می‌کند: از مدل **عدد** می‌گیری — نمایشی از معنای متن که می‌شود با آن حساب کرد. اسمش `embedding` است و پایهٔ جست‌وجوی معنایی، پیشنهاددهنده، و هر سامانه‌ای است که باید بفهمد دو متن «شبیه» هم‌اند.

</div>

---
Source: https://yaadestan.com/courses/sarnakh/lessons/t4/s04-structured-output (یادستان, Yaadestan)
