🤖 Создание мультимодального ИИ-агента с помощью Graph RAG, ADK и Memory Bank

1. Введение

кавер-версия

1. Задача

При реагировании на стихийные бедствия координация выживших с разными навыками, ресурсами и потребностями в нескольких местах требует интеллектуального управления данными и возможностей поиска. На этом семинаре вы научитесь создавать рабочую систему ИИ, которая сочетает в себе:

  1. 🗄️ Графовая база данных (Spanner). Храните сложные связи между выжившими, навыками и ресурсами.
  2. 🔍 Поиск на основе искусственного интеллекта: Гибридный поиск по ключевым словам и семантике с использованием эмбеддингов.
  3. 📸 Мультимодальная обработка. Извлекайте структурированные данные из изображений, текста и видео.
  4. 🤖 Оркестровка нескольких агентов. Координируйте работу специализированных агентов для выполнения сложных рабочих процессов.
  5. 🧠 Долговременная память. Персонализация с помощью Vertex AI Memory Bank.

разговор

2. Что вы создадите

База данных графов сети выживших, содержащая:

  • 🗺️ Интерактивная 3D-визуализация отношений между выжившими.
  • 🔍 Умный поиск (по ключевым словам, семантический и гибридный).
  • 📸 Мультимодальная загрузка (извлечение объектов из изображений и видео)
  • 🤖 Мультиагентная система для выполнения сложных задач.
  • 🧠 Интеграция Memory Bank для персонализированного взаимодействия.

3. Базовые технологии

Компонент

Технологии

Цель

Database

Cloud Spanner Graph

Хранение узлов (выжившие, навыки) и ребер (отношения)

ИИ-поиск

Gemini + эмбеддинги

Семантическое понимание и поиск по сходству

Agent Framework

ADK (Agent Development Kit)

Управляйте рабочими процессами ИИ

Память

Банк памяти Vertex AI

Долгосрочное хранение пользовательских настроек

Frontend

React + Three.js

Интерактивная визуализация 3D-графиков

2. 🛠️ Подготовка среды (пропустите, если вы на семинаре)

Часть 1. Включите платежный аккаунт

Чтобы выполнить эту практическую работу, вам понадобится платежный аккаунт с положительным балансом. Чтобы начать, используйте бонусы из баннера в верхней части этой практической работы. Если вы уже подключены к платежному аккаунту, пропустите этот шаг.

Часть 2. Открытая среда

  1. 👉 Нажмите на эту ссылку, чтобы перейти в редактор Cloud Shell.
  2. 👉 Если в какой-то момент вам будет предложено авторизоваться, нажмите Авторизовать, чтобы продолжить. Нажмите, чтобы авторизовать Cloud Shell
  3. 👉 Если терминал не появился внизу экрана, откройте его:
    • Нажмите Вид.
    • Выберите Терминал.Открыть новый терминал в редакторе Cloud Shell
  4. 👉💻 В терминале убедитесь, что вы уже прошли аутентификацию и что в качестве проекта указан идентификатор вашего проекта. Для этого используйте следующую команду:
    gcloud auth list
    
  5. 👉💻 Клонируйте проект bootstrap из GitHub:
    git clone https://github.com/gca-americas/way-back-home.git
    

Часть 3. Создание нового проекта

👉💻 В терминале сделайте скрипт init исполняемым и запустите его:

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

3. 🛠️ Настройка среды

1. Открыть Cloud Shell

Если терминал редактора Cloud Shell не отображается внизу экрана, откройте его:

  • Нажмите Вид.
  • Выберите Терминал.

Открыть новый терминал в редакторе Cloud Shell

2. Настройка проекта

👉💻 В терминале задайте идентификатор проекта:

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

👉💻 Включите необходимые API (это займет 2–3 минуты):

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

3. Запустите скрипт настройки

👉💻 Выполните скрипт настройки:

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

Будет создан файл .env. В Cloud Shell откройте проект way_back_home. В папке level_2 вы увидите созданный для вас файл .env. Если вы не можете найти его, нажмите View -> Toggle Hidden File. open_project

