# فصل ۰۴ — نقش و پارامتر در کد

<div dir="rtl">

# فصل ۰۴ — نقش و پارامتر در کد

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

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

![ماشینی که یک بستهٔ درخواست را سرِ هم می‌کند: یک کارتِ نقش در شکافِ بالا می‌نشیند و یک درجهٔ چرخان کنارش میزانِ خلاقیت را تنظیم می‌کند](/lesson-assets/t5-s04-system-in-code/prompt/01-image-role-dial.png)

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

- به مدل از داخلِ کد یک نقشِ ثابت بدهی با `system_instruction`
- با `generationConfig` پارامترِ `temperature` را بفرستی و خلاق‌بودن یا دقیق‌بودنِ جواب را کنترل کنی
- طولِ جواب را هم از همان `generationConfig` مهار کنی
- بگویی چرا تنظیم‌کردن در کد با تنظیم‌کردن در زمینِ بازیِ چت فرق دارد

## قبل از شروع

- **از فصل ۳:** اپِ سادهٔ `دستیارِ من` — یک `<input>` برای کلید، یک `<textarea>` برای سؤال، و `fetch`ی که فقط `contents` را می‌فرستد و جواب را نشان می‌دهد.
- **از فصل‌های ۵ و ۶ ترم ۲:** `system prompt` نقشِ پایدارِ مدل را تعیین می‌کند (فصل ۵)، و `temperature` تعادلِ خلاق در برابر دقیق را جابه‌جا می‌کند (فصل ۶).
- **از ترم ۷ تاروپود (پیش‌نیاز):** `fetch`، `async`/`await` و خواندنِ `res.json()`.

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

> 🧪 **آزمایشگاه:** [آزمایشگاه این فصل را باز کن](/lab/embed/hamhoosh/term-5-building/session-04-system-in-code) — اپِ فصل ۳ آماده است؛ اینجا `system_instruction` و `generationConfig` را خودت اضافه می‌کنی و اثرِ `temperature` را با چشمِ خودت می‌بینی.

## ۱. چرا نقش و پارامتر را در کد بگذاری

بدنهٔ درخواستی که در فصل ۳ فرستادی فقط یک چیز داشت: `contents`، یعنی سؤالِ کاربر. مدل هیچ زمینه‌ای از اینکه «تو کی هستی و چطور باید جواب بدهی» نداشت، پس رفتارِ پیش‌فرضش را انتخاب می‌کرد. برای یک ابزارِ واقعی این کافی نیست. اگر ابزارت قرار است دستیارِ کوتاه‌گو باشد، نمی‌خواهی هر بار امیدوار باشی که مدل حدس بزند کوتاه جواب بدهد؛ می‌خواهی این را **یک‌بار در کد** بگویی و مطمئن باشی هر بار همان‌طور می‌ماند.

درست همان کاری که در زمینِ بازیِ چت با دست می‌کردی، حالا در بدنهٔ JSON انجام می‌شود. دو خانهٔ تازه به بدنه اضافه می‌کنیم: یکی برای نقش (`system_instruction`) و یکی برای پارامترها (`generationConfig`). آدرس و روشِ فرستادن هیچ فرقی نمی‌کند؛ فقط بدنه پُرتر می‌شود.

## ۲. system_instruction: نقشِ ثابت از داخلِ کد

`system_instruction` یک خانهٔ جدا در بدنهٔ درخواست است که نقشِ مدل را تعیین می‌کند — جدا از پیامِ کاربر. مدل قبل از هر جوابی این را می‌خواند، انگار به یک کارمندِ تازه گفته باشی «تو مسئولِ میزِ راهنمایی هستی؛ کوتاه و دقیق جواب بده» و بعد بگذاری مردم سؤال بپرسند. این خانه را کنارِ `contents` می‌گذاری:

</div>

```js
      system_instruction: {
        parts: [{ text: "تو یک دستیارِ فارسی، دقیق و کوتاه‌گو هستی." }]
      },
      contents: [{ parts: [{ text: prompt }] }],
```

<div dir="rtl">

به ساختارش دقت کن: عینِ `contents`، یک شیء با `parts` و یک `text` داخلش. تنها فرقش این است که این متن را **تو** می‌نویسی و ثابت است، ولی متنِ `contents` از سؤالِ کاربر می‌آید. جدا نگه‌داشتنِ نقش از سؤال مهم است: کاربر هر چه بپرسد، نقش سرِ جایش می‌ماند.

> 💡 **نکته:** نقش را کوتاه و مشخص بنویس. «دقیق و کوتاه‌گو» به مدل یک جهتِ روشن می‌دهد؛ «یک دستیارِ خیلی خوب و باهوش باش» چیزی به آن نمی‌گوید که خودش نداند.

## ۳. generationConfig و temperature: کنترلِ خلاقیت

