آیرو — خودآموز رباتیک

فصل ۷ از ۱۱

پیشرفت ترم
۰٪

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

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

الگوی پل برای اتصال به AI: سه جزیره در یک ردیف — جزیرهٔ چپ یک بردِ کوچکِ ESP32 با آیکونِ خواب و تابلوی «Session 9»، جزیرهٔ وسط یک لپ‌تاپِ روشن و فعال، جزیرهٔ راست یک ابرِ دیتاسنتر با نشانِ درخشانِ AI؛ یک پلِ محکم و روشن، جزیرهٔ لپ‌تاپ را به ابرِ AI وصل کرده و یک بستهٔ داده رویش در حرکت است؛ پلِ کم‌رنگِ آینده هم از جزیرهٔ ESP32 مستقیم به ابر کشیده شده

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

  • فرقِ MicroPython روی برد و Python استاندارد روی کامپیوتر را بگویی و Python را روی کامپیوتر نصب و در ترمینال اجرا کنی.
  • با pip کتابخانهٔ requests را نصب کنی.
  • بگویی prompt چیست و درخواستِ POST چه فرقی با GET دارد.
  • با الگوی عمومیِ «⁦POST + JSON⁩ + کلیدِ API» از کدِ خودت به Gemini پیام بفرستی و جواب را از دلِ JSON تودرتو بیرون بکشی.
  • با input() یک چتِ ساده در ترمینال بسازی و خطاهای ۴۰۳ و ۴۲۹ و KeyError را بشناسی و رفع کنی.

قبل از شروع: چک‌لیست پیش‌نیاز#

قبل از ادامه این‌ها را چک کن — اگر یکی‌شان لنگ می‌زند، اول برگرد همان فصل:

  • از فصل ۶: دیکشنریِ کامل و ساختارِ تودرتو، json.dumps و json.loads، مفهومِ API key و rate limit، فایلِ secrets.py — همه امروز به میدان می‌آیند.
  • از فصل ۲: HTTP، request و response، status code، تشبیهِ رستوران — امروز سفارشِ نوعِ جدیدی می‌دهیم.
  • از ترم ۳، فصل ۸: حلقهٔ while با متغیرِ پرچم — قلبِ چتِ ترمینالیِ امروز.
  • از ترم ۲، فصل ۶: نصبِ کتابخانه و try/except — امروز همان کارها را با ابزارِ جدید می‌کنیم.
  • از ترم ۱، فصل ۴: REPL و Thonny — ترمینالِ امروز را با مقایسه با REPL یاد می‌گیریم.

لوازم این فصل:

قطعه / ابزار تعداد جایگزین
کامپیوتر (ویندوز/مک/لینوکس) با اینترنت ۱ همان کامپیوترِ Thonny کافی است
کلیدِ رایگانِ Gemini API (ساختهٔ والدین) ۱ راهنمای قدم‌به‌قدمِ والدین در بخشِ ۳ همین فصل
ESP32 ۰ امروز برد استراحت می‌کند — فصل ۹ برمی‌گردد!

💡 نکته: این فصل روی کامپیوتر اجرا می‌شود، نه برد — پس شبیه‌سازِ امروز تعطیل است. اگر نمی‌توانی Python نصب کنی (مثلاً کامپیوترِ مدرسه است)، Thonny خودش یک Python کامل دارد: از گوشهٔ پایین-راست، به‌جای MicroPython گزینهٔ Local Python 3 را بزن و requests را از همان Manage packages نصب کن.

۱. دو پایتون: نسخهٔ جیبی و نسخهٔ کامل#

یک رازِ کوچک: چیزی که سه ترم است می‌نویسی، «MicroPython» است — نسخهٔ جیبیِ Python، مثلِ نسخهٔ Liteِ یک بازیِ موبایل: همان بازی، سبک‌شده برای دستگاهِ کوچک. Python اصلی روی کامپیوترها زندگی می‌کند، و خبرِ عالی: زبانش همان زبان است — متغیر، شرط، حلقه، تابع، دیکشنری، همه را بلدی! فرق‌ها کوچک‌اند: نسخهٔ کامل کتابخانه‌های خیلی بیشتر و حافظه‌ای تمام‌نشدنی دارد، و در عوض machine و Pin ندارد — کامپیوترِ تو پایهٔ GPIO ندارد که LED به آن ببندی!

