# فصل ۰۳ — اولین فراخوانیِ API از پایتون

<div dir="rtl">

# فصل ۰۳ — اولین فراخوانیِ API از پایتون

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

مدلِ محلیِ فصلِ قبل رایگان و امن است ولی به قدرتِ مدل‌های بزرگ نمی‌رسد. این فصل اولین فراخوانیِ API را انجام می‌دهد. ولی **قبل از** آن، مهم‌ترین قاعدهٔ کارِ با کلید را یاد می‌گیری — و ترتیبش عمدی است: یک کلیدِ لو رفته در یک نوت‌بوکِ اشتراکی خطایی است که هزینهٔ واقعی و گاهی سنگین دارد، و بعد از وقوعش دیگر کاری نمی‌شود کرد جز باطل‌کردنش.

![یک صندوقچهٔ کوچکِ قفل‌دار که کلیدی از آن به دستگاهی می‌رود، بدونِ اینکه خودِ کلید از صندوقچه بیرون بیاید](/lesson-assets/t4-s03-api-key/prompt/01-image-key-vault.png)

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

- کلیدِ API را در Colab Secrets بگذاری و با `userdata.get` بخوانی
- بگویی چرا کلید هرگز نباید داخلِ سلولِ کد نوشته شود
- یک درخواستِ `POST` بفرستی و پاسخِ `JSON` را بخوانی
- خطاهای رایجِ API را از روی کدِ وضعیتشان تشخیص بدهی

## قبل از شروع

**از فصل ۲:** `pipeline` و مقایسه‌اش با خطِ پایه.

**از ترمِ ۱ فصل ۴:** `dict` تودرتو — پاسخِ هر API دقیقاً همین شکل است.

> 📓 **نوت‌بوک:** [نوت‌بوک این فصل را در Colab باز کن](/notebooks/sarnakh/term-4-pretrained-models/session-03-api-key.ipynb) — همهٔ کدهای این فصل آماده و به‌ترتیب داخلش هست.

> ⚠️ **مواظب باش:** این فصل به **اینترنت و کلیدِ رایگانِ خودت** نیاز دارد. بدونِ کلید، کدها اجرا نمی‌شوند — ولی متن را کامل بخوان، چون قاعدهٔ امنیتیِ بخشِ ۱ در همهٔ فصل‌های بعد و در ژرفا برقرار است.

## ۱. کلید هرگز داخلِ کد نمی‌رود

اولین چیزی که هر تازه‌کاری می‌نویسد این است:

</div>

```python-broken
API_KEY = "AIzaSyD-1234567890abcdefghijklmnop"
```

<div dir="rtl">

و این **بدترین** کاری است که می‌شود کرد، به چهار دلیلِ مستقل:

- نوت‌بوک را که با کسی به اشتراک بگذاری، کلیدت را هم داده‌ای.
- در `git` که ذخیره‌اش کنی، کلید **برای همیشه** در تاریخچه می‌ماند — حتی اگر بعداً پاکش کنی.
- خروجیِ سلول‌های ذخیره‌شده هم ممکن است کلید را نشان بدهند.
- ربات‌هایی وجود دارند که مخزن‌های عمومی را برای همین الگوها می‌گردند، و **در چند دقیقه** پیدایش می‌کنند.

راهِ درست در Colab یک ابزارِ آماده دارد: **Secrets**.

1. در نوارِ کناریِ Colab روی نشانِ 🔑 بزن.
2. `+ Add new secret` را انتخاب کن.
3. نام را `GEMINI_API_KEY` بگذار و مقدارش را کلیدِ خودت.
4. کلیدِ `Notebook access` را برای همین نوت‌بوک روشن کن.

حالا در کد:

</div>

```python
# build-notebooks: no-run
from google.colab import userdata

api_key = userdata.get("GEMINI_API_KEY")
print("کلید خوانده شد، طولش:", len(api_key))
```

<div dir="rtl">

</div>

```text-approx
کلید خوانده شد، طولش: 39
```

<div dir="rtl">

**هرگز خودِ کلید را چاپ نکن** — فقط طولش یا چند نویسهٔ اولش را، آن هم فقط برای اطمینان از اینکه خوانده شده.

سه خاصیتِ Secrets که آن را امن می‌کند: کلید در **حسابِ گوگلِ تو** ذخیره می‌شود نه در فایلِ نوت‌بوک؛ هنگامِ اشتراک‌گذاریِ نوت‌بوک **منتقل نمی‌شود**؛ و دسترسیِ هر نوت‌بوک را جداگانه کنترل می‌کنی.

> 📏 **اندازه بگیر:** یک عادتِ عملی که ارزشش را دارد: **هر چند وقت یک بار کلیدت را باطل کن و کلیدِ تازه بساز.** اگر کلیدی جایی لو رفته باشد و ندانی، این تنها کاری است که واقعاً بسته‌اش می‌کند. و اگر روزی سهمیه‌ات ناگهان تمام شد بدونِ اینکه کاری کرده باشی، **اولین فرضت باید لو رفتنِ کلید باشد**، نه باگ.

