هم‌هوش — خودآموز هوش مصنوعی

فصل ۷ از ۸

پیشرفت ترم
۰٪

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

در فصل ۶ سه نگهبان را در اپت گذاشتی و از کنارِ بعضی‌هایشان سریع رد شدی. وقتی زیادی پشتِ‌هم سؤال بفرستی، وقتی کلید را غلط بزنی، وقتی اینترنت قطع باشد، اپِ خام یا با یک خطای زشت می‌ترکد یا بی‌صدا هیچ نمی‌کند. این فصل کدِ تازه‌ای اضافه نمی‌کند؛ همان نگهبان‌ها را یکی‌یکی باز می‌کند و عمداً خرابشان می‌کند تا بفهمی هر کدام چرا آنجاست. در راهش دو چیز را می‌فهمی — اینکه چرا سرویس‌ها جلوی درخواستِ بی‌حد را می‌گیرند (rate limit)، و چرا کلید مالِ خودِ توست.

یک شیرِ تنظیم که از مخزنی بالای خود آب می‌گیرد و آن را با جریانی آرام و برابر بینِ چند فنجانِ کوچک پخش می‌کند

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

  • بگویی rate limit چیست و چرا هر سرویسی آن را دارد
  • خطای پرشدنِ سهمیه (res.status === 429) را با یک پیامِ دوستانه مهار کنی
  • کلیدِ غلط و اینترنتِ قطع را هم بی‌آنکه اپ بترکد مدیریت کنی
  • توضیح بدهی چرا سهمیه و امنیت هر دو یعنی کلید مالِ خودِ کاربر است

قبل از شروع#

  • از فصل ۶ همین ترم: اپِ «دستیارِ من» که ساختی — index.html، script.js و styles.css — با try/catch و حالتِ انتظار و دکمهٔ disabled.
  • از فصل ۱ همین ترم: الگوی BYOK و اینکه کلید مالِ خودِ کاربر است.
  • از تاروپود (ترم ۷، فصل ۸): res.ok و res.status — جوابِ سرور همیشه «سالم» نیست، و کد یک عدد دارد که می‌گوید چه شد.

لوازم مثلِ همیشه: یک مرورگر و کلیدِ رایگانِ خودت.

۱. چرا سرور جلویت را می‌گیرد: rate limit#

فرض کن یک آبخوریِ عمومیِ رایگان هست. هر کسی می‌تواند بنوشد، ولی اگر یک نفر شلنگ بردارد و بخواهد کلِ مخزن را برای خودش خالی کند، برای بقیه چیزی نمی‌ماند. برای همین یک شیر می‌گذارند که فقط یک جریانِ معقول رد کند. سرویسِ API هم دقیقاً همین کار را می‌کند: به هر کلید اجازه می‌دهد در یک بازهٔ زمانی فقط تا تعدادِ مشخصی درخواست بفرستد. به این سقف می‌گویند rate limit.

دو دلیل دارد. اول انصاف: منابعِ سرویس محدود است و نباید یک کاربر همه را بردارد. دوم هزینه: هر فراخوانیِ مدل برای سرویس پول و انرژی دارد، پس ردهٔ رایگان یک سقف می‌گذارد تا رایگان بماند. عددِ دقیقِ این سقف مدام عوض می‌شود و به نوعِ کلید بستگی دارد — برای همین اینجا نمی‌نویسمش؛ هر وقت لازم شد، در مستنداتِ رسمیِ سرویس چکش کن.

عددِ سقف فرّار است، ولی خودِ پدیده پایدار است: هر سرویسی یک rate limit دارد، پس هر اپِ جدی باید بلد باشد وقتی به آن سقف خورد، آبرومندانه رفتار کند. این کارِ بخشِ بعد است.

۲. کدِ ۴۲۹: وقتی سهمیه پر می‌شود#

از تاروپود یادت هست که هر جوابِ سرور یک کدِ وضعیت دارد: عددی که می‌گوید چه شد. res.ok وقتی true است که این کد در محدودهٔ سالم باشد. یک کدِ خاص هست که دقیقاً یعنی «زیادی فرستادی و زیادی سریع؛ سهمیه‌ات پر شد»: عددِ 429. این یک عددِ فرّارِ سهمیه نیست — یک کدِ استانداردِ وب است که همه‌جا همین معنا را دارد.

اگر این کد را نادیده بگیری، اپ می‌رود سراغِ خواندنِ جواب، جوابی که نیست، و با یک خطای زشت می‌ترکد. پس قبل از هر کارِ دیگری، همین یک حالت را جدا می‌گیری. این همان تکه‌ای است که در اپِ فصل ۶ درست بعد از fetch نشسته است:

if (res.status === 429) {
  status.textContent = "سهمیهٔ الان تمام شد؛ کمی بعد دوباره امتحان کن.";
  return;
}

res.status همان عددِ کدِ وضعیت است. اگر 429 بود، یک پیامِ آدمیزاد نشان می‌دهیم و با return همان‌جا بیرون می‌زنیم — نه خطای قرمز، نه صفحهٔ شکسته. کاربر می‌فهمد فقط باید کمی صبر کند.

✅ چک کن: پرشدنِ واقعیِ سهمیه را نمی‌شود به‌دلخواه ساخت، پس موقتاً کد را عوض کن تا پیام را ببینی: به‌جای 429 بنویس 200 (کدِ جوابِ سالم). حالا یک سؤالِ معمولی بپرس — چون جوابِ سالم کدِ 200 دارد، پیامِ «سهمیهٔ الان تمام شد» ظاهر می‌شود. یعنی مسیر کار می‌کند. حالا 200 را برگردان به 429 تا اپ درست شود.