دو مارِ پایتونِ کارتونی به‌عنوانِ نمادِ نرم‌افزار: سمت چپ یک پایتونِ بزرگ و سیر که دورِ یک کامپیوترِ رومیزی پیچیده و کلی آیکونِ کتابخانه و نشانِ requests دارد، با برچسبِ Python؛ سمت راست یک پایتونِ کوچکِ جیبی که روی یک تراشهٔ ESP32 لم داده و جعبه‌ابزارِ کوچکی با نشانِ machine.Pin دارد، با برچسبِ MicroPython؛ بینشان یک علامتِ مساوی با قلب که نشان می‌دهد هر دو یک زبان حرف می‌زنند

نصبش کنیم. به سایتِ رسمیِ Python برو (python.org) و نصب‌کننده را دانلود کن. موقعِ نصب یک لحظهٔ حیاتی هست که نصفِ مشکلاتِ دنیا را می‌سازد: در اولین صفحه، تیکِ Add to PATH را حتماً بزن — یعنی «اسمِ python را به سیستم‌عامل معرفی کن». بدونِ این تیک، بعداً سیستم می‌گوید «python؟ نمی‌شناسم!».

حالا با ابزارِ محبوبِ برنامه‌نویس‌ها آشنا شو: ترمینال — پنجرهٔ سیاهی که فقط متن دارد. ترسناک نیست؛ دو ترم است با پسرعمویش REPL زندگی می‌کنی! همان‌طور که REPL دستور می‌گرفت و جوابِ Python می‌داد، ترمینال دستور می‌گیرد و جوابِ سیستم‌عامل را می‌دهد. در ویندوز اسمش PowerShell است، در مک و لینوکس Terminal. بازش کن و اولین دستور را بزن:

> python --version
Python 3.12.4

اگر شمارهٔ نسخه آمد (شمارهٔ دقیق مهم نیست — مالِ تو احتمالاً جدیدتر است)، Python کامل روی کامپیوترت زنده است. تبریک — حالا دو پایتون داری!

✅ چک کن: باید در جوابِ python --version یک شمارهٔ نسخه ببینی (مثلِ Python 3.12.4)، نه پیامِ خطا. اگر شماره آمد، Python کامل نصب و به سیستم معرفی شده.

چالش: machine.Pin روی کامپیوتر هست؟

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

۲. pip: فروشگاهِ کتابخانه‌ها، این بار تایپی#

برای حرف زدن با اینترنت، Python کامل هم کتابخانه می‌خواهد. آنجا urequests داشتیم؛ اینجا برادرِ بزرگش: requests — بدونِ u! همان خانواده، فقط کامل‌تر. ترم ۲ کتابخانه‌ها را از Manage packages نصب می‌کردی؛ روی کامپیوتر همان فروشگاه را تایپی داریم: pip.

اول بگذار یک اشتباهِ کلاسیک را عمداً بکنیم که تو هیچ‌وقت نکنی. در ترمینال تایپ کن python و Enter — سه فلشِ آشنا می‌آید: >>> — این همان REPL است، این بار REPL کامپیوتر! و حالا همین‌جا بنویس:

>>> pip install requests
  File "<stdin>", line 1
    pip install requests
        ^^^^^^^
SyntaxError: invalid syntax

SyntaxError! چرا؟ چون pip install requests جملهٔ زبانِ Python نیست — دستورِ ترمینال است و جای اشتباهی تایپ شد. این گیج‌کننده‌ترین لحظهٔ شروعِ کار است، پس قاعده‌اش را قاب کن: >>> یعنی «داخلِ Python هستی»، بدونِ >>> یعنی «در ترمینال هستی». با exit() از Python بیرون بیا و حالا در خودِ ترمینال:

> pip install requests
Collecting requests
  Downloading requests-2.32.3-py3-none-any.whl
Successfully installed requests-2.32.3 ...

پیامِ Successfully یعنی نصب شد. شماره‌های وسطِ آن خط‌ها (نسخهٔ بسته) مالِ همان روزِ ضبط است و مالِ تو تازه‌تر خواهد بود — به عددها نگاه نکن، به کلمهٔ Successfully نگاه کن. امتحانِ نهایی مثلِ همیشه: python را باز کن، import requests — سکوت. سکوت یعنی پیروزی!

