در این فصل چه یاد میگیری#
در فصل ۳ اپت جواب میگرفت، ولی هر جوابی که میآمد رفتارِ پیشفرضِ مدل بود: هر بار یک لحن، بدونِ نقشِ ثابت، و بدونِ اینکه تو تعیین کرده باشی جواب دقیق باشد یا خلاق. در ترم ۲ همین دو اهرم — system prompt و temperature — را در زمینِ بازیِ چت با یک کادر و یک اسلایدر تنظیم میکردی. در این فصل همان دو اهرم را از داخلِ کدِ خودت و در بدنهٔ همان درخواستی که میفرستی میگذاری. فرقش این است که حالا این تنظیم مالِ توست، در فایلِ توست، و هر بار عیناً تکرار میشود.

آخر این فصل میتوانی:
- به مدل از داخلِ کد یک نقشِ ثابت بدهی با
system_instruction - با
generationConfigپارامترِtemperatureرا بفرستی و خلاقبودن یا دقیقبودنِ جواب را کنترل کنی - طولِ جواب را هم از همان
generationConfigمهار کنی - بگویی چرا تنظیمکردن در کد با تنظیمکردن در زمینِ بازیِ چت فرق دارد
قبل از شروع#
- از فصل ۳: اپِ سادهٔ
دستیارِ من— یک<input>برای کلید، یک<textarea>برای سؤال، وfetchی که فقطcontentsرا میفرستد و جواب را نشان میدهد. - از فصلهای ۵ و ۶ ترم ۲:
system promptنقشِ پایدارِ مدل را تعیین میکند (فصل ۵)، وtemperatureتعادلِ خلاق در برابر دقیق را جابهجا میکند (فصل ۶). - از ترم ۷ تاروپود (پیشنیاز):
fetch،async/awaitو خواندنِres.json().
مثلِ همیشه فقط یک مرورگر و کلیدِ رایگانِ خودت لازم است. کلید از همان <input type="password"> خوانده میشود و هرگز داخلِ کد نوشته نمیشود — این ستونِ اخلاقیِ کلِ ترم است.
۱. چرا نقش و پارامتر را در کد بگذاری#
بدنهٔ درخواستی که در فصل ۳ فرستادی فقط یک چیز داشت: contents، یعنی سؤالِ کاربر. مدل هیچ زمینهای از اینکه «تو کی هستی و چطور باید جواب بدهی» نداشت، پس رفتارِ پیشفرضش را انتخاب میکرد. برای یک ابزارِ واقعی این کافی نیست. اگر ابزارت قرار است دستیارِ کوتاهگو باشد، نمیخواهی هر بار امیدوار باشی که مدل حدس بزند کوتاه جواب بدهد؛ میخواهی این را یکبار در کد بگویی و مطمئن باشی هر بار همانطور میماند.
درست همان کاری که در زمینِ بازیِ چت با دست میکردی، حالا در بدنهٔ JSON انجام میشود. دو خانهٔ تازه به بدنه اضافه میکنیم: یکی برای نقش (system_instruction) و یکی برای پارامترها (generationConfig). آدرس و روشِ فرستادن هیچ فرقی نمیکند؛ فقط بدنه پُرتر میشود.
۲. system_instruction: نقشِ ثابت از داخلِ کد#
system_instruction یک خانهٔ جدا در بدنهٔ درخواست است که نقشِ مدل را تعیین میکند — جدا از پیامِ کاربر. مدل قبل از هر جوابی این را میخواند، انگار به یک کارمندِ تازه گفته باشی «تو مسئولِ میزِ راهنمایی هستی؛ کوتاه و دقیق جواب بده» و بعد بگذاری مردم سؤال بپرسند. این خانه را کنارِ contents میگذاری:
system_instruction: {
parts: [{ text: "تو یک دستیارِ فارسی، دقیق و کوتاهگو هستی." }]
},
contents: [{ parts: [{ text: prompt }] }],
به ساختارش دقت کن: عینِ contents، یک شیء با parts و یک text داخلش. تنها فرقش این است که این متن را تو مینویسی و ثابت است، ولی متنِ contents از سؤالِ کاربر میآید. جدا نگهداشتنِ نقش از سؤال مهم است: کاربر هر چه بپرسد، نقش سرِ جایش میماند.
💡 نکته: نقش را کوتاه و مشخص بنویس. «دقیق و کوتاهگو» به مدل یک جهتِ روشن میدهد؛ «یک دستیارِ خیلی خوب و باهوش باش» چیزی به آن نمیگوید که خودش نداند.
۳. generationConfig و temperature: کنترلِ خلاقیت#
خانهٔ دوم generationConfig است — جایی برای پارامترهایی که چگونگیِ ساختنِ جواب را تنظیم میکنند. مهمترینشان temperature است که در ترم ۲ دیدی: عددی پایین یعنی جوابِ محتاط و قابلِپیشبینی، عددی بالا یعنی جوابِ متنوعتر و خلاقتر. برای یک دستیارِ دقیق، عددی پایین میگذاریم:
⚠️ مواظب باش: این اهرم در حالِ کمرنگشدن است. مستنداتِ رسمیِ Gemini در زمانِ نوشتنِ این کتاب میگوید مدلهای تازه مقدارِ
temperatureرا نادیده میگیرند، و ممکن است نسخههای بعدی آن را با خطا رد کنند. برای همین اینجا آن را یاد میگیری چون مفهومش ماندگار است و مدلهای دیگر هم دارندش، ولی در اپِ نهاییِ فصل ۶ نمیگذاریمش. وضعیتِ مدلِ تو در زمان خواندن چک شود.
contents: [{ parts: [{ text: prompt }] }],
generationConfig: { temperature: 0.4 }
حالا همه را کنارِ هم بگذار. این script.js کاملِ این فصل است — نسبت به فصل ۳ فقط دو خانهٔ system_instruction و generationConfig به بدنه اضافه شده:
// 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";
document.querySelector("#ask").addEventListener("click", async function () {
const key = document.querySelector("#key").value.trim();
const prompt = document.querySelector("#prompt").value.trim();
const answer = document.querySelector("#answer");
const res = await fetch(URL + "?key=" + key, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
system_instruction: {
parts: [{ text: "تو یک دستیارِ فارسی، دقیق و کوتاهگو هستی." }]
},
contents: [{ parts: [{ text: prompt }] }],
generationConfig: { temperature: 0.4 }
})
});
const data = await res.json();
answer.textContent = data.candidates[0].content.parts[0].text;
});
index.html و styles.css از فصل ۳ عوض نمیشوند؛ همان #key، #prompt، #ask، #status و #answer را داری، و نسخهٔ کاملِ هر دو همان است که در فصل ۳ نوشتی. پس فقط همین script.js را جایگزین کن و دو فایلِ دیگر را دست نزن.
✅ چک کن: یک سؤال بپرس — مثلاً «سه راهِ صرفهجویی در آب در خانه؟». حالا جواب باید کوتاهتر و منظمتر از فصل ۳ باشد، چون نقشِ «کوتاهگو» را از
system_instructionگرفته. اگر جوابِ بلندِ پُرحرف گرفتی، احتمالاًsystem_instructionرا جای درستی — کنارِcontents، داخلِ همان شیءِJSON.stringify— نگذاشتهای.
حالا اثرِ temperature را امتحان کن. اول با همین 0.4 یک سؤالِ باز را دو بارِ پشتِهم بفرست، مثلاً «یک اسمِ بامزه برای یک ربات پیشنهاد بده»، و دو جواب را یادداشت کن. بعد عدد را به یک عددِ بالا ببر:
generationConfig: { temperature: 1.9 }
اول حدس بزن با عددِ بالا چه میشود، بعد همان سؤال را دو بارِ دیگر بفرست.
روی مدلی که temperature را اجرا میکند، با عددِ بالا جوابها از هم دورتر و گاهی عجیبتر میشوند، و با عددِ پایین به هم نزدیکتر میمانند. روی مدلی که آن را نادیده میگیرد هیچ خطایی نمیبینی و دو دسته جواب فرقِ معناداری ندارند، چون عددی که فرستادی بیصدا کنار گذاشته شده. این هم درسی است: سرویس ممکن است پارامترِ تو را بپذیرد و اجرا نکند. پس از اینکه خطا نگرفتی نتیجه نگیر که اثر کرده است. برای دیدنِ اثرِ واقعی باید مدلی را در ثابتِ MODEL بگذاری که مستنداتش میگوید temperature را میپذیرد.
اگر روزی با این خانه خطا گرفتی، generationConfig را حذف کن و دوباره بفرست.
✅ وارسی: بالابردنِ
temperatureتنوع را زیاد میکند، ولی درستی را نه — جوابِ خلاقتر همانقدر ممکن است یک ادعای غلط بسازد، با همان لحنِ مطمئن. برای هر سؤالی که جوابش یک واقعیت است (تاریخ، عدد، نام)، خروجی را با یک منبعِ مستقل بسنج، نه با خودِ مدل. سه قانونِ ثابتِ این دوره: «اول خودت فکر کن» — «وارسی کن، خط به خط» — «مدل مطمئن است؛ دلیل نمیشود درست باشد».
۴. طول را هم مهار کن#
generationConfig فقط temperature نیست؛ چند اهرمِ دیگر هم دارد، و یکی از پرکاربردترینهایشان طولِ جواب است. اگر بخواهی جواب از یک حدی بلندتر نشود، یک سقفِ طول کنارِ temperature بگذار:
generationConfig: { temperature: 0.4, maxOutputTokens: 200 }
maxOutputTokens میگوید مدل حداکثر چند token تولید کند — یادت هست از ترم ۱ که token واحدِ کارِ مدل است. این یک ترمز است، نه یک هدف: مدل را وادار نمیکند دقیقاً اینقدر بنویسد، فقط نمیگذارد از آن بلندتر شود. در مدلهای امروزی این سقف tokenهایی را هم میشمارد که مدل پیش از نوشتنِ جواب صرفِ فکرکردن میکند. برای همین تلهاش از چیزی که بهنظر میرسد بزرگتر است:
⚠️ مواظب باش: اگر سقفِ طول را خیلی کم بگذاری، جواب وسطِ جمله بریده میشود، و سرویس کدِ خطا نمیدهد. حتی ممکن است چون سقف صرفِ فکرکردن شده، هیچ متنی نیاید. در این حالت
finishReasonبرابرِMAX_TOKENSاست وpartsوجود ندارد، پس در کدِ این فصل همان خطایCannot read properties of undefinedرا درconsoleمیبینی. اگر جوابها ناتمام یا خالیاند، اول بهmaxOutputTokensشک کن. برای جوابِ کوتاه، راهِ بهتر این است که کوتاهبودن را درsystem_instructionبخواهی. در کدِ این فصل عمداً سقفِ طول را نگذاشتهایم تا جوابِ کامل بگیری؛ اضافهکردنش با توست.
۵. چرا کد، نه زمینِ بازیِ چت#
در ترم ۲ همین کارها را در زمینِ بازیِ چت با اسلایدر و کادر میکردی. پس چه چیزی با کد به دست آوردی؟ سه چیز. اول اینکه تنظیمت میماند: نقش و پارامتر داخلِ فایلِ توست، نه در یک صفحهٔ موقتی که با بستنِ مرورگر پاک میشود. دوم اینکه تکرارپذیر است: هر بازدیدکنندهای که ابزارت را باز کند، دقیقاً همان نقش و همان temperature را میگیرد، بدونِ اینکه خودش چیزی تنظیم کند. سوم اینکه حالا این تنظیم بخشی از یک برنامه است — میتوانی رویش شرط بگذاری، عوضش کنی، و در فصلهای بعد دورش منطق بسازی.
💡 نکته: زمینِ بازیِ چت جای آزمایشکردن است؛ کد جای تثبیتکردن. اول در آزمایشگاه با نقش و
temperatureبازی کن تا ترکیبِ خوب را پیدا کنی، بعد همان را در کد بگذار. این دقیقاً همان حلقهٔ «تکرار و وارسی»ِ ترم ۲ است، حالا با یک خروجیِ ماندگار.
این نسخه هنوز شکننده است: اگر کلید غلط باشد یا اینترنت قطع شود، در console خطا میبینی و صفحه هیچ پیامی نشان نمیدهد. فعلاً همینقدر بدان؛ فصل ۶ همین اپ را با حالتهای انتظار و خطا محکم میکنیم.
واژههای تازهٔ این فصل#
| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| system_instruction | سیستماینستراکشن | خانهای در بدنهٔ درخواست که نقشِ ثابتِ مدل را تعیین میکند، جدا از پیامِ کاربر |
| generationConfig | جنریشنکانفیگ | خانهای در بدنهٔ درخواست برای پارامترهای تولید مثل temperature و طول |
| maxOutputTokens | مکساوتپوتتوکنز | سقفِ تعدادِ tokenهای جواب؛ یک ترمزِ طول، نه یک هدف |
تمرینها
اول خودت فکر کن یا امتحان کن — بعد اینجا را باز کن.
در فصل بعد#
تا اینجا جوابِ مدل یک تکه متن بود که مستقیم روی صفحه مینشست. ولی وقتی یک برنامه میخواهد با جوابِ مدل کار کند — مثلاً از دلش پنج فلشکارتِ جدا بسازد — متنِ آزاد کافی نیست؛ برنامه به ساختار نیاز دارد. فصل بعد یاد میگیری از مدل JSON بگیری، آن را با JSON.parse به دادهٔ واقعی تبدیل کنی، و وقتی خروجی خراب بود، بهجای شکستن یک پیامِ دوستانه نشان بدهی.
به آخر این فصل رسیدی!
اگر ساختی و جواب داد، این دکمه مال توست.