# فصل ۰۵ — خروجیِ ساختارمند

<div dir="rtl">

# فصل ۰۵ — خروجیِ ساختارمند

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

تا حالا جوابِ مدل یک تکه **متن** بود و تو همان را روی صفحه می‌گذاشتی. ولی خیلی وقت‌ها یک برنامه نمی‌خواهد فقط متن نشان بدهد؛ می‌خواهد با تک‌تکِ اجزای جواب کار کند — مثلاً پنج فلش‌کارت را جدا جدا بسازد، هر کدام با یک سؤال و یک جواب. برای این کار متنِ آزاد به درد نمی‌خورد؛ برنامه به **ساختار** نیاز دارد. در این فصل یک سازندهٔ فلش‌کارت می‌سازی که از مدل `JSON` می‌گیرد، آن را به دادهٔ واقعی تبدیل می‌کند، و اگر خروجی خراب بود به‌جای شکستن یک پیامِ آبرومند نشان می‌دهد.

![یک جریانِ درهمِ متن که از یک قیف می‌ریزد و آن‌طرف به قفسه‌ای از کارت‌های هم‌اندازه و مرتب تبدیل می‌شود](/lesson-assets/t5-s05-structured-output/prompt/01-image-structure-rack.png)

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

- با `responseMimeType` از مدل بخواهی جوابش را به‌صورتِ `JSON` بدهد
- با `JSON.parse` رشتهٔ `JSON` را به دادهٔ واقعیِ قابلِ‌استفاده تبدیل کنی
- خروجی را اعتبارسنجی کنی و وقتی `JSON` خراب بود، برنامه را از شکستن نجات بدهی
- بفهمی چرا «`JSON` سالم» به‌معنیِ «محتوای درست» نیست

## قبل از شروع

- **از فصل ۴:** `system_instruction` و `generationConfig` را در بدنهٔ درخواست می‌گذاری.
- **از ترم ۷ تاروپود (پیش‌نیاز):** `JSON` قالبِ متنیِ داده است؛ `createElement`، `textContent`، `append` و حلقهٔ `for...of` برای ساختنِ فهرست از داده.
- **از فصل ۴ ترم ۱:** مدل گاهی با اطمینانِ کامل چیزی می‌گوید که غلط است (`hallucination`).

مثلِ همیشه فقط یک مرورگر و کلیدِ رایگانِ خودت لازم است؛ کلید از `<input type="password">` می‌آید و هرگز در کد نوشته نمی‌شود.

> 🧪 **آزمایشگاه:** [آزمایشگاه این فصل را باز کن](/lab/embed/hamhoosh/term-5-building/session-05-structured-output) — یک موضوع بنویس، فلش‌کارت بگیر، و بعد عمداً خرابش کن تا ببینی برنامه چطور از یک `JSON`ِ ناسالم جانِ سالم به در می‌برد.

## ۱. چرا برنامه به ساختار نیاز دارد

فرض کن مدل این را برایت بنویسد: «پایتختِ فرانسه پاریس است، پایتختِ ایتالیا رم است، و پایتختِ اسپانیا مادرید.» برای چشمِ تو کاملاً روشن است. ولی حالا از برنامه بخواه «سؤالِ کارتِ سوم» را بردارد. برنامه فقط یک رشتهٔ بلندِ حروف می‌بیند؛ نمی‌داند «کارت» کجا شروع و کجا تمام می‌شود، و «سؤال» کدام تکه است. متنِ آزاد برای انسان خوانا است، ولی برای برنامه یک تودهٔ بی‌شکل است.

چیزی که برنامه می‌فهمد **آرایه** و **شیء** است — همان جنسی که در تاروپود دیدی. آنچه اینجا لازم داریم یک آرایه از پنج شیء است، و هر شیء دو کلید دارد: `question` و `answer`. آن‌وقت برنامه می‌تواند بگوید «کارتِ سوم، کلیدِ `question`» و دقیقاً همان را بردارد. کارِ این فصل این است: مدل را وادار کنیم به‌جای پاراگراف، همین ساختار را بدهد.

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

اگر فقط در پرامپت بنویسی «به‌صورتِ `JSON` جواب بده»، مدل معمولاً همکاری می‌کند، ولی نه همیشه تمیز: گاهی جلوی `JSON` یک «حتماً! این هم جوابت:» می‌گذارد، یا آن را داخلِ یک بلوکِ ```‎ می‌پیچد. هر کدام از این‌ها `JSON` را برای برنامه ناخوانا می‌کند. `generationConfig` یک اهرمِ مخصوصِ همین کار دارد: `responseMimeType`. وقتی آن را روی `"application/json"` بگذاری، به مدل می‌گویی خروجی باید `JSON`ِ خام باشد و بس. این را کنارِ نقش می‌گذاری:

</div>

```js
      system_instruction: {
        parts: [{ text: "تو سازندهٔ فلش‌کارتی. فقط یک آرایهٔ JSON از شیءهایی با کلیدِ question و answer برگردان، بدونِ هیچ متنِ اضافه." }]
      },
      contents: [{ parts: [{ text: "پنج فلش‌کارتِ کوتاه دربارهٔ: " + topic }] }],
      generationConfig: { responseMimeType: "application/json" }
