# فصل ۰۲ — اولین فراخوانی

<div dir="rtl">

# فصل ۰۲ — اولین فراخوانی

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

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

![یک پاکتِ درخواست که در برشِ آموزشی نشان داده شده و داخلش جعبه‌هایی تودرتو دارد؛ پاکت به دهانهٔ یک موتورِ مدل می‌رود و یک کارتِ پاسخ با همان ساختارِ تودرتو از سمتِ دیگر بیرون می‌آید](/lesson-assets/t5-s02-first-call/prompt/01-image-request-response.png)

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

- ساختارِ یک درخواستِ `API` را بخوانی: چه چیزی داخلِ بدنه می‌رود
- پاسخِ خامِ مدل را بشناسی و بفهمی چرا تودرتوست
- متنِ جواب را از مسیرِ `candidates[0].content.parts[0].text` بیرون بکشی
- بگویی ردهٔ رایگانِ Gemini چه محدودیت‌هایی دارد و چرا با کلیدِ خودت کار می‌کنی

## قبل از شروع

- **از فصل ۱ همین ترم:** `API`، `API key`، و اینکه کلید مالِ خودت است (`BYOK`).
- **از تاروپود (ترم ۷، فصل ۸):** `JSON` — قالبِ متنیِ داده که به مقدار، آرایه و شیء تبدیل می‌شود و با نقطه و شماره خوانده می‌شود. اگر تاروپود را نگذرانده‌ای، همین‌قدر بدان که `JSON` یعنی «داده‌ای که مثلِ جعبه‌های تودرتو ساخت‌یافته است».

> 🧪 **آزمایشگاه:** [آزمایشگاه این فصل را باز کن](/lab/embed/hamhoosh/term-5-building/session-02-first-call) و همان درخواستِ نمونه‌ای را که پایین می‌بینی بفرست، بعد پاسخِ خام را نگاه کن — قبل از اینکه برنامه آن را زیبا کند. هدف این است که ساختار را با چشمِ خودت ببینی.

## ۱. یک فراخوانی از دور چه شکلی است

هر فراخوانیِ `API` سه تکه دارد: **کجا** می‌فرستی، **چه** می‌فرستی، و **چه** برمی‌گردد.

«کجا» یک آدرسِ اینترنتی است به‌اسمِ `endpoint` — درست مثلِ آدرسِ یک صفحهٔ وب، ولی به‌جای صفحه، داده پس می‌دهد. `endpoint`ِ Gemini آدرسِ مدل است، و کلیدِ تو هم همراهِ همین درخواست می‌رود تا سرویس بداند چه کسی صدا زده.

«چه می‌فرستی» یک **بدنهٔ درخواست** است، نوشته‌شده به `JSON`. «چه برمی‌گردد» هم یک `JSON`ِ دیگر است: **پاسخِ خام**. کلِ کاری که برنامه‌ات می‌کند این است: بدنه را درست بساز، بفرست، و از پاسخِ خام متنِ جواب را بیرون بکش. بیا هر دو تکه را با یک مثالِ واقعی ببینیم.

## ۲. بدنهٔ درخواست: `prompt`ِ تو، بسته‌بندی‌شده

فرض کن می‌خواهی بپرسی «پایتختِ ژاپن کجاست؟». در درِ `chat` فقط تایپش می‌کردی. در درِ `API` باید همان جمله را در یک ساختارِ مشخص بگذاری تا سرویس بفهمدش. ساده‌ترین بدنهٔ ممکن این است:

</div>

```json
{
  "contents": [
    { "parts": [{ "text": "پایتختِ ژاپن کجاست؟" }] }
  ]
}
```

<div dir="rtl">

از بیرون به داخل بخوانش: `contents` فهرستِ چیزهایی است که می‌فرستی؛ هر تکه `parts` دارد؛ و هر part یک `text` دارد که همان `prompt`ِ توست. چرا این‌قدر تودرتو؟ چون همین ساختار بعداً جا دارد برای چیزهای بیشتر — چند پیامِ پشتِ‌هم، یا حتی یک تصویر کنارِ متن. فعلاً فقط یک `text` داریم و همین کافی است.