4. Загрузить пример данных

👉💻 Перейдите в серверную часть и установите зависимости:

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 Spanner.

open_spanner

Вы увидите Spanner в консоли Google Cloud.

Spanner

4. 🚀 Визуализация данных графа в Spanner Studio

В этом руководстве рассказывается, как визуализировать данные графа Survivor Network и взаимодействовать с ними непосредственно в консоли Google Cloud с помощью Spanner Studio. Это отличный способ проверить данные и понять структуру графа, прежде чем создавать ИИ-агента.

1. Как получить доступ к Spanner Studio

  1. На последнем шаге обязательно нажмите на ссылку и откройте Spanner Studio.

spanner_studio

2. Структура графа (общая картина)

Набор данных Survivor Network можно представить как логическую головоломку или состояние игры.

Объект

Роль в системе

Аналогия

Survivors

Агенты/игроки

Игроки

Биомы

местоположение;

Зоны на карте

Навыки

Что они могут делать

Возможности

Потребности

Чего им не хватает (кризисы)

Квесты и миссии

Полезные ресурсы

Предметы, найденные в мире

Добыча

Цель. ИИ-агент должен сопоставить навыки (решения) с потребностями (проблемами), учитывая биомы (ограничения по местоположению).

🔗 Ребра (связи)

  • SurvivorInBiome: отслеживание местоположения
  • SurvivorHasSkill – инвентарь способностей.
  • SurvivorHasNeed: список активных проблем
  • SurvivorFoundResource – инвентарь.
  • SurvivorCanHelp: предполагаемые отношения (рассчитываются ИИ)

3. Запросы к графу

Давайте выполним несколько запросов, чтобы увидеть "историю" в данных.

Spanner Graph использует GQL (Graph Query Language). Чтобы выполнить запрос, введите GRAPH SurvivorNetwork и шаблон соответствия.

👉 Запрос 1. Глобальный список (кто где находится?) Это основа: понимание местоположения критически важно для спасательных операций.

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

Результат должен выглядеть следующим образом: query1

👉 Запрос 2. Матрица навыков (возможности). Теперь, когда вы знаете, где все находятся, узнайте, что они могут делать.

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

Результат должен выглядеть следующим образом: query2

👉 Запрос 3. Кто в кризисе? (Доска миссий) Посмотрите, кому из выживших нужна помощь и что им нужно.

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

Результат должен выглядеть следующим образом: query3

🔎 [Optional] Matchmaking - Who Can Help Whom?

Вот где график становится мощным! Этот запрос находит выживших, у которых есть навыки, позволяющие удовлетворить потребности других выживших.

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 Что делает этот запрос

Вместо того чтобы просто показать, что "Первая помощь лечит ожоги" (что очевидно из схемы), этот запрос находит:

  • Доктор Елена Фрост (имеет медицинское образование) → может лечить → Капитана Танаку (имеет ожоги)
  • Дэвид Чен (умеет оказывать первую помощь) → может вылечить → лейтенанта Пак (растяжение лодыжки).

Почему это важно

Что будет делать ИИ-агент

Когда пользователь спрашивает "Кто может лечить ожоги?", агент:

  1. Как выполнить запрос с похожим графиком
  2. Возвращаемое значение: "Dr. Frost has Medical Training and can help Captain Tanaka".
  3. Пользователю не нужно знать о промежуточных таблицах или отношениях!

5. 🚀 Эмбеддинги на основе ИИ в Spanner

1. Зачем нужны эмбеддинги? (только чтение)

В сценарии выживания время имеет решающее значение. Когда пострадавший сообщает о чрезвычайной ситуации, например I need someone who can treat burns или Looking for a medic, у него нет времени угадывать точные названия навыков в базе данных.

Реальный сценарий. Выживший: Captain Tanaka has burns—we need medical help NOW!.

Традиционный поиск по ключевому слову "медик" → 0 результатов ❌

Семантический поиск с эмбеддингами → находит "Медицинская подготовка", "Первая помощь" ✅