```

<div dir="rtl">

دو کار با هم انجام دادیم: در `system_instruction` **شکلِ دقیق** را توصیف کردیم (آرایه‌ای از شیءها با `question` و `answer`)، و در `generationConfig` با `responseMimeType` گفتیم خروجی `JSON` باشد. حالا متنی که برمی‌گردد چیزی شبیهِ این است (خروجیِ تو ممکن است فرق کند):

</div>

```json
[
  { "question": "پایتختِ فرانسه؟", "answer": "پاریس" },
  { "question": "پایتختِ سوئیس؟", "answer": "ژنو" },
  { "question": "پایتختِ ایتالیا؟", "answer": "رم" },
  { "question": "پایتختِ اسپانیا؟", "answer": "مادرید" },
  { "question": "پایتختِ پرتغال؟", "answer": "لیسبون" }
]
```

<div dir="rtl">

> ✅ **چک کن:** جوابِ خام را یک‌بار با `console.log(raw)` نگاه کن. باید با `[` شروع شود و با `]` تمام، بدونِ هیچ جمله‌ای قبل یا بعدش. اگر جلوی `[` یک «حتماً!» دیدی، یعنی `responseMimeType` را نگذاشته‌ای یا اشتباه نوشته‌ای.

## ۳. JSON.parse: از رشته به داده

یک نکتهٔ ظریف: آنچه در `data.candidates[0].content.parts[0].text` است، هنوز یک **رشته** است — یک متن که *شبیهِ* `JSON` است، نه دادهٔ واقعی. اگر همین‌طور از دلش `[0]` را بخواهی، حرفِ اولِ متن را می‌گیری، نه کارتِ اول را. باید اول این رشته را به دادهٔ واقعی تبدیل کنی، و ابزارش `JSON.parse` است:

</div>

```js
  const data = await res.json();
  const raw = data.candidates[0].content.parts[0].text;

  const list = JSON.parse(raw);
```

<div dir="rtl">

از این به بعد `list` یک آرایهٔ واقعی است: `list[0].question` سؤالِ کارتِ اول است و `list[0].answer` جوابش.

اینجا **دو** تبدیل پشتِ‌هم انجام شد و قاطی‌کردنشان رایج‌ترین گیجیِ این فصل است. تبدیلِ اول همان `res.json()`ِ آشنای تاروپود است که کلِ جوابِ سرور را از `JSON` به داده برمی‌گرداند. ولی داخلِ آن داده، در خانهٔ `text`، **یک رشتهٔ دیگر** نشسته — همان چیزی که خودِ مدل نوشت — و آن هم `JSON` است. تبدیلِ دوم مالِ همین یکی است، و با `JSON.parse` خودت انجامش می‌دهی.

> ✅ **چک کن:** بعد از `JSON.parse`، یک `console.log(list[0].question)` بگذار. اگر سؤالِ کارتِ اول را دیدی، تبدیل درست انجام شده. اگر `undefined` گرفتی، یعنی شکلِ داده آن‌طور که فکر می‌کردی نیست — شاید مدل کلیدها را `q` و `a` گذاشته، نه `question` و `answer`.

## ۴. وقتی JSON خراب است

`responseMimeType` احتمالِ خرابی را خیلی کم می‌کند، ولی صفر نمی‌کند. مدل قطعی نیست؛ گاهی یک کاما جا می‌اندازد و گاهی وسطِ کار یک جملهٔ اضافه می‌نویسد. مشکل این است که `JSON.parse` روی متنِ ناسالم **می‌ترکد** و کلِ برنامه‌ات وسطِ راه می‌ایستد. مثلاً اگر مدل این را بدهد:

</div>

```text
حتماً! این هم فلش‌کارت‌ها:
[
  { "question": "پایتختِ فرانسه؟", "answer": "پاریس" }
]
```

<div dir="rtl">

آن جملهٔ اول باعث می‌شود `JSON.parse` خطا بدهد، چون کلِ متن دیگر `JSON`ِ معتبر نیست.

یک حالتِ دیگر هم هست که حتماً باید بشناسی، به‌خصوص اگر `responseMimeType` را نگذاری، چون از دور شبیهِ `JSON`ِ سالم است و راحت گولت می‌زند: مدل آرایه را داخلِ همان علامت‌گذاریِ `markdown` می‌پیچد که برنامه‌نویس‌ها برای نشان‌دادنِ کد به‌کار می‌برند — یعنی یک خطِ آغازین از سه نشانِ backtick و کلمهٔ `json`، خودِ آرایه، و یک خطِ پایانیِ سه‌نشانه. این کار را می‌کند چون در تقریباً هر متنی که دیده، کد همین‌طور نوشته شده بود. نتیجه‌اش این است که خطِ اول و خطِ آخرِ `raw` اصلاً `JSON` نیستند و `JSON.parse` باز هم می‌ترکد. اگر در `console` دیدی که `raw` با backtick شروع می‌شود، مشکل همین است. راهِ درست این است که `JSON.parse` را داخلِ `try`/`catch` بگذاری و بعد مطمئن شوی چیزی که گرفتی واقعاً یک **آرایه** است. `try`/`catch` یعنی «این تکه را امتحان کن؛ اگر ترکید، به‌جای شکستنِ برنامه برو سراغِ بلوکِ `catch`»:

</div>

```js
  let list;
  try {
    list = JSON.parse(raw);
  } catch (e) {
    status.textContent = "مدل چیزی داد که JSON سالم نبود؛ دوباره امتحان کن.";
    return;
  }

  if (!Array.isArray(list)) {
    status.textContent = "خروجی یک فهرست نبود؛ دوباره امتحان کن.";
    return;
  }
```

<div dir="rtl">

دو نگهبان گذاشتیم: `try`/`catch` جلوی ترکیدنِ `JSON.parse` را می‌گیرد، و `Array.isArray` مطمئن می‌شود مدل یک آرایه داده، نه مثلاً یک شیءِ تنها یا یک عدد. این‌ها همان **اعتبارسنجیِ خروجی**اند: هیچ‌وقت به مدل اعتماد نکن که دقیقاً همان شکلی را داده که خواستی؛ اول بررسی کن، بعد استفاده کن.

دقت کن این `try`/`catch` فقط دورِ `JSON.parse` است — یعنی تنها **شکلِ** خروجیِ مدل را مهار می‌کند. خودِ شبکه (جوابِ ناسالمِ سرور، کلیدِ غلط، یا پرشدنِ سهمیه) در این فصل هنوز نگهبانی ندارد؛ آن سخت‌کاریِ شبکه را در فصل ۶ به اپِ اصلی اضافه می‌کنیم.

> 🔧 **اگر جواب نگرفتی:** اگر مدام پیامِ «`JSON` سالم نبود» را می‌گیری، جوابِ خام را با `console.log(raw)` ببین. اغلب یک جملهٔ توضیحیِ اضافه سرِ خط است — `system_instruction` را محکم‌تر کن: «فقط و فقط آرایهٔ `JSON`، هیچ کلمهٔ دیگری ننویس.»

## ۵. نمایشِ ساختارمند — و یک تلهٔ مهم

حالا که `list` یک آرایهٔ سالم است، با همان `for...of`ِ تاروپود رویش حلقه بزن و برای هر کارت یک جعبه بساز. این `script.js` کاملِ این فصل است:

</div>

```js
// script.js
// modelِ رایگان — dar zaman-e khandan az mostanadat-e Gemini check kon:
const MODEL = "gemini-flash-latest";
const URL = "https://generativelanguage.googleapis.com/v1beta/models/" + MODEL + ":generateContent";

const makeBtn = document.querySelector("#make");

makeBtn.addEventListener("click", async function () {
  const key = document.querySelector("#key").value.trim();
  const topic = document.querySelector("#topic").value.trim();
  const status = document.querySelector("#status");
  const cards = document.querySelector("#cards");

  cards.textContent = "";
  status.textContent = "در حالِ ساختن…";

  const res = await fetch(URL + "?key=" + key, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      system_instruction: {
        parts: [{ text: "تو سازندهٔ فلش‌کارتی. فقط یک آرایهٔ JSON از شیءهایی با کلیدِ question و answer برگردان، بدونِ هیچ متنِ اضافه." }]
      },
      contents: [{ parts: [{ text: "پنج فلش‌کارتِ کوتاه دربارهٔ: " + topic }] }],
      generationConfig: { responseMimeType: "application/json" }
    })
  });

  const data = await res.json();
  const raw = data.candidates[0].content.parts[0].text;

  let list;
  try {
    list = JSON.parse(raw);
  } catch (e) {
    status.textContent = "مدل چیزی داد که JSON سالم نبود؛ دوباره امتحان کن.";
    return;
  }

  if (!Array.isArray(list)) {
    status.textContent = "خروجی یک فهرست نبود؛ دوباره امتحان کن.";
    return;
  }

  status.textContent = "";
  for (const card of list) {
    const box = document.createElement("div");
    box.classList.add("card");

    const q = document.createElement("p");
    q.classList.add("q");
    q.textContent = card.question;

    const a = document.createElement("p");
    a.classList.add("a");
    a.textContent = card.answer;

    box.append(q);
    box.append(a);
    cards.append(box);
  }
});
```

<div dir="rtl">

و این هم `index.html`ِ سازندهٔ فلش‌کارت:

</div>

```html
<!DOCTYPE html>
<html lang="fa" dir="rtl">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>سازندهٔ فلش‌کارت</title>
    <link rel="stylesheet" href="styles.css">
  </head>
  <body>
    <main>
      <h1>سازندهٔ فلش‌کارت</h1>
      <p class="hint">کلیدِ Gemini خودت را بگذار، یک موضوع بنویس، بعد بساز.</p>
      <input type="password" id="key" placeholder="کلیدِ API خودت — روی کامپیوترِ خودت می‌ماند">
      <input type="text" id="topic" placeholder="موضوع؛ مثلاً «پایتخت‌های اروپا»">
      <button id="make">بساز</button>
      <p id="status" class="status"></p>
      <div id="cards" class="cards"></div>
    </main>
    <script src="script.js"></script>
  </body>