✅ چک کن: بعد از import requests باید بی هیچ پیامِ خطایی به خطِ >>> برگردی. آن سکوت یعنی کتابخانه نصب و آمادهٔ استفاده است.

🔧 اگر کار نکرد: پیامِ 'python' is not recognized... گرفتی؟ تیکِ Add to PATH موقعِ نصب زده نشده — نصب را دوباره اجرا کن و تیک را بزن (یا در ویندوز به‌جای python بنویس py). و اگر بعدِ نصب هم ModuleNotFoundError: No module named 'requests' گرفتی، شاید چند Python روی سیستم است؛ به‌جای pip install requests بنویس python -m pip install requests.

چالش: pip را کجا تایپ کنی؟

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

۳. کلید در خانهٔ امن + prompt چیست#

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

  1. در مرورگر به aistudio.google.com بروید و با حسابِ Google بزرگسال وارد شوید.
  2. شرایطِ استفاده را بخوانید و اگر قبول دارید بپذیرید.
  3. بخشِ مربوط به کلیدها را پیدا کنید و یک کلیدِ تازه بسازید. یک رشتهٔ طولانی از حرف و عدد می‌گیرید.
  4. کلید را کامل کپی کنید و کنارِ فرزندتان در فایلِ secrets.py پایین بگذارید. جای دیگری نگهش ندارید.

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

حالا کلید داری، و فصل قبل گفتیم: کلید مثلِ رمزِ عبور است، پس همان‌جایی می‌رود که رمزها می‌روند: secrets.py. روی کامپیوتر یک پوشه برای پروژه بساز — مثلاً airo-ai روی دسکتاپ — و الگوی آشنای فصل ۶ را داخلش بساز، این بار با ساکنِ جدید:

# secrets.py - hame-ye ramz-haye project inja hastand
# IN FILE RA BA HICHKAS SHARE NAKON! na git, na Wokwi-e umumi, na screenshot!

GEMINI_API_KEY = "kelid-e-vagheiy-ra-inja-bogzar"

اگر روزی از صفحه‌ات فیلم گرفتی یا عکس فرستادی، رویِ خطِ کلید را تار کن. کلید لو رفت؟ مثلِ رمزِ عبور: در همان سایت باطلش کن و کلیدِ نو بساز.

و حالا مفهومِ ستارهٔ امشب: prompt — بخوان «پرامپت». پرامپت یعنی متنی که به AI می‌فرستی: سؤالت، درخواستت، توضیحِ کاری که می‌خواهی. همین! ولی یک قانونِ طلایی دارد: هرچه دقیق‌تر بگویی چه می‌خواهی، بهتر می‌گیری. مثلِ سفارش به آشپزی که هر غذایی بلد است: «یک چیزی بده» یک چیزی می‌دهد؛ «پاستای بدونِ فلفل، سسِ کم» دقیقاً همان می‌شود.

💡 نکته: پرامپت را در کد به انگلیسیِ ساده می‌نویسیم تا کد تمیز و LTR بماند — ولی داخلش می‌گوییم «به فارسی جواب بده». مدل‌ها فارسی را خوب می‌فهمند و می‌نویسند؛ هر جا خواستی، خودِ پرامپت را هم فارسی بده.

چالش: کدام پرامپت بهتر است؟

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

۴. اولین تماس: سفارشی از نوعِ جدید#

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

بستهٔ POST ما سه قسمت دارد — این ساختار را قاب کن، چون الگوی همهٔ سرویس‌های AI دنیاست:

  1. آدرس (URL): کجا بفرستیم — آدرسِ سرویسِ Gemini و اسمِ مدلش (در کدِ پایین آمده است).
  2. هدرها (headers): برچسب‌های روی بسته — یکی می‌گوید محتوا JSON است، یکی کلیدِ توست.
  3. بدنه (body): خودِ نامه — پرامپت، در قالبی که Gemini می‌خواهد (دیکشنریِ تودرتو!).