Это именно то, что нужно агентам: умный, похожий на человеческий поиск, который понимает намерения, а не только ключевые слова.

2. Создать модель встраивания

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, а затем нажмите кнопку Run (Выполнить).

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 (веса модели не хранятся локально).
  • Указывает на модель Google text-embedding-004 в Vertex AI.
  • Определяет контракт: входные данные – текст, выходные данные – массив с плавающей запятой размерности 768.

Почему стоит выбрать удаленную работу?

  • Spanner не запускает модель самостоятельно.
  • Когда вы используете ML.PREDICT, он вызывает Vertex AI через API.
  • Zero-ETL. Нет необходимости экспортировать данные в Python, обрабатывать их и повторно импортировать.

Нажмите кнопку Run. Если все пройдет успешно, вы увидите следующий результат:

spanner_result

3. Добавить столбец эмбеддингов

👉 Добавьте столбец для хранения эмбеддингов:

ALTER TABLE Skills ADD COLUMN skill_embedding ARRAY<FLOAT32>;

Нажмите кнопку Run. Если все пройдет успешно, вы увидите следующий результат:

embedding_result

4. Сгенерировать представления

👉 Используйте ИИ для создания векторных вложений для каждого навыка:

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

Что происходит. Название каждого навыка (например, "первая помощь") преобразуется в вектор из 768 измерений, представляющий его семантическое значение.

5. Проверить представления

👉 Проверьте, созданы ли эмбеддинги:

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;
  • Преобразует поисковый запрос пользователя "медик" во встраивание.
  • Сохраняет его во временной таблице query_embedding.

Ожидаемые результаты (чем меньше расстояние, тем больше сходство):

spanner_result

7. Создать модель 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

8. Как использовать 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."

6. 🚀 Создание агента GraphRAG с гибридным поиском

1. Обзор архитектуры системы

В этом разделе мы создадим систему поиска с несколькими методами, которая позволит агенту обрабатывать разные типы запросов. Система состоит из трех уровней: уровня агента, уровня инструмента и уровня сервиса.

architecture_hybrid_search

Почему три уровня?

  • Разделение ответственности. Агент фокусируется на намерении, инструменты – на интерфейсе, а сервис – на реализации.
  • Гибкость. Агент может принудительно использовать определенные методы или разрешить ИИ автоматически выбирать маршрут.
  • Оптимизация. Если метод известен, можно пропустить дорогостоящий анализ ИИ.

В этом разделе вы в основном будете реализовывать семантический поиск (RAG) – поиск результатов по значению, а не только по ключевым словам. Позже мы расскажем, как гибридный поиск объединяет несколько методов.

