سرنخ — خودآموز پایتون و برنامه‌نویسی برای هوش مصنوعی (مقدماتی)

فصل ۳ از ۸

پیشرفت ترم
۰٪

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

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

یک صندوقچهٔ کوچکِ قفل‌دار که کلیدی از آن به دستگاهی می‌رود، بدونِ اینکه خودِ کلید از صندوقچه بیرون بیاید

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

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

قبل از شروع#

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

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

📓 نوت‌بوک: نوت‌بوک این فصل را در Colab باز کن — همهٔ کدهای این فصل آماده و به‌ترتیب داخلش هست.

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

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

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

API_KEY = "AIzaSyD-1234567890abcdefghijklmnop"

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

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

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

  1. در نوارِ کناریِ Colab روی نشانِ 🔑 بزن.
  2. + Add new secret را انتخاب کن.
  3. نام را GEMINI_API_KEY بگذار و مقدارش را کلیدِ خودت.
  4. کلیدِ 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 با شکلِ مشخص — و مهم‌تر از آن، اعتبارسنجی‌اش کنی. چون مدل گاهی قالب را رعایت نمی‌کند، و برنامه‌ای که این را در نظر نگیرد، در اولین موردِ واقعی می‌شکند.

به آخر این فصل رسیدی!

اگر ساختی و جواب داد، این دکمه مال توست.