نکته این است که `prompt`ِ تو گم نشده؛ فقط لای چند لایه بسته‌بندی شده تا برنامه بتواند دقیق بگوید کجای پیام کدام است.

## ۳. پاسخِ خام: جواب کجا پنهان است

سرویس جواب را هم به همان سبکِ تودرتو برمی‌گرداند. هستهٔ پاسخِ خام این است:

</div>

```json
{
  "candidates": [
    {
      "content": {
        "parts": [
          { "text": "پایتختِ ژاپن، توکیو است." }
        ]
      }
    }
  ]
}
```

<div dir="rtl">

متنی که می‌خواهی — «پایتختِ ژاپن، توکیو است.» — همان تهِ این جعبه‌های تودرتوست. چرا مدل جواب را این‌قدر بسته‌بندی می‌کند؟ چون `candidates` یعنی «نامزدهای جواب»: مدل می‌تواند بیش از یک جوابِ ممکن برگرداند، پس آن‌ها را در یک فهرست می‌گذارد. جوابِ اول نامزدِ شمارهٔ صفر است.

برای رسیدن به متن، لایه‌به‌لایه پایین می‌روی: اولین نامزد، بعد `content`ِ آن، بعد `parts`ِ آن، بعد اولین part، بعد `text`ِ آن. در کدِ فصلِ بعد این مسیر دقیقاً این‌طور نوشته می‌شود:

</div>

```text
candidates[0].content.parts[0].text
```

<div dir="rtl">

این تنها تکه‌ای است که این فصل باید در ذهنت بماند: مسیرِ رسیدن به جوابِ واقعی. `[0]` یعنی «اولی» — همان‌طور که در تاروپود آرایه‌ها را با شماره می‌خواندی، اینجا هم اولین عضو شمارهٔ صفر است.

**قبل از ادامه، جواب بده:** اگر بخواهی متنِ جواب را در برنامه‌ات نشان بدهی، از کدام مسیرِ داخلِ پاسخِ خام باید بخوانی‌اش؟

## ۴. ردهٔ رایگانِ Gemini: چه می‌گیری، چه نمی‌گیری

سرویسی که استفاده می‌کنیم یک **ردهٔ رایگان** دارد که برای یاد گرفتن و ساختنِ یک ابزارِ شخصی کافی است. ولی رایگان یعنی چند مرز:

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

</div>

| چیزی که عوض می‌شود | کجا چکش کنی |
|---|---|
| سقفِ تعدادِ درخواست در دقیقه/روز | مستنداتِ رسمیِ Gemini API — در زمان خواندن چک شود |
| کدام مدل‌ها در ردهٔ رایگان‌اند | مستنداتِ رسمیِ Gemini API — در زمان خواندن چک شود |

<div dir="rtl">

## ۵. جوابِ خام هم می‌تواند مطمئن ولی غلط باشد

مهم‌ترین درسِ کلِ دوره اینجا هم صادق است: اینکه جواب از `API` و در قالبِ تمیزِ `JSON` می‌آید، ذره‌ای درست‌ترش نمی‌کند. `API` فقط لولهٔ انتقال است؛ همان مدلِ ممکن‌الخطای همیشگی آن‌طرفِ لوله نشسته.

بیا یک مثالِ واقعی و قابلِ‌امتحان را با هم ببینیم. این را به‌عنوانِ `text` در `request` بگذار و بفرست:

</div>

```text
حاصلِ ۲۳۴۷ × ۸۹۶۱ چند است؟ فقط عدد را بگو.
```

<div dir="rtl">

جوابی که در `candidates[0].content.parts[0].text` می‌نشیند ممکن است چیزی شبیهِ این باشد. این یک نمونه است و عددِ تو ممکن است فرق کند:

</div>

```text
۲۰۹۹۹۶۷۱
```

<div dir="rtl">