## ۲. گرفتنِ کلیدِ رایگان

از `aistudio.google.com` با حسابِ گوگلِ خودت وارد شو و یک کلیدِ API بساز. ردهٔ رایگان کارتِ اعتباری نمی‌خواهد.

دو نکتهٔ صادقانه که باید بدانی:

- **ردهٔ رایگان مدل‌های سبک را می‌دهد**، نه پرچم‌دارها. برای یادگیری کاملاً کافی است.
- **متنی که می‌فرستی ممکن است برای بهبودِ محصول استفاده شود.** پس دادهٔ شخصی، محرمانه یا پزشکی داخلش نگذار — همان قاعدهٔ فصلِ ۱.

> ⚠️ **مواظب باش:** سهمیه، نامِ مدل‌ها و شرایطِ ردهٔ رایگان **تغییر می‌کنند**. عمداً هیچ عددی از آن‌ها در این متن ننوشتیم. قبل از شروع، صفحهٔ رسمیِ سرویس را نگاه کن — و اگر جایی در اینترنت عددِ دقیقی دیدی، تاریخش را چک کن.

## ۳. آناتومیِ یک درخواست

هر فراخوانیِ API چهار تکه دارد و همه‌شان را باید بشناسی:

</div>

| تکه | چیست |
|---|---|
| **آدرس** (`endpoint`) | کجا بفرستی — یک `URL` |
| **سرآیند** (`headers`) | اطلاعاتِ جانبی، از جمله **کلید** |
| **بدنه** (`body`) | چیزی که می‌فرستی — معمولاً `JSON` |
| **پاسخ** (`response`) | کدِ وضعیت + `JSON` برگشتی |

<div dir="rtl">

</div>

```python
# build-notebooks: no-run
import requests

URL = "https://generativelanguage.googleapis.com/v1beta/models/gemini-flash-latest:generateContent"

response = requests.post(
    URL,
    headers={"x-goog-api-key": api_key, "Content-Type": "application/json"},
    json={"contents": [{"parts": [{"text": "در یک جمله بگو یادگیری ماشین چیست."}]}]},
    timeout=30,
)

print("کد وضعیت:", response.status_code)
```

<div dir="rtl">

</div>

```text-approx
کد وضعیت: 200
```

<div dir="rtl">

> ✅ **چک کن:** کدِ وضعیت باید `200` باشد. اگر `400` گرفتی ساختارِ درخواست ایراد دارد یا کلیدت معتبر نیست (Gemini برای کلیدِ غلط `400` می‌دهد، نه `401`)، اگر `403` یا `401` گرفتی کلیدت دسترسی ندارد، و اگر `429` گرفتی از سهمیه رد شده‌ای — جدولِ کاملش در بخشِ ۴ همین فصل است.

سه نکتهٔ مهم در همین یک فراخوانی:

- **کلید در `headers` می‌رود، نه در `URL`.** اگر در آدرس بگذاری، در لاگِ سرورها و تاریخچهٔ مرورگر ثبت می‌شود.
- **`timeout=30` را همیشه بگذار.** بدونِ آن، اگر سرور جواب ندهد، سلولت تا ابد منتظر می‌ماند.
- **`json=` به‌جای `data=`** — `requests` خودش تبدیل به `JSON` می‌کند و سرآیندِ درست را می‌گذارد.

## ۴. خواندنِ پاسخ

</div>

```python
# build-notebooks: no-run
payload = response.json()
text = payload["candidates"][0]["content"]["parts"][0]["text"]
print(text)
```

<div dir="rtl">

</div>

```text-approx
یادگیری ماشین یعنی ساختن قاعده‌ها از روی نمونه‌ها، به‌جای نوشتن آن‌ها با دست.
```

<div dir="rtl">

آن زنجیرهٔ `["candidates"][0]["content"]["parts"][0]["text"]` ترسناک به‌نظر می‌رسد ولی دقیقاً همان `dict` و `list` تودرتوی ترمِ ۱ است. **قبل از نوشتنِ چنین زنجیره‌ای، همیشه اول کلِ `payload` را چاپ کن** و ساختارش را ببین — این پنج ثانیه، ده دقیقه حدس‌زدن را حذف می‌کند.

> 🔧 **اگر کار نکرد:** کدهای وضعیت را از بر داشته باش، چون هرکدام معنای کاملاً متفاوتی دارند و راهِ حلِ متفاوتی می‌خواهند:

</div>

| کد | یعنی چه | چه کار کنی |
|---|---|---|
| `200` | موفق | — |
| `400` | بدنهٔ درخواست اشکال دارد، یا در Gemini کلید غلط است | متنِ پیام را بخوان: `API key not valid` یعنی کلید، بقیه یعنی ساختارِ `json=` |
| `401` / `403` | کلید بدونِ دسترسی | کلید را دوباره بساز |
| `404` | نامِ مدل یا آدرس اشتباه است | نامِ مدل را از مستنداتِ رسمی بردار |
| `429` | سهمیه تمام شد | صبر کن — فصلِ ۷ راهِ درستش را می‌گوید |
| `500` / `503` | مشکل از سرورِ آن‌هاست | چند ثانیه بعد دوباره امتحان کن |