آدرس را از خطِ URL کدِ پایین بردار. هدرها دو تا لازم داریم: یکی می‌گوید «محتوای بسته JSON است» و دیگری کلید توست، چسبیده روی بسته، که سرویس بداند این سفارش مالِ کیست. و بدنه یک دیکشنریِ تودرتو است — داخلش لیست، داخلِ لیست دیکشنری — دقیقاً همان هیولای دوست‌داشتنی که فصل ۶ رامش کردی. برای متن‌کردنش هم json.dumps را داریم؛ قولش را داده بودم که «برای فرستادن» به کار می‌آید.

آناتومیِ یک درخواستِ POST به شکلِ یک بستهٔ پستی: برچسبِ بزرگِ POST روی جعبه؛ سه فلشِ توضیح: (۱) برچسبِ آدرس با نامِ URL روی خطِ نشانی، (۲) دو استیکرِ HEADERS روی جعبه — یکی «Content-Type: JSON» و دیگری آیکونِ کلیدِ طلاییِ API KEY، (۳) دربِ بازِ جعبه که نامه‌ای با ساختارِ آکولادهای تودرتوی JSON با برچسبِ BODY نشان می‌دهد؛ گوشهٔ تصویر ابری با نشانِ AI به‌عنوانِ مقصد

فایلِ 01_first_ai_call.py را در همان پوشه بساز. import ها، آدرس، هدرها با کلید از secrets، پرامپت، بدنهٔ تودرتو، و شلیک با requests.post. کدِ کامل در 01_first_ai_call.py:

# Term 4 - Session 07 - avalin tamas ba AI (roye COMPUTER, na ESP32!)
# ejra dar terminal:  python 01_first_ai_call.py
# pish-niaz: pip install requests  +  file-e secrets.py kenar-e hamin file
import requests
import json
import secrets

# address + esm-e model: gahi avaz mishavand (404 = esm-e model avaz shode)
URL = "https://generativelanguage.googleapis.com/v1beta/models/gemini-flash-latest:generateContent"

headers = {
    "Content-Type": "application/json",        # mohtavaye baste JSON ast
    "x-goog-api-key": secrets.GEMINI_API_KEY,  # kelid az khane-ye amn - hargez mostaghim nanevis!
}

# prompt = sefaresh-e daghigh-e to be AI
prompt = "You are a friendly robot. Say hello to a teenage robotics student in one short Persian sentence."

# body = name-ye ma dar ghaleb-e Gemini: dictionary-e too dar too (jalase 6!)
body = {
    "contents": [
        {"parts": [{"text": prompt}]}
    ]
}

print("dar hale ferestadan-e sefaresh (POST)...")
r = requests.post(URL, headers=headers, data=json.dumps(body))
print(f"status code: {r.status_code}")
print("---- matn-e kham-e pasokh ----")
print(r.text)

به دو خطِ headers خوب دقت کن: کلیدِ تو در سربرگی به اسمِ x-goog-api-key می‌رود که سرویسِ Gemini با آن تو را می‌شناسد — نه در آدرس، نه در بدنه، فقط همین سربرگ. حالا در ترمینال اجرا کن:

> python 01_first_ai_call.py
dar hale ferestadan-e sefaresh (POST)...
status code: 200
---- matn-e kham-e pasokh ----
{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "سلام! من یک ربات مهربانم و از آشنایی با تو خیلی خوشحالم!"
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP"
    }
  ],
  ...

یک لحظه مکث کن. status code: ۲۰۰. و آن وسط، بینِ آکولادها، یک جملهٔ فارسی که چند لحظه پیش هیچ‌جای دنیا وجود نداشت. یک هوش مصنوعی آن را همین الان، در جوابِ کدِ تو، نوشت. این اولین مکالمهٔ کدِ تو با AI بود — تاریخ بزن!

✅ چک کن: باید status code: 200 را ببینی و پایینش، لای آکولادهای JSON، یک جملهٔ فارسیِ تازه که AI همین حالا برایت نوشت. اگر ۲۰۰ نیامد، بلوکِ زیر را بخوان.

