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

فصل ۳ از ۸

پیشرفت ترم
۰٪

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

دو فصلِ اول را روی کاغذ فهمیدی؛ این فصل برای اولین بار زنده‌اش می‌کنی. یک صفحهٔ وبِ کوچک می‌سازی — «دستیارِ من» — که یک کادرِ کلید دارد، یک کادرِ سؤال، و یک دکمه. دکمه را که بزنی، برنامه‌ات با fetch مدل را از درِ API صدا می‌زند، متنِ جواب را از پاسخِ خام بیرون می‌کشد، و روی همان صفحه نشانش می‌دهد. و مهم‌تر از همه: کلید را از کادرِ ورودی می‌خوانی، نه از کد — دقیقاً همان الگوی BYOKِ فصل ۱.

یک برشِ آموزشی از یک کارتِ ابزارِ تک‌صفحه‌ای که بالایش یک شکافِ کلید دارد، پایینش یک کادرِ متن، و یک بازوی مکانیکی که سؤال را به یک موتورِ مدل می‌رساند و متنِ جواب را برمی‌گرداند؛ کلید داخلِ شکافِ خودِ کارت می‌ماند

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

  • یک صفحهٔ وب بسازی که با fetch مدل را از کد صدا می‌زند
  • کلید را طبقِ BYOK از یک کادرِ ورودی بخوانی، نه از داخلِ کد
  • بدنهٔ درخواست را با method، headers و body و JSON.stringify برای POST بسازی — یک قدمِ کوچکِ تازه روی fetchِ تاروپود
  • متنِ جواب را از مسیرِ candidates[0].content.parts[0].text روی صفحه نشان بدهی

قبل از شروع#

  • از فصل ۱ و ۲ همین ترم: API، API key، الگوی BYOK، و مسیرِ candidates[0].content.parts[0].text.
  • از تاروپود (ترم ۷، فصل ۸) — پیش‌نیازِ اعلام‌شده: fetch، async/await. این‌ها را اینجا از نو و عمیق آموزش نمی‌دهیم؛ فقط کوتاه یادآوری می‌کنیم و به‌کارشان می‌بریم. اگر تاروپود را نگذرانده‌ای، بخشِ ۲ برایت یک مرورِ فشرده است.

۱. نقشهٔ اپ: کلید، سؤال، جواب#

اول صفحه را می‌سازیم، بی‌آنکه هنوز کاری بکند. صفحه پنج چیز دارد: یک کادرِ کلید، یک کادرِ سؤال، یک دکمه، یک خطِ وضعیت (فعلاً خالی می‌ماند؛ در فصل ۶ برای پیام‌های انتظار و خطا ازش استفاده می‌کنیم)، و یک جعبهٔ جواب. به یک نکته دقت کن: کادرِ کلید type="password" است، تا وقتی کلیدت را تایپ می‌کنی روی صفحه پیدا نباشد. این هم بخشی از BYOK است.

<!DOCTYPE html>
<html lang="fa" dir="rtl">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>دستیارِ من</title>
    <link rel="stylesheet" href="styles.css">
  </head>
  <body>
    <main>
      <h1>دستیارِ من</h1>
      <p class="hint">کلیدِ Gemini خودت را بگذار، بعد بپرس.</p>
      <input type="password" id="key" placeholder="کلیدِ API خودت — روی کامپیوترِ خودت می‌ماند">
      <textarea id="prompt" placeholder="سؤالت را اینجا بنویس"></textarea>
      <button id="ask">بپرس</button>
      <p id="status" class="status"></p>
      <div id="answer" class="answer"></div>
    </main>
    <script src="script.js"></script>
  </body>
</html>

هر عنصر یک id دارد تا کد بتواند پیدایش کند: key، prompt، ask، status، answer.

✅ چک کن: index.html را در مرورگر باز کن. باید کادرِ کلید، کادرِ سؤال و دکمه را ببینی. هنوز هیچ‌کاری نمی‌کند — طبیعی است، چون script.js را ننوشته‌ایم.

۲. fetch، async، await — قرض از تاروپود#

