راه بازگشت به خانه - سطح ۰: خودتان را معرفی کنید

سیگنال پریشانی

مدت زمان: ۱ دقیقه

سربرگ

کپسول فرار شما در فضای یک دنیای ناشناخته فرو می‌رود. چراغ‌های هشدار در تمام پنل‌ها چشمک می‌زنند. سیستم ناوبری از کار افتاده است. ارتباطات قطع شده است. همزمان با فعال شدن پروتکل‌های اضطراری کپسول، دستیار هوش مصنوعی فعال می‌شود:

«بازمانده شناسایی شد. فرود اضطراری موفقیت‌آمیز بود. پروتکل ارسال سیگنال نجات آغاز شد...»

«هشدار: تأیید هویت الزامی است. شبکه نجات کهکشانی نمی‌تواند کاوشگران ثبت‌نام‌نشده را پیدا کند. لطفاً هویت خود را تأیید کنید تا چراغ راهنمای شما فعال شود.»

از دریچه‌ی دید به بیرون نگاه می‌کنید. منظره‌ای بیگانه تا افق امتداد یافته است - صخره‌های عجیب، پوشش گیاهی ناآشنا، آسمانی با رنگ‌های عجیب. جایی آن بیرون، بازماندگان دیگری از ماموریت شما در سراسر سطح این سیاره پراکنده شده‌اند.

اما اول از همه: شما باید در سیستم وجود داشته باشید.

آنچه خواهید ساخت

در این مرحله، شما هویت منحصر به فرد خود به عنوان یک کاوشگر فضایی را با استفاده از تولید تصویر چند مرحله‌ای با مدل‌های تولید تصویر Gemini گوگل (که با نام Nano Banana 🍌 نیز شناخته می‌شود) ایجاد خواهید کرد. آواتار شما در نقشه نجات جهانی ظاهر می‌شود و برای سایر بازماندگان حاضر در رویداد کارگاه شما قابل مشاهده خواهد بود.

معماری

آنچه یاد خواهید گرفت

مفهوم توضیحات
تولید تصویر چند نوبتی چگونه با استفاده از جلسات چت، ثبات شخصیت را در چندین نسل تصویر حفظ کنیم
مهندسی سریع برای تصاویر ایجاد دستورالعمل‌های مؤثر برای خروجی‌های سبک‌مند و سازگار با محدودیت‌های خاص
API تصویر Gemini (نانو موز) استفاده از قابلیت‌های تولید تصویر بومی Gemini از طریق Python SDK
جلسات چت بهره‌گیری از زمینه مکالمه برای اصلاح مکرر و ثبات شخصیت

در پایان این سطح، شما موارد زیر را خواهید داشت:

✅ با استفاده از هوش مصنوعی تبدیل متن به تصویر، تصویری از کاوشگر شما ایجاد شد
✅ با استفاده از مکالمه چند نوبتی، یک آیکون نقشه ثابت ایجاد شد
✅ هویت خود را در شبکه نجات ثبت کردید
✅ در کنار سایر کاوشگران روی نقشه زنده جهان ظاهر شد

بیایید شما را روی نقشه ثبت کنیم! 📍

محیط خود را آماده کنید

مدت زمان: ۲ دقیقه

دسترسی به پوسته ابری

ابتدا، Cloud Shell را باز می‌کنیم که یک ترمینال مبتنی بر مرورگر است و Google Cloud SDK و سایر ابزارهای ضروری از پیش نصب شده روی آن قرار دارند.

به اعتبار ابری گوگل نیاز دارید؟

• اگر در کارگاه آموزشی تحت نظر مربی شرکت می‌کنید : مربی شما یک کد اعتباری در اختیارتان قرار خواهد داد. لطفاً از کدی که ارائه می‌دهد استفاده کنید.
• اگر خودتان به تنهایی در این Codelab کار می‌کنید : می‌توانید از اعتبار رایگان Google Cloud برای پوشش هزینه‌های کارگاه استفاده کنید. لطفاً برای دریافت اعتبار ، روی این لینک کلیک کنید و مراحل راهنمای ویدیویی زیر را برای اعمال آن به حساب خود دنبال کنید.
ویدیو را تماشا کنید

روی «فعال کردن پوسته ابری» در بالای کنسول گوگل کلود کلیک کنید (این نماد ترمینال در نوار ناوبری بالا سمت راست است).

پوسته ابری

شناسه پروژه گوگل کلود خود را پیدا کنید:

  • کنسول گوگل کلود را باز کنید: https://console.cloud.google.com
  • پروژه‌ای را که می‌خواهید برای این کارگاه استفاده کنید، از منوی کشویی پروژه در بالای صفحه انتخاب کنید.
  • شناسه پروژه شما در کارت اطلاعات پروژه در داشبورد نمایش داده می‌شود.
    شناسه پروژه