🔧 اگر کار نکرد: به‌جای ۲۰۰ عددِ دیگری دیدی؟ دو بلای رایج را بشناس. ۴۰۳ (یا PERMISSION_DENIED) یعنی «تو را نمی‌شناسم — کلید نرسیده»: مستقیم برو سراغِ کلید — هست؟ درست کپی شده؟ اسمِ هدرش (x-goog-api-key) درست است؟ (کلیدِ غلط ممکن است ۴۰۰ با پیامِ «API key not valid» بدهد؛ معنی‌اش یکی است: مشکل از کلید.) ۴۲۹ (RESOURCE_EXHAUSTED) یعنی «سهمیه‌ات فعلاً تمام — نفس بگیر»: کلیدت خراب نشده، کمی صبر کنی برمی‌گردد. همان قانونِ بوفهٔ فصل ۶: حلقه‌های تند و بی‌وقفه ننویس؛ فقط وقتی لازم است بپرس — هم به‌خاطرِ سرویس، هم به‌خاطرِ برقی که در دیتاسنترها می‌سوزد.

۵. بیرون کشیدن جواب از JSON تودرتو#

مهندس با «یک جایی آن وسط» راضی نمی‌شود — باید جواب را تمیز بیرون بکشیم. قیافهٔ پاسخ را نگاه کن: candidates یک لیست است (سرویس می‌تواند چند جوابِ پیشنهادی بدهد، معمولاً یکی)، عضوِ اولش [0]، داخلش content، داخلِ آن parts که باز لیست است، عضوِ اولش، و بالاخره text. بگذار اول مثلِ کارآگاهِ فصل ۶ عمداً غلط برویم که راهش یادمان بماند — عجله کن و بنویس data["text"]:

Traceback (most recent call last):
  File "C:\Users\airo\Desktop\airo-ai\02_parse_answer.py", line 27, in <module>
    answer = data["text"]
KeyError: 'text'

KeyError: 'text' — آشنای قدیمی! کشوی text در طبقهٔ اولِ قفسه نیست؛ پنج طبقه پایین‌تر است. قانونِ کارآگاه: اول نقشه را چاپ کن، بعد مسیر را طبقه‌به‌طبقه بنویس.

مسیرِ درست را طبقه‌به‌طبقه بنویس. کدِ کامل در 02_parse_answer.py:

# Term 4 - Session 07 - parse-e javab: candidates[0] -> content -> parts[0] -> text
# ejra dar terminal:  python 02_parse_answer.py
import requests
import json
import secrets

# address + esm-e model: gahi avaz mishavand (404 = esm-e model avaz shode)
URL = "https://generativelanguage.googleapis.com/v1beta/models/gemini-flash-latest:generateContent"

headers = {
    "Content-Type": "application/json",
    "x-goog-api-key": secrets.GEMINI_API_KEY,
}

prompt = "Suggest three fun Persian names for a small two-wheeled robot. Answer in Persian, max 3 lines."

body = {
    "contents": [
        {"parts": [{"text": prompt}]}
    ]
}

r = requests.post(URL, headers=headers, data=json.dumps(body))
data = r.json()

# ghanun-e karagah (jalase 6): aval naghshe ra chap kon, bad tabaghe be tabaghe boro
answer = data["candidates"][0]["content"]["parts"][0]["text"]
print("---- javab-e AI ----")
print(answer)

اجرا... و این بار فقط خودِ جواب، تمیز و مرتب. آن خطِ پارس — data["candidates"][0]["content"]["parts"][0]["text"] — را لای دفترچهٔ مهندسی‌ات بگذار؛ در سه فصلِ آینده بارها می‌نویسی‌اش. یک صداقتِ کوچک هم بدهکارم: این مسیر، مسیرِ پاسخِ امروزِ همین سرویس است. سرویس‌ها ساختارِ پاسخشان را عوض می‌کنند، پس اگر روزی این خط KeyError داد، اول نگران نشو — print(r.text) بزن، نقشهٔ تازه را ببین و مسیر را از رویش بنویس. مهارتِ اصلی همان «نقشه‌خوانی» است، نه حفظ‌کردنِ این یک خط.

✅ چک کن: این بار باید فقط خودِ جوابِ AI را ببینی — بی هیچ آکولاد و candidates و JSONِ خام. یعنی مسیرِ پارس را درست طبقه‌به‌طبقه رفته‌ای.

چالش: چرا [0] بعد از candidates ولی کلید بعد از content؟

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

۶. پروژهٔ اصلی: چت در ترمینال#

