Way Back Home - Level 0: Identify Yourself

إشارة الاستغاثة

المدة: دقيقة واحدة

العنوان

تخترق مركبة النجاة غلافًا جويًا لعالم مجهول. تومض أضواء التحذير على كل لوحة. تعطّل نظام الملاحة. تعطّلت وسائل الاتصال. عندما يتم تفعيل بروتوكولات الطوارئ في المركبة، يبدأ مساعد الذكاء الاصطناعي بالعمل:

تم رصد ناجٍ. تم الهبوط الاضطراري بنجاح. جارٍ بدء بروتوكول إشارة الاستغاثة..."

"تحذير: يجب إثبات الهوية. لا يمكن لشبكة الإنقاذ الكونية تحديد موقع المستكشفين غير المسجّلين. يُرجى تأكيد هويتك لتفعيل جهاز الإرسال."

يمكنك النظر من خلال إطار العرض. تمتد المناظر الطبيعية الغريبة إلى الأفق، وتتضمّن تشكيلات صخرية غريبة ونباتات غير مألوفة وسماء ذات لون غريب. في مكان ما على سطح هذا الكوكب، ينتشر ناجون آخرون من مهمتك.

لكن قبل كل شيء، يجب أن يكون لديك حساب في النظام.

ما ستنشئه

في هذا المستوى، ستنشئ هوية فريدة لمستكشف الفضاء باستخدام إنشاء الصور المتعددة الجولات باستخدام نماذج إنشاء الصور من Gemini من Google (المعروفة أيضًا باسم Nano Banana 🍌). سيظهر الأفاتار الخاص بك على خريطة الإنقاذ العالمية، وسيكون مرئيًا لجميع الناجين الآخرين في ورشة العمل.

الهندسة المعمارية

ما ستتعلمه

الفكرة الوصف
إنشاء الصور في عدة مراحل كيفية الحفاظ على اتساق الشخصية في مختلف الصور التي يتم إنشاؤها باستخدام جلسات المحادثة
هندسة الطلبات لإنشاء الصور صياغة طلبات فعّالة للحصول على ردود متسقة ومصمَّمة بأسلوب معيّن مع مراعاة قيود محدّدة
Gemini Image API (Nano Banana) استخدام إمكانات إنشاء الصور الأصلية في Gemini من خلال حزمة تطوير البرامج (SDK) الخاصة بلغة Python
جلسات المحادثة الاستفادة من سياق المحادثة لتحسين المحتوى بشكل متكرّر والحفاظ على اتساق الشخصية

في نهاية هذا المستوى، ستكون قد:

✅ إنشاء صورة شخصية للمستكشف باستخدام الذكاء الاصطناعي لتحويل النص إلى صورة
✅ إنشاء رمز خريطة متسق باستخدام المحادثات المتعددة
✅ تسجيل هويتك في شبكة الإنقاذ
✅ الظهور على خريطة العالم المباشرة إلى جانب مستكشفين آخرين

لنضعك على الخريطة! 📍

إعداد البيئة

المدة: دقيقتان

الوصول إلى Cloud Shell

أولاً، سنفتح Cloud Shell، وهي وحدة طرفية مستندة إلى المتصفّح مع تثبيت مسبق لحزمة تطوير البرامج (SDK) من Google Cloud وأدوات أساسية أخرى.

هل تحتاج إلى أرصدة Google Cloud؟

• إذا كنت تحضر ورشة عمل بإشراف معلّم: سيقدّم لك المعلّم رمز رصيد. يُرجى استخدام الرمز الذي يقدّمونه.
• إذا كنت تعمل على هذا الدرس التطبيقي بنفسك: يمكنك الاستفادة من رصيد مجاني على Google Cloud لتغطية تكاليف ورشة العمل. يُرجى النقر على هذا الرابط للحصول على رصيد واتّباع الخطوات الواردة في دليل الفيديو أدناه لتطبيقه على حسابك.
مشاهدة الفيديو

انقر على تفعيل Cloud Shell في أعلى Google Cloud Console (رمز الوحدة الطرفية في شريط التنقّل أعلى يسار الصفحة).

cloud shell

ابحث عن رقم تعريف مشروعك على Google Cloud باتّباع الخطوات التالية:

  • افتح Google Cloud Console: 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

تفعيل واجهات برمجة التطبيقات المطلوبة

فعِّل واجهة برمجة التطبيقات 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

تثبيت الحِزم التابعة

انتقِل إلى المستوى 0 وثبِّت حِزم Python المطلوبة:

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

تشمل التبعيات الرئيسية ما يلي:

الحزمة الغرض
google-genai أداة Gemini API لإنشاء الصور
requests برنامج HTTP للتعامل مع طلبات البيانات من واجهة برمجة التطبيقات إلى 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!

ما أكملته للتو

✅ فتح Cloud Shell
✅ إعداد مشروعك على Google Cloud
✅ تفعيل واجهات برمجة تطبيقات Vertex AI
✅ استنساخ مستودع نموذج التعليمات البرمجية
✅ تثبيت التبعيات في Python
✅ التحقّق من الإعداد