پس از باز شدن Cloud Shell، تأیید کنید که احراز هویت شده‌اید:

# Check that you are logged in
gcloud auth list

باید حساب خود را به عنوان (ACTIVE) مشاهده کنید.

پروژه خود را پیکربندی کنید

تأیید کنید که پروژه شما به درستی تنظیم شده است:

export PROJECT_ID=$(gcloud config get-value project)
echo "Using project: $PROJECT_ID"

اگر هیچ پروژه‌ای تنظیم نشده است یا باید آن را تغییر دهید:

gcloud config set project YOUR_PROJECT_ID

فعال کردن API های مورد نیاز

فعال کردن Vertex AI API برای تولید تصویر:

gcloud services enable aiplatform.googleapis.com

مخزن را کلون کنید

مخزن Way Back Home را کلون کنید و به پروژه بروید:

git clone https://github.com/ayoisio/way-back-home.git
cd way-back-home

نصب وابستگی‌ها

به سطح ۰ بروید و بسته‌های پایتون مورد نیاز را نصب کنید:

cd level_0
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

وابستگی‌های کلیدی عبارتند از:

بسته هدف
google-genai کلاینت Gemini API برای تولید تصویر
requests کلاینت HTTP برای فراخوانی‌های API به Mission Control
Pillow پردازش تصویر و مدیریت فایل‌ها

تأیید تنظیمات

برای اطمینان از پیکربندی صحیح همه چیز، یک تأیید سریع اجرا کنید:

cd ~/way-back-home
python scripts/verify_setup.py

شما باید ببینید:

✓ Google Cloud project configured: your-project-id
✓ Vertex AI API enabled
✓ Dependencies installed
✓ Ready to proceed!

کاری که تازه تمام کردی

✅ پوسته ابری باز شده
✅ پروژه Google Cloud خود را پیکربندی کردید
✅ فعال‌سازی APIهای هوش مصنوعی Vertex
✅ مخزن codelab کلون شد
✅ وابستگی‌های پایتون نصب شده
✅ تنظیمات شما تأیید شد

مرحله بعد: به Mission Control متصل شوید و نام کاوشگر خود را دریافت کنید.

اتصال به کنترل ماموریت

مدت زمان: ۲ دقیقه

اسکریپت راه‌اندازی را اجرا کنید

اسکریپت راه‌اندازی شما را به شبکه نجات Way Back Home متصل می‌کند و هویت کاوشگر شما را ذخیره می‌کند. آن را از ریشه پروژه اجرا کنید:

cd ~/way-back-home
chmod +x scripts/setup.sh
./scripts/setup.sh

از شما دو اطلاعات خواسته می‌شود.

کد رویداد خود را وارد کنید

کد رویداد مشخص می‌کند که در کدام رویداد کارگاهی شرکت می‌کنید.

اگر در کارگاه آموزشی هستید: کد رویداد را از کد QR، اسلاید یا مدرس کارگاه خود وارد کنید. 

🚀 Welcome to Way Back Home!

Enter event code (from QR/slide): devfest-nyc-26
Validating event...
✓ Connected to: DevFest NYC 2026

اگر خودتان به تنهایی یاد می‌گیرید: برای پیوستن به محیط یادگیری عمومی، وارد sandbox شوید. 

🚀 Welcome to Way Back Home!

Enter event code (from QR/slide): sandbox
Validating event...
✓ Connected to: Way Back Home Sandbox

نام کاوشگر خود را انتخاب کنید

یک نام منحصر به فرد برای کاوشگر خود انتخاب کنید. به این ترتیب در نقشه جهان و جدول امتیازات ظاهر خواهید شد. 

Choose your explorer name: AstroAyo
✓ Username available!

اگر نام انتخابی شما قبلاً توسط شرکت‌کننده دیگری در همان رویداد انتخاب شده باشد: 

Choose your explorer name: SpaceExplorer
⚠️  That name is taken. Try another.
Choose your explorer name: SpaceExplorer42
✓ Username available!

راه‌اندازی کامل شد

پس از تکمیل، تأیید را مشاهده خواهید کرد: 

Initializing your explorer profile...

✓ Environment configured!
  Explorer ID: a1b2c3d4
  Starting coordinates: (47, 23)

Next: cd level_0 && python customize.py

اکنون به دایرکتوری سطح ۰ بروید (وابستگی‌های شما از قبل از ماژول ۲ نصب شده‌اند): 

cd level_0

پیکربندی خود را بررسی کنید

به آنچه ذخیره شده است نگاهی بیندازید (config.json در ریشه پروژه قرار دارد): 

cat ../config.json

{
    "event_code": "devfest-nyc-26",
    "event_name": "DevFest NYC 2026",
    "username": "AstroAyo",
    "participant_id": "a1b2c3d4",
    "starting_x": 47,
    "starting_y": 23,
    "api_base": "https://api.waybackhome.dev",
    "project_id": "your-project-id"
}

