🤖 ساختن «عامل هوشواره‌ای چندحالتی» با Graph RAG،‏ ADK، و Memory Bank

۱. مقدمه

بازخوانی شده

۱. چالش

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

  1. 🗄️ پایگاه داده گراف (Spanner): روابط پیچیده بین بازماندگان، مهارت‌ها، و منابع را ذخیره کنید
  2. 🔍 جستجوی هوشواره‌ای: جستجوی ترکیبی معنایی + کلیدواژه بااستفاده از جاسازی‌ها
  3. 📸 پردازش چندحالتی: استخراج داده‌های ساختاریافته از تصاویر، نوشتار، و ویدیو
  4. 🤖 هماهنگ‌سازی چندعاملی: هماهنگ کردن عامل‌های تخصصی برای گردش کارهای پیچیده
  5. 🧠 حافظه بلندمدت: شخصی‌سازی با «بانک حافظه Vertex AI»

مکالمه

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

پایگاه داده گراف شبکه بازماندگان با:

  • 🗺️ مصورسازی گراف تعاملی سه‌بعدی از روابط بازماندگان
  • 🔍 جستجوی هوشمند (کلیدواژه، معنایی، و ترکیبی)
  • 📸 خط لوله بارگذاری چندحالته (استخراج نهادها از تصاویر/ویدیو)
  • 🤖 سیستم چندعاملی برای هماهنگ‌سازی تکالیف پیچیده
  • 🧠 ادغام Memory Bank برای تعاملات شخصی‌سازی‌شده

۳. فناوری‌های اصلی

مؤلفه

فناوری

هدف

پایگاه داده

Cloud Spanner Graph

گره‌ها (بازماندگان، مهارت‌ها) و لبه‌ها (روابط) را ذخیره کنید

جستجوی هوشواره‌ای

Gemini + Embeddings

درک معنایی + جستجوی شباهت

چارچوب عامل

ADK (کیت توسعه عامل)

هماهنگ‌سازی گردش کارهای هوش مصنوعی

خاطره

Vertex AI Memory Bank

فضای ذخیره‌سازی اولویت کاربر بلندمدت

Frontend

React + Three.js

مصورسازی گراف سه‌بعدی تعاملی

۲. 🛠️ آماده‌سازی محیط (اگر در کارگاه هستید، رد شوید)

بخش یک: فعال کردن حساب صورت‌حساب

برای اجرای این codelab، به حساب صورت‌حساب با مقداری اعتبار نیاز دارید. برای شروع، از اعتبارهای موجود در برنمای بالای این codelab استفاده کنید. اگر ازقبل به حساب صورت‌حساب متصل شده‌اید، می‌توانید از این مرحله رد شوید.

بخش دوم: محیط باز

  1. 👉 برای رفتن مستقیم به ویرایشگر Cloud Shell، روی این پیوند کلیک کنید
  2. 👉 اگر امروز در هر مرحله‌ای از شما خواسته شد که مجوز بدهید، برای ادامه دادن روی مجاز کردن کلیک کنید. برای صدور مجوز Cloud Shell کلیک کنید
  3. 👉 اگر پایانه در پایین صفحه نشان داده نمی‌شود، آن را باز کنید:
    • روی مشاهده کلیک کنید
    • روی پایانه کلیک کنیدباز کردن پایانه جدید در «ویرایشگر Cloud Shell»
  4. 👉💻 در پایانه، بااستفاده از فرمان زیر، تأیید کنید که قبلاً اصالت‌سنجی شده‌اید و پروژه روی شناسه پروژه شما تنظیم شده است:
    gcloud auth list
    
  5. 👉💻 پروژه راه‌اندازی را از GitHub همانندسازی کنید:
    git clone https://github.com/gca-americas/way-back-home.git
    

بخش سوم: ایجاد پروژه جدید

👉💻 در پایانه، دستورگان init را اجرایی کنید و آن را اجرا کنید:

cd ~/way-back-home/level_2
./init.sh

۳. 🛠️ راه‌اندازی محیط

۱. باز کردن Cloud Shell

در پایانه ویرایشگر Cloud Shell، اگر پایانه در پایین صفحه نشان داده نمی‌شود، آن را باز کنید:

  • روی مشاهده کلیک کنید
  • روی پایانه کلیک کنید.

باز کردن پایانه جدید در «ویرایشگر Cloud Shell»

۲. پیکربندی پروژه

👉💻 در پایانه، شناسه پروژه را تنظیم کنید:

gcloud config set project $(cat ~/project_id.txt) --quiet

👉💻 میاناهای برنامه‌سازی کاربردی لازم را فعال کنید (این کار حدود ۲ تا ۳ دقیقه طول می‌کشد):

gcloud services enable compute.googleapis.com \
                       aiplatform.googleapis.com \
                       run.googleapis.com \
                       cloudbuild.googleapis.com \
                       artifactregistry.googleapis.com \
                       spanner.googleapis.com \
                       storage.googleapis.com

۳. اجرای دستورگان راه‌اندازی

👉💻 دستورگان راه‌اندازی را اجرا کنید:

cd ~/way-back-home/level_2
./setup.sh

با این کار، .env برای شما ایجاد می‌شود. در cloudshell، پروژه way_back_home را باز کنید. در پوشه level_2، می‌توانید ببینید که فایل .env برای شما ایجاد شده است. اگر نمی‌توانید آن را پیدا کنید، می‌توانید روی View -> Toggle Hidden File کلیک کنید تا آن را ببینید. open_project

۴. بار کردن داده‌های نمونه‌گیری‌شده

👉💻 به پس‌زمینه بروید و وابستگی‌ها را نصب کنید:

cd ~/way-back-home/level_2/backend
uv sync

👉💻 بار کردن داده‌های اولیه بازمانده:

uv run python ~/way-back-home/level_2/backend/setup_data.py

این کار موارد زیر را ایجاد می‌کند:

  • نمونه Spanner‏ (survivor-network)
  • پایگاه داده (graph-db)
  • همه جدول‌های گره و لبه
  • گراف‌های دارایی برای پُرسمان برونداد موردانتظار:
============================================================
SUCCESS! Database setup complete.
============================================================

Instance:  survivor-network
Database:  graph-db
Graph:     SurvivorGraph

Access your database at:
https://console.cloud.google.com/spanner/instances/survivor-network/databases/graph-db?project=waybackhome

اگر روی پیوند بعداز Access your database at در خروجی کلیک کنید، می‌توانید Google Cloud Console Spanner را باز کنید.

open_spanner

و Spanner را در Google Cloud Console خواهید دید!

آچار

۴. 🚀 دیداری‌سازی کردن داده‌های نمودار در Spanner Studio

این راهنما به شما کمک می‌کند تا بااستفاده از Spanner Studio، داده‌های گراف Survivor Network را مستقیماً در «کنسول Google Cloud» تجسم کنید و با آن‌ها تعامل داشته باشید. این روشی عالی برای درستی‌سنجی داده‌ها و درک ساختار نمودار قبل‌از ساختن عامل هوش مصنوعی است.

۱. دسترسی به Spanner Studio

  1. در مرحله آخر، حتماً روی پیوند کلیک کنید و Spanner Studio را باز کنید.

spanner_studio

۲. درک ساختار نمودار («تصویر کلی»)

مجموعه داده Survivor Network را به‌عنوان یک معمای منطقی یا یک وضعیت بازی درنظر بگیرید:

نهاد

نقش در سیستم

قیاس

Survivors

عامل‌ها/بازیکنان

بازیکنان

Biomes

مکان آن‌ها

مناطق نقشه

مهارت‌ها

کارهایی که می‌توانند انجام دهند

توانایی‌ها

نیازها

آنچه ندارند (بحران‌ها)

مأموریت‌ها/ مأموریت‌ها

منابع

موارد یافت‌شده در جهان

غارت کردن

هدف: وظیفه عامل هوش مصنوعی این است که با درنظر گرفتن زیست‌بوم‌ها (محدودیت‌های مکان)، مهارت‌ها (راه‌حل‌ها) را به نیازها (مشکلات) متصل کند.

🔗 لبه‌ها (روابط):

  • ‫SurvivorInBiome: ردگیری مکان
  • SurvivorHasSkill: فهرست توانایی‌ها
  • ‫SurvivorHasNeed: فهرست مشکلات فعال
  • ‫SurvivorFoundResource: سیاهه موارد
  • SurvivorCanHelp: رابطه استنباط‌شده (هوش مصنوعی این را محاسبه می‌کند!)