2. Реализация сервиса 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
        """

3. Определение инструмента семантического поиска

👉💻 В терминале откройте файл в редакторе 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)}"

Когда агент использует:

  • Запросы, в которых требуется найти что-то похожее ("найди похожее на X").
  • Концептуальные запросы ("целительные способности")
  • Когда важно понять смысл

4. Руководство по принятию решений для агентов (инструкции)

В определении агента скопируйте и вставьте в инструкцию часть, связанную с семантическим поиском.

👉💻 В терминале откройте файл в редакторе 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

5. Как работает гибридный поиск (только для чтения, никаких действий не требуется)

На шагах 2–4 вы реализовали семантический поиск (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

В этой практической работе вы реализовали компонент семантического поиска (RAG), который является основой. В сервисе уже реализованы методы поиска по ключевым словам и гибридный метод. Ваш агент может использовать все три.

Поздравляем! Вы успешно создали агента Graph RAG с гибридным поиском.

7. 🚀 Тестирование агента с помощью ADK Web

Проще всего протестировать агент с помощью команды adk web, которая запускает агент со встроенным интерфейсом чата.

1. Запуск агента

👉💻 Перейдите в каталог серверной части (где определен ваш агент) и запустите веб-интерфейс:

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

Эта команда запускает агент, определенный в

agent/agent.py

и открывает веб-интерфейс для тестирования.

👉 Откройте URL:

Команда выведет локальный URL (обычно http://127.0.0.1:8000 или похожий). Откройте эту страницу в браузере.

adk web

Нажмите на URL, чтобы открыть веб-интерфейс ADK. Убедитесь, что в левом верхнем углу выбран агент.

adk_ui

2. Тестирование возможностей поиска

Агент разработан так, чтобы эффективно обрабатывать ваши запросы. Попробуйте ввести в окне чата следующие запросы, чтобы увидеть, как работают разные методы поиска.

Находит объекты на основе смысла и концепции, даже если ключевые слова не совпадают.

Тестовые запросы (выберите любой из перечисленных ниже)

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 в командной строке.

8. 🚀 Запуск приложения

Обзор архитектуры Full Stack

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

1. Подать заявку

Если предыдущий терминал все ещё работает, закройте его, нажав Ctrl+C.

👉💻 Запустите приложение:

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

После успешного запуска бэкенда вы увидите Local: http://localhost:5173/", как показано ниже. fronted

👉 Нажмите 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.

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

👉💻 Запустите скрипт завершения:

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

Откройте приложение "waybackhome.dev". Вы увидите, что ваше местоположение обновилось. Поздравляем с завершением уровня 2!

итоговый результат

9. ☕️ [Optional] Multimodal Pipeline (Read Only) — Tooling Layer

Зачем нужен мультимодальный конвейер?

Сеть выживания – это не просто текст. Выжившие отправляют неструктурированные данные прямо в чат:

  • 📸 Изображения. Фотографии ресурсов, опасностей или оборудования.
  • 🎥 Видео: отчеты о статусе или трансляции SOS.
  • 📄 Текст: полевые заметки или журналы.

Какие файлы мы обрабатываем?

В отличие от предыдущего шага, на котором мы искали существующие данные, здесь мы обрабатываем файлы, загруженные пользователем. Интерфейс chat.py обрабатывает прикрепленные файлы динамически:

Источник

Контент

Цель

Прикрепление пользователя

Изображение/видео/текст

Информация, которую нужно добавить на график

Контекст чата

"Вот фото материалов"

Намерение и дополнительные сведения

Запланированный подход: последовательный конвейер агентов

Мы используем последовательного агента (multimedia_agent.py), который объединяет специализированных агентов в цепочку:

architecture_uploading

В backend/agent/multimedia_agent.py это определяется как SequentialAgent.

Уровень инструментов предоставляет возможности, которые могут вызывать агенты. Инструменты отвечают за то, как это сделать: загрузить файлы, извлечь объекты и сохранить их в базе данных.

1. Откройте файл Tools.

👉💻 Откройте файл level_2/backend/agent/tools/extraction_tools.py или введите в терминале следующую команду: Откройте новое окно терминала. В терминале откройте файл в редакторе Cloud Shell:

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

2. Как внедрить инструмент 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)}

3. Как внедрить инструмент 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)}

Основные сведения о реализации

  • Мультимодальный ввод. Мы передаем generate_content и текстовый запрос (_get_extraction_prompt()), и объект изображения.
  • Структурированный вывод. response_mime_type="application/json" гарантирует, что LLM возвращает действительный JSON, что критически важно для конвейера.
  • Связывание визуальных объектов. В запросе упоминаются известные объекты, поэтому Gemini может распознать определенных персонажей.

4. Как внедрить инструмент save_to_spanner

Этот инструмент сохраняет извлеченные объекты и связи в базе данных Spanner Graph.

👉 В файле def save_to_spanner(extraction_result: Any, survivor_id: Optional[str] = None) -> Dict[str, Any]: следующий код показывает, как сохранить извлеченные объекты и связи в базе данных Spanner Graph.

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

Предоставляя агентам инструменты высокого уровня, мы обеспечиваем целостность данных и используем возможности агента по рассуждению.

5. Обновить сервис 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.

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

Благодаря абстрагированию этого в сервис агенту не нужно знать о сегментах GCS, именах BLOB-объектов или создании подписанных URL. Вместо этого предлагается загрузить файл.

6. Почему агентные рабочие процессы лучше традиционных подходов?

Преимущества агентного подхода

Функция

Конвейер пакетной обработки

Управляемый событиями

Рабочий процесс с агентами

Сложность

Низкий (1 скрипт)

Высокая (более 5 сервисов)

Низкий (1 файл Python: multimedia_agent.py)

Управление состоянием

Глобальные переменные

Жесткая (несвязанная)

Унифицированный (статус агента)

Обработка ошибок

Сбои

Журналы без уведомлений

Интерактивный ("Не удалось прочитать файл")

Отзывы пользователей

Вывод в консоль

Нужен опрос

Немедленно (в чате)

Адаптивность

Исправлена логика

Жесткие функции

Умный (LLM решает, что делать дальше)

Контекстно-зависимый доступ

Нет

Нет

Полное (намерение пользователя понятно)

Почему это важно. Используя multimedia_agent.py (SequentialAgent с четырьмя субагентами: Upload, Extract, Save и Summary), мы заменяем сложную инфраструктуру и ненадежные скрипты интеллектуальной логикой приложения, основанной на диалогах.

10. ☕️ [Optional] Multimodal Pipeline (Read Only) — Agent Layer

Уровень агентов определяет интеллект – агентов, которые используют инструменты для выполнения задач. У каждого агента есть своя роль, и он передает контекст следующему. Ниже приведена схема архитектуры мультиагентной системы.

agent_diagram

1. Откройте файл агента.

👉💻 Откройте файл level_2/backend/agent/multimedia_agent.py или введите в терминале следующую команду: Откройте новое окно терминала. В терминале откройте файл в редакторе Cloud Shell:

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

2. Определите агент загрузки

Этот агент извлекает путь к файлу из сообщения пользователя и загружает его в 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"
)

3. Определите агент извлечения

Этот агент "видит" загруженные медиафайлы и извлекает структурированные данные с помощью 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 передается состояние между агентами.

4. Определите агент 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).

5. Определите агента для создания сводок

Этот агент синтезирует результаты всех предыдущих шагов в удобный для пользователя ответ.

👉 В файле 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

Что – управление конвейером

11. 🚀 Мультимодальный конвейер данных – оркестрация

Основой новой системы является MultimediaExtractionPipeline, определенный в backend/agent/multimedia_agent.py. Он использует шаблон последовательного агента из ADK (Agent Development Kit).

1. Почему именно последовательный?

Обработка загрузки – это линейная цепочка зависимостей:

  1. Вы не можете извлечь данные, пока у вас нет файла (Загрузка).
  2. Вы не можете сохранить данные, пока не извлечете их.
  3. Вы не можете обобщить результаты, пока не получите их (сохраните).

Для этого идеально подходит SequentialAgent. Выходные данные одного агента передаются в качестве контекста или входных данных следующему.

2. Определение агента

Давайте посмотрим, как конвейер собирается в нижней части файла 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]

3. Подключиться к корневому агенту

👉💻 В терминале откройте файл в редакторе Cloud Shell, выполнив следующую команду:

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

Найдите комментарий # TODO: REPLACE_ADD_SUBAGENT. Замените всю эту строку следующим кодом:

    sub_agents=[multimedia_agent],

Этот единственный объект эффективно объединяет четырех «экспертов» в одну вызываемую сущность.

4. Поток данных между агентами

Каждый агент сохраняет свои выходные данные в общем контексте, к которому могут обращаться последующие агенты:

architecture_uploading

5. Откройте приложение (пропустите этот шаг, если оно уже запущено).

👉💻 Запустите приложение:

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

👉 Нажмите Local: http://localhost:5173/ в терминале.

6. Загрузка тестового изображения

👉 В интерфейсе чата выберите любое из этих фото и загрузите его.

В интерфейсе чата расскажите агенту о своем контексте:

Here is the survivor note

и прикрепите изображение.

upload_input

upload_result

👉💻 Чтобы завершить процесс, нажмите Ctrl + C в терминале.

6. Как проверить мультимодальную загрузку в сегмент GCS

gcs

  • Выберите сегмент и нажмите media.

медиа

  • Посмотрите загруженное изображение. uploaded_img

7. Проверьте мультимодальную загрузку в Spanner (необязательно)

Ниже показан пример выходных данных в интерфейсе для test_photo1.

  • Откройте консоль Google Cloud 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

12. ☕️ [Optional] Memory Bank with Agent Engine

1. Как работает память

Система использует два типа памяти: для непосредственного контекста и для долгосрочного обучения.

memory_bank

2. Что такое темы воспоминаний?

Темы памяти определяют категории информации, которую агент должен запоминать в разных разговорах. Их можно сравнить с картотеками, в которых хранятся разные типы пользовательских настроек.

Наши темы:

  1. search_preferences: как пользователь предпочитает искать информацию.
    • Какой поиск они предпочитают: по ключевым словам или семантический?
    • Какие навыки/биомы они ищут чаще всего?
    • Пример: "Пользователь предпочитает семантический поиск для медицинских навыков".
  2. urgent_needs_context: за какими кризисами они следят.
    • Какие ресурсы они отслеживают?
    • О каких выживших они беспокоятся?
    • Пример: "Пользователь отслеживает нехватку лекарств в Северном лагере".

3. Настройка тем воспоминаний

Темы памяти определяют, что агент должен запоминать. Они настраиваются при развертывании 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, чтобы указать LLM, какую информацию нужно извлечь и сохранить.

👉 В файле 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."
                """,
            )
        )
    ]