این فایل پیکربندی توسط اسکریپت‌های بعدی برای شناسایی شما به شبکه نجات استفاده خواهد شد.

کاری که تازه تمام کردی

✓ متصل به API کنترل ماموریت
✓ نام اکسپلورر منحصر به فرد شما رزرو شده است
✓ شناسه شرکت‌کننده و مختصات شروع خود را دریافت کردید
✓ پیکربندی برای مراحل بعدی ذخیره شد

بعدی: ظاهر اکسپلورر خود را سفارشی کنید.

اکسپلورر خود را سفارشی کنید

مدت زمان: ۱ دقیقه

اجرای اسکریپت سفارشی‌سازی

قبل از ایجاد آواتار خود، چند انتخاب در مورد ظاهر کاوشگر خود خواهید داشت: 

python customize.py

رنگ کت و شلوار خود را انتخاب کنید

یک رنگ برای لباس فضایی کاوشگر خود انتخاب کنید: 

🎨 Let's create your explorer identity!

Select suit color:
  1. Deep Blue
  2. Crimson Red
  3. Forest Green
  4. Royal Purple
  5. Solar Gold
  6. Silver

Choice [1-6, default=6]: 1
✓ Deep Blue selected

کاوشگر خود را توصیف کنید (اختیاری)

می‌توانید توضیح مختصری از ظاهر اکسپلورر خود ارائه دهید، یا برای تخصیص تصادفی، Enter را فشار دهید: 

Brief description of your explorer (or Enter for random):
Example: 'short dark hair, glasses, friendly smile'
> short dark hair, glasses, determined expression

✓ Preferences saved!

اگر بدون تایپ کردن چیزی، Enter را فشار دهید، صفات تصادفی دریافت خواهید کرد: 

> 
✓ Random traits: confident expression, short styled hair

پیکربندی به‌روزرسانی شد

تنظیمات برگزیده شما اکنون ذخیره شده است: 

✓ Preferences saved!
Next: Open generator.py and follow the codelab instructions
Then run: python create_identity.py

پیکربندی به‌روزرسانی‌شده را تأیید کنید: 

cat ../config.json

خواهید دید که تنظیمات برگزیده شما اضافه شده است: 

{
    "event_code": "devfest-nyc-26",
    "event_name": "DevFest NYC 2026",
    "username": "AstroAyo",
    "participant_id": "a1b2c3d4",
    "starting_x": 47,
    "starting_y": 23,
    "api_base": "https://api.waybackhome.dev",
    "project_id": "your-project-id",
    "suit_color": "deep blue with silver accents",
    "appearance": "short dark hair, glasses, determined expression"
}

کاری که تازه تمام کردی

✓ رنگ کت و شلوار خود را انتخاب کنید
✓ ظاهر کاوشگر خود را تعریف کنید
✓ پیکربندی آماده برای تولید تصویر

بعدی: رویداد اصلی - نوشتن کد تولید تصویر!

ساخت مولد آواتار

مدت زمان: ۴ دقیقه

این ماژول یادگیری اصلی است. شما کد پایتونی خواهید نوشت که با استفاده از قابلیت‌های تولید تصویر چند مرحله‌ای Gemini (Nano Banana) آواتار اکسپلورر منحصر به فرد شما را تولید می‌کند.

فایل ژنراتور را باز کنید

مولد آواتار را در ویرایشگر Cloud Shell باز کنید: 

cloudshell edit generator.py

یا روی Open Editor در Cloud Shell کلیک کنید و به generator.py در پوشه level_0 بروید.

درک ساختار فایل

این فایل دارای کد آغازین و سه بخش جایگذاری است که پیاده‌سازی خود را در آنها اضافه خواهید کرد: 

"""
Level 0: Avatar Generator

This module generates your unique space explorer avatar using
multi-turn image generation with Gemini (Nano Banana) for
character consistency across portrait and icon.
"""

from google import genai
from google.genai import types
from PIL import Image
import json
import os
import io

# Load configuration from setup (config.json is in project root)
CONFIG_PATH = "../config.json"

with open(CONFIG_PATH) as f:
    config = json.load(f)

USERNAME = config["username"]
SUIT_COLOR = config["suit_color"]
APPEARANCE = config["appearance"]

# Initialize the Gemini client for Vertex AI
client = genai.Client(
    vertexai=True,
    project=os.environ.get("GOOGLE_CLOUD_PROJECT", config.get("project_id")),
    location="us-central1"
)