۳. کلیدِ غلط و اینترنتِ قطع#

سهمیه یک راهِ خراب‌شدن بود؛ دو تای دیگر هم هست. کلیدِ غلط: اگر کلید را اشتباه تایپ کنی، سرور جواب می‌دهد ولی جوابش «تو را نمی‌شناسم» است — یک کدِ ناسالمِ دیگر، نه 429. این را با res.ok می‌گیری: اگر جواب سالم نبود، به‌جای خواندنش، کد را نشان بده.

if (!res.ok) {
  status.textContent = "خطا از سرور: " + res.status;
  return;
}

اینترنتِ قطع: اینجا اصلاً جوابی نمی‌آید و خودِ fetch شکست می‌خورد. این را نه با if، که با try/catch می‌گیری — همان جفتی که از تاروپود می‌شناسی: هر چیزی داخلِ try بترکد، به‌جای شکستنِ صفحه می‌پری داخلِ catch.

} catch (e) {
  status.textContent = "در اینترنت یا کلیدت مشکلی هست؛ دوباره امتحان کن.";
} finally {
  askBtn.disabled = false;
}

و finally تضمین می‌کند دکمه در هر حالت — چه موفق، چه خطا — دوباره فعال شود، تا اپ قفل نکند.

✅ چک کن: یک بار کلید را عمداً غلط بزن و بپرس؛ باید پیامِ «خطا از سرور» با یک عدد را ببینی، نه صفحهٔ شکسته. بعد اینترنتت را قطع کن و دوباره بپرس؛ این‌بار پیامِ catch می‌آید. در هر دو حالت دکمه دوباره فعال است و می‌توانی دوباره امتحان کنی.

اینجا خوب است یک قدم بایستی و از دستیارت کمک بگیری — ولی با احتیاط:

✅ وارسی: کدِ وضعیت یا خطای قرمزِ console را کپی کن و از دستیارِ هوش مصنوعی‌ات بپرس «این خطا یعنی چه و چطور مهارش کنم؟». جوابش معمولاً مسیر را نشان می‌دهد، ولی گاهی با اطمینان یک عددِ دقیقِ سهمیه یا یک زمانِ صبرِ مشخص می‌گوید که از خودش ساخته — همان عددِ فرّار. آن عدد را باور نکن؛ فقط در مستنداتِ رسمی چکش کن. سه قانونِ ثابتِ این دوره: «اول خودت فکر کن» — «وارسی کن، خط به خط» — «مدل مطمئن است؛ دلیل نمی‌شود درست باشد».

۴. چرا کلید مالِ خودِ توست#

حالا که سهمیه را دیدی، دلیلِ BYOK (فصلِ ۱) ملموس‌تر می‌شود. rate limit و هزینه به کلید بسته‌اند، نه به اپ. یعنی وقتی اپت را با کلیدِ خودت می‌سازی و بعد (فصلِ بعد) منتشرش می‌کنی، هر کسی که بازش کند کلیدِ خودش را می‌گذارد، پس سهمیه و هزینهٔ هر کس مالِ خودش است — نه اینکه صدها بازدیدکننده سهمیهٔ تو را یک‌جا خالی کنند.

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

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

کدِ کاملِ سخت‌شده#

سه گاردی که باز کردیم، یعنی 429، !res.ok و try/catch، همه سرِ جای خودشان در اپِ فصل ۶ نشسته‌اند. پس script.js این فصل با فصلِ قبل یکی است، و اگر ترفندِ 200 را برگردانده باشی چیزی برای تغییر نمانده است. index.html و styles.css هم همان‌اند. برای مرور، کلِ فایل این است:

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

const askBtn = document.querySelector("#ask");

askBtn.addEventListener("click", async function () {
  const key = document.querySelector("#key").value.trim();
  const prompt = document.querySelector("#prompt").value.trim();
  const status = document.querySelector("#status");
  const answer = document.querySelector("#answer");

  answer.textContent = "";
  if (key === "" || prompt === "") {
    status.textContent = "کلید و سؤال را بگذار.";
    return;
  }
  status.textContent = "در حالِ فکر کردن…";
  askBtn.disabled = true;

  try {
    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 }] }]
      })
    });

    if (res.status === 429) {
      status.textContent = "سهمیهٔ الان تمام شد؛ کمی بعد دوباره امتحان کن.";
      return;
    }
    if (!res.ok) {
      status.textContent = "خطا از سرور: " + res.status;
      return;
    }

    const data = await res.json();
    const text = data.candidates[0].content.parts[0].text;
    status.textContent = "";
    answer.textContent = text;
  } catch (e) {
    status.textContent = "در اینترنت یا کلیدت مشکلی هست؛ دوباره امتحان کن.";
  } finally {
    askBtn.disabled = false;
  }
});

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

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

کلمه تلفظ به حروف فارسی یعنی چه
rate limit رِیت لیمیت سقفِ تعدادِ درخواست در یک بازهٔ زمانی که سرویس روی هر کلید می‌گذارد
429 چهارصد و بیست‌ونه کدِ وضعیتِ استانداردِ وب برای «سهمیه‌ات پر شد»
res.status رِس دات استاتوس عددِ کدِ وضعیتِ جوابِ سرور

تمرین‌ها

اول خودت فکر کن یا امتحان کن — بعد اینجا را باز کن.

در فصل بعد#

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

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

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