</html>
```

<div dir="rtl">

استایلِ کارت‌ها در `styles.css` است — همان پالتِ آشنای اپ با یک کلاسِ `card` برای هر جعبه.

> ✅ **چک کن:** موضوعِ «پایتخت‌های اروپا» را بنویس و بساز را بزن. باید چند کارتِ جدا ببینی، هر کدام با سؤالِ پررنگ و جوابِ کم‌رنگ‌تر زیرش. اگر همه‌چیز در یک تودهٔ به‌هم‌چسبیده آمد، یعنی حلقهٔ `for...of` یا `append` درست کار نکرده.

حالا مهم‌ترین درسِ این فصل. به کارت‌ها با دقت نگاه کن. در همان نمونهٔ بالا، کارتِ سوئیس این بود: «پایتختِ سوئیس؟ → ژنو». این `JSON` **کاملاً سالم** بود، `JSON.parse` بی‌هیچ خطایی بازش کرد، و کارت هم قشنگ رندر شد. ولی جوابْ **غلط** است: پایتختِ سوئیس بِرن است، نه ژنو. برنامه هیچ راهی ندارد این را بفهمد — ساختار درست بود، پس همه‌چیز «کار کرد».

> ✅ **وارسی:** «`JSON`ِ سالم» و «محتوای درست» دو چیزِ کاملاً جدا هستند. `Array.isArray` و `JSON.parse` فقط **شکل** را وارسی می‌کنند، نه **حقیقت** را؛ یک کارتِ خوش‌ساخت می‌تواند یک واقعیتِ غلط را با اطمینانِ کامل جا بزند. هر کارتی که یک ادعای واقعی دارد باید با یک منبعِ مستقل سنجیده شود. سه قانونِ ثابتِ این دوره: **«اول خودت فکر کن» — «وارسی کن، خط به خط» — «مدل مطمئن است؛ دلیل نمی‌شود درست باشد».**

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

</div>

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| JSON | جِی‌سان | قالبِ متنیِ داده که به آرایه و شیء تبدیل می‌شود؛ زبانی که برنامه‌ها با آن ساختار ردوبدل می‌کنند |
| responseMimeType | ری‌اسپانس‌مایم‌تایپ | پارامتری در `generationConfig` که می‌گوید خروجی چه قالبی داشته باشد؛ `"application/json"` یعنی `JSON`ِ خام |
| `JSON.parse` | جِی‌سان‌پارس | تبدیلِ رشتهٔ `JSON` به دادهٔ واقعیِ قابلِ‌استفاده در برنامه |

<div dir="rtl">

## تمرین‌ها

**تمرین اجباری:** موضوعِ فلش‌کارت را به چیزی عوض کن که خودت درباره‌اش تخصص داری (یک درس، یک بازی، یک سرگرمی). کارت‌ها را بساز و **همه** را خط‌به‌خط وارسی کن. حداقل یک کارت با یک واقعیتِ غلط یا مبهم پیدا کن و در یک جمله بنویس چطور فهمیدی غلط است.

**تمرین ستاره‌دار ⭐:** `system_instruction` را عوض کن و از مدل بخواه هر شیء یک کلیدِ سومِ `difficulty` هم داشته باشد (مثلاً «آسان» یا «سخت»). بعد کد را طوری تغییر بده که این مقدار هم روی کارت نشان داده شود. اگر مدل گاهی این کلید را جا انداخت، فکر کن: برنامه‌ات چطور باید با نبودنِ یک کلید کنار بیاید بدونِ اینکه بترکد؟

## در فصل بعد

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

</div>

---
Source: https://yaadestan.com/courses/hamhoosh/lessons/t5/s05-structured-output (یادستان, Yaadestan)