def generate_explorer_avatar() -> dict:
    """
    Generate portrait and icon using multi-turn chat for consistency.
    
    The key technique here is using a CHAT SESSION rather than independent
    API calls. This allows Gemini to "remember" the character it created
    in the first turn, ensuring the icon matches the portrait.
    
    Returns:
        dict with portrait_path and icon_path
    """
    
    # MODULE_5_STEP_1_CREATE_CHAT_SESSION
    # TODO: Create a chat session for multi-turn generation
    chat = None  # Replace this line
    
    # MODULE_5_STEP_2_GENERATE_PORTRAIT
    # TODO: Generate the explorer portrait
    portrait_image = None  # Replace this section
    
    # MODULE_5_STEP_3_GENERATE_ICON
    # TODO: Generate a consistent map icon
    icon_image = None  # Replace this section
    
    return {
        "portrait_path": "outputs/portrait.png",
        "icon_path": "outputs/icon.png"
    }


if __name__ == "__main__":
    # Create outputs directory if it doesn't exist
    os.makedirs("outputs", exist_ok=True)
    
    print(f"Generating avatar for {USERNAME}...")
    result = generate_explorer_avatar()
    print(f"✅ Avatar created!")
    print(f"   Portrait: {result['portrait_path']}")
    print(f"   Icon: {result['icon_path']}")

شما سه بخش TODO را با پیاده‌سازی خود جایگزین خواهید کرد.

مرحله ۱: ایجاد جلسه چت

جای خالی MODULE_5_STEP_1_CREATE_CHAT_SESSION را پیدا کنید و خط chat = None # Replace this line : 

    # MODULE_5_STEP_1_CREATE_CHAT_SESSION
    # Create a chat session to maintain character consistency across generations.
    # The chat session preserves context between turns, so Gemini "remembers"
    # what it generated and can create consistent variations.
    chat = client.chats.create(
        model="gemini-2.5-flash-image",  # Nano Banana - Gemini with image generation
        config=types.GenerateContentConfig(
            response_modalities=["TEXT", "IMAGE"]
        )
    )

مرحله ۲: ایجاد پرتره

MODULE_5_STEP_2_GENERATE_PORTRAIT را پیدا کنید و portrait_image = None # Replace this section : 

    # MODULE_5_STEP_2_GENERATE_PORTRAIT
    # First turn: Generate the explorer portrait.
    # This establishes the character that will be referenced in subsequent turns.
    portrait_prompt = f"""Create a stylized space explorer portrait.

Character appearance: {APPEARANCE}
Name on suit patch: "{USERNAME}"
Suit color: {SUIT_COLOR}

CRITICAL STYLE REQUIREMENTS:
- Digital illustration style, clean lines, vibrant saturated colors
- Futuristic but weathered space suit with visible mission patches
- Background: Pure solid white (#FFFFFF) - absolutely no gradients, patterns, or elements
- Frame: Head and shoulders only, 3/4 view facing slightly left
- Lighting: Soft diffused studio lighting, no harsh shadows
- Expression: Determined but approachable
- Art style: Modern animated movie character portrait (similar to Pixar or Dreamworks style)

The white background is essential - the avatar will be composited onto a map."""

    print("🎨 Generating your portrait...")
    portrait_response = chat.send_message(portrait_prompt)
    
    # Extract the image from the response.
    # Gemini returns a response with multiple "parts" - we need to find the image part.
    portrait_image = None
    for part in portrait_response.candidates[0].content.parts:
        if part.inline_data is not None:
            # Found the image! Convert from bytes to PIL Image and save.
            image_bytes = part.inline_data.data
            portrait_image = Image.open(io.BytesIO(image_bytes))
            portrait_image.save("outputs/portrait.png")
            break
    
    if portrait_image is None:
        raise Exception("Failed to generate portrait - no image in response")
    
    print("✓ Portrait generated!")

مرحله ۳: ایجاد آیکون نقشه

MODULE_5_STEP_3_GENERATE_ICON را پیدا کنید و icon_image = None # Replace this section 

    # MODULE_5_STEP_3_GENERATE_ICON
    # Second turn: Generate a consistent icon for the map.
    # Because we're in the same chat session, Gemini remembers the character
    # from the portrait and will maintain visual consistency.
    icon_prompt = """Now create a circular map icon of this SAME character.

CRITICAL REQUIREMENTS:
- SAME person, SAME face, SAME expression, SAME suit — maintain perfect consistency with the portrait
- Tighter crop: just the head and very top of shoulders
- Background: Pure solid white (#FFFFFF)
- Optimized for small display sizes (will be used as a 64px map marker)
- Keep the exact same art style, colors, and lighting as the portrait
- Square 1:1 aspect ratio

This icon must be immediately recognizable as the same character from the portrait."""

    print("🖼️  Creating map icon...")
    icon_response = chat.send_message(icon_prompt)
    
    # Extract the icon image from the response
    icon_image = None
    for part in icon_response.candidates[0].content.parts:
        if part.inline_data is not None:
            image_bytes = part.inline_data.data
            icon_image = Image.open(io.BytesIO(image_bytes))
            icon_image.save("outputs/icon.png")
            break
    
    if icon_image is None:
        raise Exception("Failed to generate icon - no image in response")
    
    print("✓ Icon generated!")