4. Интеграция с агентом

Чтобы сохранять и извлекать информацию, код агента должен знать о банке памяти.

👉💻 В терминале откройте файл в редакторе 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, выполнив следующую команду:

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
    )

13. ☕️ [Необязательно] Как подключить агент к Agent Engine

1. Настройка и развертывание

Прежде чем тестировать функции памяти, необходимо развернуть агент с новыми темами памяти и убедиться, что среда настроена правильно.

Для этого мы подготовили специальный скрипт.

Запуск скрипта развертывания

👉💻 В терминале запустите скрипт развертывания:

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

Этот скрипт выполняет следующие действия:

  • Запускает backend/deploy_agent.py, чтобы зарегистрировать агента и темы памяти в Vertex AI.
  • Получает новый идентификатор системы агента.
  • Автоматически обновляет файл .env с помощью AGENT_ENGINE_ID.
  • Убедитесь, что в файле .env задано значение USE_MEMORY_BANK=TRUE.

[!IMPORTANT] Если вы измените custom_topics в deploy_agent.py, вам нужно будет повторно запустить этот скрипт, чтобы обновить Agent Engine.

Проверить банк памяти

Теперь вы можете проверить, работает ли банк памяти. Для этого сообщите агенту о своем предпочтении и посмотрите, сохранится ли оно в следующих сеансах.