این سه را در تاروپود یاد گرفتی؛ اینجا فقط یادآوری‌شان می‌کنیم چون ابزارِ اصلیِ فراخوانی‌اند. fetch یعنی «از داخلِ کد یک درخواست بفرست و جواب را بگیر». چون جوابِ اینترنت فوری نیست، fetch بلافاصله یک قول (promise) می‌دهد؛ await یعنی «همین‌جا بایست تا این قول به جوابِ واقعی برسد»؛ و هر functionی که تویش await داری، جلویش باید async بگذاری.

حالا بالای script.js را بنویس: نامِ مدل، آدرسِ سرویس، و listenerِ دکمه که کلید و سؤال را می‌خواند. نامِ مدل را در یک ثابت جدا می‌گذاریم چون یک عددِ فرّار است:

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

document.querySelector("#ask").addEventListener("click", async function () {
  const key = document.querySelector("#key").value.trim();
  const prompt = document.querySelector("#prompt").value.trim();
  const answer = document.querySelector("#answer");
  // ادامه در بخشِ بعد…
});

به خطِ const key = document.querySelector("#key").value.trim(); خوب نگاه کن: کلید از کادرِ ورودی خوانده می‌شود، نه از یک ثابتِ داخلِ کد. این جانِ BYOK است. .trim() هم فاصله‌های اضافیِ اول و آخر را می‌گیرد که موقعِ کپی‌کردنِ کلید معمولاً جا می‌مانند.

⚠️ مواظب باش: هرگز، حتی برای یک تستِ سریع، کلیدت را این‌طور در کد ننویس: const key = "AIza...";. اگر همین فایل را منتشر کنی، کلیدت لو رفته. کلید فقط و فقط از کادرِ ورودی می‌آید.

۳. فرستادنِ prompt و خواندنِ جواب#

حالا قلبِ کار: با fetch بدنهٔ درخواست را به endpoint می‌فرستیم و کلید را در آدرس همراهش می‌کنیم. بدنه همان ساختارِ سادهٔ فصل ۲ است — فقط contents. بعد متن را از مسیرِ آشنایش بیرون می‌کشیم:

  const res = await fetch(URL + "?key=" + key, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      contents: [{ parts: [{ text: prompt }] }]
    })
  });
  const data = await res.json();
  answer.textContent = data.candidates[0].content.parts[0].text;

خط‌به‌خط: fetch با method: "POST" می‌فرستد (چون داریم داده می‌فرستیم، نه فقط می‌گیریم)، headers می‌گوید بدنه از جنسِ JSON است، و JSON.stringify شیءِ ما را به همان متنِ JSONِ فصل ۲ تبدیل می‌کند. res.json() جوابِ خام را به دادهٔ قابلِ استفاده برمی‌گرداند، و مسیرِ candidates[0].content.parts[0].text — همان که فصلِ قبل با انگشت دنبالش کردی — متنِ جواب را می‌دهد.

💡 نکته: در تاروپود fetch را برای گرفتن (GET) دیدی — فقط یک آدرس می‌دادی و جواب می‌گرفتی. اینجا یک قدمِ کوچکِ تازه به آن اضافه می‌کنیم: با method، headers و body همان fetch را برای فرستادن (POST) به‌کار می‌بریم، و بدنه را با JSON.stringify می‌سازیم. غیر از این یک تکه، بقیهٔ fetch همان است که می‌شناسی.

✅ چک کن: کلیدت را در کادر بگذار، یک سؤالِ ساده بنویس («یک لطیفهٔ کوتاه بگو») و دکمه را بزن. بعد از یک لحظه، جوابِ مدل در جعبهٔ جواب می‌نشیند. اولین فراخوانیِ واقعی‌ات از کد انجام شد.

۴. کدِ کاملِ این فصل#

حالا همه‌چیز کنارِ هم. این script.jsِ کامل است — همان تکه‌هایی که ساختیم، سرِ جای درستشان. عمداً ساده و «مسیرِ خوش» است: فرض می‌کند کلید درست است و اینترنت وصل. محکم‌کردنش در برابرِ کلیدِ غلط و اینترنتِ قطع کارِ فصل ۶ است.

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

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

  const res = await fetch(URL + "?key=" + key, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      contents: [{ parts: [{ text: prompt }] }]
    })
  });
  const data = await res.json();
  answer.textContent = data.candidates[0].content.parts[0].text;
});