کد تکمیل شده شما

بعد از اضافه کردن هر سه بخش، تابع generate_explorer_avatar() شما باید به شکل زیر باشد: 

def generate_explorer_avatar() -> dict:
    """
    Generate portrait and icon using multi-turn chat for consistency.
    
    The key technique here is using a CHAT SESSION rather than independent
    API calls. This allows Gemini to "remember" the character it created
    in the first turn, ensuring the icon matches the portrait.
    
    Returns:
        dict with portrait_path and icon_path
    """
    
    # MODULE_5_STEP_1_CREATE_CHAT_SESSION
    # Create a chat session to maintain character consistency across generations.
    # The chat session preserves context between turns, so Gemini "remembers"
    # what it generated and can create consistent variations.
    chat = client.chats.create(
        model="gemini-2.5-flash-image",  # Nano Banana - Gemini with image generation
        config=types.GenerateContentConfig(
            response_modalities=["TEXT", "IMAGE"]
        )
    )
    
    # MODULE_5_STEP_2_GENERATE_PORTRAIT
    # First turn: Generate the explorer portrait.
    # This establishes the character that will be referenced in subsequent turns.
    portrait_prompt = f"""Create a stylized space explorer portrait.

Character appearance: {APPEARANCE}
Name on suit patch: "{USERNAME}"
Suit color: {SUIT_COLOR}

CRITICAL STYLE REQUIREMENTS:
- Digital illustration style, clean lines, vibrant saturated colors
- Futuristic but weathered space suit with visible mission patches
- Background: Pure solid white (#FFFFFF) - absolutely no gradients, patterns, or elements
- Frame: Head and shoulders only, 3/4 view facing slightly left
- Lighting: Soft diffused studio lighting, no harsh shadows
- Expression: Determined but approachable
- Art style: Modern animated movie character portrait (similar to Pixar or Dreamworks style)

The white background is essential - the avatar will be composited onto a map."""

    print("🎨 Generating your portrait...")
    portrait_response = chat.send_message(portrait_prompt)
    
    # Extract the image from the response.
    # Gemini returns a response with multiple "parts" - we need to find the image part.
    portrait_image = None
    for part in portrait_response.candidates[0].content.parts:
        if part.inline_data is not None:
            # Found the image! Convert from bytes to PIL Image and save.
            image_bytes = part.inline_data.data
            portrait_image = Image.open(io.BytesIO(image_bytes))
            portrait_image.save("outputs/portrait.png")
            break
    
    if portrait_image is None:
        raise Exception("Failed to generate portrait - no image in response")
    
    print("✓ Portrait generated!")
    
    # MODULE_5_STEP_3_GENERATE_ICON
    # Second turn: Generate a consistent icon for the map.
    # Because we're in the same chat session, Gemini remembers the character
    # from the portrait and will maintain visual consistency.
    icon_prompt = """Now create a circular map icon of this SAME character.

CRITICAL REQUIREMENTS:
- SAME person, SAME face, SAME expression, SAME suit — maintain perfect consistency with the portrait
- Tighter crop: just the head and very top of shoulders
- Background: Pure solid white (#FFFFFF)
- Optimized for small display sizes (will be used as a 64px map marker)
- Keep the exact same art style, colors, and lighting as the portrait
- Square 1:1 aspect ratio

This icon must be immediately recognizable as the same character from the portrait."""

    print("🖼️  Creating map icon...")
    icon_response = chat.send_message(icon_prompt)
    
    # Extract the icon image from the response
    icon_image = None
    for part in icon_response.candidates[0].content.parts:
        if part.inline_data is not None:
            image_bytes = part.inline_data.data
            icon_image = Image.open(io.BytesIO(image_bytes))
            icon_image.save("outputs/icon.png")
            break
    
    if icon_image is None:
        raise Exception("Failed to generate icon - no image in response")
    
    print("✓ Icon generated!")
    
    return {
        "portrait_path": "outputs/portrait.png",
        "icon_path": "outputs/icon.png"
    }

فایل خود را ذخیره کنید

مطمئن شوید که generator.py را ذخیره کرده‌اید:

  • ویرایشگر Cloud Shell: Ctrl+S (ویندوز/لینوکس) یا Cmd+S (مک)
  • vim: کلید Escape را فشار دهید، سپس :wq تایپ کرده و Enter را بزنید.

چیزی که تازه ساختی