خانهٔ دوم `generationConfig` است — جایی برای پارامترهایی که **چگونگیِ** ساختنِ جواب را تنظیم می‌کنند. مهم‌ترینشان `temperature` است که در ترم ۲ دیدی: عددی پایین یعنی جوابِ محتاط و قابلِ‌پیش‌بینی، عددی بالا یعنی جوابِ متنوع‌تر و خلاق‌تر. برای یک دستیارِ دقیق، عددی پایین می‌گذاریم:

> ⚠️ **مواظب باش:** این اهرم در حالِ کم‌رنگ‌شدن است. مستنداتِ رسمیِ Gemini در زمانِ نوشتنِ این کتاب می‌گوید مدل‌های تازه مقدارِ `temperature` را **نادیده می‌گیرند**، و ممکن است نسخه‌های بعدی آن را با خطا رد کنند. برای همین اینجا آن را یاد می‌گیری چون مفهومش ماندگار است و مدل‌های دیگر هم دارندش، ولی در اپِ نهاییِ فصل ۶ نمی‌گذاریمش. وضعیتِ مدلِ تو **در زمان خواندن چک شود**.

</div>

```js
      contents: [{ parts: [{ text: prompt }] }],
      generationConfig: { temperature: 0.4 }
```

<div dir="rtl">

حالا همه را کنارِ هم بگذار. این `script.js` کاملِ این فصل است — نسبت به فصل ۳ فقط دو خانهٔ `system_instruction` و `generationConfig` به بدنه اضافه شده:

</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";

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;
});
```

<div dir="rtl">

`index.html` و `styles.css` از فصل ۳ عوض نمی‌شوند؛ همان `#key`، `#prompt`، `#ask`، `#status` و `#answer` را داری، و نسخهٔ کاملِ هر دو همان است که در فصل ۳ نوشتی. پس فقط همین `script.js` را جایگزین کن و دو فایلِ دیگر را دست نزن.

> ✅ **چک کن:** یک سؤال بپرس — مثلاً «سه راهِ صرفه‌جویی در آب در خانه؟». حالا جواب باید کوتاه‌تر و منظم‌تر از فصل ۳ باشد، چون نقشِ «کوتاه‌گو» را از `system_instruction` گرفته. اگر جوابِ بلندِ پُرحرف گرفتی، احتمالاً `system_instruction` را جای درستی — کنارِ `contents`، داخلِ همان شیءِ `JSON.stringify` — نگذاشته‌ای.

حالا اثرِ `temperature` را امتحان کن. اول با همین `0.4` یک **سؤالِ باز** را دو بارِ پشتِ‌هم بفرست، مثلاً «یک اسمِ بامزه برای یک ربات پیشنهاد بده»، و دو جواب را یادداشت کن. بعد عدد را به یک عددِ بالا ببر:

</div>

```js
      generationConfig: { temperature: 1.9 }
```

<div dir="rtl">

اول حدس بزن با عددِ بالا چه می‌شود، بعد همان سؤال را دو بارِ دیگر بفرست.

روی مدلی که `temperature` را اجرا می‌کند، با عددِ بالا جواب‌ها از هم دورتر و گاهی عجیب‌تر می‌شوند، و با عددِ پایین به هم نزدیک‌تر می‌مانند. روی مدلی که آن را نادیده می‌گیرد هیچ خطایی نمی‌بینی و دو دسته جواب فرقِ معناداری ندارند، چون عددی که فرستادی بی‌صدا کنار گذاشته شده. این هم درسی است: **سرویس ممکن است پارامترِ تو را بپذیرد و اجرا نکند.** پس از اینکه خطا نگرفتی نتیجه نگیر که اثر کرده است. برای دیدنِ اثرِ واقعی باید مدلی را در ثابتِ `MODEL` بگذاری که مستنداتش می‌گوید `temperature` را می‌پذیرد.

اگر روزی با این خانه خطا گرفتی، `generationConfig` را حذف کن و دوباره بفرست.

> ✅ **وارسی:** بالابردنِ `temperature` تنوع را زیاد می‌کند، ولی درستی را نه — جوابِ خلاق‌تر همان‌قدر ممکن است یک ادعای غلط بسازد، با همان لحنِ مطمئن. برای هر سؤالی که جوابش یک **واقعیت** است (تاریخ، عدد، نام)، خروجی را با یک منبعِ مستقل بسنج، نه با خودِ مدل. سه قانونِ ثابتِ این دوره: **«اول خودت فکر کن» — «وارسی کن، خط به خط» — «مدل مطمئن است؛ دلیل نمی‌شود درست باشد».**

## ۴. طول را هم مهار کن

`generationConfig` فقط `temperature` نیست؛ چند اهرمِ دیگر هم دارد، و یکی از پرکاربردترین‌هایشان طولِ جواب است. اگر بخواهی جواب از یک حدی بلندتر نشود، یک سقفِ طول کنارِ `temperature` بگذار:

</div>

```js
      generationConfig: { temperature: 0.4, maxOutputTokens: 200 }
```

<div dir="rtl">

