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

آخر این فصل میتوانی:
- با
responseMimeTypeاز مدل بخواهی جوابش را بهصورتِJSONبدهد - با
JSON.parseرشتهٔJSONرا به دادهٔ واقعیِ قابلِاستفاده تبدیل کنی - خروجی را اعتبارسنجی کنی و وقتی
JSONخراب بود، برنامه را از شکستن نجات بدهی - بفهمی چرا «
JSONسالم» بهمعنیِ «محتوای درست» نیست
قبل از شروع#
- از فصل ۴:
system_instructionوgenerationConfigرا در بدنهٔ درخواست میگذاری. - از ترم ۷ تاروپود (پیشنیاز):
JSONقالبِ متنیِ داده است؛createElement،textContent،appendو حلقهٔfor...ofبرای ساختنِ فهرست از داده. - از فصل ۴ ترم ۱: مدل گاهی با اطمینانِ کامل چیزی میگوید که غلط است (
hallucination).
مثلِ همیشه فقط یک مرورگر و کلیدِ رایگانِ خودت لازم است؛ کلید از <input type="password"> میآید و هرگز در کد نوشته نمیشود.
۱. چرا برنامه به ساختار نیاز دارد#
فرض کن مدل این را برایت بنویسد: «پایتختِ فرانسه پاریس است، پایتختِ ایتالیا رم است، و پایتختِ اسپانیا مادرید.» برای چشمِ تو کاملاً روشن است. ولی حالا از برنامه بخواه «سؤالِ کارتِ سوم» را بردارد. برنامه فقط یک رشتهٔ بلندِ حروف میبیند؛ نمیداند «کارت» کجا شروع و کجا تمام میشود، و «سؤال» کدام تکه است. متنِ آزاد برای انسان خوانا است، ولی برای برنامه یک تودهٔ بیشکل است.
چیزی که برنامه میفهمد آرایه و شیء است — همان جنسی که در تاروپود دیدی. آنچه اینجا لازم داریم یک آرایه از پنج شیء است، و هر شیء دو کلید دارد: question و answer. آنوقت برنامه میتواند بگوید «کارتِ سوم، کلیدِ question» و دقیقاً همان را بردارد. کارِ این فصل این است: مدل را وادار کنیم بهجای پاراگراف، همین ساختار را بدهد.
۲. responseMimeType: از مدل JSON بخواه#
اگر فقط در پرامپت بنویسی «بهصورتِ JSON جواب بده»، مدل معمولاً همکاری میکند، ولی نه همیشه تمیز: گاهی جلوی JSON یک «حتماً! این هم جوابت:» میگذارد، یا آن را داخلِ یک بلوکِ ``` میپیچد. هر کدام از اینها JSON را برای برنامه ناخوانا میکند. generationConfig یک اهرمِ مخصوصِ همین کار دارد: responseMimeType. وقتی آن را روی "application/json" بگذاری، به مدل میگویی خروجی باید JSONِ خام باشد و بس. این را کنارِ نقش میگذاری:
system_instruction: {
parts: [{ text: "تو سازندهٔ فلشکارتی. فقط یک آرایهٔ JSON از شیءهایی با کلیدِ question و answer برگردان، بدونِ هیچ متنِ اضافه." }]
},
contents: [{ parts: [{ text: "پنج فلشکارتِ کوتاه دربارهٔ: " + topic }] }],
generationConfig: { responseMimeType: "application/json" }
دو کار با هم انجام دادیم: در system_instruction شکلِ دقیق را توصیف کردیم (آرایهای از شیءها با question و answer)، و در generationConfig با responseMimeType گفتیم خروجی JSON باشد. حالا متنی که برمیگردد چیزی شبیهِ این است (خروجیِ تو ممکن است فرق کند):
[
{ "question": "پایتختِ فرانسه؟", "answer": "پاریس" },
{ "question": "پایتختِ سوئیس؟", "answer": "ژنو" },
{ "question": "پایتختِ ایتالیا؟", "answer": "رم" },
{ "question": "پایتختِ اسپانیا؟", "answer": "مادرید" },
{ "question": "پایتختِ پرتغال؟", "answer": "لیسبون" }
]
✅ چک کن: جوابِ خام را یکبار با
console.log(raw)نگاه کن. باید با[شروع شود و با]تمام، بدونِ هیچ جملهای قبل یا بعدش. اگر جلوی[یک «حتماً!» دیدی، یعنیresponseMimeTypeرا نگذاشتهای یا اشتباه نوشتهای.
۳. JSON.parse: از رشته به داده#
یک نکتهٔ ظریف: آنچه در data.candidates[0].content.parts[0].text است، هنوز یک رشته است — یک متن که شبیهِ JSON است، نه دادهٔ واقعی. اگر همینطور از دلش [0] را بخواهی، حرفِ اولِ متن را میگیری، نه کارتِ اول را. باید اول این رشته را به دادهٔ واقعی تبدیل کنی، و ابزارش JSON.parse است:
const data = await res.json();
const raw = data.candidates[0].content.parts[0].text;
const list = JSON.parse(raw);
از این به بعد 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 روی متنِ ناسالم میترکد و کلِ برنامهات وسطِ راه میایستد. مثلاً اگر مدل این را بدهد:
حتماً! این هم فلشکارتها:
[
{ "question": "پایتختِ فرانسه؟", "answer": "پاریس" }
]
آن جملهٔ اول باعث میشود JSON.parse خطا بدهد، چون کلِ متن دیگر JSONِ معتبر نیست.
یک حالتِ دیگر هم هست که حتماً باید بشناسی، بهخصوص اگر responseMimeType را نگذاری، چون از دور شبیهِ JSONِ سالم است و راحت گولت میزند: مدل آرایه را داخلِ همان علامتگذاریِ markdown میپیچد که برنامهنویسها برای نشاندادنِ کد بهکار میبرند — یعنی یک خطِ آغازین از سه نشانِ backtick و کلمهٔ json، خودِ آرایه، و یک خطِ پایانیِ سهنشانه. این کار را میکند چون در تقریباً هر متنی که دیده، کد همینطور نوشته شده بود. نتیجهاش این است که خطِ اول و خطِ آخرِ raw اصلاً JSON نیستند و JSON.parse باز هم میترکد. اگر در console دیدی که raw با backtick شروع میشود، مشکل همین است. راهِ درست این است که JSON.parse را داخلِ try/catch بگذاری و بعد مطمئن شوی چیزی که گرفتی واقعاً یک آرایه است. try/catch یعنی «این تکه را امتحان کن؛ اگر ترکید، بهجای شکستنِ برنامه برو سراغِ بلوکِ catch»:
let list;
try {
list = JSON.parse(raw);
} catch (e) {
status.textContent = "مدل چیزی داد که JSON سالم نبود؛ دوباره امتحان کن.";
return;
}
if (!Array.isArray(list)) {
status.textContent = "خروجی یک فهرست نبود؛ دوباره امتحان کن.";
return;
}
دو نگهبان گذاشتیم: try/catch جلوی ترکیدنِ JSON.parse را میگیرد، و Array.isArray مطمئن میشود مدل یک آرایه داده، نه مثلاً یک شیءِ تنها یا یک عدد. اینها همان اعتبارسنجیِ خروجیاند: هیچوقت به مدل اعتماد نکن که دقیقاً همان شکلی را داده که خواستی؛ اول بررسی کن، بعد استفاده کن.
دقت کن این try/catch فقط دورِ JSON.parse است — یعنی تنها شکلِ خروجیِ مدل را مهار میکند. خودِ شبکه (جوابِ ناسالمِ سرور، کلیدِ غلط، یا پرشدنِ سهمیه) در این فصل هنوز نگهبانی ندارد؛ آن سختکاریِ شبکه را در فصل ۶ به اپِ اصلی اضافه میکنیم.
🔧 اگر جواب نگرفتی: اگر مدام پیامِ «
JSONسالم نبود» را میگیری، جوابِ خام را باconsole.log(raw)ببین. اغلب یک جملهٔ توضیحیِ اضافه سرِ خط است —system_instructionرا محکمتر کن: «فقط و فقط آرایهٔJSON، هیچ کلمهٔ دیگری ننویس.»
۵. نمایشِ ساختارمند — و یک تلهٔ مهم#
حالا که list یک آرایهٔ سالم است، با همان for...ofِ تاروپود رویش حلقه بزن و برای هر کارت یک جعبه بساز. این script.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);
}
});
و این هم index.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>
استایلِ کارتها در styles.css است — همان پالتِ آشنای اپ با یک کلاسِ card برای هر جعبه.
✅ چک کن: موضوعِ «پایتختهای اروپا» را بنویس و بساز را بزن. باید چند کارتِ جدا ببینی، هر کدام با سؤالِ پررنگ و جوابِ کمرنگتر زیرش. اگر همهچیز در یک تودهٔ بههمچسبیده آمد، یعنی حلقهٔ
for...ofیاappendدرست کار نکرده.
حالا مهمترین درسِ این فصل. به کارتها با دقت نگاه کن. در همان نمونهٔ بالا، کارتِ سوئیس این بود: «پایتختِ سوئیس؟ → ژنو». این JSON کاملاً سالم بود، JSON.parse بیهیچ خطایی بازش کرد، و کارت هم قشنگ رندر شد. ولی جوابْ غلط است: پایتختِ سوئیس بِرن است، نه ژنو. برنامه هیچ راهی ندارد این را بفهمد — ساختار درست بود، پس همهچیز «کار کرد».
✅ وارسی: «
JSONِ سالم» و «محتوای درست» دو چیزِ کاملاً جدا هستند.Array.isArrayوJSON.parseفقط شکل را وارسی میکنند، نه حقیقت را؛ یک کارتِ خوشساخت میتواند یک واقعیتِ غلط را با اطمینانِ کامل جا بزند. هر کارتی که یک ادعای واقعی دارد باید با یک منبعِ مستقل سنجیده شود. سه قانونِ ثابتِ این دوره: «اول خودت فکر کن» — «وارسی کن، خط به خط» — «مدل مطمئن است؛ دلیل نمیشود درست باشد».
واژههای تازهٔ این فصل#
| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| JSON | جِیسان | قالبِ متنیِ داده که به آرایه و شیء تبدیل میشود؛ زبانی که برنامهها با آن ساختار ردوبدل میکنند |
| responseMimeType | ریاسپانسمایمتایپ | پارامتری در generationConfig که میگوید خروجی چه قالبی داشته باشد؛ "application/json" یعنی JSONِ خام |
JSON.parse |
جِیسانپارس | تبدیلِ رشتهٔ JSON به دادهٔ واقعیِ قابلِاستفاده در برنامه |
تمرینها
اول خودت فکر کن یا امتحان کن — بعد اینجا را باز کن.
در فصل بعد#
حالا هم میدانی چطور به مدل نقش و پارامتر بدهی و هم چطور خروجیِ ساختارمند بگیری و اعتبارش را بسنجی. فصل بعد — قلبِ این ترم — همهچیز را کنارِ هم میگذاری: به دستیارِ اصلیات برمیگردی و آن را به یک ابزارِ واقعیِ کامل تبدیل میکنی، با حالتهای انتظار و خطا و یک دکمهای که وقتِ کار غیرفعال میشود. هیچ مفهومِ تازهای از API نمیآید؛ فقط همهچیزِ بلدی را محکم و آبرومند سرِ هم میکنیم.
به آخر این فصل رسیدی!
اگر ساختی و جواب داد، این دکمه مال توست.