✓ ایجاد یک جلسه چت برای تولید تصویر چند نوبتی
✓ یک دستورالعمل دقیق برای تولید پرتره با محدودیت‌های سبک ایجاد کرد.
✓ با استفاده از متن مکالمه، یک آیکون نقشه ثابت ایجاد شد
✓ یادگیری تجزیه داده‌های تصویری از پاسخ‌های Gemini

مفاهیم کلیدی آموخته شده:

مفهوم آنچه آموختید
جلسات چت client.chats.create() ‎ زمینه را در چندین نوبت حفظ می‌کند.
روش‌های پاسخ ["TEXT", "IMAGE"] امکان تولید تصویر در پاسخ‌ها را فراهم می‌کند.
ساختار سریع موضوع → متغیرها → سبک → محدودیت‌های فنی
ثبات شخصیت جلسه چت یکسان = کاراکتر یکسان در تصاویر مختلف
تجزیه پاسخ استخراج تصاویر از inline_data در بخش‌های پاسخ

بعدی: کد خود را اجرا کنید و خودتان را روی نقشه ببینید!

تولید و ثبت

مدت زمان: ۲ دقیقه

شناسه پروژه خود را تنظیم کنید

مطمئن شوید که شناسه پروژه شما به عنوان یک متغیر محیطی در دسترس است: 

export GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)

اجرای سازنده هویت

اکنون اسکریپت اصلی را که تولید، آپلود و ثبت را هماهنگ می‌کند، اجرا کنید: 

python create_identity.py

پیشرفت تولید را به صورت بلادرنگ مشاهده خواهید کرد: 

🚀 Creating identity for AstroAyo...

🎨 Generating your portrait...
✓ Portrait generated!
🖼️  Creating map icon...
✓ Icon generated!

☁️  Uploading to mission database...
✓ Avatar uploaded!

📍 Registering with rescue network...
✓ Registration complete!

╔═══════════════════════════════════════════════════════════════╗
║                    ✅ IDENTITY CONFIRMED!                      ║
╠═══════════════════════════════════════════════════════════════╣
║                                                               ║
║  Explorer: AstroAyo                                           ║
║  Location: (47, 23) — unconfirmed                             ║
║                                                               ║
║  🗺️  You're now on the map!                                   ║
║  https://waybackhome.dev/e/devfest-nyc-26                     ║
║                                                               ║
║  NEXT: Proceed to Level 1 to pinpoint your exact location!   ║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝

آواتار ساخته شده خود را مشاهده کنید

تصاویر تولید شده خود را به صورت محلی بررسی کنید: 

# List the generated files
ls -la outputs/

# Download to view on your local machine
cloudshell download outputs/portrait.png
cloudshell download outputs/icon.png

یا با رفتن به پوشه outputs/ و کلیک روی فایل‌های تصویری، آنها را مستقیماً در ویرایشگر Cloud Shell مشاهده کنید.

تصویر و آیکون ایجاد شده چیزی شبیه به این تصاویر خواهد بود:

نمونه پرترهآیکون نمونه

خودتان را روی نقشه ببینید!

آدرس اینترنتی نقشه جهان که در خروجی شما نشان داده شده است را باز کنید:

https://waybackhome.dev/e/{your-event-code}

برای مثال: https://waybackhome.dev/e/devfest-nyc-26

آواتار خود را روی نقشه پیدا کنید! خواهید دید:

  • نماد شما که موقعیت شما را روی سطح سیاره نشان می‌دهد
  • نام کاوشگر شما به عنوان برچسبی در زیر آیکون شما
  • یک چراغ دریایی کم‌نور که به آرامی در اطراف نشانگر شما می‌چرخد

نمونه آواتار روی نقشه

برای دیدن تصویر کامل خود در کارت جزئیات، روی نشانگر خود کلیک کنید.

از آواتار خود راضی نیستید؟ دوباره متولد شوید!

اگر آواتار دیگری می‌خواهید، می‌توانید آن را بازسازی کنید: 

# Option 1: Change your appearance settings first
python customize.py

# Option 2: Just regenerate with current settings
python create_identity.py

هر بار که create_identity.py اجرا می‌کنید، یک آواتار کاملاً جدید (جلسه چت جدید = شخصیت جدید) ایجاد می‌کند و ثبت‌نام شما را به‌روزرسانی می‌کند. می‌توانید این کار را تا زمانی که از نتیجه راضی هستید، تکرار کنید!

عیب‌یابی

کاری که تازه تمام کردی

✓ پرتره کاوشگر منحصر به فرد خود را ایجاد کنید
✓ یک آیکون نقشه ثابت ایجاد کرد
✓ دارایی‌های آپلود شده در Mission Control
✓ هویت خود را در شبکه نجات ثبت کردید
✓ روی نقشه زنده جهان ظاهر شد!

تبریک می‌گویم، کاشف! شما اکنون در شبکه نجات هستید. چراغ راهنمای شما فعال است (هرچند کم‌نور)، و سایر بازماندگان می‌توانند شما را روی نقشه ببینند.