`maxOutputTokens` می‌گوید مدل حداکثر چند `token` تولید کند — یادت هست از ترم ۱ که `token` واحدِ کارِ مدل است. این یک ترمز است، نه یک هدف: مدل را وادار نمی‌کند دقیقاً این‌قدر بنویسد، فقط نمی‌گذارد از آن بلندتر شود. در مدل‌های امروزی این سقف `token`هایی را هم می‌شمارد که مدل پیش از نوشتنِ جواب صرفِ فکرکردن می‌کند. برای همین تله‌اش از چیزی که به‌نظر می‌رسد بزرگ‌تر است:

> ⚠️ **مواظب باش:** اگر سقفِ طول را خیلی کم بگذاری، جواب وسطِ جمله **بریده** می‌شود، و سرویس کدِ خطا نمی‌دهد. حتی ممکن است چون سقف صرفِ فکرکردن شده، هیچ متنی نیاید. در این حالت `finishReason` برابرِ `MAX_TOKENS` است و `parts` وجود ندارد، پس در کدِ این فصل همان خطای `Cannot read properties of undefined` را در `console` می‌بینی. اگر جواب‌ها ناتمام یا خالی‌اند، اول به `maxOutputTokens` شک کن. برای جوابِ کوتاه، راهِ بهتر این است که کوتاه‌بودن را در `system_instruction` بخواهی. در کدِ این فصل عمداً سقفِ طول را نگذاشته‌ایم تا جوابِ کامل بگیری؛ اضافه‌کردنش با توست.

## ۵. چرا کد، نه زمینِ بازیِ چت

در ترم ۲ همین کارها را در زمینِ بازیِ چت با اسلایدر و کادر می‌کردی. پس چه چیزی با کد به دست آوردی؟ سه چیز. اول اینکه تنظیمت **می‌ماند**: نقش و پارامتر داخلِ فایلِ توست، نه در یک صفحهٔ موقتی که با بستنِ مرورگر پاک می‌شود. دوم اینکه **تکرارپذیر** است: هر بازدیدکننده‌ای که ابزارت را باز کند، دقیقاً همان نقش و همان `temperature` را می‌گیرد، بدونِ اینکه خودش چیزی تنظیم کند. سوم اینکه حالا این تنظیم بخشی از یک **برنامه** است — می‌توانی رویش شرط بگذاری، عوضش کنی، و در فصل‌های بعد دورش منطق بسازی.

> 💡 **نکته:** زمینِ بازیِ چت جای **آزمایش‌کردن** است؛ کد جای **تثبیت‌کردن**. اول در آزمایشگاه با نقش و `temperature` بازی کن تا ترکیبِ خوب را پیدا کنی، بعد همان را در کد بگذار. این دقیقاً همان حلقهٔ «تکرار و وارسی»ِ ترم ۲ است، حالا با یک خروجیِ ماندگار.

این نسخه هنوز شکننده است: اگر کلید غلط باشد یا اینترنت قطع شود، در `console` خطا می‌بینی و صفحه هیچ پیامی نشان نمی‌دهد. فعلاً همین‌قدر بدان؛ فصل ۶ همین اپ را با حالت‌های انتظار و خطا محکم می‌کنیم.

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

</div>

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| system_instruction | سیستم‌اینستراکشن | خانه‌ای در بدنهٔ درخواست که نقشِ ثابتِ مدل را تعیین می‌کند، جدا از پیامِ کاربر |
| generationConfig | جنریشن‌کانفیگ | خانه‌ای در بدنهٔ درخواست برای پارامترهای تولید مثل `temperature` و طول |
| maxOutputTokens | مکس‌اوت‌پوت‌توکنز | سقفِ تعدادِ `token`های جواب؛ یک ترمزِ طول، نه یک هدف |

<div dir="rtl">

## تمرین‌ها

**تمرین اجباری:** متنِ `system_instruction` را عوض کن و به مدل یک نقشِ کاملاً متفاوت بده — مثلاً «تو یک معلمِ مهربانِ ریاضی هستی که هر جواب را با یک مثالِ ساده توضیح می‌دهی». بعد همان سؤالی را بپرس که با نقشِ قبلی پرسیده بودی و در یک جمله بنویس چه چیزی در لحن و شکلِ جواب عوض شد.

**تمرین ستاره‌دار ⭐:** یک سؤالِ **واقعی‌محور** بساز که جوابش یک عددِ مشخص است (مثلاً «فاصلهٔ زمین تا ماه چند کیلومتر است؟»). یک‌بار با `temperature` پایین و یک‌بار با `temperature` بالا بپرس. آیا عددِ برگشتی فرق کرد؟ جوابِ هر دو را با یک منبعِ مستقل تطبیق بده و بنویس: بالابردنِ `temperature` جواب را «درست‌تر» کرد یا فقط «متنوع‌تر»؟ اگر مدلت `temperature` را نادیده می‌گیرد، این را هم در جوابت بنویس.

## در فصل بعد

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

</div>

---
Source: https://yaadestan.com/courses/hamhoosh/lessons/t5/s04-system-in-code (یادستان, Yaadestan)