Шаг 1. Открыть приложение

Снова откройте приложение, следуя инструкциям ниже. Если предыдущий терминал все ещё работает, закройте его, нажав Ctrls+C.

👉💻 Запустите приложение:

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

👉 Нажмите Local: http://localhost:5173/ в терминале.

Шаг 2. Тестирование банка памяти с текстом

В интерфейсе чата расскажите агенту о своем контексте:

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

👉 Подождите около 30 секунд, пока воспоминание обрабатывается в фоновом режиме.

Шаг 3. Как начать новый сеанс

Обновите страницу, чтобы очистить историю текущего разговора (краткосрочную память).

Задайте вопрос, опираясь на контекст, который вы предоставили ранее:

"What kind of missions am I interested in?"

Ожидаемый ответ

"Судя по предыдущим разговорам, вас интересует:

  • Медицинские спасательные миссии
  • Операции в горах и на большой высоте
  • Необходимые навыки: первая помощь, скалолазание

Хотите, я найду выживших, соответствующих этим критериям?"

Шаг 4. Тестирование с загрузкой изображения

Загрузите изображение и спросите:

remember this

Вы можете выбрать любое из этих изображений или загрузить свое.

Шаг 5. Проверить в Vertex AI Agent Engine

Перейдите в консоль Google Cloud Agent Engine.

  1. Выберите проект в левом верхнем углу:селектор проектов
  2. Проверьте агент, который вы только что развернули с помощью предыдущей команды use_memory_bank.sh:движок агентаНажмите на созданный агент.
  3. Нажмите на вкладку Memories в этом развернутом агенте, чтобы посмотреть всю память.Посмотреть воспоминание