۳. درحال پُرسمان گراف

بیایید چند پُرسمان اجرا کنیم تا «داستان» را در داده‌ها ببینیم.

‫Spanner Graph از GQL (Graph Query Language) استفاده می‌کند. برای اجرای پرسمان، از GRAPH SurvivorNetwork و سپس الگوی مطابقت استفاده کنید.

👉 پرس‌وجو ۱: فهرست جهانی (چه کسی کجاست؟) این پایه شما است - درک مکان برای عملیات نجات حیاتی است.

GRAPH SurvivorNetwork
MATCH result = (s:Survivors)-[:SurvivorInBiome]->(b:Biomes)
RETURN TO_JSON(result) AS json_result

انتظار می‌رود نتیجه به‌صورت زیر باشد: query1

👉 پرس‌وجو ۲: ماتریس مهارت (توانایی‌ها) اکنون که می‌دانید همه کجا هستند، ببینید چه کارهایی می‌توانند انجام دهند.

GRAPH SurvivorNetwork
MATCH result = (s:Survivors)-[h:SurvivorHasSkill]->(k:Skills)
RETURN TO_JSON(result) AS json_result

انتظار می‌رود نتیجه به‌صورت زیر باشد: query2

👉 پُرسمان ۳: چه کسی در بحران است؟ («تابلو مأموریت») بازماندگانی را که به کمک نیاز دارند و آنچه را که نیاز دارند ببینید.

GRAPH SurvivorNetwork
MATCH result = (s:Survivors)-[h:SurvivorHasNeed]->(n:Needs)
RETURN TO_JSON(result) AS json_result

انتظار می‌رود نتیجه به‌صورت زیر باشد: query3

🔎 [اختیاری] همسان‌سازی - چه کسی می‌تواند به چه کسی کمک کند؟

اینجا است که نمودار قدرتمند می‌شود! این پُرسمان بازماندگانی را پیدا می‌کند که مهارت‌هایی برای درمان نیازهای بازماندگان دیگر دارند.

GRAPH SurvivorNetwork
MATCH result = (helper:Survivors)-[:SurvivorHasSkill]->(skill:Skills)-[:SkillTreatsNeed]->(need:Needs)<-[:SurvivorHasNeed]-(helpee:Survivors)
RETURN TO_JSON(result) AS json_result

انتظار می‌رود نتیجه به‌صورت زیر باشد: query4

aside positive What This Query Does:

این پُرسمان به‌جای اینکه فقط «کمک‌های اولیه سوختگی را درمان می‌کند» (که از طرح‌واره مشخص است) را نشان دهد، موارد زیر را پیدا می‌کند:

  • دکتر النا فراست (که آموزش پزشکی دیده است) ← می‌تواند درمان کند ← کاپیتان تاناکا (که دچار سوختگی شده است)
  • دیوید چن (که کمک‌های اولیه بلد است) → می‌تواند درمان کند → ستوان پارک (که مچ پایش پیچ خورده است)

چرا این ویژگی قدرتمند است:

عامل هوش مصنوعی شما چه کاری انجام خواهد داد:

وقتی کاربری می‌پرسد «چه کسی می‌تواند سوختگی را درمان کند؟»، عامل:

  1. اجرای پُرسمان گراف مشابه
  2. برمی‌گرداند: «دکتر فراست آموزش پزشکی دیده است و می‌تواند به کاپیتان تاناکا کمک کند»
  3. کاربر نیازی به دانستن درباره جدول‌ها یا روابط واسط ندارد!

۵. 🚀 جاسازی‌های با پشتیبانی هوش مصنوعی در Spanner

۱. چرا جاسازی‌ها؟ (بدون کنش، فقط خواندنی)

در سناریو بقا، زمان حیاتی است. وقتی بازمانده‌ای وضعیت اضطراری‌ای مثل I need someone who can treat burns یا Looking for a medic را گزارش می‌کند، نمی‌تواند وقتش را برای حدس زدن نام دقیق مهارت‌ها در پایگاه داده تلف کند.

سناریو واقعی: بازمانده: Captain Tanaka has burns—we need medical help NOW!

جستجوی کلیدواژه سنتی برای «medic» ← ۰ نتیجه ❌

جستجوی معنایی با جاسازی‌ها ← «آموزش پزشکی»، «کمک‌های اولیه» را پیدا می‌کند ✅

این دقیقاً همان چیزی است که نمایندگان نیاز دارند: جستجوی هوشمند و شبیه انسان که قصد را درک می‌کند، نه فقط کلیدواژه‌ها را.

۲. ایجاد مدل جاسازی

spanner_embedding

اکنون بیایید مدلی ایجاد کنیم که بااستفاده از text-embedding-004 Google، نوشتار را به جاسازی تبدیل می‌کند.

👉 در Spanner Studio، این SQL را اجرا کنید ($YOUR_PROJECT_ID را با شناسه پروژه واقعی‌تان جایگزین کنید):

‼️ در ویرایشگر Cloud shell،‏ File -> Open Folder -> way-back-home/level_2 را باز کنید تا کل پروژه را ببینید.

project_id

👉 این پُرسمان را با کپی و جای‌گذاری کردن پُرسمان زیر در Spanner Studio اجرا کنید و سپس روی دکمه «اجرا» کلیک کنید:

CREATE OR REPLACE MODEL TextEmbeddings
INPUT(content STRING(MAX))
OUTPUT(embeddings STRUCT<values ARRAY<FLOAT32>>)
REMOTE OPTIONS (
    endpoint = '//aiplatform.googleapis.com/projects/$YOUR_PROJECT_ID/locations/us-central1/publishers/google/models/text-embedding-004'
);

این تنظیم چه کاری انجام می‌دهد:

  • یک مدل مجازی در Spanner ایجاد می‌کند (هیچ وزن مدلی به‌صورت محلی ذخیره نمی‌شود)
  • به text-embedding-004 Google در Vertex AI اشاره می‌کند
  • قرارداد را تعریف می‌کند: ورودی نوشتار است، برونداد آرایه اعشاری ۷۶۸ بعدی است

چرا «گزینه‌های ازراه‌دور»؟

  • Spanner خودش مدل را اجرا نمی‌کند
  • وقتی از ML.PREDICT استفاده می‌کنید، Vertex AI را ازطریق میانای برنامه‌سازی کاربردی فراخوانی می‌کند
  • Zero-ETL: نیازی به صادر کردن داده‌ها به Python، پردازش، و وارد کردن مجدد نیست

روی دکمه Run کلیک کنید، پس‌از موفقیت، می‌توانید نتیجه را به‌صورت زیر ببینید:

spanner_result

۳. افزودن ستون جاسازی

👉 ستونی برای ذخیره جاسازی‌ها اضافه کنید:

ALTER TABLE Skills ADD COLUMN skill_embedding ARRAY<FLOAT32>;

روی دکمه Run کلیک کنید، پس‌از موفقیت، می‌توانید نتیجه را به‌صورت زیر ببینید:

embedding_result

۴. تولید کردن جاسازی‌ها

👉 از هوش مصنوعی برای ایجاد جاسازی‌های برداری برای هر مهارت استفاده کنید:

UPDATE Skills
SET skill_embedding = (
    SELECT embeddings.values
    FROM ML.PREDICT(
        MODEL TextEmbeddings,
        (SELECT name AS content)
    )
)
WHERE skill_embedding IS NULL;

روی دکمه Run کلیک کنید، پس‌از موفقیت، می‌توانید نتیجه را به‌صورت زیر ببینید:

skills_result

چه اتفاقی می‌افتد: هر نام مهارت (برای مثال، «کمک‌های اولیه») به یک بردار ۷۶۸ بعدی تبدیل می‌شود که نشان‌دهنده معنای معنایی آن است.

۵. درستی‌سنجی جاسازی‌ها

👉 بررسی کنید که جاسازی‌ها ایجاد شده باشند:

SELECT 
    skill_id,
    name,
    ARRAY_LENGTH(skill_embedding) AS embedding_dimensions
FROM Skills
LIMIT 5;

برونداد موردانتظار:

spanner_result

اکنون مورد استفاده دقیق سناریو خود را آزمایش می‌کنیم: یافتن مهارت‌های پزشکی بااستفاده از اصطلاح «پزشک».

👉 مهارت‌های مشابه «پزشک» را پیدا کن:

WITH query_embedding AS (
    SELECT embeddings.values AS val
    FROM ML.PREDICT(MODEL TextEmbeddings, (SELECT "medic" AS content))
)
SELECT
    s.name AS skill_name,
    s.category,
    COSINE_DISTANCE(s.skill_embedding, (SELECT val FROM query_embedding)) AS distance
FROM Skills AS s
WHERE s.skill_embedding IS NOT NULL
ORDER BY distance ASC
LIMIT 10;
  • عبارت جستجوی کاربر «medic» را به جاسازی تبدیل می‌کند
  • آن را در جدول موقت query_embedding ذخیره می‌کند

نتایج موردانتظار (فاصله کمتر = شباهت بیشتر):

spanner_result

‫۷. ایجاد مدل Gemini برای تجزیه‌وتحلیل

spanner_gemini

👉 یک مرجع مدل هوش مصنوعی زایا ایجاد کنید ($YOUR_PROJECT_ID را با شناسه پروژه واقعی خود جایگزین کنید):

CREATE OR REPLACE MODEL GeminiPro
INPUT(prompt STRING(MAX))
OUTPUT(content STRING(MAX))
REMOTE OPTIONS (
    endpoint = '//aiplatform.googleapis.com/projects/$YOUR_PROJECT_ID/locations/us-central1/publishers/google/models/gemini-2.5-pro',
    default_batch_size = 1
);

تفاوت با مدل جاسازی:

  • جاسازی‌ها: نوشتار ← بردار (برای جستجوی شباهت)
  • Gemini: نوشتار ← نوشتار تولیدشده (برای استدلال/ تحلیل)

spanner_result

‫۸. استفاده از Gemini برای «تحلیل سازگاری»

👉 جفت‌های بازمانده را برای سازگاری با مأموریت تجزیه‌وتحلیل کنید:

WITH PairData AS (
    SELECT
        s1.name AS Name_A,
        s2.name AS Name_B,
        CONCAT(
            "Assess compatibility of these two survivors for a resource-gathering mission. ",
            "Survivor 1: ", s1.name, ". ",
            "Survivor 2: ", s2.name, ". ",
            "Give a score from 1-10 and a 1-sentence reason."
        ) AS prompt
    FROM Survivors s1
    JOIN Survivors s2 ON s1.survivor_id < s2.survivor_id
    LIMIT 1
)
SELECT
    Name_A,
    Name_B,
    content AS ai_assessment
FROM ML.PREDICT(
    MODEL GeminiPro,
    (SELECT Name_A, Name_B, prompt FROM PairData)
);

برونداد موردانتظار:

Name_A          | Name_B            | ai_assessment
----------------|-------------------|----------------
"David Chen"    | "Dr. Elena Frost" | "**Score: 9/10** Their compatibility is extremely high as David's practical, hands-on scavenging skills are perfectly complemented by Dr. Frost's specialized knowledge to identify critical medical supplies and avoid biological hazards."

‫۶. 🚀 ساختن Graph RAG Agent با Hybrid Search

۱. نمای کلی معماری سیستم

این بخش یک سیستم جستجوی چندروشی می‌سازد که به نماینده شما انعطاف‌پذیری می‌دهد تا انواع مختلف پُرسمان‌ها را مدیریت کند. این سیستم سه لایه دارد: لایه عامل، لایه ابزار، لایه سرویس.

architecture_hybrid_search

چرا سه لایه؟

  • جداسازی نگرانی‌ها: عامل بر قصد، ابزارها بر میانجی، و سرویس بر پیاده‌سازی تمرکز دارد
  • انعطاف‌پذیری: نماینده می‌تواند روش‌های خاصی را اجباری کند یا به هوش مصنوعی اجازه دهد به‌طور خودکار مسیر را تعیین کند
  • بهینه‌سازی: وقتی روش مشخص باشد، می‌تواند از تجزیه‌وتحلیل گران‌قیمت هوش مصنوعی صرف‌نظر کند

در این بخش، در درجه اول جستجوی معنایی (RAG) را پیاده‌سازی خواهید کرد - یافتن نتایج براساس معنی و نه فقط کلیدواژه‌ها. بعداً توضیح خواهیم داد که چگونه جستجوی ترکیبی چندین روش را ادغام می‌کند.

۲. پیاده‌سازی سرویس RAG

👉💻 در ترمینال، فایل را با اجرای دستور زیر در «ویرایشگر Cloud Shell» باز کنید:

cloudshell edit ~/way-back-home/level_2/backend/services/hybrid_search_service.py

پیدا کردن نظر # TODO: REPLACE_SQL

کل این خط را با کد زیر جایگزین کنید:

        # This is your working query from the successful run!
        sql = """
            WITH query_embedding AS (
                SELECT embeddings.values AS val
                FROM ML.PREDICT(
                    MODEL TextEmbeddings,
                    (SELECT @query AS content)
                )
            )
            SELECT
                s.survivor_id,
                s.name AS survivor_name,
                s.biome,
                sk.skill_id,
                sk.name AS skill_name,
                sk.category,
                COSINE_DISTANCE(
                    sk.skill_embedding, 
                    (SELECT val FROM query_embedding)
                ) AS distance
            FROM Survivors s
            JOIN SurvivorHasSkill shs ON s.survivor_id = shs.survivor_id
            JOIN Skills sk ON shs.skill_id = sk.skill_id
            WHERE sk.skill_embedding IS NOT NULL
            ORDER BY distance ASC
            LIMIT @limit
        """

۳. تعریف ابزار جستجوی معنایی

👉💻 در ترمینال، فایل را با اجرای دستور زیر در «ویرایشگر Cloud Shell» باز کنید:

cloudshell edit ~/way-back-home/level_2/backend/agent/tools/hybrid_search_tools.py

در hybrid_search_tools.py، نظر # TODO: REPLACE_SEMANTIC_SEARCH_TOOL را پیدا کنید

👉کل این خط را با کد زیر جایگزین کنید:

async def semantic_search(query: str, limit: int = 10) -> str:
    """
    Force semantic (RAG) search using embeddings.
    
    Use this when you specifically want to find things by MEANING,
    not just matching keywords. Great for:
    - Finding conceptually similar items
    - Handling vague or abstract queries
    - When exact terms are unknown
    
    Example: "healing abilities" will find "first aid", "surgery", 
    "herbalism" even though no keywords match exactly.
    
    Args:
        query: What you're looking for (describe the concept)
        limit: Maximum results
        
    Returns:
        Semantically similar results ranked by relevance
    """
    try:
        service = _get_service()
        result = service.smart_search(
            query, 
            force_method=SearchMethod.RAG,
            limit=limit
        )
        
        return _format_results(
            result["results"],
            result["analysis"],
            show_analysis=True
        )
        
    except Exception as e:
        return f"Error in semantic search: {str(e)}"

وقتی Agent از این موارد استفاده می‌کند:

  • پُرسمان‌هایی که درخواست شباهت دارند («مشابه X را پیدا کن»)
  • پُرسمان‌های مفهومی («توانایی‌های شفابخشی»)
  • وقتی درک معنا حیاتی است

۴. راهنمای تصمیم‌گیری نماینده (دستورالعمل‌ها)

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

👉💻 در ترمینال، فایل را با اجرای دستور زیر در «ویرایشگر Cloud Shell» باز کنید:

cloudshell edit ~/way-back-home/level_2/backend/agent/agent.py

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

👉در فایل agent.py، نظر # TODO: REPLACE_SEARCH_LOGIC را پیدا کنید، کل این خط را با کد زیر جایگزین کنید:

- `semantic_search`: Force RAG/embedding search
  Use for: "Find similar to X", conceptual queries, unknown terminology
  Example: "Find skills related to healing"

👉نظر # TODO: ADD_SEARCH_TOOLReplace this whole line را پیدا کنید و آن را با کد زیر جایگزین کنید:

    semantic_search,         # Force RAG

۵. Understanding How Hybrid Search Works (Read Only, No Action Needed)

در مراحل ۲ تا ۴، جستجوی معنایی (RAG) را پیاده‌سازی کردید که روش اصلی جستجو برای پیدا کردن نتایج براساس معنی است. اما شاید متوجه شده باشید که این سیستم «جستجوی ترکیبی» نامیده می‌شود. در اینجا نحوه هماهنگی آن‌ها با یکدیگر آورده شده است:

نحوه عملکرد «ادغام ترکیبی»:

در فایل way-back-home/level_2/backend/services/hybrid_search_service.py، وقتی hybrid_search() فراخوانی می‌شود، سرویس هر دو جستجو را اجرا می‌کند و نتایج را ادغام می‌کند:

# Location: backend/services/hybrid_search_service.py

    rank_kw = keyword_ranks.get(surv_id, float('inf'))
    rank_rag = rag_ranks.get(surv_id, float('inf'))

    rrf_score = 0.0
    if rank_kw != float('inf'):
        rrf_score += 1.0 / (K + rank_kw)
    if rank_rag != float('inf'):
        rrf_score += 1.0 / (K + rank_rag)

    combined_score = rrf_score

برای این codelab، مؤلفه جستجوی معنایی (RAG) را که پایه است پیاده‌سازی کردید. روش‌های ترکیبی و کلیدواژه ازقبل در این سرویس پیاده‌سازی شده‌اند - نماینده شما می‌تواند از هر سه روش استفاده کند!

تبریک! «عامل Graph RAG» خود را با جستجوی ترکیبی باموفقیت به‌پایان رساندید!

‫۷. 🚀 آزمایش کردن «عامل» با ADK Web

ساده‌ترین راه برای آزمایش کردن نماینده‌تان استفاده از فرمان adk web است که نماینده‌تان را با میانای گپ داخلی راه‌اندازی می‌کند.

۱. درحال اجرای Agent

👉💻 به دایرکتوری پس‌بک (جایی که عامل شما تعریف شده است) بروید و «میانای وب» را راه‌اندازی کنید::

cd ~/way-back-home/level_2/backend
uv run adk web

این فرمان نماینده تعریف‌شده در را شروع می‌کند

agent/agent.py

و میانای وب را برای آزمایش باز می‌کند.

👉 نشانی وب را باز کنید:

این فرمان یک نشانی وب محلی (معمولاً http://127.0.0.1:8000 یا مشابه آن) را خروجی می‌دهد. این را در مرورگرتان باز کنید.

adk web

پس‌از کلیک کردن روی نشانی وب، «رابط کاربری وب ADK» را خواهید دید. مطمئن شوید که «نماینده» را از گوشه بالا سمت راست انتخاب کرده‌اید.

adk_ui

۲. آزمایش قابلیت‌های جستجو

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

موارد را براساس معنی و مفهوم پیدا می‌کند، حتی اگر کلیدواژه‌ها مطابقت نداشته باشند.

پرسمان‌های آزمایشی: (یکی از موارد زیر را انتخاب کنید)

Who can help with injuries?
What abilities are related to survival?

به‌دنبال چه چیزی باید گشت:

  • استدلال باید به جستجوی معنایی یا RAG اشاره کند.
  • باید نتایجی را ببینید که ازنظر مفهومی مرتبط هستند (مثلاً «جراحی» هنگام درخواست «کمک‌های اولیه»).
  • نتایج نماد 🧬 خواهند داشت.

فیلترهای کلیدواژه را با درک معنایی برای پُرسمان‌های پیچیده ترکیب می‌کند.

پرس‌وجوهای آزمایشی:(یکی از موارد زیر را انتخاب کنید)

Find someone who can fly a plane in the volcanic area
Who has healing abilities in the FOSSILIZED?
Who has healing abilities in the mountains?

به‌دنبال چه چیزی باید گشت:

  • استدلال باید به جستجوی ترکیبی اشاره کند.
  • نتایج باید با هر دو معیار (مفهوم + مکان/دسته) مطابقت داشته باشد.
  • نتایجی که با هر دو روش پیدا شده‌اند نماد 🔀 خواهند داشت و بالاترین رتبه را دارند.

👉💻 وقتی آزمایش تمام شد، با فشار دادن Ctrl+C در خط فرمان، فرایند را به‌پایان برسانید.

‫۸. 🚀 اجرای برنامه کامل

نمای کلی معماری پشته کامل

architecture_fullstack

افزودن SessionService و Runner

👉💻 در ترمینال، فایل chat.py را در «ویرایشگر Cloud Shell» با اجرای دستور زیر باز کنید (قبل‌از ادامه دادن، حتماً با «ctrl+C» فرایند قبلی را پایان دهید):

cloudshell edit ~/way-back-home/level_2/backend/api/routes/chat.py

👉در فایل chat.py، نظر # TODO: REPLACE_INMEMORY_SERVICES را پیدا کنید، کل این خط را با کد زیر جایگزین کنید:

    session_service = InMemorySessionService()
    memory_service = InMemoryMemoryService()

👉در فایل chat.py، نظر # TODO: REPLACE_RUNNER را پیدا کنید، کل این خط را با کد زیر جایگزین کنید:

runner = Runner(
    agent=root_agent, 
    session_service=session_service,
    memory_service=memory_service,
    app_name="survivor-network"
)

۱. شروع درخواست

اگر پایانه قبلی همچنان درحال اجرا است، با فشار دادن Ctrl+C آن را پایان دهید.

👉💻 Start App:

cd ~/way-back-home/level_2/
./start_app.sh

وقتی با موفقیت باطن را شروع کرد، Local: http://localhost:5173/" را به‌صورت زیر خواهید دید: جلو

👉 از پایانه، روی Local: http://localhost:5173/ کلیک کنید.

مکالمه

پُرسمان:

Find skills similar to healing

گپ

چه اتفاقی می‌افتد:

  • عامل درخواست شباهت را تشخیص می‌دهد
  • جاسازی برای «healing» تولید می‌کند
  • از فاصله کسینوسی برای پیدا کردن مهارت‌های مشابه ازنظر معنایی استفاده می‌کند
  • برمی‌گرداند: کمک‌های اولیه (هرچند نام‌ها با «التیام» مطابقت ندارد)

پُرسمان:

Find medical skills in the mountains

چه اتفاقی می‌افتد:

  1. مؤلفه کلیدواژه: فیلتر برای category='medical'
  2. مؤلفه معنایی: جاسازی «پزشکی» و رتبه‌بندی براساس شباهت
  3. ادغام: ترکیب نتایج، با اولویت دادن به نتایجی که با هر دو روش پیدا شده‌اند 🔀

پُرسمان (اختیاری):

Who is good at survival and in the forest?

چه اتفاقی می‌افتد:

  • کلیدواژه: biome='forest'
  • یافته‌های معنایی: مهارت‌های مشابه «بقا»
  • «ترکیبی» برای بهترین نتایج، هر دو را ترکیب می‌کند

👉💻 وقتی آزمایش تمام شد، در پایانه، با فشار دادن Ctrl+C آن را پایان دهید.

۴. (!ONLY FOR WORKSHOP ATTENDEE) Update your location

👉💻 دستورگان تکمیل را اجرا کنید:

cd ~/way-back-home/level_2
./set_level_2.sh

اکنون waybackhome.dev را باز کنید، خواهید دید که مکانتان به‌روز شده است. تبریک می‌گوییم که سطح ۲ را تمام کردید!

نتیجه نهایی

‫۹. ☕️ [اختیاری] خط لوله چندحالتی (فقط خواندنی) — لایه ابزارسازی

چرا به خط لوله چندحالتی نیاز داریم؟

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

  • 📸 تصاویر: عکس‌های منابع، خطرات، یا تجهیزات
  • 🎥 ویدیوها: گزارش‌های وضعیت یا پخش‌های SOS
  • 📄 نوشتار: یادداشت‌ها یا گزارش‌های میدانی

چه فایل‌هایی را پردازش می‌کنیم؟

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

منبع

محتوا

هدف

پیوست کاربر

تصویر/ ویدیو/ نوشتار

اطلاعاتی که باید به گراف اضافه شود

بافت گپ

«این عکسی از لوازم است»

هدف و جزئیات بیشتر

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

ما از یک عامل متوالی (multimedia_agent.py) استفاده می‌کنیم که عامل‌های تخصصی را به‌صورت زنجیره‌ای به هم متصل می‌کند:

architecture_uploading

این مورد در backend/agent/multimedia_agent.py به‌عنوان SequentialAgent تعریف شده است.

لایه ابزارسازی قابلیت‌هایی را ارائه می‌دهد که عوامل می‌توانند فراخوانی کنند. ابزارها «چگونگی» را مدیریت می‌کنند — بارگذاری فایل‌ها، استخراج نهادها، و ذخیره در پایگاه داده.

۱. باز کردن فایل ابزارها

👉💻 فایل level_2/backend/agent/tools/extraction_tools.py را باز کنید یا فرمان زیر را در پایانه تایپ کنید. پایانه جدیدی باز کنید. در پایانه، فایل را در «ویرایشگر Cloud Shell» باز کنید:

cloudshell edit ~/way-back-home/level_2/backend/agent/tools/extraction_tools.py

۲. پیاده‌سازی ابزار upload_media

این ابزار فایل محلی را در Google Cloud Storage بارگذاری می‌کند.

👉 در def upload_media(file_path: str, survivor_id: Optional[str] = None) -> Dict[str, Any]:، کد زیر درباره نحوه بارگذاری فایل‌ها در GCS و تشخیص نوع آن است:

    """
    Upload media file to GCS and detect its type.
    
    Args:
        file_path: Path to the local file
        survivor_id: Optional survivor ID to associate with upload
        
    Returns:
        Dict with gcs_uri, media_type, and status
    """
    try:
        if not file_path:
            return {"status": "error", "error": "No file path provided"}
        
        # Strip quotes if present
        file_path = file_path.strip().strip("'").strip('"')
        
        if not os.path.exists(file_path):
            return {"status": "error", "error": f"File not found: {file_path}"}
        
        gcs_uri, media_type, signed_url = gcs_service.upload_file(file_path, survivor_id)
        
        return {
            "status": "success",
            "gcs_uri": gcs_uri,
            "signed_url": signed_url,
            "media_type": media_type.value,
            "file_name": os.path.basename(file_path),
            "survivor_id": survivor_id
        }
    except Exception as e:
        logger.error(f"Upload failed: {e}")
        return {"status": "error", "error": str(e)}

۳. پیاده‌سازی ابزار extract_from_media

این ابزار یک رهیاب است — media_type را بررسی می‌کند و به استخراج‌کننده صحیح (نوشتار، تصویر، یا ویدیو) ارسال می‌کند.

👉 در async def extract_from_media(gcs_uri: str, media_type: str, signed_url: Optional[str] = None) -> Dict[str, Any]:، کد زیر درباره نحوه استخراج نهادها و روابط از رسانه بارگذاری‌شده است.

    """
    Extract entities and relationships from uploaded media.
    
    Args:
        gcs_uri: GCS URI of the uploaded file
        media_type: Type of media (text/image/video)
        signed_url: Optional signed URL for public/temporary access
        
    Returns:
        Dict with extraction results
    """
    try:
        if not gcs_uri:
             return {"status": "error", "error": "No GCS URI provided"}

        # Select appropriate extractor
        if media_type == MediaType.TEXT.value or media_type == "text":
            result = await text_extractor.extract(gcs_uri)
        elif media_type == MediaType.IMAGE.value or media_type == "image":
            result = await image_extractor.extract(gcs_uri)
        elif media_type == MediaType.VIDEO.value or media_type == "video":
            result = await video_extractor.extract(gcs_uri)
        else:
            return {"status": "error", "error": f"Unsupported media type: {media_type}"}
            
        # Inject signed URL into broadcast info if present
        if signed_url:
            if not result.broadcast_info:
                result.broadcast_info = {}
            result.broadcast_info['thumbnail_url'] = signed_url
        
        return {
            "status": "success",
            "extraction_result": result.to_dict(), # Return valid JSON dict instead of object
            "summary": result.summary,
            "entities_count": len(result.entities),
            "relationships_count": len(result.relationships),
            "entities": [e.to_dict() for e in result.entities],
            "relationships": [r.to_dict() for r in result.relationships]
        }
    except Exception as e:
        logger.error(f"Extraction failed: {e}")
        return {"status": "error", "error": str(e)}

جزئیات کلیدی پیاده‌سازی:

  • ورودی چندحالته: هم پیام‌واره نوشتاری (_get_extraction_prompt()) و هم شیء تصویر را به generate_content ارسال می‌کنیم.
  • برونداد ساختاریافته: response_mime_type="application/json" تضمین می‌کند که مدل زبانی بزرگ JSON معتبر برمی‌گرداند، که برای خط لوله حیاتی است.
  • پیوند دادن نهاد بصری: پیام‌واره حاوی نهادهای شناخته‌شده است تا Gemini بتواند نویسه‌های خاص را تشخیص دهد.

۴. پیاده‌سازی ابزار save_to_spanner

این ابزار موجودیت‌ها و روابط استخراج‌شده را در Spanner Graph DB ذخیره می‌کند.

👉 در def save_to_spanner(extraction_result: Any, survivor_id: Optional[str] = None) -> Dict[str, Any]:، کد زیر درباره نحوه ذخیره کردن روابط و نهادهای استخراج‌شده در Spanner Graph DB است.

    """
    Save extracted entities and relationships to Spanner Graph DB.
    
    Args:
        extraction_result: ExtractionResult object (or dict from previous step if passed as dict)
        survivor_id: Optional survivor ID to associate with the broadcast
        
    Returns:
        Dict with save statistics
    """
    try:
        # Handle if extraction_result is passed as the wrapper dict from extract_from_media
        result_obj = extraction_result
        if isinstance(extraction_result, dict) and 'extraction_result' in extraction_result:
             result_obj = extraction_result['extraction_result']
        
        # If result_obj is a dict (from to_dict()), reconstruct it
        if isinstance(result_obj, dict):
            from extractors.base_extractor import ExtractionResult
            result_obj = ExtractionResult.from_dict(result_obj)
        
        if not result_obj:
            return {"status": "error", "error": "No extraction result provided"}
            
        stats = spanner_service.save_extraction_result(result_obj, survivor_id)
        
        return {
            "status": "success",
            "entities_created": stats['entities_created'],
            "entities_existing": stats['entities_found_existing'],
            "relationships_created": stats['relationships_created'],
            "broadcast_id": stats['broadcast_id'],
            "errors": stats['errors'] if stats['errors'] else None
        }
    except Exception as e:
        logger.error(f"Spanner save failed: {e}")
        return {"status": "error", "error": str(e)}

با ارائه ابزارهای سطح بالا به نمایندگان، ضمن بهره‌برداری از قابلیت‌های استدلال نماینده، تمامیت داده‌ها را تضمین می‌کنیم.

۵. به‌روزرسانی سرویس GCS

GCSService بارگذاری واقعی فایل در Google Cloud Storage را مدیریت می‌کند.

👉💻 فایل level_2/backend/services/gcs_service.py را باز کنید، یا می‌توانید در پایانه تایپ کنید تا فایل در «ویرایشگر Cloud Shell» باز شود:

cloudshell edit ~/way-back-home/level_2/backend/services/gcs_service.py

👉 در def upload_file(self, file_path: str, survivor_id: Optional[str] = None) -> Tuple[str, MediaType, str]:، کد زیر نحوه ذخیره کردن نهادها و روابط استخراج‌شده را در Spanner Graph DB نشان می‌دهد.

        blob = self.bucket.blob(blob_name)
        blob.upload_from_filename(file_path)

با خلاصه کردن این مورد در یک سرویس، «نماینده» نیازی به دانستن درباره سطل‌های GCS، نام‌های blob، یا تولید نشانی وب امضاشده ندارد. فقط می‌گوید «بارگذاری کنید».

‫۶. چرا گردش کار عامل‌گرا > رویکردهای سنتی؟

مزیت عامل‌محور:

ویژگی

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

رویدادمحور

گردش کار عامل‌گرا

پیچیدگی

کم (۱ دستورگان)

بالا (بیش‌از ۵ سرویس)

پایین (۱ فایل Python: multimedia_agent.py)

مدیریت وضعیت

متغیرهای سراسری

سخت (جداشده)

یکپارچه (وضعیت نماینده)

مدیریت کردن خطا

ازکار می‌افتد

گزارش‌های بی‌صدا

تعاملی («نتوانستم آن فایل را بخوانم»)

بازخورد کاربر

چاپ‌های کنسول

نظرسنجی لازم است

فوری (بخشی از گپ)

انطباق‌پذیری

منطق ثابت

توابع صلب

هوشمند (مدل زبانی بزرگ مرحله بعدی را تعیین می‌کند)

آگاهی از بافت

خالی

خالی

کامل (قصد کاربر را می‌داند)

چرا این موضوع اهمیت دارد: بااستفاده از multimedia_agent.py (یک SequentialAgent با ۴ عامل فرعی: بارگذاری ← استخراج ← ذخیره ← خلاصه)، زیرساخت پیچیده و اسکریپت‌های شکننده را با منطق برنامه مکالمه‌ای هوشمند جایگزین می‌کنیم.

‫۱۰. ☕️ [اختیاری] خط لوله چندحالته (فقط خواندنی) — لایه عامل

لایه عامل هوش را تعریف می‌کند — عامل‌هایی که از ابزارها برای انجام تکالیف استفاده می‌کنند. هر عامل نقش خاصی دارد و بافت را به عامل بعدی منتقل می‌کند. در زیر نمودار معماری سیستم چندعاملی را می‌بینید.

agent_diagram

۱. باز کردن فایل «عامل»

👉💻 فایل level_2/backend/agent/multimedia_agent.py را باز کنید یا فرمان زیر را در پایانه تایپ کنید. پایانه جدیدی باز کنید. در پایانه، فایل را در «ویرایشگر Cloud Shell» باز کنید:

cloudshell edit ~/way-back-home/level_2/backend/agent/multimedia_agent.py

۲. تعریف کردن «عامل بارگذاری»

این عامل مسیر فایل را از پیام کاربر استخراج می‌کند و آن را در GCS بارگذاری می‌کند.

👉در فایل multimedia_agent.py، با کد زیر، upload_agent را ایجاد می‌کند که در GCS بارگذاری می‌شود:

upload_agent = LlmAgent(
    name="UploadAgent",
    model="gemini-2.5-flash",
    instruction="""Extract the file path from the user's message and upload it.

Use `upload_media(file_path, survivor_id)` to upload the file.
The survivor_id is optional - include it if the user mentions a specific survivor (e.g., "survivor Sarah" -> "Sarah").
If the user provides a path like "/path/to/file", use that.

Return the upload result with gcs_uri and media_type.""",
    tools=[upload_media],
    output_key="upload_result"
)

۳. تعریف کردن «عامل استخراج»

این عامل رسانه بارگذاری‌شده را «می‌بیند» و بااستفاده از Gemini Vision داده‌های ساختاریافته را استخراج می‌کند.

👉در فایل multimedia_agent.py، با کد زیر، extraction_agent ایجاد می‌شود که اطلاعات را از رسانه بارگذاری‌شده استخراج می‌کند:

extraction_agent = LlmAgent(
    name="ExtractionAgent", 
    model="gemini-2.5-flash",
    instruction="""Extract information from the uploaded media.

Previous step result: {upload_result}

Use `extract_from_media(gcs_uri, media_type, signed_url)` with the values from the upload result.
The gcs_uri is in upload_result['gcs_uri'], media_type in upload_result['media_type'], and signed_url in upload_result['signed_url'].

Return the extraction results including entities and relationships found.""",
    tools=[extract_from_media],
    output_key="extraction_result"
)

توجه کنید که چگونه instruction به {upload_result} ارجاع می‌دهد — این نحوه انتقال وضعیت بین عامل‌ها در ADK است.

۴. تعریف کردن «عامل Spanner»

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

👉در فایل multimedia_agent.py، با کد زیر، spanner_agent را ایجاد می‌کند که اطلاعات استخراج‌شده را در پایگاه داده ذخیره می‌کند:

spanner_agent = LlmAgent(
    name="SpannerAgent",
    model="gemini-2.5-flash", 
    instruction="""Save the extracted information to the database.

Upload result: {upload_result}
Extraction result: {extraction_result}

Use `save_to_spanner(extraction_result, survivor_id)` to save to Spanner.
Pass the WHOLE `extraction_result` object/dict from the previous step.
Include survivor_id if it was provided in the upload step.

Return the save statistics.""",
    tools=[save_to_spanner],
    output_key="spanner_result"
)

این عامل بافتار را از هر دو مرحله قبلی (upload_result و extraction_result) دریافت می‌کند.

۵. تعریف کردن «عامل خلاصه»

این عامل نتایج همه مراحل قبلی را در یک پاسخ کاربرپسند ترکیب می‌کند.

👉در فایل multimedia_agent.py، با کد زیر، پیام‌واره summary_agent را که نتیجه را خلاصه می‌کند تعریف می‌کند:

USE_MEMORY_BANK = os.getenv("USE_MEMORY_BANK", "false").lower() == "true"
save_msg = "6. Mention that the data is also being synced to the memory bank." if USE_MEMORY_BANK else ""

summary_instruction = f"""Provide a user-friendly summary of the media processing.

Upload: {{upload_result}}
Extraction: {{extraction_result}}
Database: {{spanner_result}}

Summarize:
1. What file was processed (name and type)
2. Key information extracted (survivors, skills, needs, resources found) - list names and counts
3. Relationships identified
4. What was saved to the database (broadcast ID, number of entities)
5. Any issues encountered
{save_msg}

Be concise but informative."""

این عامل به ابزار نیاز ندارد — فقط بافت هم‌رسانی‌شده را می‌خواند و خلاصه تمیزی برای کاربر تولید می‌کند.

🧠 خلاصه معماری

لایه

فایل

مسئولیت

ابزار

‫extraction_tools.py + gcs_service.py

نحوه انجام — بارگذاری، استخراج، ذخیره

عامل

multimedia_agent.py

What — Orchestrate the pipeline

‫۱۱. 🚀 Multimodal Data Pipeline — Orchestration

هسته سیستم جدید ما MultimediaExtractionPipeline است که در backend/agent/multimedia_agent.py تعریف شده است. این برنامه از الگوی Sequential Agent از ADK (Agent Development Kit) استفاده می‌کند.

۱. چرا متوالی؟

پردازش بارگذاری یک زنجیره وابستگی خطی است:

  1. تا زمانی که فایل را نداشته باشید نمی‌توانید داده‌ها را استخراج کنید (بارگذاری).
  2. تا زمانی‌که داده‌ها را استخراج نکنید نمی‌توانید آن‌ها را ذخیره کنید (استخراج).
  3. تا زمانی که نتایج را نداشته باشید نمی‌توانید خلاصه کنید (ذخیره).

SequentialAgent برای این کار عالی است. برونداد یک نماینده را به‌عنوان بافت/ورودی به نماینده بعدی منتقل می‌کند.

۲. تعریف عامل

بیایید ببینیم خط لوله چگونه در پایین multimedia_agent.py مونتاژ می‌شود: 👉💻 در پایانه، فایل را در «ویرایشگر Cloud Shell» با اجرای دستور زیر باز کنید:

cloudshell edit ~/way-back-home/level_2/backend/agent/multimedia_agent.py

ورودی‌ها را از هر دو مرحله قبلی دریافت می‌کند. نظر # TODO: REPLACE_ORCHESTRATION را پیدا کنید. کل این خط را با کد زیر جایگزین کنید:

    sub_agents=[upload_agent, extraction_agent, spanner_agent, summary_agent]

۳. متصل شدن با «عامل Root»

👉💻 در ترمینال، فایل را با اجرای دستور زیر در «ویرایشگر Cloud Shell» باز کنید:

cloudshell edit ~/way-back-home/level_2/backend/agent/agent.py

نظر # TODO: REPLACE_ADD_SUBAGENT را پیدا کنید. کل این خط را با کد زیر جایگزین کنید:

    sub_agents=[multimedia_agent],

این شیء واحد به‌طور مؤثری چهار «کارشناس» را در یک موجودیت قابل‌فراخوانی بسته‌بندی می‌کند.

۴. جریان داده‌ها بین عوامل

هر عامل خروجی خود را در یک زمینه مشترک ذخیره می‌کند که عوامل بعدی می‌توانند به آن دسترسی داشته باشند:

architecture_uploading

۵. باز کردن برنامه (اگر برنامه همچنان درحال اجرا است، رد شود)

👉💻 Start App:

cd ~/way-back-home/level_2/
./start_app.sh

👉 از پایانه، روی Local: http://localhost:5173/ کلیک کنید.

‫۶. بارگذاری تصویر آزمایش

👉 در میانای گپ، یکی از عکس‌های اینجا را انتخاب کنید و در میانای کاربر بارگذاری کنید:

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

Here is the survivor note

و سپس تصویر را اینجا پیوست کنید.

upload_input

upload_result

👉💻 در پایانه، وقتی آزمایش تمام شد، «Ctrl+C» را فشار دهید تا فرایند پایان یابد.

‫۶. درستی‌سنجی بارگذاری چندحالتی در سطل GCS

راهکارهای مشتری Google

  • مخزن خود را انتخاب کنید و روی media کلیک کنید.

رسانه

  • تصویر بارگذاری‌شده‌تان را اینجا ببینید. uploaded_img

‫۷. درستی‌سنجی بارگذاری چندحالتی در Spanner (اختیاری)

در زیر نمونه‌ای از خروجی در واسط کاربر برای test_photo1 آورده شده است.

  • Google Cloud Console Spanner را باز کنید.
  • نمونه‌تان را انتخاب کنید: Survivor Network
  • پایگاه داده‌تان را انتخاب کنید: graph-db
  • در نوار کناری سمت راست، روی Spanner Studio کلیک کنید

👉 در Spanner Studio، داده‌های جدید را پُرسمان کنید:

SELECT 
  s.name AS Survivor,
  s.role AS Role,
  b.name AS Biome,
  r.name AS FoundResource,
  s.created_at
FROM Survivors s
LEFT JOIN SurvivorInBiome sib ON s.survivor_id = sib.survivor_id
LEFT JOIN Biomes b ON sib.biome_id = b.biome_id
LEFT JOIN SurvivorFoundResource sfr ON s.survivor_id = sfr.survivor_id
LEFT JOIN Resources r ON sfr.resource_id = r.resource_id
ORDER BY s.created_at DESC;

می‌توانیم آن را با دیدن نتیجه زیر تأیید کنیم:

spanner_verify

‫۱۲. ☕️ [اختیاری] Memory Bank با Agent Engine

۱. نحوه عملکرد «حافظه»

این سیستم از رویکرد حافظه دوگانه برای مدیریت بافت فوری و یادگیری بلندمدت استفاده می‌کند.

memory_bank

۲. موضوعات خاطره چیست؟

موضوعات حافظه دسته‌های اطلاعاتی را که نماینده باید در مکالمه‌ها به‌خاطر بسپارد تعریف می‌کنند. آن‌ها را به‌عنوان کابینت‌های فایل برای انواع مختلف اولویت‌های کاربر درنظر بگیرید.

۲ موضوع ما:

  1. search_preferences: کاربر چگونه دوست دارد جستجو کند
    • آیا جستجوی کلیدواژه‌ای را ترجیح می‌دهند یا معنایی؟
    • اغلب چه مهارت‌ها/زیست‌بوم‌هایی را جستجو می‌کنند؟
    • نمونه حافظه: «کاربر جستجوی معنایی را برای مهارت‌های پزشکی ترجیح می‌دهد»
  2. urgent_needs_context: چه بحران‌هایی را ردیابی می‌کنند
    • چه منابعی را پایش می‌کنند؟
    • نگران کدام بازماندگان هستند؟
    • نمونه حافظه: «کاربر درحال پیگیری کمبود دارو در کمپ شمالی است»

۳. درحال راه‌اندازی موضوعات حافظه

موضوعات حافظه سفارشی مشخص می‌کنند که عامل باید چه چیزی را به‌خاطر بسپارد. این موارد هنگام استقرار Agent Engine پیکربندی می‌شوند.

👉💻 در ترمینال، فایل را با اجرای دستور زیر در «ویرایشگر Cloud Shell» باز کنید:

cloudshell edit ~/way-back-home/level_2/backend/deploy_agent.py

با این کار، ~/way-back-home/level_2/backend/deploy_agent.py در ویرایشگرتان باز می‌شود.

ما اشیای ساختار MemoryTopic را تعریف می‌کنیم تا مدل زبانی بزرگ را درباره اینکه چه اطلاعاتی را استخراج و ذخیره کند راهنمایی کنیم.

👉در فایل deploy_agent.py، # TODO: SET_UP_TOPIC را با موارد زیر جایگزین کنید:

# backend/deploy_agent.py

    custom_topics = [
        # Topic 1: Survivor Search Preferences
        MemoryTopic(
            custom_memory_topic=CustomMemoryTopic(
                label="search_preferences",
                description="""Extract the user's preferences for how they search for survivors. Include:
                - Preferred search methods (keyword, semantic, direct lookup)
                - Common filters used (biome, role, status)
                - Specific skills they value or frequently look for
                - Geographic areas of interest (e.g., "forest biome", "mountain outpost")
                
                Example: "User prefers semantic search for finding similar skills."
                Example: "User frequently checks for survivors in the Swamp Biome."
                """,
            )
        ),
        # Topic 2: Urgent Needs Context
        MemoryTopic(
            custom_memory_topic=CustomMemoryTopic(
                label="urgent_needs_context",
                description="""Track the user's focus on urgent needs and resource shortages. Include:
                - Specific resources they are monitoring (food, medicine, ammo)
                - Critical situations they are tracking
                - Survivors they are particularly concerned about
                
                Example: "User is monitoring the medicine shortage in the Northern Camp."
                Example: "User is looking for a doctor for the injured survivors."
                """,
            )
        )
    ]

۴. یکپارچه‌سازی عامل

کد عامل باید از «بانک حافظه» مطلع باشد تا بتواند اطلاعات را ذخیره و بازیابی کند.

👉💻 در ترمینال، فایل را با اجرای دستور زیر در «ویرایشگر Cloud Shell» باز کنید:

cloudshell edit ~/way-back-home/level_2/backend/agent/agent.py

با این کار، ~/way-back-home/level_2/backend/agent/agent.py در ویرایشگرتان باز می‌شود.

ایجاد عامل

هنگام ایجاد نماینده، after_agent_callback را ارسال می‌کنیم تا مطمئن شویم جلسه‌ها پس‌از تعاملات در حافظه ذخیره می‌شوند. تابع add_session_to_memory به‌صورت ناهمگام اجرا می‌شود تا سرعت پاسخ گپ کاهش نیابد.

👉در فایل agent.py، نظر # TODO: REPLACE_ADD_SESSION_MEMORY را پیدا کنید، کل این خط را با کد زیر جایگزین کنید:

async def add_session_to_memory(
        callback_context: CallbackContext
) -> Optional[types.Content]:
    """Automatically save completed sessions to memory bank in the background"""
    if hasattr(callback_context, "_invocation_context"):
        invocation_context = callback_context._invocation_context
        if invocation_context.memory_service:
            # Use create_task to run this in the background without blocking the response
            asyncio.create_task(
                invocation_context.memory_service.add_session_to_memory(
                    invocation_context.session
                )
            )
            logger.info("Scheduled session save to memory bank in background")

ذخیره کردن پس‌زمینه‌ای

👉در فایل agent.py، نظر # TODO: REPLACE_ADD_MEMORY_BANK_TOOL را پیدا کنید، کل این خط را با کد زیر جایگزین کنید:

if USE_MEMORY_BANK:
    agent_tools.append(PreloadMemoryTool())

👉در فایل agent.py، نظر # TODO: REPLACE_ADD_CALLBACK را پیدا کنید، کل این خط را با کد زیر جایگزین کنید:

    after_agent_callback=add_session_to_memory if USE_MEMORY_BANK else None

راه‌اندازی کردن Vertex AI Session Service

👉💻 در ترمینال، فایل chat.py را با اجرای دستور زیر در Cloud Shell Editor باز کنید:

cloudshell edit ~/way-back-home/level_2/backend/api/routes/chat.py

👉در فایل chat.py، نظر # TODO: REPLACE_VERTEXAI_SERVICES را پیدا کنید، کل این خط را با کد زیر جایگزین کنید:

    session_service = VertexAiSessionService(
        project=project_id,
        location=location,
        agent_engine_id=agent_engine_id
    )
    memory_service = VertexAiMemoryBankService(
        project=project_id,
        location=location,
        agent_engine_id=agent_engine_id
    )

‫۱۳. ☕️ [اختیاری] پیوست کردن عامل با Agent Engine

۱. راه‌اندازی و استقرار

قبل‌از آزمایش کردن ویژگی‌های حافظه، باید عامل را با موضوعات حافظه جدید مستقر کنید و مطمئن شوید محیط شما به‌درستی پیکربندی شده است.

ما یک اسکریپت راحت برای مدیریت این فرایند ارائه کرده‌ایم.

درحال اجرای دستورگان پیاده‌سازی

👉💻 در پایانه، دستورگان استقرار را اجرا کنید:

cd ~/way-back-home/level_2
./deploy_and_update_env.sh

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

  • backend/deploy_agent.py را اجرا می‌کند تا عامل و موضوعات حافظه را در Vertex AI ثبت کند.
  • شناسه موتور عامل جدید را ضبط می‌کند.
  • فایل .env شما را به‌طور خودکار با AGENT_ENGINE_ID به‌روز می‌کند.
  • مطمئن شوید USE_MEMORY_BANK=TRUE در فایل .env شما تنظیم شده باشد.

[!مهم] اگر تغییراتی در custom_topics در deploy_agent.py ایجاد کنید، باید این دستور را دوباره اجرا کنید تا Agent Engine به‌روز شود.

درستی‌سنجی بانک حافظه

اکنون می‌توانید با آموزش دادن یک اولویت به نماینده و بررسی اینکه آیا در جلسات مختلف باقی می‌ماند یا نه، تأیید کنید که بانک حافظه کار می‌کند.

مرحله یک. برنامه را باز کنید

با دنبال کردن دستورالعمل زیر، «برنامه» را دوباره باز کنید: اگر پایانه قبلی همچنان درحال اجرا است، با فشار دادن Ctrls+C آن را ببندید.

👉💻 Start App:

cd ~/way-back-home/level_2/
./start_app.sh

👉 از پایانه، روی Local: http://localhost:5173/ کلیک کنید.

مرحله دو. درحال آزمایش بانک حافظه با نوشتار

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

"I'm planning a medical rescue mission in the mountains. I need survivors with first aid and climbing skills."

👉 حدود ۳۰ ثانیه صبر کنید تا خاطره در پس‌زمینه پردازش شود.

مرحله سه. شروع جلسه جدید

برای پاک کردن سابقه مکالمه فعلی (حافظه کوتاه‌مدت)، صفحه را بازآوری کنید.

سؤالی بپرسید که به زمینه‌ای که قبلاً ارائه کرده‌اید متکی باشد:

"What kind of missions am I interested in?"

پاسخ موردانتظار:

«براساس مکالمه‌های قبلی‌تان، به این موارد علاقه دارید:

  • مأموریت‌های نجات پزشکی
  • عملیات در کوهستان/ارتفاع زیاد
  • مهارت‌های موردنیاز: کمک‌های اولیه، کوهنوردی

می‌خواهید بازماندگان منطبق با این معیارها را پیدا کنم؟»

مرحله چهار. آزمایش با بارگذاری تصویر

تصویری بارگذاری کنید و بپرسید:

remember this

می‌توانید هرکدام از عکس‌های اینجا یا عکس‌های خودتان را انتخاب کنید و در واسط کاربر بارگذاری کنید:

مرحله پنج. درستی‌سنجی در Vertex AI Agent Engine

به Google Cloud Console Agent Engine بروید

  1. مطمئن شوید پروژه را از انتخابگر پروژه در بالا سمت راست انتخاب کنید:انتخاب‌گر پروژه
  2. موتور عاملی را که به‌تازگی از فرمان قبلی مستقر کرده‌اید درستی‌سنجی کنید use_memory_bank.sh:موتور عاملروی موتور عاملی که به‌تازگی ایجاد کرده‌اید کلیک کنید.
  3. روی برگه Memories در این عامل مستقرشده کلیک کنید، می‌توانید همه حافظه را در اینجا مشاهده کنید.مشاهده خاطره

👉💻 وقتی آزمایش تمام شد، در پایانه، روی «Ctrl + C» کلیک کنید تا فرایند پایان یابد.

🎉 تبریک می‌گوییم! بانک حافظه را به عاملتان پیوست کردید!

‫۱۴. ☕️ [اختیاری] مستقر کردن در Cloud Run

۱. اجرای دستورگان پیاده‌سازی

👉💻 دستورگان پیاده‌سازی را اجرا کنید:

cd ~/way-back-home/level_2
./deploy_cloud_run.sh

پس‌از مستقر شدن موفقیت‌آمیز، نشانی وب را خواهید داشت، این نشانی وب مستقرشده برای شما است! مستقرشده

👉💻 قبل‌از گرفتن نشانی وب، با اجرای این دستور اجازه را اعطا کنید:

source .env && gcloud run services add-iam-policy-binding survivor-frontend --region $REGION --member=allUsers --role=roles/run.invoker && gcloud run services add-iam-policy-binding survivor-backend --region $REGION --member=allUsers --role=roles/run.invoker

به نشانی وب مستقرشده بروید و برنامه خود را به‌صورت زنده در آنجا ببینید!

۲. آشنایی با خط لوله ساخت

فایل cloudbuild.yaml مراحل متوالی زیر را تعریف می‌کند:

  1. ساختن باطن: تصویر Docker را از backend/Dockerfile می‌سازد.
  2. Backend Deploy: کانتینر پس‌زمینه را در Cloud Run مستقر می‌کند.
  3. ضبط نشانی وب: نشانی وب جدید Backend را دریافت می‌کند.
  4. ساخت Frontend:
    • وابستگی‌ها را نصب می‌کند.
    • «برنامه React» را می‌سازد و VITE_API_URL= را تزریق می‌کند.
  5. تصویر Frontend: تصویر Docker را از frontend/Dockerfile می‌سازد (بسته‌بندی دارایی‌های ثابت).
  6. استقرار پیشانه: محتوی پیشانه را مستقر می‌کند.

۳. تأیید استقرار

پس‌از تکمیل ساخت (پیوند گزارش‌های ارائه‌شده توسط اسکریپت را بررسی کنید)، می‌توانید موارد زیر را درستی‌سنجی کنید:

  1. به کنسول Cloud Run بروید.
  2. سرویس survivor-frontend را پیدا کنید.
  3. برای باز کردن برنامه، روی نشانی وب کلیک کنید.
  4. عبارتی را جستجو کنید تا مطمئن شوید که بخش کاربری می‌تواند با بخش پشتیبان ارتباط برقرار کند.

(اختیاری) ۴. استقرار دستی

اگر ترجیح می‌دهید فرمان‌ها را به‌صورت دستی اجرا کنید یا فرایند را بهتر درک کنید، در اینجا نحوه استفاده مستقیم از cloudbuild.yaml آورده شده است.

درحال نوشتن cloudbuild.yaml

فایل cloudbuild.yaml به Google Cloud Build می‌گوید چه مراحلی را اجرا کند.

  • مراحل: فهرستی از کنش‌های متوالی. هر مرحله در یک محفظه اجرا می‌شود (مثلاً docker، gcloud، node، bash).
  • جایگزینی‌ها: متغیرهایی که می‌توانند در زمان ساخت منتقل شوند (مثلاً $_REGION).
  • فضای کاری: دایرکتوری مشترکی که مراحل می‌توانند فایل‌ها را هم‌رسانی کنند (مثل نحوه هم‌رسانی backend_url.txt).

درحال اجرای استقرار

برای پیاده‌سازی کردن به‌صورت دستی بدون دستورگان، از فرمان gcloud builds submit استفاده کنید. باید متغیرهای جایگزین لازم را ارسال کنید.

# Load your env vars first or replace these values manually
export PROJECT_ID=your-project-id
export REGION=us-central1

gcloud builds submit --config cloudbuild.yaml \
    --project "$PROJECT_ID" \
    --substitutions _REGION="us-central1",_GOOGLE_API_KEY="",_AGENT_ENGINE_ID="your-agent-id",_USE_MEMORY_BANK="TRUE",_GOOGLE_GENAI_USE_VERTEXAI="TRUE"

‫۱۵. نتیجه‌گیری

۱. آنچه ساخته‌اید

✅ پایگاه داده گراف: Spanner با گره‌ها (بازماندگان، مهارت‌ها) و لبه‌ها (روابط)
✅ جستجوی هوش مصنوعی: جستجوی کلیدواژه‌ای، معنایی، و ترکیبی با جاسازی‌ها
✅ خط لوله چندحالتی: استخراج نهادها از تصاویر/ ویدیو با Gemini
✅ سیستم چندعاملی: گردش کار هماهنگ با ADK
✅ بانک حافظه: شخصی‌سازی بلندمدت با Vertex AI
✅ استقرار تولید: Cloud Run + Agent Engine

۲. خلاصه معماری

architecture_fullstack

۳. نکات کلیدی

  1. Graph RAG: ساختار پایگاه داده گراف را با جاسازی‌های معنایی برای جستجوی هوشمند ترکیب می‌کند
  2. الگوهای چندعاملی: خطوط لوله متوالی برای گردش کارهای پیچیده و چندمرحله‌ای
  3. هوش مصنوعی چندحالتی: استخراج داده‌های ساختاریافته از رسانه‌های ساختارنیافته (تصاویر/ویدیو)
  4. عامل‌های باحالت: Memory Bank شخصی‌سازی را در جلسه‌های مختلف امکان‌پذیر می‌کند

۴. محتوای کارگاه آموزشی

۵. منابع