الخطوة التالية: الاتصال بـ "مركز القيادة" والمطالبة باسم المستكشف

الاتصال بـ Mission Control

المدة: دقيقتان

تشغيل نص الإعداد البرمجي

يتم ربطك بشبكة الإنقاذ Way Back Home من خلال نص الإعداد البرمجي، كما يتم حجز هوية المستكشف الخاصة بك. نفِّذها من جذر المشروع:

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

سيُطلب منك تقديم معلوماتَين.

أدخِل رمز الحدث

يحدّد رمز الحدث حدث ورشة العمل الذي تشارك فيه.

إذا كنت في ورشة عمل: أدخِل رمز الحدث من رمز الاستجابة السريعة أو الشريحة أو معلّم ورشة العمل.

🚀 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

انتقِل الآن إلى الدليل Level 0 (تم تثبيت التبعيات مسبقًا من الوحدة 2):

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"
}

سيتم استخدام ملف الإعداد هذا من خلال النصوص البرمجية اللاحقة للتعرّف عليك في شبكة الاسترداد.

ما أكملته للتو

✓ تم الربط بواجهة برمجة التطبيقات Mission Control
✓ تم حجز اسم المستكشف الفريد
✓ تم استلام رقم تعريف المشارك والإحداثيات الأولية
✓ تم حفظ الإعدادات للخطوات اللاحقة

التالي: تخصيص مظهر المستكشف

تخصيص "المستكشف"

المدة: دقيقة واحدة

تشغيل "نص التخصيص البرمجي"

قبل إنشاء الأفاتار، عليك اتّخاذ بعض القرارات بشأن مظهر المستكشف:

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"
}

ما أكملته للتو

✓ اختيار لون البدلة
✓ تحديد مظهر المستكشف
✓ إعدادات جاهزة لإنشاء الصور

التالي: الحدث الرئيسي، أي كتابة رمز إنشاء الصورة.

إنشاء أداة إنشاء الأفاتار

المدة: 4 دقائق

هذه هي وحدة التعلّم الأساسية. ستكتب رمز Python البرمجي الذي ينشئ الصورة الرمزية الفريدة الخاصة بك باستخدام إمكانات إنشاء الصور المتعددة الجولات في Gemini (Nano Banana).

فتح ملف أداة الإنشاء

افتح أداة إنشاء الصور الرمزية في "محرِّر Cloud Shell":

cloudshell edit generator.py

أو انقر على فتح المحرِّر في 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 الثلاثة بعملية التنفيذ.

الخطوة 1: إنشاء جلسة المحادثة

ابحث عن العنصر النائب 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"]
        )
    )

الخطوة 2: إنشاء صورة الوضع العمودي

ابحث عن 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!")

الخطوة 3: إنشاء رمز الخريطة

ابحث عن 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 (في نظام التشغيل Windows أو Linux) أو Cmd+S (في نظام التشغيل Mac)
  • vim: اضغط على Escape، ثم اكتب :wq واضغط على Enter

ما أنشأته للتو

✓ إنشاء جلسة محادثة لإنشاء صور متعددة
✓ إنشاء طلب مفصّل لإنشاء صور شخصية مع قيود على الأسلوب
✓ إنشاء رمز خريطة متسق باستخدام سياق المحادثة
✓ تعلُّم كيفية تحليل بيانات الصور من ردود Gemini

المفاهيم الأساسية التي تم إتقانها:

الفكرة ما تعلّمته
جلسات المحادثة تحافظ client.chats.create() على السياق خلال عدة محادثات
طُرق الرد تتيح ["TEXT", "IMAGE"] إنشاء الصور في الردود
بنية الطلب الموضوع → المتغيّرات → النمط → القيود الفنية
اتساق الشخصيات جلسة المحادثة نفسها = الشخصية نفسها في جميع الصور
تحليل الاستجابة استخراج الصور من inline_data في أجزاء الردود

التالي: شغِّل الرمز واطّلِع على موقعك الجغرافي على الخريطة.

إنشاء وتسجيل

المدة: دقيقتان

تحديد رقم تعريف مشروعك

تأكَّد من توفّر رقم تعريف مشروعك كمتغيّر بيئة:

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

تشغيل أداة Identity Creator

الآن، شغِّل النص البرمجي الرئيسي الذي ينسّق عملية الإنشاء والتحميل والتسجيل:

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

أو يمكنك عرضها مباشرةً في Cloud Shell Editor من خلال الانتقال إلى المجلد outputs/ والنقر على ملفات الصور.

ستبدو الصورة الشخصية والرمز اللذان تم إنشاؤهما كما في الصور التالية:

مثال على صورة عمودية رمز المثال

مشاهدة نفسك على الخريطة

افتح عنوان URL الخاص بخريطة العالم المعروض في الناتج:

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، يتم إنشاء صورة رمزية جديدة تمامًا (جلسة محادثة جديدة = شخصية جديدة) ويتم تعديل تسجيلك. يمكنك تكرار العملية إلى أن تحصل على النتيجة التي تريدها.

تحديد المشاكل وحلّها

ما أكملته للتو