حالا که تک‌تماس را بلدیم، بیا چتِ واقعی بسازیم: تو تایپ کنی، AI جواب بدهد، و همین‌طور ادامه — تا خودت بگویی تمام. فقط یک قطعه کم داریم: تا حالا برنامه‌هایمان از دکمه و سنسور ورودی می‌گرفتند؛ از آدمِ پشتِ کیبورد چطور؟ تابعِ input() — قرینهٔ print! print می‌گوید، input گوش می‌دهد: برنامه می‌ایستد تا چیزی تایپ کنی و Enter بزنی، و آن متن را به تو می‌دهد. نکته‌ای که بعداً جانت را نجات می‌دهد: هرچه input بدهد رشته است — حتی اگر عدد تایپ کنی، "42" می‌گیری نه 42.

طرحِ برنامه: اول تماس با AI را داخلِ یک تابعِ تمیز می‌گذاریم — ask_ai(prompt) — که پرامپت بگیرد و جوابِ متنی برگرداند؛ پارس را هم در try/except KeyError می‌گذاریم تا اگر پاسخ شکلِ عجیبی داشت، برنامه به‌جای سقوط، پیام بدهد. بعد حلقهٔ چت — و اینجا الگوی آشنای ترم ۳ برمی‌گردد: while با متغیرِ پرچم، همان که دنبال‌کنندهٔ خط را با آن روشن و خاموش می‌کردی. کدِ کامل در 03_terminal_chat.py:

# Term 4 - Session 07 - chat ba AI dar terminal (roye COMPUTER)
# baraye khorooj: benevis exit
# note: in chat hafeze nadarad - har soal yek tamas-e taze ast!
import requests
import json
import secrets

# address + esm-e model: gahi avaz mishavand (404 = esm-e model avaz shode)
URL = "https://generativelanguage.googleapis.com/v1beta/models/gemini-flash-latest:generateContent"

headers = {
    "Content-Type": "application/json",
    "x-goog-api-key": secrets.GEMINI_API_KEY,
}

def ask_ai(prompt):
    # yek tamas-e kamel: body -> POST -> parse; javab-e matni bar migardanad
    body = {
        "contents": [
            {"parts": [{"text": prompt}]}
        ]
    }
    r = requests.post(URL, headers=headers, data=json.dumps(body))
    data = r.json()
    try:
        return data["candidates"][0]["content"]["parts"][0]["text"]
    except KeyError:
        # javab shekl-e adi nadasht (khata ya filter-e imeni) - naghshe ra neshan bede
        return "javab-e ghabel-e khandan nagereftam! status: " + str(r.status_code)

print("=== AIRO AI chat ===")
print("soalet ra benevis va Enter bezan (khorooj: exit)")

running = True
while running:
    question = input("to: ")
    if question == "exit":
        running = False
        print("khodahafez! ta jalase-ye bad.")
    else:
        answer = ask_ai(question)
        print("AI:", answer)
        print()

اجرا کن و تایپ کن: se ta esm-e bahal baraye yek robot-e do-charkh pishnahad bede - be farsi — جواب می‌آید: سه اسمِ بامزهٔ فارسی! یکی دیگر بپرس: ESP32 chand pin darad? — جواب می‌دهد. داری با کدِ پنجاه‌خطیِ خودت چت می‌کنی!

✅ چک کن: باید بتوانی چند سؤالِ پشتِ سرِ هم بپرسی و هر بار جوابِ AI را زیرش ببینی، و آخرش با تایپِ exit تمیز از حلقه بیرون بیایی. اگر این کار کرد، اولین چتِ AI ساختهٔ خودت آماده است!

دو نکتهٔ صادقانه دربارهٔ این چت. اول: به AI بگو «اسمِ من آیروست»، بعد بپرس «اسمِ من چیست؟» — نمی‌داند! چون هر صدازدنِ ask_ai یک تماسِ کاملاً تازه است؛ ما تاریخچهٔ گفت‌وگو را نگه نمی‌داریم و نمی‌فرستیم. چت‌های حرفه‌ای پیام‌های قبلی را هر بار همراهِ پرامپتِ جدید می‌فرستند — در تمرینِ ستاره‌دار خودت برایش حافظه می‌سازی! دوم: در بعضی ترمینال‌ها تایپِ فارسی به‌هم‌ریخته دیده می‌شود؛ عیب از کدت نیست — ترمینال‌ها با راست‌به‌چپ میانهٔ خوبی ندارند. راهِ عملی: سؤال را فینگلیش بنویس و داخلش بگو be farsi javab bede.