نتیجه‌گیری

مدت زمان: ۱ دقیقه

آنچه ساختید

تنها در 10 دقیقه، شما یک سیستم کامل تولید آواتار با استفاده از تولید تصویر هوش مصنوعی چند مرحله‌ای ایجاد کردید: 

┌─────────────────────────────────────────────────────────────┐
│                     Your Creation                            │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   📝 Input                       🖼️  Output                  │
│   ──────────                     ────────                    │
│   • Explorer name                • Stylized portrait         │
│   • Suit color                   • Consistent map icon       │
│   • Appearance description       • Live map presence         │
│                                                              │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   🧠 Techniques You Used                                     │
│   ──────────────────────                                     │
│   • Multi-turn chat sessions for character consistency      │
│   • Structured prompt engineering with style constraints    │
│   • Response parsing to extract generated images            │
│   • API integration for cloud registration                  │
│                                                              │
└─────────────────────────────────────────────────────────────┘

نکات کلیدی

درس چرا مهم است؟
جلسات چت، زمینه را حفظ می‌کنند ضروری برای تولید کاراکترهای سازگار در تصاویر متعدد بدون تغییر در رانش
ساختار سریع اهمیت دارد محدودیت‌های واضح (پس‌زمینه سفید، سبک خاص، قاب‌بندی) نتایج قابل پیش‌بینی و آماده برای تولید را ایجاد می‌کنند.
چند نوبتی، تماس‌های مستقل را شکست می‌دهد هر پیام در یک چت بر اساس زمینه قبلی ساخته می‌شود و امکان اصلاح و ثبات مکرر را فراهم می‌کند.
روش‌های پاسخ، خروجی را کنترل می‌کنند تنظیم ["TEXT", "IMAGE"] برای تولید تصویر الزامی است—بدون آن، فقط متن دریافت خواهید کرد

خلاصه هزینه

برای این مرحله، شما با استفاده از Gemini 2.5 Flash (Nano Banana) دو تصویر ایجاد کردید:

مورد توکن‌ها هزینه
پرتره (۱۰۲۴×۱۰۲۴) حدود ۱۲۹۰ توکن خروجی ۰.۰۳۹ دلار
آیکون (۱۰۲۴×۱۰۲۴) حدود ۱۲۹۰ توکن خروجی ۰.۰۳۹ دلار
مجموع حدود ۲۵۸۰ توکن ~۰.۰۸ دلار

سفر ادامه دارد

هویت کاوشگر شما تأیید شده است، اما مشکلی وجود دارد: مکان شما تأیید نشده است.

به نقشه جهان نگاه کنید - چراغ راهنمای شما کم نور است و به آرامی می‌تپد. شبکه نجات می‌داند که شما وجود دارید، اما دقیقاً نمی‌دانند کجا هستید. شما می‌توانید در هر نقطه‌ای از منطقه وسیعی از سطح سیاره باشید.

در سطح ۱: موقعیت مکانی خود را مشخص کنید ، شما:

  • ساخت یک سیستم چندعاملی با استفاده از کیت توسعه عامل گوگل (ADK)
  • ایجاد سرورهای MCP برای تجزیه و تحلیل زمین شناسی، گیاه شناسی و نجومی
  • پردازش ورودی چندوجهی (تصاویر از محل سقوط شما)
  • با استفاده از هوش مصنوعی، یک نقشه توپوگرافی از مکان تأیید شده خود ایجاد کنید
  • چراغ راهنمای خود را واقعاً روشن کنید - تا تیم‌های نجات بتوانند شما را پیدا کنند!

سطح ۱ مفاهیم بسیار پیشرفته‌تری را معرفی می‌کند: هماهنگی چندعاملی، پروتکل زمینه مدل (MCP) و الگوهای استقرار تولید. شما از استفاده از یک ویژگی مدل واحد به ساخت یک سیستم عامل کامل خواهید رسید.

تمیز کردن (اختیاری)

اگر می‌خواهید فایل‌های محلی را پاک کنید (از دایرکتوری level_0 اجرا کنید): 

rm -rf outputs/
rm ../config.json
deactivate  # Exit virtual environment

ثبت نام شما در شبکه نجات همچنان ادامه دارد—حتی پس از حذف فایل‌های محلی، همچنان روی نقشه ظاهر خواهید شد. تصاویر در فضای ابری ذخیره می‌شوند، نه به صورت محلی.

منابع

چراغ راهنمای شما منتظر تأیید است. در سطح ۱ می‌بینمت، کاشف. 🚀

جایزه: آواتار مبتنی بر عکس (اختیاری)

مدت زمان: ۳ دقیقه

چه زمانی از تبدیل عکس به آواتار استفاده کنیم؟