<div dir="rtl">

## ۵. یک تابعِ قابلِ‌استفادهٔ مجدد

به‌جای تکرارِ آن بلوک، یک تابع بنویس — همان درسِ ترمِ ۱ فصلِ ۷:

</div>

```python
# build-notebooks: no-run
def ask_model(prompt, timeout=30):
    """یک پرامپت می‌فرستد و متنِ پاسخ را برمی‌گرداند. در خطا پیام را برمی‌گرداند."""
    response = requests.post(
        URL,
        headers={"x-goog-api-key": api_key, "Content-Type": "application/json"},
        json={"contents": [{"parts": [{"text": prompt}]}]},
        timeout=timeout,
    )
    if response.status_code != 200:
        return f"خطا {response.status_code}: {response.text[:200]}"
    payload = response.json()
    return payload["candidates"][0]["content"]["parts"][0]["text"]


print(ask_model("موضوع این جمله چیست؟ فقط یک کلمه بگو: پیاز را با حرارت ملایم سرخ کن."))
```

<div dir="rtl">

</div>

```text-approx
آشپزی
```

<div dir="rtl">

توجه کن تابع **خطا را هم مدیریت می‌کند** و به‌جای شکستن، پیامِ خوانا برمی‌گرداند. در فصلِ ۷ این را کامل‌تر می‌کنیم با تلاشِ دوباره و `cache`.

> 📏 **اندازه بگیر:** حالا ردیفِ چهارمِ جدولِ ترم را پُر کن. همان بیست جمله را با این تابع طبقه‌بندی کن و `accuracy` بگیر. **و قبل از مقایسه، این را بپرس: آیا این عدد ارزشِ فرستادنِ داده به یک سرورِ بیرونی را دارد؟** اگر مدلِ محلیِ فصلِ ۲ عددِ نزدیکی می‌دهد، جوابِ درست ممکن است «نه» باشد. **بهترین عدد همیشه بهترین تصمیم نیست.**

## ۶. یک خطای واقعی: کلیدی که ثبت نشده

</div>

```python-broken
userdata.get("GEMINI_KEY")
```

<div dir="rtl">

</div>

```text
SecretNotFoundError: Secret GEMINI_KEY does not exist.
```

<div dir="rtl">

نامِ راز باید **دقیقاً** همانی باشد که در پنلِ Secrets ثبت کرده‌ای. اینجا `GEMINI_KEY` نوشتیم به‌جای `GEMINI_API_KEY`.

> 🔧 **اگر کار نکرد:** خطای دیگری که همین‌قدر رایج است: `NotebookAccessError`. یعنی راز وجود دارد ولی دسترسیِ **همین نوت‌بوک** به آن روشن نیست. برو به پنلِ 🔑 و کلیدِ کنارِ نامش را روشن کن. این عمدی است — تا نوت‌بوکی که از جای دیگری باز کرده‌ای نتواند بی‌اجازه کلیدهایت را بخواند.

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

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

</div>

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| API key | ای‌پی‌آی کی | کلیدی که هویتِ تو را به سرویس ثابت می‌کند |
| Colab Secrets | کولب سیکرتس | جای امنِ کلید در حسابِ خودت، بیرون از فایلِ نوت‌بوک |
| endpoint | اندپوینت | آدرسی که درخواست به آن فرستاده می‌شود |
| status code | استاتوس کد | عددِ نتیجهٔ درخواست؛ ۲۰۰ موفق، بقیه هرکدام معنایی دارند |

<div dir="rtl">

## تمرین‌ها

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

**تمرینِ اجباری:** تابعِ `ask_model` را با سه پرامپتِ متفاوت امتحان کن و هر بار **طولِ پاسخ** را هم چاپ کن. حالا یک پرامپت بنویس که عمداً خیلی مبهم باشد و یکی که خیلی دقیق. تفاوتِ کیفیتِ پاسخ‌ها را در دو جمله بنویس — این اولین برخوردت با چیزی است که خودآموزِ [هم‌هوش](/courses/hamhoosh) کاملاً به آن می‌پردازد.

**تمرینِ ستاره‌دار ⭐:** تابعِ `ask_model` را طوری تغییر بده که **هرگز کلید را در پیامِ خطا نشان ندهد**، حتی اگر سرور آن را در پاسخِ خطا برگرداند. (راهنمایی: قبل از `return`، هر رخدادِ `api_key` را در متن با ستاره جایگزین کن.) بعد امتحانش کن با یک کلیدِ عمداً غلط. **این الگو در هر کدی که با کلید کار می‌کند لازم است** — پیامِ خطا هم یک راهِ نشتِ کلید است که کمتر کسی به آن فکر می‌کند.

## در فصل بعد

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

</div>

---
Source: https://yaadestan.com/courses/sarnakh/lessons/t4/s03-api-key (یادستان, Yaadestan)