چالش: Exit با E بزرگ چه می‌شود؟

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

۷. چهار قانونِ دنیای AI#

از امروز تا آخرِ دوره، هر جلسه AI با ماست — این چهار قانون اختیاری نیستند:

یک: کلید مثلِ رمزِ عبور. فقط در secrets.py زندگی می‌کند؛ نه در کدِ اصلی، نه در اسکرین‌شات، نه در گروه، نه در پروژهٔ عمومیِ آزمایشگاه. رویِ کلید را همیشه تار کن.

دو: هیچ دادهٔ شخصی در prompt. اسمِ کامل، آدرسِ خانه، اسمِ مدرسه، عکس، شماره — هیچ‌کدام به AI فرستاده نمی‌شود. پرامپتِ تو به کامپیوترهای یک شرکت می‌رود؛ چیزی را بفرست که اگر روی درِ یخچالِ خانه هم چسبیده بود، مشکلی نبود.

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

چهار: جوابِ AI را همیشه چک کن. این سرویس‌ها یک فیلترِ ایمنیِ داخلی دارند (safety settings) که پیش‌فرض روشن است و جلوی محتوای نامناسب را می‌گیرد؛ اگر روزی جوابِ خالی گرفتی، شاید همین فیلتر فعال شده. ولی هیچ فیلتری درستی را تضمین نمی‌کند: AI می‌تواند با اعتمادبه‌نفسِ کامل، اشتباه بگوید. فصلِ بعد این را زنده و با سند می‌بینیم!

پوسترِ چهار قانونِ ایمنیِ AI در چیدمانِ دو-در-دو، هر کارت یک آیکونِ بزرگ و جای خالی برای متن: کارتِ ۱ کلیدِ طلایی قفل‌شده در گاوصندوقی با برچسبِ secrets.py و فلشِ اشتراکِ خط‌خورده؛ کارتِ ۲ کارتِ شناسایی و پینِ آدرسِ خانه با دایرهٔ قرمزِ ممنوع جلوی پنجرهٔ چت؛ کارتِ ۳ یک والد و نوجوان کنارِ لپ‌تاپ با سپرِ تیک‌دار؛ کارتِ ۴ حبابِ گفتارِ رباتی که با یک کتابِ باز و ذره‌بین چک می‌شود و مثلثِ هشدار؛ فقط شماره‌های ۱ تا ۴

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

کلمه تلفظ به حروف فارسی یعنی چه
Terminal تِرمینال پنجرهٔ متنیِ فرمان‌دادن به سیستم‌عامل — پسرعموی REPL
pip پیپ فروشگاهِ تایپیِ کتابخانه‌های Python روی کامپیوتر
requests ری‌کوئستس کتابخانهٔ HTTP در Python کامل — برادرِ بزرگِ urequests
POST پُست سفارشی که خودش بستهٔ داده دارد: «این را بگیر، جواب بساز»
Prompt پرامپت متنی که به AI می‌فرستی — سفارشِ دقیقِ تو
Header هِدِر برچسب‌های روی بستهٔ HTTP؛ کلید و نوعِ محتوا اینجا می‌روند
input این‌پوت تابعی که منتظرِ تایپِ کاربر می‌ماند و متنش را (رشته) می‌دهد
Model مادِل مغزِ مشخصی از AI که به آن پیام می‌دهی — هر سرویس چند مدل دارد

تمرین‌ها

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

در فصل بعد#

جلسهٔ بعد این دو دنیا به هم می‌رسند: سنسورهای ترم ۲ برمی‌گردند. DHT11 دما و رطوبتِ اتاقت را می‌خواند، LDR نور را، و این عددها می‌روند داخلِ پرامپت — و AI برایت یک گزارشِ فارسیِ آدمیزادی می‌نویسد: «اتاقت الان دم‌کرده است؛ پنجره را باز کن.» دستیارِ هواشناسیِ شخصی، ساختهٔ خودت. و یک اتفاقِ مهمِ دیگر: اولین بار مچِ AI را موقعِ اشتباه گفتن می‌گیریم — با سند و مدرک. از دستش نده!

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

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