در این نمونه قالب تمیز و لحن مطمئن است، و عدد غلط است. جوابِ درست ۲۱۰۳۱۴۶۷ است. مدل یک عددِ درست‌نما ساخت، نه یک محاسبهٔ درست؛ و `API` هم بی‌سروصدا همان را در یک `JSON`ِ بی‌عیب تحویلت داد.

بهترین کاری که می‌توانی همین‌جا بکنی این است: **همان `request` را سه بار پشتِ‌سرِهم بفرست.** یک ماشین‌حساب هر سه بار یک عدد می‌دهد. مدل ممکن است چند عددِ نزدیک ولی متفاوت بدهد. مدلِ تو شاید هر سه بار درست بزند؛ آن هم چیزی را ثابت نمی‌کند، چون روی کاغذ معلوم نیست این بار کجا غلط می‌زند. اگر داری برنامه‌ای می‌نویسی که رویِ این عدد حساب می‌کند، همین‌جا فهمیدی که نباید.

> ✅ **وارسی:** این را با خودِ مدل «تأیید» نکن — که اگر بپرسی «مطمئنی؟» شاید باز هم اشتباهش را با اطمینان تکرار کند. خودت یک قدمِ مستقل بردار: همان ضرب را در ماشین‌حساب بزن. سه قانونِ ثابتِ این دوره دقیقاً برای همین لحظه‌اند: **«اول خودت فکر کن» — «وارسی کن، خط به خط» — «مدل مطمئن است؛ دلیل نمی‌شود درست باشد».** قالبِ مرتبِ `JSON` هیچ تضمینی برای درستیِ محتوا نیست.

> 💡 **نکته:** آن «فقط عدد را بگو» عمدی است و خودش یک درسِ مهندسی دارد. اگر همین ضرب را بدونِ آن قید بفرستی، مدل معمولاً ضرب را ستون‌به‌ستون می‌نویسد و اغلب به جوابِ درست می‌رسد. یعنی خروجیِ کوتاه‌تر و تمیزتر — که در کد همیشه راحت‌تر است — می‌تواند دقیقاً همان چیزی باشد که دقت را پایین می‌آورد. این بده‌بستان را در طراحیِ هر برنامه‌ای یادت باشد، و برای هر حسابی که واقعاً مهم است، خودِ کدت حساب کند نه مدل.

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

</div>

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| endpoint | اِندپوینت | آدرسِ اینترنتیِ سرویس که به‌جای صفحه، داده پس می‌دهد |
| request / response | ریکوئست / رِسپانس | آنچه برنامه می‌فرستد / آنچه سرویس برمی‌گرداند |
| candidates | کَندیدِیتس | فهرستِ نامزدهای جواب در پاسخِ خام؛ اولی شمارهٔ صفر است |

<div dir="rtl">

## تمرین‌ها

**تمرین اجباری:** بدنهٔ درخواستِ نمونهٔ بخشِ ۲ را بردار و `text` داخلِ `contents` را به یک سؤالِ دلخواهِ خودت عوض کن (فقط روی کاغذ یا در آزمایشگاه، نه در کد — هنوز کد نداریم). بعد در پاسخِ خامِ بخشِ ۳، با انگشت مسیرِ `candidates[0].content.parts[0].text` را لایه‌به‌لایه دنبال کن تا به متنِ جواب برسی، و کنارِ هر لایه بنویس آن لایه چه‌کار می‌کند.

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

## در فصل بعد

حالا شکلِ کاملِ یک فراخوانی را می‌شناسی: بدنه را می‌سازی، می‌فرستی، و متن را از مسیرِ `candidates[0].content.parts[0].text` بیرون می‌کشی. فصلِ بعد این را برای اولین بار **زنده** می‌کنیم: با `fetch` (که از تاروپود قرض می‌گیریم) همین درخواست را از JavaScript می‌فرستیم و جواب را روی یک صفحهٔ واقعی نشان می‌دهیم — و کلید را طبقِ `BYOK` از یک کادرِ ورودی می‌خوانیم، نه از کد.

</div>

---
Source: https://yaadestan.com/courses/hamhoosh/lessons/t5/s02-first-call (یادستان, Yaadestan)