و این هم styles.css که صفحه را تمیز و خوانا می‌کند:

/* styles.css */
body { font-family: Vazirmatn, Tahoma, sans-serif; background: #0f1413; color: #e9ede9; }
main { max-width: 640px; margin: 2rem auto; padding: 0 1rem; }
h1 { color: #2fc6ce; }
input, textarea { width: 100%; margin: 0.5rem 0; padding: 0.7rem; box-sizing: border-box;
  background: #151b19; color: #e9ede9; border: 1px solid #253029; border-radius: 8px; }
textarea { min-height: 8rem; }
button { background: #2fc6ce; color: #06130b; border: 0; padding: 0.7rem 1.4rem;
  border-radius: 8px; font-size: 1rem; cursor: pointer; }
button:disabled { opacity: 0.6; }
.status { color: #98a49e; }
.answer { white-space: pre-wrap; margin-top: 1rem; padding: 1rem;
  background: #151b19; border-radius: 8px; min-height: 2rem; }

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

🔧 اگر جواب نگرفتی: اگر جعبهٔ جواب خالی ماند، consoleِ مرورگر را باز کن (کلیدِ F12، سربرگِ Console). چون هنوز هیچ نگهبانی نگذاشته‌ایم، خطاها به‌جای صفحه آنجا ظاهر می‌شوند. دو خطا را باید بشناسی:

  • Cannot read properties of undefined (reading '0') یعنی سرویس جواب داده، ولی در جوابش candidates نیست. با کلیدِ غلط یا خالی همین را می‌بینی، چون پاسخِ خطا فقط خانهٔ error دارد (فصل ۲). کلید را دوباره کپی کن و مواظبِ فاصلهٔ اضافی باش.
  • Failed to fetch یعنی اصلاً جوابی نیامده. اینترنت یا فیلترِ شبکه را چک کن.

فصل ۶ همین خطاها را به پیامِ روی صفحه تبدیل می‌کند.

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

اپت کار می‌کند — ولی درست‌کارکردنِ اپ ربطی به درست‌بودنِ جواب ندارد. حالا این را از مدل بپرس: «پرجمعیت‌ترین کشورِ جهان کدام است؟». ممکن است چیزی شبیهِ این بگیری (خروجیِ تو ممکن است فرق کند):

پرجمعیت‌ترین کشورِ جهان چین است.

لحنش قاطع است، ولی جمعیت یک عددِ زنده است که مدام عوض می‌شود، و مدل تا knowledge cutoffِ خودش را می‌داند و بس — بعد از آن خبر ندارد. این دقیقاً همان‌جاست که ترم ۱ هشدار داد: مدل از لحظهٔ حال بی‌خبر است. جواب ممکن است دیروز درست بوده و امروز کهنه باشد.

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

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

کلمه تلفظ به حروف فارسی یعنی چه
fetch فِچ فرستادنِ درخواست به یک آدرس، از داخلِ کد (قرض از تاروپود)
async / await اِی‌سینک / اِوِیت علامتِ functionِ منتظر / «بایست تا جواب برسد» (قرض از تاروپود)
JSON.stringify جِی‌سان‌استرینگیفای تبدیلِ شیءِ برنامه به متنِ JSON برای فرستادن در bodyِ درخواست

تمرین‌ها

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

در فصل بعد#

اپت زنده شد: از کد صدا می‌زنی، کلید را امن از کادر می‌خوانی، و جواب را نشان می‌دهی. ولی هنوز مدل را «هدایت» نکرده‌ای — هر بار فقط promptِ خام را می‌فرستی. فصلِ بعد به همین script.js دو چیز اضافه می‌کنیم: system prompt در کد (تا مدل یک نقشِ ثابت بگیرد) و temperature (تا خلاق یا دقیق بودنش را کنترل کنی) — همان پارامترهایی که در ترم ۲ در زمینِ بازیِ چت دیدی، این‌بار داخلِ کدِ خودت.

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

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