✓ إنشاء صورة فريدة للمستكشف
✓ إنشاء رمز متسق للخريطة
✓ تحميل مواد العرض إلى "مركز التحكّم"
✓ تسجيل هويتك في شبكة الإنقاذ
✓ الظهور على خريطة العالم المباشرة

تهانينا، أيها المستكشف! أنت الآن جزء من شبكة الإنقاذ. يكون جهاز التتبُّع نشطًا (وإن كان ضوؤه خافتًا)، ويمكن للناجين الآخرين رؤيتك على الخريطة.

الخاتمة

المدة: دقيقة واحدة

ما أنشأته

في غضون 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):

العنصر الرموز المميزة التكلفة
الوضع العمودي (1024×1024) ‫~1,290 رمزًا مميزًا للناتج ‫~$0.039
الرمز (1024×1024) ‫~1,290 رمزًا مميزًا للناتج ‫~$0.039
الإجمالي ‫~2,580 رمزًا مميزًا 0.08 دولار أمريكي تقريبًا

تتواصل الرحلة

تم تأكيد هوية المستكشف، ولكن هناك مشكلة: لم يتم تأكيد موقعك الجغرافي.

انظر إلى خريطة العالم، ستجد أنّ جهاز التتبّع الخاص بك يومض ببطء وبضوء خافت. تعرف شبكة الإنقاذ أنّك موجود، ولكنّها لا تعرف مكانك بالتحديد. قد تكون متواجدًا في أي مكان ضمن منطقة واسعة من سطح الكوكب.

في المستوى 1: تحديد موقعك الجغرافي، عليك إجراء ما يلي:

  • إنشاء نظام متعدد الوكلاء باستخدام "حزمة تطوير الوكلاء" (ADK) من Google
  • إنشاء خوادم MCP للتحليل الجيولوجي والنباتي والفلكي
  • معالجة الإدخال المتعدد الوسائط (الصور من موقع الحادث)
  • إنشاء خريطة طبوغرافية لموقعك الجغرافي المؤكَّد باستخدام الذكاء الاصطناعي
  • أضئ جهاز الإرسال والاستقبال لكي تتمكّن فِرق الإنقاذ من العثور عليك.

يقدّم المستوى 1 مفاهيم أكثر تقدّمًا بشكلٍ كبير، مثل التنسيق بين عدّة وكلاء، وبروتوكول سياق النموذج (MCP)، وأنماط نشر الإنتاج. ستنتقل من استخدام ميزة نموذج واحد إلى إنشاء نظام كامل يعتمد على الوكلاء.

التنظيف (اختياري)

إذا كنت تريد تنظيف الملفات المحلية (يتم التشغيل من الدليل level_0):

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

سيظل تسجيلك في شبكة الإنقاذ ساريًا، وستبقى معلوماتك ظاهرة على الخريطة حتى بعد حذف الملفات المحلية. يتم تخزين الصور في السحابة الإلكترونية، وليس على الجهاز.

الموارد

جهاز التتبّع بانتظار التأكيد. نراك في المستوى 1، أيها المستكشف. 🚀

ميزة إضافية: الأفاتار المستند إلى الصور (اختيارية)

المدة: 3 دقائق

حالات استخدام ميزة "تحويل الصورة إلى أفاتار"

قد تفضّل هذا النهج في الحالات التالية:

  • أن يكون الأفاتار مشابهاً لك
  • لديك صورة معيّنة تريد تطبيق أسلوب عليها
  • تريد استكشاف قدرات 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: "أنشئ رمزًا لهذا الشخص نفسه" → رمز متسق

بما أنّ جلسة المحادثة تتذكّر النسخة المعدَّلة التي أنشأتها (وليس الصورة الأصلية)، سيتطابق الرمز تمامًا مع الصورة الشخصية المحوَّلة.

اعتبارات الخصوصية

تجربة الميزة في Vertex AI Studio

يمكنك أيضًا تجربة تحويل الصور بشكل تفاعلي في Google Cloud Console قبل كتابة الرمز:

  1. انتقِل إلى Vertex AI Studio.
  2. اختيار نموذج Gemini يتضمّن ميزات مرتبطة بالصور
  3. حمِّل صورتك باستخدام زر المرفقات
  4. أدخِل طلب التحويل
  5. كرِّر ذلك إلى أن تحصل على النتيجة المطلوبة
  6. نزِّل النتيجة واحفظها بتنسيق outputs/portrait.png.
  7. استخدِم الأمر Run: python create_identity.py --skip-generation (إذا كان هذا الخيار متاحًا) لتحميل الصور التي تم إنشاؤها يدويًا.

هذه الطريقة التفاعلية رائعة لتجربة الطلبات ورؤية النتائج في الوقت الفعلي قبل الالتزام بالرمز.

ما تعلّمته (مكافأة)

✓ كيفية استخدام ميزة تحويل الصور باستخدام Gemini
✓ إرسال محتوى متعدد الوسائط (نص + صورة) في رسالة واحدة
✓ الحفاظ على التشابه عند تطبيق ميزة نقل الأنماط الفنية
✓ اعتبارات الخصوصية المتعلقة بالإنشاء المستند إلى الذكاء الاصطناعي