👉💻 По завершении тестирования нажмите Ctrl + C в терминале, чтобы завершить процесс.

🎉 Поздравляем! Вы прикрепили банк памяти к агенту.

14. ☕️ [Необязательно] Развертывание в Cloud Run

1. Запустите скрипт развертывания

👉💻 Запустите скрипт развертывания:

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

После успешного развертывания вы получите URL. Это и есть URL развертывания. развернуто

👉💻 Прежде чем копировать URL, предоставьте разрешение, выполнив следующую команду:

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

Перейдите по URL развертывания, чтобы увидеть свое приложение.

2. Общие сведения о конвейере сборки

Файл cloudbuild.yaml определяет следующие последовательные шаги:

  1. Backend Build. Создает образ Docker из backend/Dockerfile.
  2. Backend Deploy – развертывает серверный контейнер в Cloud Run.
  3. Capture URL (Получить URL). Получение нового URL бэкенда.
  4. Сборка интерфейса:
    • Устанавливает зависимости.
    • Создает приложение React, внедряя VITE_API_URL=.
  5. Frontend Image: создает образ Docker из frontend/Dockerfile (упаковывает статические объекты).
  6. Frontend Deploy (Развертывание интерфейса). Развертывание контейнера интерфейса.

3. Проверка развертывания

После завершения сборки (проверьте ссылку на журналы, предоставленную скриптом) вы можете проверить:

  1. Откройте Cloud Run Console.
  2. Найдите сервис "survivor-frontend".
  3. Нажмите на URL, чтобы открыть приложение.
  4. Выполните поисковый запрос, чтобы убедиться, что интерфейс может взаимодействовать с серверной частью.

4. Ручное развертывание

Если вы предпочитаете выполнять команды вручную или хотите лучше понять процесс, ниже описано, как использовать cloudbuild.yaml напрямую.

Запись файла "cloudbuild.yaml"…

Файл cloudbuild.yaml сообщает Google Cloud Build, какие шаги нужно выполнить.

  • steps – список последовательных действий. Каждый шаг выполняется в контейнере (например, docker, gcloud, node, bash).
  • substitutions – переменные, которые можно передать во время сборки (например, $_REGION).
  • workspace – общий каталог, в котором шаги могут обмениваться файлами (например, 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"

15. Заключение

1. Что вы построили

✅ Графовая база данных. Spanner с узлами (выжившие, навыки) и ребрами (отношения).
✅ ИИ-поиск. Поиск по ключевым словам, семантический и гибридный поиск с эмбеддингами.
✅ Мультимодальный конвейер. Извлечение объектов из изображений и видео с помощью Gemini.
✅ Мультиагентная система. Координированный рабочий процесс с ADK.
✅ Банк памяти. Долгосрочная персонализация с помощью Vertex AI.
✅ Развертывание в рабочей среде. Cloud Run + Agent Engine.

2. Обзор архитектуры

architecture_fullstack

3. Основные выводы

  1. Graph RAG – сочетает структуру базы данных графов с семантическими эмбеддингами для умного поиска.
  2. Шаблоны с несколькими агентами. Последовательные конвейеры для сложных многоэтапных рабочих процессов.
  3. Мультимодальный ИИ. Извлечение структурированных данных из неструктурированных медиафайлов (изображений и видео).
  4. Агенты с сохранением состояния. Memory Bank позволяет персонализировать работу агентов в разных сеансах.

4. Контент мастерской

5. Ресурсы