اگر موارد زیر را داشته باشید، ممکن است این رویکرد را ترجیح دهید:

  • شما می‌خواهید آواتارتان واقعاً شبیه خودتان باشد
  • شما یک عکس خاص دارید که می‌خواهید به آن استایل بدهید
  • شما می‌خواهید قابلیت‌های تبدیل تصویر به تصویر Gemini را بررسی کنید.

چگونه کار می‌کند؟

به جای اینکه صرفاً از روی توضیحات متنی، یک شخصیت بسازید، یک عکس ارائه می‌دهید و از Gemini می‌خواهید که آن را تغییر شکل دهد و در عین حال، شباهت شخصیت را حفظ کند:

جریان تبدیل عکس به آواتار

عکس خود را آپلود کنید

ابتدا، یک عکس در Cloud Shell آپلود کنید:

  1. در Cloud Shell، روی منوی سه نقطه (⋮) در نوار ابزار ترمینال کلیک کنید.
  2. آپلود را انتخاب کنید
  3. یک عکس پرتره واضح (JPEG یا PNG) انتخاب کنید
  4. به مسیر آپلود شده توجه کنید (مثلاً /home/your-username/my_photo.jpg )

ژنراتور را تغییر دهید

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

    # MODULE_5_STEP_2_GENERATE_PORTRAIT (Photo-based version)
    
    # Load your photo
    photo_path = "/home/your-username/my_photo.jpg"  # Update this path!
    user_photo = Image.open(photo_path)
    
    # Convert photo to bytes for the API
    photo_buffer = io.BytesIO()
    user_photo.save(photo_buffer, format="JPEG")
    photo_bytes = photo_buffer.getvalue()
    
    portrait_prompt = f"""Transform this person into a stylized space explorer portrait.

PRESERVE from the original photo:
- The person's facial features, face shape, and likeness
- Their general expression and personality
- Any distinctive features (glasses, facial hair, etc.)

TRANSFORM with this style:
- Digital illustration style, clean lines, vibrant saturated colors
- Add a futuristic space suit with the name "{USERNAME}" on a shoulder patch
- Suit color: {SUIT_COLOR}
- Background: Pure solid white (#FFFFFF) - no gradients or elements
- Frame: Head and shoulders, 3/4 view
- Lighting: Soft diffused studio lighting
- Art style: Modern animated movie character (Pixar/Dreamworks aesthetic)

The result should be clearly recognizable as THIS specific person, but illustrated as a heroic space explorer."""

    print("🎨 Transforming your photo into an explorer portrait...")
    
    # Send both the prompt AND the image
    portrait_response = chat.send_message([
        portrait_prompt,
        types.Part.from_bytes(data=photo_bytes, mime_type="image/jpeg")
    ])
    
    # Rest of the extraction code stays the same...

سازگاری چند نوبتی هنوز هم کار می‌کند

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

  • مرحله ۱ : عکس + سوال → پرتره استایل‌دار (تصویر شما، تصویرسازی شده)
  • مرحله ۲ : «آیکونی از این کاراکتر یکسان ایجاد کن» → آیکن ثابت

از آنجا که جلسه چت نسخه تغییر یافته‌ای را که ایجاد کرده است به خاطر می‌سپارد (نه عکس اصلی)، آیکون کاملاً با پرتره تغییر یافته مطابقت خواهد داشت.

ملاحظات حریم خصوصی

آن را در استودیوی هوش مصنوعی ورتکس امتحان کنید

همچنین می‌توانید قبل از نوشتن کد، به صورت تعاملی در کنسول ابری گوگل، تبدیل عکس را آزمایش کنید:

  1. به استودیوی هوش مصنوعی ورتکس بروید
  2. یک مدل Gemini با قابلیت تصویر انتخاب کنید
  3. عکس خود را با استفاده از دکمه پیوست آپلود کنید
  4. اعلان تبدیل را وارد کنید
  5. روی استایل تکرار کنید تا از نتیجه راضی شوید
  6. نتیجه را دانلود کنید و آن را با نام outputs/portrait.png ذخیره کنید.
  7. برای آپلود تصاویر تولید شده دستی، python create_identity.py --skip-generation (در صورت پشتیبانی از این پرچم) را اجرا کنید.

این رویکرد تعاملی برای آزمایش دستورالعمل‌ها و مشاهده نتایج به صورت بلادرنگ قبل از شروع کدنویسی عالی است!

آنچه آموختید (امتیاز ویژه)

✓ نحوه استفاده از تبدیل تصویر به تصویر با Gemini
✓ ارسال محتوای چندوجهی (متن + تصویر) در یک پیام واحد
✓ حفظ شباهت در عین انتقال سبک هنری
✓ ملاحظات حریم خصوصی برای تولید هوش مصنوعی مبتنی بر عکس