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

آخر این فصل میتوانی:
- کلیدِ API را در Colab Secrets بگذاری و با
userdata.getبخوانی - بگویی چرا کلید هرگز نباید داخلِ سلولِ کد نوشته شود
- یک درخواستِ
POSTبفرستی و پاسخِJSONرا بخوانی - خطاهای رایجِ API را از روی کدِ وضعیتشان تشخیص بدهی
قبل از شروع#
از فصل ۲: pipeline و مقایسهاش با خطِ پایه.
از ترمِ ۱ فصل ۴: dict تودرتو — پاسخِ هر API دقیقاً همین شکل است.
📓 نوتبوک: نوتبوک این فصل را در Colab باز کن — همهٔ کدهای این فصل آماده و بهترتیب داخلش هست.
⚠️ مواظب باش: این فصل به اینترنت و کلیدِ رایگانِ خودت نیاز دارد. بدونِ کلید، کدها اجرا نمیشوند — ولی متن را کامل بخوان، چون قاعدهٔ امنیتیِ بخشِ ۱ در همهٔ فصلهای بعد و در ژرفا برقرار است.
۱. کلید هرگز داخلِ کد نمیرود#
اولین چیزی که هر تازهکاری مینویسد این است:
API_KEY = "AIzaSyD-1234567890abcdefghijklmnop"
و این بدترین کاری است که میشود کرد، به چهار دلیلِ مستقل:
- نوتبوک را که با کسی به اشتراک بگذاری، کلیدت را هم دادهای.
- در
gitکه ذخیرهاش کنی، کلید برای همیشه در تاریخچه میماند — حتی اگر بعداً پاکش کنی. - خروجیِ سلولهای ذخیرهشده هم ممکن است کلید را نشان بدهند.
- رباتهایی وجود دارند که مخزنهای عمومی را برای همین الگوها میگردند، و در چند دقیقه پیدایش میکنند.
راهِ درست در Colab یک ابزارِ آماده دارد: Secrets.
- در نوارِ کناریِ Colab روی نشانِ 🔑 بزن.
+ Add new secretرا انتخاب کن.- نام را
GEMINI_API_KEYبگذار و مقدارش را کلیدِ خودت. - کلیدِ
Notebook accessرا برای همین نوتبوک روشن کن.
حالا در کد:
# build-notebooks: no-run
from google.colab import userdata
api_key = userdata.get("GEMINI_API_KEY")
print("کلید خوانده شد، طولش:", len(api_key))
کلید خوانده شد، طولش: 39
هرگز خودِ کلید را چاپ نکن — فقط طولش یا چند نویسهٔ اولش را، آن هم فقط برای اطمینان از اینکه خوانده شده.
سه خاصیتِ Secrets که آن را امن میکند: کلید در حسابِ گوگلِ تو ذخیره میشود نه در فایلِ نوتبوک؛ هنگامِ اشتراکگذاریِ نوتبوک منتقل نمیشود؛ و دسترسیِ هر نوتبوک را جداگانه کنترل میکنی.
📏 اندازه بگیر: یک عادتِ عملی که ارزشش را دارد: هر چند وقت یک بار کلیدت را باطل کن و کلیدِ تازه بساز. اگر کلیدی جایی لو رفته باشد و ندانی، این تنها کاری است که واقعاً بستهاش میکند. و اگر روزی سهمیهات ناگهان تمام شد بدونِ اینکه کاری کرده باشی، اولین فرضت باید لو رفتنِ کلید باشد، نه باگ.
۲. گرفتنِ کلیدِ رایگان#
از aistudio.google.com با حسابِ گوگلِ خودت وارد شو و یک کلیدِ API بساز. ردهٔ رایگان کارتِ اعتباری نمیخواهد.
دو نکتهٔ صادقانه که باید بدانی:
- ردهٔ رایگان مدلهای سبک را میدهد، نه پرچمدارها. برای یادگیری کاملاً کافی است.
- متنی که میفرستی ممکن است برای بهبودِ محصول استفاده شود. پس دادهٔ شخصی، محرمانه یا پزشکی داخلش نگذار — همان قاعدهٔ فصلِ ۱.
⚠️ مواظب باش: سهمیه، نامِ مدلها و شرایطِ ردهٔ رایگان تغییر میکنند. عمداً هیچ عددی از آنها در این متن ننوشتیم. قبل از شروع، صفحهٔ رسمیِ سرویس را نگاه کن — و اگر جایی در اینترنت عددِ دقیقی دیدی، تاریخش را چک کن.
۳. آناتومیِ یک درخواست#
هر فراخوانیِ API چهار تکه دارد و همهشان را باید بشناسی:
| تکه | چیست |
|---|---|
آدرس (endpoint) |
کجا بفرستی — یک URL |
سرآیند (headers) |
اطلاعاتِ جانبی، از جمله کلید |
بدنه (body) |
چیزی که میفرستی — معمولاً JSON |
پاسخ (response) |
کدِ وضعیت + JSON برگشتی |
# 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)
کد وضعیت: 200
✅ چک کن: کدِ وضعیت باید
200باشد. اگر400گرفتی ساختارِ درخواست ایراد دارد یا کلیدت معتبر نیست (Gemini برای کلیدِ غلط400میدهد، نه401)، اگر403یا401گرفتی کلیدت دسترسی ندارد، و اگر429گرفتی از سهمیه رد شدهای — جدولِ کاملش در بخشِ ۴ همین فصل است.
سه نکتهٔ مهم در همین یک فراخوانی:
- کلید در
headersمیرود، نه درURL. اگر در آدرس بگذاری، در لاگِ سرورها و تاریخچهٔ مرورگر ثبت میشود. timeout=30را همیشه بگذار. بدونِ آن، اگر سرور جواب ندهد، سلولت تا ابد منتظر میماند.json=بهجایdata=—requestsخودش تبدیل بهJSONمیکند و سرآیندِ درست را میگذارد.
۴. خواندنِ پاسخ#
# build-notebooks: no-run
payload = response.json()
text = payload["candidates"][0]["content"]["parts"][0]["text"]
print(text)
یادگیری ماشین یعنی ساختن قاعدهها از روی نمونهها، بهجای نوشتن آنها با دست.
آن زنجیرهٔ ["candidates"][0]["content"]["parts"][0]["text"] ترسناک بهنظر میرسد ولی دقیقاً همان dict و list تودرتوی ترمِ ۱ است. قبل از نوشتنِ چنین زنجیرهای، همیشه اول کلِ payload را چاپ کن و ساختارش را ببین — این پنج ثانیه، ده دقیقه حدسزدن را حذف میکند.
🔧 اگر کار نکرد: کدهای وضعیت را از بر داشته باش، چون هرکدام معنای کاملاً متفاوتی دارند و راهِ حلِ متفاوتی میخواهند:
| کد | یعنی چه | چه کار کنی |
|---|---|---|
200 |
موفق | — |
400 |
بدنهٔ درخواست اشکال دارد، یا در Gemini کلید غلط است | متنِ پیام را بخوان: API key not valid یعنی کلید، بقیه یعنی ساختارِ json= |
401 / 403 |
کلید بدونِ دسترسی | کلید را دوباره بساز |
404 |
نامِ مدل یا آدرس اشتباه است | نامِ مدل را از مستنداتِ رسمی بردار |
429 |
سهمیه تمام شد | صبر کن — فصلِ ۷ راهِ درستش را میگوید |
500 / 503 |
مشکل از سرورِ آنهاست | چند ثانیه بعد دوباره امتحان کن |
۵. یک تابعِ قابلِاستفادهٔ مجدد#
بهجای تکرارِ آن بلوک، یک تابع بنویس — همان درسِ ترمِ ۱ فصلِ ۷:
# 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("موضوع این جمله چیست؟ فقط یک کلمه بگو: پیاز را با حرارت ملایم سرخ کن."))
آشپزی
توجه کن تابع خطا را هم مدیریت میکند و بهجای شکستن، پیامِ خوانا برمیگرداند. در فصلِ ۷ این را کاملتر میکنیم با تلاشِ دوباره و cache.
📏 اندازه بگیر: حالا ردیفِ چهارمِ جدولِ ترم را پُر کن. همان بیست جمله را با این تابع طبقهبندی کن و
accuracyبگیر. و قبل از مقایسه، این را بپرس: آیا این عدد ارزشِ فرستادنِ داده به یک سرورِ بیرونی را دارد؟ اگر مدلِ محلیِ فصلِ ۲ عددِ نزدیکی میدهد، جوابِ درست ممکن است «نه» باشد. بهترین عدد همیشه بهترین تصمیم نیست.
۶. یک خطای واقعی: کلیدی که ثبت نشده#
userdata.get("GEMINI_KEY")
SecretNotFoundError: Secret GEMINI_KEY does not exist.
نامِ راز باید دقیقاً همانی باشد که در پنلِ Secrets ثبت کردهای. اینجا GEMINI_KEY نوشتیم بهجای GEMINI_API_KEY.
🔧 اگر کار نکرد: خطای دیگری که همینقدر رایج است:
NotebookAccessError. یعنی راز وجود دارد ولی دسترسیِ همین نوتبوک به آن روشن نیست. برو به پنلِ 🔑 و کلیدِ کنارِ نامش را روشن کن. این عمدی است — تا نوتبوکی که از جای دیگری باز کردهای نتواند بیاجازه کلیدهایت را بخواند.
🤖 از دستیارت بپرس: «چه راههایی وجود دارد که یک کلیدِ API ناخواسته لو برود؟ فقط فهرست کن.» جوابش احتمالاً git، اسکرینشات، لاگ، و اشتراکگذاریِ نوتبوک را میآورد. برای هر مورد، بررسی کن که در جریانِ کارِ خودت کدامها ممکناند — و همانها را ببند. این تمرین پنج دقیقه است و یک بار برای همیشه جواب میدهد.
واژههای تازهٔ این فصل#
| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| API key | ایپیآی کی | کلیدی که هویتِ تو را به سرویس ثابت میکند |
| Colab Secrets | کولب سیکرتس | جای امنِ کلید در حسابِ خودت، بیرون از فایلِ نوتبوک |
| endpoint | اندپوینت | آدرسی که درخواست به آن فرستاده میشود |
| status code | استاتوس کد | عددِ نتیجهٔ درخواست؛ ۲۰۰ موفق، بقیه هرکدام معنایی دارند |
تمرینها
اول خودت فکر کن یا امتحان کن — بعد اینجا را باز کن.
در فصل بعد#
مدل جواب میدهد، ولی جوابش متنِ آزاد است و برنامهات نمیتواند رویش حساب کند. فصلِ بعد یاد میگیری از مدل خروجیِ ساختارمند بگیری — JSON با شکلِ مشخص — و مهمتر از آن، اعتبارسنجیاش کنی. چون مدل گاهی قالب را رعایت نمیکند، و برنامهای که این را در نظر نگیرد، در اولین موردِ واقعی میشکند.
به آخر این فصل رسیدی!
اگر ساختی و جواب داد، این دکمه مال توست.