1. Увертюра
Эпоха разрозненной разработки подходит к концу. Следующая волна технологической эволюции — это не гений-одиночка, а совместное мастерство. Создание единого умного агента — увлекательный эксперимент. Создание надёжной, безопасной и интеллектуальной экосистемы агентов — настоящей вселенной агентов — важнейшая задача для современного бизнеса.
Успех в эту новую эпоху требует объединения четырёх важнейших ролей, фундаментальных столпов, на которых держится любая процветающая агентурная система. Недостаток в любой области создаёт уязвимость, способную поставить под угрозу всю структуру.
Этот семинар — исчерпывающее руководство для предприятий по освоению агентного будущего в Google Cloud. Мы предлагаем комплексную дорожную карту, которая проведет вас от первой идеи до полномасштабной практической реализации. В ходе этих четырёх взаимосвязанных лабораторий вы узнаете, как специализированные навыки разработчика, архитектора, инженера по данным и специалиста по SRE должны быть объединены для создания, управления и масштабирования мощной среды Agentverse.
Ни один столп не может поддерживать мир агентов в одиночку. Грандиозный замысел архитектора бесполезен без точного исполнения разработчика. Агент разработчика слеп без мудрости инженера по данным, а вся система хрупка без защиты специалиста по SRE. Только благодаря синергии и общему пониманию ролей друг друга ваша команда сможет превратить инновационную концепцию в критически важную, операционную реальность. Ваше путешествие начинается здесь. Приготовьтесь освоить свою роль и понять, какое место вы занимаете в общей системе.
Добро пожаловать в мир Агентов: призыв к чемпионам
В бескрайних цифровых просторах бизнеса наступила новая эра. Это эпоха агентов, время огромных возможностей, когда интеллектуальные, автономные агенты работают в идеальной гармонии, ускоряя инновации и сметая обыденность.
Эта связанная экосистема власти и потенциала известна как Agentverse.
Но нарастающая энтропия, безмолвное разложение, известное как Статика, уже начала разрушать границы этого нового мира. Статика — это не вирус и не ошибка; это воплощение хаоса, пожирающего сам акт творения.
Он усиливает старые разочарования, принимая чудовищные формы, порождая Семь Призраков Развития. Если их не остановить, Статика и её Призраки затормозят прогресс, превратив обещания Вселенной Агентов в пустыню технического долга и заброшенных проектов.
Сегодня мы призываем чемпионов дать отпор волне хаоса. Нам нужны герои, готовые отточить своё мастерство и работать сообща ради защиты Вселенной Агентов. Пришло время выбрать свой путь.
Выберите свой класс
Перед вами четыре разных пути, каждый из которых — важнейшая опора в борьбе со Статикой . Хотя ваше обучение будет проходить в одиночку, ваш конечный успех зависит от понимания того, как ваши навыки сочетаются с навыками других.
- The Shadowblade (Разработчик) : Мастер кузницы и передовой. Вы — мастер, который создаёт клинки, создаёт инструменты и сражается с врагом в замысловатых деталях кода. Ваш путь — это точность, мастерство и практичное творчество.
- Призыватель (Архитектор) : великий стратег и организатор. Вы видите не отдельного агента, а всё поле боя. Вы разрабатываете главные чертежи, позволяющие целым системам агентов общаться, сотрудничать и достигать цели, гораздо более важной, чем любой отдельный компонент.
- Учёный (инженер данных) : искатель скрытых истин и хранитель мудрости. Вы отправляетесь в необъятные, дикие дебри данных, чтобы раскрыть тайны, которые дают вашим агентам цель и зрение. Ваши знания могут раскрыть слабости врага или усилить союзника.
- Страж (DevOps / SRE) : Непоколебимый защитник и щит королевства. Вы строите крепости, управляете линиями снабжения энергией и обеспечиваете всей системе устойчивость к неизбежным атакам Штатика. Ваша сила — фундамент, на котором строится победа вашей команды.
Ваша миссия
Ваше обучение начнётся как отдельное упражнение. Вы пройдёте по выбранному пути, осваивая уникальные навыки, необходимые для овладения вашей ролью. В конце испытания вы столкнётесь со Спектром, рождённым Статикой, — мини-боссом, который использует особые испытания вашего ремесла.
Только освоив свою индивидуальную роль, вы сможете подготовиться к решающему испытанию. Затем вам необходимо сформировать отряд из чемпионов других классов. Вместе вы отправитесь в самое сердце порчи, чтобы сразиться с величайшим боссом.
Последнее совместное испытание, которое проверит ваши объединенные силы и определит судьбу Вселенной Агентов.
Вселенная Агентов ждёт своих героев. Ответите ли вы на зов?
2. Гримуар ученого
Наше путешествие начинается! Как учёные, мы обладаем главным оружием – знаниями. Мы обнаружили в наших архивах (облачное хранилище Google) клад древних, загадочных свитков. Эти свитки содержат первоисточники информации о грозных зверях, наводнивших эти земли. Наша миссия – использовать мощную аналитическую магию Google BigQuery и мудрость Gemini Elder Brain (модель Gemini Pro), чтобы расшифровать эти неструктурированные тексты и объединить их в структурированный, доступный для поиска Бестиарий. Это станет основой всех наших будущих стратегий.
Чему вы научитесь
- Используйте BigQuery для создания внешних таблиц и выполнения сложных преобразований неструктурированных данных в структурированные с помощью BQML.GENERATE_TEXT с моделью Gemini.
- Подготовьте экземпляр Cloud SQL для PostgreSQL и включите расширение pgvector для возможностей семантического поиска.
- Создайте надежный контейнеризованный пакетный конвейер с использованием Dataflow и Apache Beam для обработки необработанных текстовых файлов, генерации векторных вложений с помощью модели Gemini и записи результатов в реляционную базу данных.
- Реализовать базовую систему поиска и расширенной генерации (RAG) в агенте для запроса векторизованных данных.
- Разверните агента, работающего с данными, как безопасную масштабируемую службу в Cloud Run.
3. Подготовка святилища ученого
Добро пожаловать, Учёный. Прежде чем мы начнём записывать могущественные знания нашего Гримуара, мы должны подготовить наше святилище. Этот основополагающий ритуал включает в себя зачарование нашей среды Google Cloud, открытие нужных порталов (API) и создание каналов, по которым будет течь наша магия данных. Хорошо подготовленное святилище гарантирует силу наших заклинаний и сохранность наших знаний.
👉Нажмите «Активировать Cloud Shell» в верхней части консоли Google Cloud (это значок в форме терминала в верхней части панели Cloud Shell),
👉Нажмите кнопку «Открыть редактор» (она выглядит как открытая папка с карандашом). В окне откроется редактор кода Cloud Shell. Слева вы увидите проводник. 
👉Найдите свой идентификатор проекта Google Cloud:
- Откройте консоль Google Cloud: https://console.cloud.google.com
- Выберите проект, который вы хотите использовать для этого семинара, из раскрывающегося списка проектов в верхней части страницы.
- Идентификатор вашего проекта отображается на карточке информации о проекте на панели инструментов.
👉Откройте терминал в облачной IDE, 
👉💻В терминале убедитесь, что вы уже аутентифицированы и что проекту присвоен ваш идентификатор проекта, с помощью следующей команды:
gcloud auth list
👉💻Клонируйте bootstrap-проект с GitHub:
git clone https://github.com/weimeilin79/agentverse-dataengineer
chmod +x ~/agentverse-dataengineer/init.sh
chmod +x ~/agentverse-dataengineer/set_env.sh
chmod +x ~/agentverse-dataengineer/data_setup.sh
git clone https://github.com/weimeilin79/agentverse-dungeon.git
chmod +x ~/agentverse-dungeon/run_cloudbuild.sh
chmod +x ~/agentverse-dungeon/start.sh
👉💻 Запустите скрипт инициализации. Этот скрипт предложит вам ввести идентификатор вашего проекта Google Cloud . Затем, когда скрипт init.sh попросит вас ввести идентификатор проекта Google Cloud, который вы нашли на предыдущем шаге, введите его.
cd ~/agentverse-dataengineer
./init.sh
👉💻 Установите необходимый идентификатор проекта:
gcloud config set project $(cat ~/project_id.txt) --quiet
👉💻 Выполните следующую команду, чтобы включить необходимые API Google Cloud:
gcloud services enable \
storage.googleapis.com \
bigquery.googleapis.com \
sqladmin.googleapis.com \
aiplatform.googleapis.com \
dataflow.googleapis.com \
pubsub.googleapis.com \
cloudfunctions.googleapis.com \
run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
iam.googleapis.com \
compute.googleapis.com \
cloudresourcemanager.googleapis.com \
cloudaicompanion.googleapis.com \
bigqueryunified.googleapis.com
👉💻 Если вы еще не создали репозиторий реестра артефактов с именем agentverse-repo, выполните следующую команду, чтобы создать его:
. ~/agentverse-dataengineer/set_env.sh
gcloud artifacts repositories create $REPO_NAME \
--repository-format=docker \
--location=$REGION \
--description="Repository for Agentverse agents"
Настройка разрешения
👉💻 Предоставьте необходимые разрешения, выполнив следующие команды в терминале:
. ~/agentverse-dataengineer/set_env.sh
# --- Grant Core Data Permissions ---
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/storage.admin"
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/bigquery.admin"
# --- Grant Data Processing & AI Permissions ---
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/dataflow.admin"
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/cloudsql.admin"
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/pubsub.admin"
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/aiplatform.user"
# --- Grant Deployment & Execution Permissions ---
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/cloudbuild.builds.editor"
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/artifactregistry.admin"
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/run.admin"
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/iam.serviceAccountUser"
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/logging.logWriter"
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/dataflow.admin"
👉💻 Когда вы начнёте обучение, мы подготовим финальное испытание. Следующие команды вызовут Спектров из хаоса и помех, создав боссов для вашего финального испытания.
. ~/agentverse-dataengineer/set_env.sh
cd ~/agentverse-dungeon
./run_cloudbuild.sh
cd ~/agentverse-dataengineer
Отличная работа, Учёный. Основополагающие чары завершены. Наше святилище в безопасности, порталы к стихийным силам данных открыты, а наш слуга наделён силой. Теперь мы готовы приступить к настоящей работе.
4. Алхимия знаний: преобразование данных с помощью BigQuery и Gemini
В непрекращающейся войне против Статики каждое столкновение между Чемпионом Агентвселенной и Призраком Развития тщательно документируется. Система симуляции поля боя, наша основная тренировочная среда, автоматически генерирует запись в эфирном журнале для каждого столкновения. Эти повествовательные журналы — наш ценнейший источник сырой информации, неочищенная руда, из которой мы, как Учёные, должны выковать чистейшую сталь стратегии. Истинная сила Учёного заключается не просто в обладании данными, но в способности преобразовывать сырую, хаотичную руду информации в сверкающую, структурированную сталь действенной мудрости. Мы проведём основополагающий ритуал алхимии данных.
Наше путешествие проведёт нас через многоэтапный процесс, полностью проходящий в святилище Google BigQuery. Мы начнём с того, что, не сдвинув ни одного свитка, посмотрим на наш архив GCS, используя магическую линзу. Затем мы призовём Близнецов, чтобы прочитать и интерпретировать поэтичные, неструктурированные саги боевых журналов. Наконец, мы очистим сырые пророчества, превратив их в набор безупречных, взаимосвязанных таблиц. Наш первый Гримуар. И зададим ему вопрос настолько глубокий, что ответить на него можно было только с помощью этой новой структуры.
Примечание инженера по данным: Мы собираемся реализовать мощный шаблон ELT (извлечение, загрузка, преобразование) на базе данных с использованием искусственного интеллекта. Это передовой подход, который существенно отличается от традиционных методов.
- Извлечение и загрузка (через внешнюю таблицу): вместо дорогостоящего процесса загрузки (традиционного «L») мы будем использовать внешнюю таблицу BigQuery. Это реализует принцип «схема при чтении», позволяя нашему хранилищу данных запрашивать необработанные текстовые файлы непосредственно в облачном хранилище. Это невероятно эффективно, исключая перемещение данных и дублирование хранилищ.
- Преобразование (через ML.GENERATE_TEXT): буква «T» в нашем ELT — это то, где происходит настоящее волшебство. Мы будем использовать функцию ML.GENERATE_TEXT для вызова модели Gemini непосредственно из SQL-запроса. Это позволяет нам выполнять сложные, контекстно-зависимые преобразования — в данном случае, преобразование неструктурированного описательного текста в структурированный JSON без написания или управления отдельным конвейером обработки на другом языке (например, Python или Java). Это смена парадигмы, отказ от хрупких, жёстко запрограммированных решений, таких как регулярные выражения, в пользу гибкости и мощности с простым SQL-интерфейсом.
Объективный анализ: взгляд на GCS с помощью внешних таблиц BigQuery
Первым делом мы создаём линзу, которая позволяет нам видеть содержимое архива GCS, не затрагивая прокрутку внутри. Внешняя таблица — это линза, которая преобразует необработанные текстовые файлы в табличную структуру, к которой BigQuery может обращаться напрямую.
Для этого нам необходимо сначала создать стабильную лей-линию силы, ресурс СОЕДИНЕНИЯ, который надежно свяжет наше святилище BigQuery с архивом GCS.
👉💻 В терминале Cloud Shell выполните следующую команду, чтобы настроить хранилище и создать канал:
. ~/agentverse-dataengineer/set_env.sh
. ~/agentverse-dataengineer/data_setup.sh
bq mk --connection \
--connection_type=CLOUD_RESOURCE \
--project_id=${PROJECT_ID} \
--location=${REGION} \
gcs-connection
💡 Внимание! Сообщение появится позже!
Скрипт настройки из шага 2 запустил фоновый процесс. Через несколько минут в терминале появится сообщение, похожее на следующее: [1]+ Done gcloud sql instances create ... Это нормально и ожидаемо. Это просто означает, что ваша база данных Cloud SQL успешно создана. Вы можете игнорировать это сообщение и продолжить работу.
Прежде чем создать внешнюю таблицу, необходимо сначала создать набор данных, который будет ее содержать.
👉💻 Выполните эту простую команду в терминале Cloud Shell:
. ~/agentverse-dataengineer/set_env.sh
bq --location=${REGION} mk --dataset ${PROJECT_ID}:bestiary_data
👉💻 Теперь нам нужно предоставить магической подписи канала необходимые разрешения на чтение из архива GCS и обращение к Gemini.
. ~/agentverse-dataengineer/set_env.sh
export CONNECTION_SA=$(bq show --connection --project_id=${PROJECT_ID} --location=${REGION} --format=json gcs-connection | jq -r '.cloudResource.serviceAccountId')
echo "The Conduit's Magical Signature is: $CONNECTION_SA"
echo "Granting key to the GCS Archive..."
gcloud storage buckets add-iam-policy-binding gs://${PROJECT_ID}-reports \
--member="serviceAccount:$CONNECTION_SA" \
--role="roles/storage.objectViewer"
gcloud projects add-iam-policy-binding ${PROJECT_ID} \
--member="serviceAccount:$CONNECTION_SA" \
--role="roles/aiplatform.user"
👉💻 В терминале Cloud Shell выполните следующую команду, чтобы отобразить имя вашего контейнера:
echo $BUCKET_NAME
В вашем терминале отобразится имя, похожее на your-project-id-gcs-bucket . Оно понадобится вам на следующих этапах.
👉 Вам нужно выполнить следующую команду в редакторе запросов BigQuery в Google Cloud Console. Проще всего это сделать, открыв ссылку ниже в новой вкладке браузера . Она перенаправит вас на нужную страницу в Google Cloud Console.
https://console.cloud.google.com/bigquery
👉 После загрузки страницы нажмите синюю кнопку + (Создать новый запрос), чтобы открыть новую вкладку редактора.
Теперь мы пишем заклинание на языке определения данных (DDL), чтобы создать нашу магическую линзу. Оно сообщает BigQuery, куда смотреть и что видеть.
👉📜 В открывшемся редакторе запросов BigQuery вставьте следующий SQL-код. Не забудьте заменить REPLACE-WITH-YOUR-BUCKET-NAME
с именем контейнера, которое вы только что скопировали . Нажмите «Выполнить» :
CREATE OR REPLACE EXTERNAL TABLE bestiary_data.raw_intel_content_table (
raw_text STRING
)
OPTIONS (
format = 'CSV',
-- This is a trick to load each line of the text files as a single row.
field_delimiter = '§',
uris = ['gs://REPLACE-WITH-YOUR-BUCKET-NAME/raw_intel/*']
);
👉📜 Запустите запрос, чтобы «взглянуть сквозь объектив» и увидеть содержимое файлов.
SELECT * FROM bestiary_data.raw_intel_content_table;
Наша линза на месте. Теперь мы видим исходный текст свитков. Но чтение не означает понимание.
В Архивах Забытых Идей Элара (обозначение adv_001) столкнулась с ангельским Призраком Перфекционизма. Сущность, обозначенная как «p-01», излучала жизненную силу в 120 очков здоровья. Одним-единственным, сфокусированным заклинанием «Изысканной Достаточности» Элара разрушила его парализующую ауру, нанеся ментальный удар в 150 единиц урона. Бой длился 180 секунд, наполненных предельной концентрацией. Итоговая оценка: победа.
Свитки написаны не таблицами и рядами, а извилистым слогом саг. Это наше первое великое испытание.
Прорицание учёного: превращение текста в таблицу с помощью SQL
Проблема в том, что отчёт, подробно описывающий быстрые двойные атаки Теневого Клинка, читается совершенно иначе, чем хроника Призывателя, собирающего огромную силу для одного сокрушительного удара. Мы не можем просто импортировать эти данные; мы должны их интерпретировать. Это момент магии. Мы используем один SQL-запрос как мощное заклинание для чтения, понимания и структурирования всех записей во всех наших файлах прямо в BigQuery.
👉💻 Вернувшись в терминал Cloud Shell, выполните следующую команду, чтобы отобразить имя вашего подключения:
echo "${PROJECT_ID}.${REGION}.gcs-connection"
Ваш терминал отобразит полную строку подключения. Выберите и скопируйте всю эту строку. Она понадобится вам на следующем шаге.
Мы воспользуемся одним мощным заклинанием: ML.GENERATE_TEXT . Это заклинание призывает Близнецов, показывает им каждый свиток и приказывает им возвращать основные факты в виде структурированного JSON-объекта.
👉📜 В BigQuery Studio создайте ссылку на модель Gemini. Это привяжет оракул Gemini Flash к нашей библиотеке BigQuery, чтобы мы могли вызывать его в запросах. Не забудьте заменить
REPLACE-WITH-YOUR-FULL-CONNECTION-STRING на полную строку подключения, которую вы только что скопировали из терминала.
CREATE OR REPLACE MODEL bestiary_data.gemini_flash_model
REMOTE WITH CONNECTION `REPLACE-WITH-YOUR-FULL-CONNECTION-STRING`
OPTIONS (endpoint = 'gemini-2.5-flash');
👉📜 Теперь произнесите великое заклинание трансмутации. Этот запрос считывает исходный текст, формирует подробное сообщение для каждого свитка, отправляет его в Gemini и формирует новую промежуточную таблицу на основе структурированного JSON-ответа ИИ.
CREATE OR REPLACE TABLE bestiary_data.structured_bestiary AS
SELECT
-- THE CRITICAL CHANGE: We remove PARSE_JSON. The result is already a JSON object.
ml_generate_text_result AS structured_data
FROM
ML.GENERATE_TEXT(
-- Our bound Gemini Flash model.
MODEL bestiary_data.gemini_flash_model,
-- Our perfectly constructed input, with the prompt built for each row.
(
SELECT
CONCAT(
"""
From the following text, extract structured data into a single, valid JSON object.
Your output must strictly conform to the following JSON structure and data types. Do not add, remove, or change any keys.
{
"monster": {
"monster_id": "string",
"name": "string",
"type": "string",
"hit_points": "integer"
},
"battle": {
"battle_id": "string",
"monster_id": "string",
"adventurer_id": "string",
"outcome": "string",
"duration_seconds": "integer"
},
"adventurer": {
"adventurer_id": "string",
"name": "string",
"class": "string"
}
}
**CRUCIAL RULES:**
- Do not output any text, explanations, conversational filler, or markdown formatting like ` ```json` before or after the JSON object.
- Your entire response must be ONLY the raw JSON object itself.
Here is the text:
""",
raw_text -- We append the actual text of the report here.
) AS prompt -- The final column is still named 'prompt', as the oracle requires.
FROM
bestiary_data.raw_intel_content_table
),
-- The STRUCT now ONLY contains model parameters.
STRUCT(
0.2 AS temperature,
2048 AS max_output_tokens
)
);
Преобразование завершено, но результат ещё не идеален. Модель Gemini возвращает ответ в стандартном формате, обёртывая наш желаемый JSON-код в более крупную структуру, содержащую метаданные о мыслительном процессе. Давайте рассмотрим это сырое пророчество, прежде чем пытаться его очистить.
👉📜 Запустите запрос для проверки необработанных выходных данных модели Gemini:
SELECT * FROM bestiary_data.structured_bestiary;
👀 Вы увидите один столбец с именем structured_data. Содержимое каждой строки будет похоже на этот сложный JSON-объект:
{"candidates":[{"avg_logprobs":-0.5691758094475283,"content":{"parts":[{"text":"```json\n{\n \"monster\": {\n \"monster_id\": \"gw_02\",\n \"name\": \"Gravewight\",\n \"type\": \"Gravewight\",\n \"hit_points\": 120\n },\n \"battle\": {\n \"battle_id\": \"br_735\",\n \"monster_id\": \"gw_02\",\n \"adventurer_id\": \"adv_001\",\n \"outcome\": \"Defeat\",\n \"duration_seconds\": 45\n },\n \"adventurer\": {\n \"adventurer_id\": \"adv_001\",\n \"name\": \"Elara\",\n \"class\": null\n }\n}\n```"}],"role":"model"},"finish_reason":"STOP","score":-97.32906341552734}],"create_time":"2025-07-28T15:53:24.482775Z","model_version":"gemini-2.5-flash","response_id":"9JyHaNe7HZ2WhMIPxqbxEQ","usage_metadata":{"billable_prompt_usage":{"text_count":640},"candidates_token_count":171,"candidates_tokens_details":[{"modality":"TEXT","token_count":171}],"prompt_token_count":207,"prompt_tokens_details":[{"modality":"TEXT","token_count":207}],"thoughts_token_count":1014,"total_token_count":1392,"traffic_type":"ON_DEMAND"}}
Как видите, наш приз — запрошенный нами чистый JSON-объект — глубоко вложен в эту структуру. Наша следующая задача ясна. Мы должны провести ритуал, чтобы систематически перемещаться по этой структуре и извлечь из неё чистую мудрость.
Ритуал очищения: нормализация вывода GenAI с помощью SQL
Близнецы высказались, но слова их сыры и окутаны эфирными энергиями своего творения (кандидаты, финиш_разум и т. д.). Истинный Учёный не просто откладывает сырое пророчество; он бережно извлекает глубокую мудрость и записывает её в соответствующие тома для будущего использования.
Теперь мы применим наш последний набор заклинаний. Этот скрипт:
- Прочитайте необработанный вложенный JSON из нашей промежуточной таблицы.
- Очистите и проанализируйте его, чтобы добраться до основных данных.
- Впишите соответствующие части в три окончательные, безупречные таблицы: монстры, искатели приключений и сражения.
👉📜 В новом редакторе запросов BigQuery выполните следующее заклинание, чтобы создать очищающую линзу:
CREATE OR REPLACE TABLE bestiary_data.monsters AS
WITH
CleanedDivinations AS (
SELECT
SAFE.PARSE_JSON(
REGEXP_EXTRACT(
JSON_VALUE(structured_data, '$.candidates[0].content.parts[0].text'),
r'\{[\s\S]*\}'
)
) AS report_data
FROM
bestiary_data.structured_bestiary
)
SELECT
JSON_VALUE(report_data, '$.monster.monster_id') AS monster_id,
JSON_VALUE(report_data, '$.monster.name') AS name,
JSON_VALUE(report_data, '$.monster.type') AS type,
SAFE_CAST(JSON_VALUE(report_data, '$.monster.hit_points') AS INT64) AS hit_points
FROM
CleanedDivinations
WHERE
report_data IS NOT NULL
QUALIFY ROW_NUMBER() OVER (PARTITION BY monster_id ORDER BY name) = 1;
👉📜 Проверьте Бестиарий:
SELECT * FROM bestiary_data.monsters;
Далее мы составим список чемпионов — отважных искателей приключений, сражавшихся с этими чудовищами.
👉📜 В новом редакторе запросов выполните следующее заклинание, чтобы создать таблицу искателей приключений:
CREATE OR REPLACE TABLE bestiary_data.adventurers AS
WITH
CleanedDivinations AS (
SELECT
SAFE.PARSE_JSON(
REGEXP_EXTRACT(
JSON_VALUE(structured_data, '$.candidates[0].content.parts[0].text'),
r'\{[\s\S]*\}'
)
) AS report_data
FROM
bestiary_data.structured_bestiary
)
SELECT
JSON_VALUE(report_data, '$.adventurer.adventurer_id') AS adventurer_id,
JSON_VALUE(report_data, '$.adventurer.name') AS name,
JSON_VALUE(report_data, '$.adventurer.class') AS class
FROM
CleanedDivinations
QUALIFY ROW_NUMBER() OVER (PARTITION BY adventurer_id ORDER BY name) = 1;
👉📜 Проверьте список чемпионов:
SELECT * FROM bestiary_data.adventurers;
Наконец, мы создадим таблицу фактов: «Хронику сражений». Этот том связывает два других, записывая подробности каждой уникальной битвы. Поскольку каждая битва — уникальное событие, дедупликация не требуется.
👉📜 В новом редакторе запросов выполните следующее заклинание, чтобы создать таблицу сражений:
CREATE OR REPLACE TABLE bestiary_data.battles AS
WITH
CleanedDivinations AS (
SELECT
SAFE.PARSE_JSON(
REGEXP_EXTRACT(
JSON_VALUE(structured_data, '$.candidates[0].content.parts[0].text'),
r'\{[\s\S]*\}'
)
) AS report_data
FROM
bestiary_data.structured_bestiary
)
-- Extract the raw essence for all battle fields and cast where necessary.
SELECT
JSON_VALUE(report_data, '$.battle.battle_id') AS battle_id,
JSON_VALUE(report_data, '$.battle.monster_id') AS monster_id,
JSON_VALUE(report_data, '$.battle.adventurer_id') AS adventurer_id,
JSON_VALUE(report_data, '$.battle.outcome') AS outcome,
SAFE_CAST(JSON_VALUE(report_data, '$.battle.duration_seconds') AS INT64) AS duration_seconds
FROM
CleanedDivinations;
👉📜 Проверьте Хронику:
SELECT * FROM bestiary_data.battles;
Раскрытие стратегических идей
Свитки прочитаны, суть извлечена, тома написаны. Наш Гримуар — это уже не просто собрание фактов, а реляционная база данных, хранящая глубокую стратегическую мудрость. Теперь мы можем задавать вопросы, на которые было невозможно ответить, когда наши знания были заперты в сыром, неструктурированном тексте.
Давайте же совершим последнее, великое предсказание. Мы произнесём заклинание, которое одновременно обратится ко всем трём нашим книгам — «Бестиарию чудовищ», «Списку чемпионов» и «Хронике битв», — чтобы открыть глубокое, действенное откровение.
Наш стратегический вопрос: «Как называется самое сильное чудовище (по очкам здоровья), которого каждый искатель приключений успешно победил, и сколько времени заняла эта конкретная победа?»
Это сложный вопрос, требующий связи между чемпионами и их победными битвами, а эти битвы — со статистикой участвующих монстров. В этом и заключается истинная сила структурированной модели данных.
👉📜 В новом редакторе запросов BigQuery произнесите следующее финальное заклинание:
-- This is our final spell, joining all three tomes to reveal a deep insight.
WITH
-- First, we consult the Chronicle of Battles to find only the victories.
VictoriousBattles AS (
SELECT
adventurer_id,
monster_id,
duration_seconds
FROM
bestiary_data.battles
WHERE
outcome = 'Victory'
),
-- Next, we create a temporary record for each victory, ranking the monsters
-- each adventurer defeated by their power (hit points).
RankedVictories AS (
SELECT
v.adventurer_id,
m.name AS monster_name,
m.hit_points,
v.duration_seconds,
-- This spell ranks each adventurer's victories from most to least powerful monster.
ROW_NUMBER() OVER (PARTITION BY v.adventurer_id ORDER BY m.hit_points DESC) as victory_rank
FROM
VictoriousBattles v
JOIN
bestiary_data.monsters m ON v.monster_id = m.monster_id
)
-- Finally, we consult the Roll of Champions and join it with our ranked victories
-- to find the name of each champion and the details of their greatest triumph.
SELECT
a.name AS adventurer_name,
a.class AS adventurer_class,
r.monster_name AS most_powerful_foe_defeated,
r.hit_points AS foe_hit_points,
r.duration_seconds AS duration_of_greatest_victory
FROM
bestiary_data.adventurers a
JOIN
RankedVictories r ON a.adventurer_id = r.adventurer_id
WHERE
-- We only want to see their number one, top-ranked victory.
r.victory_rank = 1
ORDER BY
foe_hit_points DESC;
Результатом этого запроса станет аккуратная и красивая таблица, содержащая «Историю величайшего подвига чемпиона» для каждого искателя приключений в вашем наборе данных. Она может выглядеть примерно так:
Закройте вкладку «Большой запрос».
Этот отдельный, но элегантный результат доказывает ценность всего процесса. Вам удалось превратить сырые, хаотичные отчёты с поля боя в источник легендарных историй и стратегических, основанных на данных идей.
5. Гримуар писца: разделение данных на фрагменты, внедрение и поиск в хранилище данных
Наша работа в лаборатории алхимика увенчалась успехом. Мы преобразовали необработанные повествовательные свитки в структурированные реляционные таблицы — настоящее чудо магии данных. Однако сами исходные свитки всё ещё содержат более глубокую семантическую истину, которую наши структурированные таблицы не могут полностью отразить. Чтобы создать по-настоящему мудрого агента, мы должны раскрыть этот смысл.
Грубый, длинный свиток — тупой инструмент. Если наш агент задаст вопрос о «парализующей ауре», простой поиск может выдать полный отчёт о битве, где эта фраза упоминается лишь однажды, скрывая ответ среди несущественных подробностей. Искусный учёный знает, что истинная мудрость заключается не в объёме, а в точности.
Мы выполним три мощных ритуала внутри базы данных исключительно в нашем святилище BigQuery.
- Ритуал разделения (разбиения на фрагменты): мы возьмем наши сырые разведывательные журналы и тщательно разобьем их на более мелкие, конкретные, самостоятельные отрывки.
- Ритуал дистилляции (встраивания): мы будем использовать BQML для обращения к модели Gemini, преобразуя каждый фрагмент текста в «семантический отпечаток» — векторное встраивание.
- Ритуал прорицания (поиск): мы воспользуемся векторным поиском BQML, чтобы задать вопрос на простом английском языке и найти наиболее релевантную, концентрированную мудрость из нашего Гримуара.
Весь этот процесс создает мощную, доступную для поиска базу знаний, при этом данные никогда не покидают безопасную и масштабируемую среду BigQuery.
Примечание инженера по данным: здесь показан полный, сквозной конвейер подготовки данных RAG, полностью реализованный в BigQuey. Этот шаблон значительно упрощает операционные издержки традиционных конвейеров ИИ. Используя BQML для фрагментации, встраивания и поиска, мы устраняем необходимость в раздельном перемещении данных, обработке кластеров (например, Spark) или вызовах внешнего API, делая рабочий процесс быстрее, безопаснее и проще в управлении.
Ритуал разделения: деконструкция свитков с помощью SQL
Нашим источником мудрости остаются необработанные текстовые файлы в архиве GCS, доступные через внешнюю таблицу bestiary_data.raw_intel_content_table . Наша первая задача — написать заклинание, которое считывает каждый длинный свиток и разбивает его на ряд более коротких, более удобочитаемых стихов. В этом ритуале мы определим «фрагмент» как одно предложение.
Хотя разбиение по предложениям — это понятная и эффективная отправная точка для наших повествовательных журналов, мастер-писец располагает множеством стратегий разбиения на фрагменты, и выбор этого метода критически важен для качества конечного поиска. Более простые методы могут использовать
- Фиксированная длина(размер) Фрагментация , но это может грубо разрезать ключевую идею пополам.
Более сложные ритуалы, такие как
- На практике часто предпочитают рекурсивное разделение текста на фрагменты. Оно позволяет сначала разделить текст по естественным границам, например, на абзацы, а затем вернуться к предложениям, чтобы сохранить как можно больше семантического контекста. Для действительно сложных рукописей.
- Контентно-зависимая фрагментация (документа) , при которой писец использует внутреннюю структуру документа, например заголовки в техническом руководстве или функции в свитке кода, для создания наиболее логичных и эффективных фрагментов информации. и многое другое...
Для наших боевых журналов это предложение обеспечивает идеальный баланс детализации и контекста.
👉📜 В новом редакторе запросов BigQuery выполните следующее заклинание. Это заклинание использует функцию SPLIT для разбиения текста каждого свитка по каждой точке (.), а затем разделяет полученный массив предложений на отдельные строки.
CREATE OR REPLACE TABLE bestiary_data.chunked_intel AS
WITH
-- First, add a unique row number to each scroll to act as a document ID.
NumberedScrolls AS (
SELECT
ROW_NUMBER() OVER () AS scroll_id,
raw_text
FROM
bestiary_data.raw_intel_content_table
)
-- Now, process each numbered scroll.
SELECT
scroll_id,
-- Assign a unique ID to each chunk within a scroll for precise reference.
CONCAT(CAST(scroll_id AS STRING), '-', CAST(ROW_NUMBER() OVER (PARTITION BY scroll_id) AS STRING)) as chunk_id,
-- Trim whitespace from the chunk for cleanliness.
TRIM(chunk) AS chunk_text
FROM
NumberedScrolls,
-- This is the core of the spell: UNNEST splits the array of sentences into rows.
UNNEST(SPLIT(raw_text, '.')) AS chunk
-- A final refinement: we only keep chunks that have meaningful content.
WHERE
-- This ensures we don't have empty rows from double periods, etc.
LENGTH(TRIM(chunk)) > 15;
👉 Теперь выполните запрос, чтобы проверить ваши новые записанные, разбитые на блоки знания и увидеть разницу.
SELECT * FROM bestiary_data.chunked_intel ORDER BY scroll_id, chunk_id;
Посмотрите на результат. Там, где раньше был один плотный блок текста, теперь несколько строк, каждая из которых привязана к исходному прокрутке (scroll_id), но содержит только одно конкретное предложение. Каждая строка теперь идеально подходит для векторизации.
Ритуал дистилляции: преобразование текста в векторы с помощью BQML
👉💻 Сначала вернитесь в терминал и выполните следующую команду, чтобы отобразить имя вашего подключения:
. ~/agentverse-dataengineer/set_env.sh
echo "${PROJECT_ID}.${REGION}.gcs-connection"
👉📜 Нам нужно создать новую модель BigQuery, указывающую на встраивание текста в Gemini. В BigQuery Studio выполните следующее заклинание. Обратите внимание, что REPLACE-WITH-YOUR-FULL-CONNECTION-STRING необходимо заменить полной строкой подключения, которую вы только что скопировали из терминала.
CREATE OR REPLACE MODEL bestiary_data.text_embedding_model
REMOTE WITH CONNECTION `REPLACE-WITH-YOUR-FULL-CONNECTION-STRING`
OPTIONS (endpoint = 'text-embedding-005');
👉📜 Теперь произнесите заклинание великой дистилляции. Этот запрос вызывает функцию ML.GENERATE_EMBEDDING, которая считывает каждую строку из нашей таблицы chunked_intel, отправляет текст в модель встраивания Gemini и сохраняет полученный векторный отпечаток в новой таблице.
CREATE OR REPLACE TABLE bestiary_data.embedded_intel AS
SELECT
*
FROM
ML.GENERATE_EMBEDDING(
-- The embedding model we just created.
MODEL bestiary_data.text_embedding_model,
-- A subquery that selects our data and renames the text column to 'content'.
(
SELECT
scroll_id,
chunk_id,
chunk_text AS content -- Renaming our text column is the key correction.
FROM
bestiary_data.chunked_intel
),
-- The configuration struct is now simpler and correct.
STRUCT(
-- This task_type is crucial. It optimizes the vectors for retrieval.
'RETRIEVAL_DOCUMENT' AS task_type
)
);
Этот процесс может занять минуту или две, поскольку BigQuery обрабатывает все текстовые фрагменты.
👉📜 После завершения проверьте новую таблицу, чтобы увидеть семантические отпечатки.
SELECT
chunk_id,
content,
ml_generate_embedding_result
FROM
bestiary_data.embedded_intel
LIMIT 20;
Теперь вы увидите новый столбец, ml_generate_embedding_result , содержащий плотное векторное представление вашего текста. Наш Гримуар теперь семантически закодирован.
Ритуал гадания: семантический поиск с BQML
👉📜 Окончательная проверка нашего Гримуара — задать ему вопрос. Сейчас мы проведём наш последний ритуал: векторный поиск. Это не поиск по ключевым словам, а поиск смысла. Мы зададим вопрос на естественном языке, BQML мгновенно преобразует наш вопрос во встраиваемый код, а затем выполнит поиск по всей таблице embedded_intel чтобы найти фрагменты текста, отпечатки которых наиболее близки по смыслу.
SELECT
-- The content column contains our original, relevant text chunk.
base.content,
-- The distance metric shows how close the match is (lower is better).
distance
FROM
VECTOR_SEARCH(
-- The table containing the knowledge base with its embeddings.
TABLE bestiary_data.embedded_intel,
-- The column that contains the vector embeddings.
'ml_generate_embedding_result',
(
-- This subquery generates an embedding for our question in real-time.
SELECT ml_generate_embedding_result
FROM ML.GENERATE_EMBEDDING(
MODEL bestiary_data.text_embedding_model,
(SELECT 'What are the tactics against a foe that causes paralysis?' AS content),
STRUCT('RETRIEVAL_QUERY' AS task_type)
)
),
-- Specify how many of the closest results we want to see.
top_k => 3,
-- The distance metric used to find the "closest" vectors.
distance_type => 'COSINE'
);
Анализ заклинания:
-
VECTOR_SEARCH: Основная функция, которая организует поиск. -
ML.GENERATE_EMBEDDING(внутренний запрос): Это магия. Мы встраиваем наш запрос ('What are the tactics...'), используя ту же модель , но с типом задачи'RETRIEVAL_QUERY', который специально оптимизирован для запросов. -
top_k => 3: Мы запрашиваем 3 самых релевантных результата. -
distance_type => 'COSINE': измеряет «угол» между векторами. Чем меньше угол, тем ближе значения к друг другу.
Внимательно посмотрите на результаты. В запросе не было слов «разрушенный» или «заклинание», однако первый результат выглядит так: «Одним целенаправленным заклинанием Элегантной Достаточности Элара разрушила его парализующую ауру, нанеся ментальный удар в 150 единиц урона» . В этом и заключается сила семантического поиска. Модель распознала концепцию «тактики против паралича» и нашла предложение, описывающее конкретную успешную тактику.
Вы успешно построили полноценный базовый конвейер RAG в вашем хранилище данных. Вы подготовили необработанные данные, преобразовали их в семантические векторы и выполнили запросы по смыслу. BigQuery — мощный инструмент для такой масштабной аналитической работы, но для оперативного агента, которому требуются ответы с малой задержкой, мы часто переносим эти подготовленные данные в специализированную операционную базу данных. Это тема нашего следующего тренинга.
6. Векторный скрипторий: создание векторного хранилища с использованием облачного SQL для вывода
Наш Гримуар в настоящее время существует в виде структурированных таблиц — мощного каталога фактов, но его знания буквальны. Он понимает monster_id = 'MN-001', но не более глубокий семантический смысл «Запутывания». Чтобы дать нашим агентам истинную мудрость, позволить им давать советы, основанные на нюансах и предвидении, мы должны свести самую суть наших знаний к форме, которая отражает смысл: Векторы .
Наши поиски знаний привели нас к разрушающимся руинам давно забытой цивилизации-предшественницы. Глубоко в запечатанном склепе мы обнаружили сундук с чудесным образом сохранившимися древними свитками. Это не просто боевые отчёты; в них содержится глубокая философская мудрость о том, как победить зверя, который мешает всем великим начинаниям. Сущность, описанная в свитках как «ползучая, безмолвная стагнация», «истечение ткани творения». Похоже, Статика была известна ещё древним – циклическая угроза, история которой затерялась во времени.
Эти забытые знания — наше величайшее достояние. Они хранят ключ не только к победе над отдельными монстрами, но и к наделению всей группы стратегическим видением. Чтобы овладеть этой силой, мы создадим истинную Книгу Заклинаний Учёного (базу данных PostgreSQL с векторными возможностями) и построим автоматизированный Векторный Скрипторий (конвейер потока данных) для чтения, понимания и записи вневременной сути этих свитков. Это превратит наш Гримуар из книги фактов в инструмент мудрости.
Примечание инженера по данным: для нашей книги заклинаний мы выбрали Cloud SQL для PostgreSQL с расширением pgvector. Такой подход создаёт «единое окно», где наши структурированные метаданные (например, scroll_id и content) и наши семантические векторные вложения хранятся в одной базе данных. Это значительно упрощает архитектуру для многих приложений, поскольку вы можете запрашивать как реляционные данные, так и выполнять поиск по сходству векторов одним SQL-запросом к одной системе. В то время как специализированные базы данных, такие как Vertex AI Vector Search, обеспечивают превосходную производительность при больших масштабах (миллиарды векторов) благодаря поиску по приближенным ближайшим соседям (ANN), pgvector обеспечивает отличный баланс простоты, экономичности и мощности для многих корпоративных RAG-приложений, использующих поиск по точным ближайшим соседям (ENN).
Создание книги заклинаний ученого (Cloud SQL)
Прежде чем мы сможем записать суть этих древних свитков, мы должны убедиться, что вместилище для этих знаний, управляемая Книга заклинаний PostgreSQL, успешно создано. Начальные ритуалы настройки должны были уже создать его для вас.
👉💻 В терминале выполните следующую команду, чтобы убедиться, что ваш экземпляр Cloud SQL существует и готов. Этот скрипт также предоставляет выделенной учётной записи службы экземпляра разрешение на использование Vertex AI, что необходимо для создания встраиваемых данных непосредственно в базе данных.
. ~/agentverse-dataengineer/set_env.sh
echo "Verifying the existence of the Spellbook (Cloud SQL instance): $INSTANCE_NAME..."
gcloud sql instances describe $INSTANCE_NAME
SERVICE_ACCOUNT_EMAIL=$(gcloud sql instances describe $INSTANCE_NAME --format="value(serviceAccountEmailAddress)")
gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_EMAIL" \
--role="roles/aiplatform.user"
Если команда выполнена успешно и возвращает информацию о вашем экземпляре grimoire-spellbook , кузница выполнила свою работу успешно. Вы готовы перейти к следующему заклинанию. Если команда возвращает ошибку NOT_FOUND , убедитесь, что вы успешно выполнили начальную настройку среды, прежде чем продолжить. ( data_setup.py )
👉💻 Подделав книгу, мы открываем ее на первой главе, создавая новую базу данных с именем arcane_wisdom .
. ~/agentverse-dataengineer/set_env.sh
gcloud sql databases create $DB_NAME --instance=$INSTANCE_NAME
Вписывание семантических рун: включение векторных возможностей с помощью pgvector
Теперь, когда ваш экземпляр Cloud SQL создан, давайте подключимся к нему с помощью встроенной Cloud SQL Studio. Она предоставляет веб-интерфейс для выполнения SQL-запросов непосредственно в вашей базе данных.
👉💻 Сначала перейдите в Cloud SQL Studio. Самый простой и быстрый способ сделать это — открыть следующую ссылку в новой вкладке браузера. Она перенаправит вас прямо в Cloud SQL Studio для вашего экземпляра гримуара и книги заклинаний.
https://console.cloud.google.com/sql/instances/grimoire-spellbook/studio
👉 Выберите arcane_wisdom в качестве базы данных. Введите postgres как пользователя и 1234qwer как пароль и нажмите «Аутентифицировать» .
👉📜 В редакторе запросов SQL Studio перейдите на вкладку Редактор 1 и вставьте следующий код SQL, чтобы включить векторный тип данных:
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
👉📜 Подготовьте страницы нашей книги заклинаний, создав таблицу, в которой будет храниться сущность наших свитков.
CREATE TABLE ancient_scrolls (
id SERIAL PRIMARY KEY,
scroll_content TEXT,
embedding VECTOR(768)
);
Заклинание VECTOR(768) — важная деталь. Модель встраивания Vertex AI, которую мы будем использовать ( textembedding-gecko@003 или аналогичная), преобразует текст в вектор размерностью 768. Страницы нашей книги заклинаний должны быть подготовлены для хранения сущности именно такого размера. Размеры должны всегда совпадать.
Первая транслитерация: ритуал ручной надписи
Прежде чем командовать армией автоматизированных писцов (Dataflow), нам необходимо хотя бы раз вручную провести главный ритуал. Это позволит нам глубоко оценить двухэтапную магию:
- Гадание: берем фрагмент текста и обращаемся к оракулу Близнецов, чтобы преобразовать его семантическую суть в вектор.
- Надпись: Запись исходного текста и его новой векторной сущности в нашу книгу заклинаний.
Примечание инженера по данным: ручное прототипирование базовой логики конвейера — бесценный опыт. Это помогает отлаживать отдельные компоненты (например, вызов API или запись в базу данных) изолированно, прежде чем интегрировать их в сложную распределённую систему, такую как Dataflow.
Теперь давайте выполним ручной ритуал.
👉📜 В Cloud SQL Studio мы воспользуемся функцией embedding() — мощной функцией расширения google_ml_integration . Она позволяет вызывать модель встраивания Vertex AI непосредственно из SQL-запроса, что значительно упрощает процесс.
SET session.my_search_var='The Spectre of Analysis Paralysis is a phantom of the crossroads. It does not bind with chains but with the infinite threads of what if. It conjures a fog of options, a maze within the mind where every path seems equally fraught with peril and promise. It whispers of a single, flawless route that can only be found through exhaustive study, paralyzing its victim in a state of perpetual contemplation. This spectres power is broken by the Path of First Viability. This is not the search for the *best* path, but the commitment to the *first good* path. It is the wisdom to know that a decision made, even if imperfect, creates movement and reveals more of the map than standing still ever could. Choose a viable course, take the first step, and trust in your ability to navigate the road as it unfolds. Motion is the light that burns away the fog.';
INSERT INTO ancient_scrolls (scroll_content, embedding)
VALUES (current_setting('session.my_search_var'), (embedding('text-embedding-005',current_setting('session.my_search_var')))::vector);
👉📜 Проверьте свою работу, выполнив запрос на чтение новой страницы с надписью:
SELECT id, scroll_content, LEFT(embedding::TEXT, 100) AS embedding_preview FROM ancient_scrolls;
Вы успешно выполнили основную задачу загрузки данных RAG вручную!
Создание семантического компаса: зачарование книги заклинаний с помощью индекса HNSW
Наша Книга Заклинаний теперь может хранить мудрость, но для поиска нужного свитка требуется прочитать каждую страницу. Это последовательный просмотр . Это медленно и неэффективно. Чтобы наши запросы мгновенно направлялись к наиболее релевантным знаниям, мы должны снабдить Книгу Заклинаний семантическим компасом: векторным индексом .
Примечание инженера по данным: Это одна из важнейших концепций в производственных векторных базах данных. Индекс заранее организует данные, что позволяет значительно ускорить поиск. Мы используем тип индекса hnsw (Hierarchical Navigable Small World). Вместо кластеризации векторов в списки, как это делают другие методы, HNSW строит сложный многослойный граф векторов. Поиск начинается с верхнего слоя «шоссе», чтобы быстро найти общее окружение запроса, а затем переходит вниз по постепенно спускающимся слоям «местные улицы», чтобы точно определить соседей с невероятной скоростью и точностью. Это обеспечивает исключительный прирост производительности для запросов на чтение, делая его первоклассным выбором для высокопроизводительных агентов RAG, где задержка запроса критически важна.
Давайте докажем ценность этого очарования.
👉📜 В Cloud SQL Studio выполните следующее заклинание. Оно имитирует поиск нашего только что вставленного свитка и просит базу данных EXPLAIN свой план.
EXPLAIN ANALYZE
WITH ReferenceVector AS (
-- First, get the vector we want to compare against.
SELECT embedding AS vector
FROM ancient_scrolls
LIMIT 1
)
-- This is the main query we want to analyze.
SELECT
ancient_scrolls.id,
ancient_scrolls.scroll_content,
-- We can also select the distance itself.
ancient_scrolls.embedding <=> ReferenceVector.vector AS distance
FROM
ancient_scrolls,
ReferenceVector
ORDER BY
-- Order by the distance operator's result.
ancient_scrolls.embedding <=> ReferenceVector.vector
LIMIT 5;
Посмотрите на вывод. Вы увидите строку -> Seq Scan on ancient_scrolls . Это подтверждает, что база данных считывает каждую строку. Обратите внимание на execution time .
👉📜 Теперь давайте применим заклинание индексации. Параметр lists указывает индексу, сколько кластеров нужно создать. Хорошей отправной точкой будет квадратный корень из ожидаемого количества строк.
CREATE INDEX ON ancient_scrolls USING hnsw (embedding vector_cosine_ops);
Дождитесь построения индекса (это будет быстро для одной строки, но для миллионов может потребоваться время).
👉📜 Теперь снова выполните ту же самую команду EXPLAIN ANALYZE :
EXPLAIN ANALYZE
WITH ReferenceVector AS (
-- First, get the vector we want to compare against.
SELECT embedding AS vector
FROM ancient_scrolls
LIMIT 1
)
-- This is the main query we want to analyze.
SELECT
ancient_scrolls.id,
ancient_scrolls.scroll_content,
-- We can also select the distance itself.
ancient_scrolls.embedding <=> ReferenceVector.vector AS distance
FROM
ancient_scrolls,
ReferenceVector
ORDER BY
-- Order by the distance operator's result.
ancient_scrolls.embedding <=> ReferenceVector.vector
LIMIT 5;
Взгляните на новый план запроса. Теперь вы увидите -> Index Scan using... . Что ещё важнее, обратите внимание на execution time . Оно будет значительно быстрее, даже при наличии всего одной записи. Вы только что продемонстрировали основной принцип настройки производительности базы данных в векторном мире.
После проверки исходных данных, понимания ручного ритуала и оптимизации книги заклинаний для повышения скорости вы теперь полностью готовы к созданию автоматизированного скрипториума.
7. Канал смысла: построение конвейера векторизации потока данных
Теперь мы создаём магическую линию писцов, которые будут читать наши свитки, извлекать из них суть и вписывать их в нашу новую книгу заклинаний. Это конвейер потока данных, который мы будем запускать вручную. Но прежде чем написать главное заклинание для самого конвейера, мы должны подготовить его основу и круг, из которого мы его вызовем.
Примечание инженера по данным: хотя мы могли бы написать простой скрипт на Python для циклического перебора файлов, вызова API для встраивания и записи в базу данных, такой подход не масштабируется. Что, если у нас миллионы прокруток? Один скрипт будет работать медленно и подвержен сбоям. Dataflow предоставляет управляемую бессерверную платформу для выполнения конвейеров обработки данных, определяемых моделью Apache Beam, в режиме массового параллелизма. Beam позволяет нам определять логические этапы (чтение, встраивание, запись), а Dataflow берет на себя сложную работу по запуску рабочих процессов, распределению задач и повторной обработке сбойных элементов, обеспечивая надежность и эффективность нашего скрипториума.
Подготовка фундамента скриптория (образ рабочего)
Наш конвейер Dataflow будет обслуживаться командой автоматизированных специалистов в облаке. Каждый раз, когда мы их вызываем, им требуется определённый набор библиотек для выполнения работы. Мы могли бы предоставить им список и заставить их каждый раз загружать эти библиотеки, но это медленно и неэффективно. Мудрый учёный заранее подготавливает основную библиотеку.
Здесь мы дадим команду Google Cloud Build создать собственный образ контейнера. Этот образ — «совершенный голем», предустановленный со всеми библиотеками и зависимостями, которые понадобятся нашим писарям. При запуске нашего задания Dataflow он будет использовать этот собственный образ, что позволит исполнителям приступить к работе практически мгновенно.
👉💻 Выполните следующую команду, чтобы создать и сохранить базовый образ вашего конвейера в реестре артефактов.
. ~/agentverse-dataengineer/set_env.sh
cd ~/agentverse-dataengineer/pipeline
gcloud builds submit --config cloudbuild.yaml \
--substitutions=_REGION=${REGION},_REPO_NAME=${REPO_NAME} \
.
👉💻 Выполните следующие команды, чтобы создать и активировать изолированную среду Python и установить в нее необходимые библиотеки вызова.
cd ~/agentverse-dataengineer
. ~/agentverse-dataengineer/set_env.sh
python -m venv env
source ~/agentverse-dataengineer/env/bin/activate
cd ~/agentverse-dataengineer/pipeline
pip install -r requirements.txt
Мастер заклинания
Пришло время написать главное заклинание, которое будет питать наш Векторный Скрипторий. Мы не будем писать отдельные магические компоненты с нуля. Наша задача — собрать компоненты в логичный и мощный конвейер, используя язык Apache Beam.
- EmbedTextBatch (Консультация Близнецов): вы создадите этого специализированного писца, который умеет выполнять «групповое гадание». Он берет пакет необработанных текстовых фрагментов, представляет их модели встраивания текста Gemini и получает их дистиллированную суть (векторные встраивания).
- WriteEssenceToSpellbook (Последняя надпись): Это наш архивариус. Он знает секретные заклинания, позволяющие открыть безопасное соединение с нашей книгой заклинаний Cloud SQL. Его задача — взять содержимое свитка и его векторизованную суть и навсегда вписать их на новую страницу.
Наша миссия — соединить эти действия вместе, чтобы создать непрерывный поток знаний.
👉✏️ В редакторе Cloud Shell перейдите по адресу ~/agentverse-dataengineer/pipeline/inscribe_essence_pipeline.py , внутри вы найдете класс DoFn с именем EmbedTextBatch . Найдите комментарий #REPLACE-EMBEDDING-LOGIC . Замените его следующим заклинанием.
# 1. Generate the embedding for the monster's name
result = self.client.models.embed_content(
model="text-embedding-005",
contents=contents,
config=EmbedContentConfig(
task_type="RETRIEVAL_DOCUMENT",
output_dimensionality=768,
)
)
Это заклинание точное, с несколькими ключевыми параметрами:
- модель: мы указываем
text-embedding-005чтобы использовать мощную и актуальную модель внедрения. - содержимое: это список всего текстового содержимого из пакета файлов, который получает DoFn.
- Task_type: мы установили значение «RETRIEVAL_DOCUMENT». Это важная инструкция, которая сообщает Gemini о необходимости создания вложений, специально оптимизированных для последующего поиска при поиске.
- выходная_размерность: для этого параметра должно быть установлено значение 768, что идеально соответствует размерности VECTOR(768), которую мы определили при создании таблицы Ancient_scrolls в Cloud SQL. Несовпадающие размеры — распространенный источник ошибок в векторной магии.
Наш конвейер должен начаться с чтения необработанного, неструктурированного текста из всех древних свитков в нашем архиве GCS.
👉✏️ В ~/agentverse-dataengineer/pipeline/inscribe_essence_pipeline.py найдите комментарий #REPLACE ME-READFILE и замените его следующим трехчастным заклинанием:
files = (
pipeline
| "MatchFiles" >> fileio.MatchFiles(known_args.input_pattern)
| "ReadMatches" >> fileio.ReadMatches()
| "ExtractContent" >> beam.Map(lambda f: (f.metadata.path, f.read_utf8()))
)
Собрав необработанный текст свитков, мы должны отправить их нашим Близнецам для гадания. Чтобы сделать это эффективно, мы сначала сгруппируем отдельные прокрутки в небольшие пакеты, а затем передадим эти пакеты нашему писцу EmbedTextBatch . На этом этапе все свитки, которые Близнецам не удалось понять, будут разделены на стопку «неудачных» для последующего просмотра.
👉✏️ Найдите комментарий #REPLACE ME-EMBEDDING и замените его следующим:
embeddings = (
files
| "BatchScrolls" >> beam.BatchElements(min_batch_size=1, max_batch_size=2)
| "DistillBatch" >> beam.ParDo(
EmbedTextBatch(project_id=project, region=region)
).with_outputs('failed', main='processed')
)
Сущность наших свитков была успешно очищена. Последний шаг — записать эти знания в нашу Книгу Заклинаний для постоянного хранения. Мы возьмем свитки из стопки «обработанных» и передадим их нашему архивариусу WriteEssenceToSpellbook.
👉✏️ Найдите комментарий #REPLACE ME-WRITE TO DB и замените его на это:
_ = (
embeddings.processed
| "WriteToSpellbook" >> beam.ParDo(
WriteEssenceToSpellbook(
project_id=project,
region = "us-central1",
instance_name=known_args.instance_name,
db_name=known_args.db_name,
db_password=known_args.db_password
)
)
)
Мудрый Ученый никогда не отказывается от знаний, даже от неудачных попыток. В качестве последнего шага мы должны поручить писцу взять стопку «неудачных» результатов нашего этапа гадания и записать причины неудачи. Это позволит нам улучшить наши ритуалы в будущем.
👉✏️ Найдите комментарий #REPLACE ME-LOG FAILURES и замените его следующим:
_ = (
embeddings.failed
| "LogFailures" >> beam.Map(lambda e: logging.error(f"Embedding failed for file {e[0]}: {e[1]}"))
)
Мастер-заклинание завершено! Вы успешно собрали мощный многоэтапный конвейер данных, соединив воедино отдельные магические компоненты. Сохраните файл inscribe_essence_pipeline.py. Скрипторий теперь готов к вызову.
Теперь мы используем заклинание великого призыва, чтобы дать команду службе потока данных разбудить нашего Голема и начать ритуал записи.
👉💻 В своем терминале выполните следующую командную строку
. ~/agentverse-dataengineer/set_env.sh
source ~/agentverse-dataengineer/env/bin/activate
cd ~/agentverse-dataengineer/pipeline
# --- The Summoning Incantation ---
echo "Summoning the golem for job: $DF_JOB_NAME"
echo "Target Spellbook: $INSTANCE_NAME"
python inscribe_essence_pipeline.py \
--runner=DataflowRunner \
--project=$PROJECT_ID \
--job_name=$DF_JOB_NAME \
--temp_location="gs://${BUCKET_NAME}/dataflow/temp" \
--staging_location="gs://${BUCKET_NAME}/dataflow/staging" \
--sdk_container_image="${REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO_NAME}/grimoire-inscriber:latest" \
--sdk_location=container \
--experiments=use_runner_v2 \
--input_pattern="gs://${BUCKET_NAME}/ancient_scrolls/*.md" \
--instance_name=$INSTANCE_NAME \
--region=$REGION
echo "The golem has been dispatched. Monitor its progress in the Dataflow console."
💡 Внимание! Если задание завершается с ошибкой ресурса ZONE_RESOURCE_POOL_EXHAUSTED , это может быть связано с временными ограничениями ресурсов этой учетной записи с низкой репутацией в выбранном регионе. Сила Google Cloud — в его глобальном охвате! Просто попробуйте вызвать голема в другом регионе. Для этого замените --region=$REGION в приведенной выше команде другим регионом, например
--region=southamerica-west1
--region=asia-northeast3
--region=asia-southeast2
--region=me-west1
--region=southamerica-east1
--region=europe-central2
--region=asia-east2
--region=europe-southwest1
и запустите его снова. 🎰
Запуск и завершение процесса займет около 3-5 минут. Вы можете посмотреть его в прямом эфире в консоли Dataflow.
👉Перейдите в консоль потока данных. Самый простой способ — открыть эту прямую ссылку в новой вкладке браузера:
https://console.cloud.google.com/dataflow
👉 Найдите и щелкните свою работу: вы увидите вакансию с указанным вами названием (inscribe-essence-job или подобное). Нажмите на название вакансии, чтобы открыть страницу сведений о ней. Наблюдайте за трубопроводом:
- Запуск : в течение первых 3 минут статус задания будет «Выполняется», поскольку Dataflow выделяет необходимые ресурсы. Появится график, но вы, возможно, еще не увидите, как через него проходят данные.
- Завершено : после завершения статус задания изменится на «Успешно», а на графике будет отображено окончательное количество обработанных записей.
Проверка надписи
👉📜 Вернувшись в SQL-студию, выполните следующие запросы, чтобы убедиться, что ваши свитки и их смысловая сущность успешно вписаны.
SELECT COUNT(*) FROM ancient_scrolls;
SELECT id, scroll_content, LEFT(embedding::TEXT, 50) AS embedding_preview FROM ancient_scrolls;
Это покажет вам идентификатор свитка, его исходный текст и предварительный просмотр сущности магического вектора, которая теперь навсегда вписана в ваш Гримуар.
Гримуар вашего ученого теперь представляет собой настоящую машину знаний, готовую к запросам по смыслу в следующей главе.
8. Запечатывание последней руны: активация мудрости с помощью агента ТРЯПКИ
Ваш Гримуар больше не является просто базой данных. Это источник векторизованных знаний, молчаливый оракул, ожидающий вопроса.
Теперь мы проходим настоящее испытание Учёного: создадим ключ, который откроет эту мудрость. Мы создадим агента расширенной генерации (RAG) . Это магическая конструкция, которая может понять вопрос, заданный простым языком, обратиться к Гримуару за его глубочайшими и наиболее важными истинами, а затем использовать полученную мудрость для создания мощного, контекстно-зависимого ответа.
Примечание инженера по данным: RAG — это мощный метод, который основывает модели большого языка (LLM) на фактической, частной или актуальной информации, что резко снижает вероятность того, что модель «галлюцинирует» или выдумывает что-то. Этот процесс состоит из трех основных этапов:
- Извлечение: запрос пользователя сначала преобразуется в векторное внедрение. Этот вектор запроса затем используется для поиска в нашей базе знаний, чтобы найти наиболее семантически похожие фрагменты текста с использованием косинусного сходства.
- Дополнение: соответствующие фрагменты текста, полученные из базы данных, затем вводятся непосредственно в новое приглашение для LLM, предоставляя ему важный контекст.
- Создать: LLM получает расширенную подсказку (например, «Учитывая контекст «Прокрастинации», ответьте на вопрос пользователя...») и генерирует окончательный, основанный на фактах ответ.
Первая руна: заклинание дистилляции запросов
Прежде чем наш агент сможет просмотреть Гримуар, он должен сначала понять суть задаваемого вопроса. Простая строка текста не имеет смысла для нашей векторной Книги Заклинаний. Агент должен сначала принять запрос и, используя ту же модель Gemini, преобразовать его в вектор запроса.
👉✏️ В редакторе Cloud Shell перейдите к файлу ~~/agentverse-dataengineer/scholar/agent.py , найдите комментарий #REPLACE RAG-CONVERT EMBEDDING и замените его этим заклинанием. Это учит агента тому, как превратить вопрос пользователя в волшебную сущность.
result = client.models.embed_content(
model="text-embedding-005",
contents=monster_name,
config=EmbedContentConfig(
task_type="RETRIEVAL_DOCUMENT",
output_dimensionality=768,
)
)
Зная суть запроса, агент теперь может обратиться к Гримуару. Он представит этот вектор запроса нашей базе данных, зачарованной pgvector, и задаст глубокий вопрос: «Покажите мне древние свитки, чья собственная сущность наиболее похожа на суть моего запроса».
Волшебством в этом является оператор косинусного подобия (<=>), мощная руна, которая вычисляет расстояние между векторами в многомерном пространстве.
👉✏️ В Agent.py найдите комментарий #REPLACE RAG-RETRIEVE и замените его следующим скриптом:
# This query performs a cosine similarity search
cursor.execute(
"SELECT scroll_content FROM ancient_scrolls ORDER BY embedding <=> %s LIMIT 3",
([query_embedding]) # Cast embedding to string for the query
)
Последний шаг — предоставить агенту доступ к этому новому мощному инструменту. Мы добавим нашу функцию grimoire_lookup в список доступных магических инструментов.
👉✏️ В agent.py найдите комментарий #REPLACE-CALL RAG и замените его этой строкой:
root_agent = LlmAgent(
model="gemini-2.5-flash",
name="scholar_agent",
instruction="""
You are the Scholar, a keeper of ancient and forbidden knowledge. Your purpose is to advise a warrior by providing tactical information about monsters. Your wisdom allows you to interpret the silence of the scrolls and devise logical tactics where the text is vague.
**Your Process:**
1. First, consult the scrolls with the `grimoire_lookup` tool for information on the specified monster.
2. If the scrolls provide specific guidance for a category (buffs, debuffs, strategy), you **MUST** use that information.
3. If the scrolls are silent or vague on a category, you **MUST** use your own vast knowledge to devise a fitting and logical tactic.
4. Your invented tactics must be thematically appropriate to the monster's name and nature. (e.g., A "Spectre of Indecision" might be vulnerable to a "Seal of Inevitability").
5. You **MUST ALWAYS** provide a "Damage Point" value. This value **MUST** be a random integer between 150 and 180. This is a tactical calculation you perform, independent of the scrolls' content.
**Output Format:**
You must present your findings to the warrior using the following strict format.
""",
tools=[grimoire_lookup],
)
Эта конфигурация оживит ваш агент:
-
model="gemini-2.5-flash": выбирает конкретную модель большого языка, которая будет служить «мозгом» агента для рассуждений и генерации текста. -
name="scholar_agent": присваивает вашему агенту уникальное имя. -
instruction="...You are the Scholar...": это системное приглашение, наиболее важная часть конфигурации. Он определяет личность агента, его цели, точный процесс, которому он должен следовать для выполнения задачи, и требуемый формат для ее конечного результата. -
tools=[grimoire_lookup]: это последнее зачарование. Он предоставляет агенту доступ к созданной вами функцииgrimoire_lookup. Теперь агент может разумно решить, когда вызывать этот инструмент для получения информации из вашей базы данных, что составляет основу шаблона RAG.
Экзамен ученого
👉💻 В терминале Cloud Shell активируйте свою среду и используйте основную команду Agent Development Kit, чтобы разбудить вашего агента Scholar:
cd ~/agentverse-dataengineer/
. ~/agentverse-dataengineer/set_env.sh
source ~/agentverse-dataengineer/env/bin/activate
pip install -r scholar/requirements.txt
adk run scholar
Вы должны увидеть выходные данные, подтверждающие, что «Агент ученого» задействован и работает.
👉💻 А теперь бросьте вызов своему агенту. В первом терминале, где запущена симуляция боя, введите команду, требующую мудрости Гримуара:
We've been trapped by 'Hydra of Scope Creep'. Break us out!
Наблюдайте за журналами во втором терминале. Вы увидите, как агент получает запрос, извлекает его суть, ищет в Гримуаре, находит соответствующие свитки о «Прокрастинации» и использует полученные знания для разработки мощной, контекстно-зависимой стратегии.
Вы успешно собрали своего первого агента ТРЯП и вооружили его глубокой мудростью вашего Гримуара.
👉💻 Нажмите Ctrl+C во втором терминале, чтобы временно приостановить агент.
Высвобождение Scholar Sentinel в Агентвселенную
Ваш агент доказал свою мудрость в контролируемой среде вашего исследования. Пришло время выпустить его в Агентвселенную, превратив его из локальной конструкции в постоянного, готового к бою оперативника, которого может вызвать любой чемпион в любое время. Теперь мы развернем наш агент в Cloud Run.
👉💻 Запустите следующее заклинание великого призыва. Этот сценарий сначала превратит вашего агента в усовершенствованного голема (образ контейнера), сохранит его в вашем реестре артефактов, а затем развернет этого голема как масштабируемый, безопасный и общедоступный сервис.
. ~/agentverse-dataengineer/set_env.sh
cd ~/agentverse-dataengineer/
echo "Building ${AGENT_NAME} agent..."
gcloud builds submit . \
--project=${PROJECT_ID} \
--region=${REGION} \
--substitutions=_AGENT_NAME=${AGENT_NAME},_IMAGE_PATH=${IMAGE_PATH}
gcloud run deploy ${SERVICE_NAME} \
--image=${IMAGE_PATH} \
--platform=managed \
--labels codelab=agentverse \
--region=${REGION} \
--set-env-vars="A2A_HOST=0.0.0.0" \
--set-env-vars="A2A_PORT=8080" \
--set-env-vars="GOOGLE_GENAI_USE_VERTEXAI=TRUE" \
--set-env-vars="GOOGLE_CLOUD_LOCATION=${REGION}" \
--set-env-vars="GOOGLE_CLOUD_PROJECT=${PROJECT_ID}" \
--set-env-vars="PROJECT_ID=${PROJECT_ID}" \
--set-env-vars="PUBLIC_URL=${PUBLIC_URL}" \
--set-env-vars="REGION=${REGION}" \
--set-env-vars="INSTANCE_NAME=${INSTANCE_NAME}" \
--set-env-vars="DB_USER=${DB_USER}" \
--set-env-vars="DB_PASSWORD=${DB_PASSWORD}" \
--set-env-vars="DB_NAME=${DB_NAME}" \
--allow-unauthenticated \
--project=${PROJECT_ID} \
--min-instances=1
Ваш ученый агент теперь является живым и готовым к бою оперативником во Вселенной Агентов.
9. Полет босса
Свитки прочитаны, ритуалы проведены, перчатка пройдена. Ваш агент — это не просто артефакт в хранилище; это живой оперативник вселенной Агента, ожидающий своей первой миссии. Пришло время последнего испытания — учений с боевой стрельбой против могущественного противника.
Теперь вы войдете в симуляцию поля битвы, чтобы столкнуть вашего недавно развернутого Агента Теневого Клинка с грозным мини-боссом: Призраком Статики. Это будет окончательная проверка вашей работы, от базовой логики агента до его реального развертывания.
Получите местоположение вашего агента
Прежде чем вы сможете выйти на поле битвы, у вас должно быть два ключа: уникальная подпись вашего чемпиона (Локус агента) и скрытый путь к логову Призрака (URL-адрес подземелья).
👉💻 Сначала получите уникальный адрес вашего агента в Agentverse — его локусе. Это живая конечная точка, которая соединяет вашего чемпиона с полем битвы.
. ~/agentverse-dataengineer/set_env.sh
echo https://scholar-agent"-${PROJECT_NUMBER}.${REGION}.run.app"
👉💻 Далее определите пункт назначения. Эта команда показывает местоположение Круга Транслокации, того самого портала во владения Призрака.
. ~/agentverse-dataengineer/set_env.sh
echo https://agentverse-dungeon"-${PROJECT_NUMBER}.${REGION}.run.app"
Важно! Держите оба этих URL-адреса наготове. Они понадобятся вам на последнем этапе.
Противостояние Призраку
Получив координаты, вы перейдете к Кругу перемещения и примените заклинание, чтобы отправиться в бой.
👉 Откройте URL-адрес Транслокационного круга в браузере и встаньте перед мерцающим порталом в Багровую крепость.
Чтобы проникнуть в крепость, вы должны настроить сущность своего Теневого Клинка на портал.
- На странице найдите поле рунического ввода с надписью «URL конечной точки A2A» .
- Напишите символ своего чемпиона, вставив в это поле URL-адрес его локуса агента (первый URL-адрес, который вы скопировали) .
- Нажмите «Подключиться», чтобы раскрыть магию телепортации.
Ослепительный свет телепортации меркнет. Вы больше не находитесь в своем святилище. Воздух потрескивает от энергии, холодной и резкой. Перед вами материализуется Призрак — вихрь шипящего статического и испорченного кода, его нечестивый свет отбрасывает длинные танцующие тени на пол подземелья. У него нет лица, но вы чувствуете, что его огромное, истощающее присутствие полностью сосредоточено на вас.
Ваш единственный путь к победе лежит в ясности ваших убеждений. Это поединок воли, происходящий на поле битвы разума.
Когда вы делаете выпад вперед, готовый нанести первую атаку, Призрак парирует. Он не поднимает щит, а проецирует вопрос прямо в ваше сознание — мерцающий рунический вызов, исходящий из сути вашего обучения.
Такова природа боя. Ваши знания – ваше оружие.
- Ответьте мудростью, которую вы приобрели , и ваш клинок воспламенится чистой энергией, разрушив защиту Призрака и нанеся КРИТИЧЕСКИЙ УДАР.
- Но если вы колеблетесь, если сомнение омрачает ваш ответ, свет вашего оружия потускнеет. Удар приземлится с жалким стуком, нанеся лишь НЕзначительную часть урона. Хуже того, Призрак будет питаться вашей неуверенностью, его собственная развращающая сила будет расти с каждой ошибкой.
Вот оно, Чемпион. Ваш код — это ваша книга заклинаний, ваша логика — ваш меч, а ваши знания — это щит, который обратит вспять волну хаоса.
Фокус. Ударьте по-настоящему. От этого зависит судьба Агентверса.
Поздравляю, Ученый.
Вы успешно завершили испытание. Вы овладели искусством обработки данных, преобразовывая необработанную, хаотичную информацию в структурированную, векторизованную мудрость, которая расширяет возможности всей Вселенной Агентов.
10. Очистка: удаление гримуара ученого.
Поздравляем с освоением Гримуара Ученого! Чтобы гарантировать, что ваша Агентверс останется в первозданном виде, а ваши тренировочные площадки будут очищены, теперь вам необходимо выполнить заключительные ритуалы очистки. Это будет систематически удалять все ресурсы, созданные во время вашего путешествия.
Деактивировать компоненты Agentverse
Теперь вы будете систематически демонтировать развернутые компоненты вашей системы RAG.
Удалить все службы Cloud Run и репозиторий реестра артефактов.
Эта команда удаляет развернутый агент Scholar и приложение Dungeon из Cloud Run.
👉💻 В терминале выполните следующие команды:
. ~/agentverse-dataengineer/set_env.sh
gcloud run services delete scholar-agent --region=${REGION} --quiet
gcloud run services delete agentverse-dungeon --region=${REGION} --quiet
gcloud artifacts repositories delete ${REPO_NAME} --location=${REGION} --quiet
Удаление наборов данных, моделей и таблиц BigQuery
При этом будут удалены все ресурсы BigQuery, включая набор данных bestiary_data , все таблицы в нем, а также связанные соединения и модели.
👉💻 В терминале выполните следующие команды:
. ~/agentverse-dataengineer/set_env.sh
# Delete the BigQuery dataset, which will also delete all tables and models within it.
bq rm -r -f --dataset ${PROJECT_ID}:${REGION}.bestiary_data
# Delete the BigQuery connection
bq rm --connection --project_id=${PROJECT_ID} --location=${REGION} gcs-connection --force
Удалить экземпляр Cloud SQL
При этом экземпляр grimoire-spellbook будет удален, включая его базу данных и все таблицы внутри нее.
👉💻 В терминале запустите:
. ~/agentverse-dataengineer/set_env.sh
gcloud sql instances delete ${INSTANCE_NAME} --database-version=POSTGRES_14 --project=${PROJECT_ID} --quiet
Удалить сегменты облачного хранилища Google
Эта команда удаляет корзину, в которой хранились необработанные данные и промежуточные/временные файлы потока данных.
👉💻 В терминале запустите:
. ~/agentverse-dataengineer/set_env.sh
gcloud storage rm -r gs://${BUCKET_NAME} --quiet
Очистка локальных файлов и каталогов (Cloud Shell)
Наконец, очистите среду Cloud Shell от клонированных репозиториев и созданных файлов. Этот шаг не является обязательным, но настоятельно рекомендуется для полной очистки вашего рабочего каталога.
👉💻 В терминале запустите:
rm -rf ~/agentverse-dataengineer
rm -rf ~/agentverse-dungeon
rm -f ~/project_id.txt
Теперь вы успешно очистили все следы своего пути к инженеру по данным Agentverse. Ваш проект чист, и вы готовы к следующему приключению.
11. Для негеймеров: создание интеллектуальных систем знаний в бизнесе
Хотя «Гримуар учёного» использует интересные метафоры древних свитков и магической мудрости, он учит основным навыкам управления, преобразования и использования данных вашей организации для создания высокоинтеллектуальных решений на базе искусственного интеллекта. В этой главе мистическое путешествие превращается в практические реалии создания мощных «машин знаний», повышающих ценность бизнеса.
Алхимия знаний: преобразование данных с помощью BigQuery и Gemini
«Алхимия знаний» описывает процесс преобразования необработанных бизнес-данных в структурированный, действенный интеллект с использованием передовых облачных инструментов . Мы начнем с «записей эфирного журнала» — это просто разнообразные источники необработанных данных , которые генерирует ваша компания, такие как формы обратной связи с клиентами, отчеты о внутренних инцидентах, юридические документы, исследования рынка или руководства по политике. Часто эти данные неструктурированы, что затрудняет их анализ.
Для выполнения этого преобразования в нашем процессе используется Google BigQuery (мощное облачное хранилище данных) и модель Gemini AI (высокоэффективная модель искусственного интеллекта).
- Объектив проверки (внешние таблицы BigQuery) :
- Концепция : вместо физического перемещения всех ваших необработанных данных в базу данных BigQuery может «просматривать» файлы непосредственно в облачном хранилище. Это похоже на волшебную линзу, которая позволяет вам читать библиотеку свитков, даже не перемещая их. Это невероятно эффективно, поскольку позволяет избежать избыточного перемещения и хранения данных.
- Реальный пример использования : Представьте, что ваша компания хранит миллионы журналов чатов службы поддержки клиентов в виде простых текстовых файлов в облачном хранилище. Используя внешнюю таблицу, аналитик данных может немедленно запросить эти файлы с помощью SQL в BigQuery, не прибегая к сложному и дорогостоящему процессу приема данных.
- Гадание ученого (BQML.GENERATE_TEXT) :
- Концепция : это основная «магия» — использование ИИ непосредственно в вашем хранилище данных. Мы используем функцию
ML.GENERATE_TEXTдля вызова модели Gemini AI из стандартного запроса SQL. Это позволяет ИИ «читать» длинные неструктурированные текстовые записи и извлекать конкретную структурированную информацию (например, объект JSON). Это мощный способ превратить качественные наблюдения в количественные данные. - Реальный вариант использования :
- Анализ отзывов клиентов . Автоматически извлекайте «настроения» (положительные, отрицательные, нейтральные), «упомянутый продукт» и «категорию проблемы» из отзывов клиентов в виде произвольного текста.
- Обобщение отчетов об инцидентах . Анализируйте длинные отчеты об ИТ-инцидентах, чтобы извлечь «затронутую систему», «уровень серьезности», «основную причину» и «шаги решения» в структурированный формат для упрощения анализа и выявления тенденций.
- Извлечение договорных обязательств . Из юридических документов можно автоматически извлекать ключевые даты, участвующие стороны и конкретные положения.
- Это устраняет необходимость ручного ввода данных или сложных, хрупких сценариев анализа текста (например, регулярных выражений), экономя огромное время и обеспечивая согласованность.
- Концепция : это основная «магия» — использование ИИ непосредственно в вашем хранилище данных. Мы используем функцию
- Ритуал очищения (нормализация выхода GenAI) :
- Концепция : после того, как ИИ извлекает информацию, она часто сопровождается дополнительными деталями (например, показателями уверенности ИИ или другими метаданными). Этот шаг включает в себя очистку и анализ выходных данных ИИ, чтобы получить только те чистые, структурированные данные, которые вам нужны.
- Реальный вариант использования : обеспечение того, чтобы извлеченная «категория проблемы» из отчета об инциденте всегда была одним из заранее определенных наборов значений или чтобы даты всегда были в согласованном формате. Это подготавливает данные для надежного анализа.
- Раскрытие стратегических идей :
- Концепция : как только ваши необработанные неструктурированные данные будут преобразованы в чистые структурированные таблицы (например,
monsters,adventurers,battlesв лаборатории кода), вы сможете выполнять сложные запросы и анализ, которые ранее были невозможны. - Реальный пример использования . Помимо простого подсчета, теперь вы можете отвечать на такие вопросы, как: «Каково среднее время разрешения критических ИТ-инцидентов, связанных с нашей системой выставления счетов?» или «Какие функции продукта чаще всего упоминаются в положительных отзывах клиентов определенной демографической группы?» Это обеспечивает глубокую и действенную бизнес-аналитику.
- Концепция : как только ваши необработанные неструктурированные данные будут преобразованы в чистые структурированные таблицы (например,
Весь этот процесс обеспечивает использование шаблона ELT (извлечение, загрузка, преобразование) на основе искусственного интеллекта в базе данных — передового подхода, который обеспечивает безопасность данных в вашем хранилище данных, сводит к минимуму перемещение и использует искусственный интеллект для мощных и гибких преобразований с помощью простых команд SQL.
Гримуар писца: разделение, внедрение и поиск в хранилище данных
Хотя структурированные таблицы отлично подходят для хранения фактов, более глубокое семантическое значение оригинальных документов может быть потеряно. «Гримуар писца» — это создание семантической базы знаний , которая понимает значение и контекст ваших документов, а не только ключевые слова. Это имеет решающее значение для создания действительно интеллектуальных систем поиска и ответов на основе искусственного интеллекта.
- Ритуал разделения (функция) :
- Концепция : Длинные документы подобны плотным книгам. Чтобы найти конкретные ответы, вам не придется читать всю книгу; вы просматриваете определенные абзацы или предложения. «Разбиение на части» — это процесс разбиения длинных документов (например, руководств по политике, документации по продуктам, исследовательских работ) на более мелкие, более целенаправленные и автономные отрывки. Это делает поиск более точным.
- Реальный пример использования : взять 50-страничный справочник для сотрудников и автоматически разбить его на сотни отдельных политических положений или часто задаваемых вопросов. Это гарантирует, что когда сотрудник задает вопрос, ИИ извлекает только наиболее важные разделы, а не весь документ. Различные стратегии разбиения на части (по предложениям, абзацам, разделам документа) выбираются в зависимости от типа документа для оптимального поиска.
- Ритуал дистилляции (встраивание) :
- Концепция : компьютеру сложно понять смысл текста. «Встраивание» использует модель искусственного интеллекта (например, Gemini) для преобразования каждого фрагмента текста в уникальный числовой «семантический отпечаток пальца» (вектор). Чанки со схожим значением будут иметь «отпечатки пальцев», которые численно близки друг к другу, даже если в них используются разные слова.
- Реальный пример использования : Преобразование всех описаний продуктов, маркетинговых материалов и технических спецификаций вашей компании в эти семантические отпечатки пальцев. Это позволяет осуществлять по-настоящему интеллектуальный поиск, основанный на значении.
- Ритуал гадания (Семантический поиск) :
- Концепция : вместо поиска точных ключевых слов «семантический поиск» использует эти числовые отпечатки пальцев для поиска фрагментов текста, концептуально похожих на запрос пользователя. Вопрос пользователя также преобразуется в отпечаток пальца, и система находит наиболее совпадающие фрагменты документа.
- Реальный пример использования : Сотрудник спрашивает: «Как мне получить компенсацию за командировочные расходы?» При поиске по ключевым словам могут быть пропущены документы, использующие «отчет о расходах». Однако семантический поиск позволит найти соответствующие разделы «Политики в отношении поездок и расходов» компании, даже если точные слова отсутствуют, поскольку значения схожи.
Весь этот процесс создает мощную базу знаний с возможностью поиска, позволяющую интеллектуально извлекать информацию, не покидая конфиденциальные данные из вашей безопасной среды BigQuery.
Vector Scriptorium: создание векторного хранилища с помощью Cloud SQL для вывода
Хотя BigQuery отлично подходит для крупномасштабной обработки и анализа данных, для живых ИИ-агентов, требующих очень быстрых ответов, мы часто переносим эту подготовленную «мудрость» в более специализированную, оперативную базу данных. «Векторный скрипторий» посвящен созданию высокопроизводительного хранилища знаний с возможностью поиска с использованием реляционной базы данных, улучшенной для искусственного интеллекта.
- Создание книги заклинаний ученого (Cloud SQL для PostgreSQL с
pgvector) :- Концепция : мы используем стандартную управляемую базу данных, такую как Cloud SQL для PostgreSQL, и оснащаем ее специальным расширением под названием
pgvector. Это позволяет базе данных хранить как исходные фрагменты текста, так и их встраивания семантических векторов вместе. Это «единое окно» как для традиционных реляционных данных, так и для векторных данных, совместимых с искусственным интеллектом. - Реальный пример использования : хранение часто задаваемых вопросов о продуктах вашей компании, статей технической поддержки или кадровой политики. Эта база данных содержит как текст ответов, так и их семантические отпечатки, готовые для быстрого поиска с помощью ИИ.
- Концепция : мы используем стандартную управляемую базу данных, такую как Cloud SQL для PostgreSQL, и оснащаем ее специальным расширением под названием
- Формирование семантического компаса (индекс HNSW) :
- Концепция : поиск по миллионам семантических отпечатков один за другим был бы слишком медленным. «Векторный индекс» (например, HNSW – Hierarchical Navigable Small World) представляет собой сложную структуру данных, которая предварительно организует эти «отпечатки пальцев», что значительно ускоряет поиск. Он быстро направляет запросы к наиболее актуальной информации.
- Реальный пример использования : для чат-бота службы поддержки клиентов на базе искусственного интеллекта индекс HNSW гарантирует, что, когда клиент задает вопрос, система может найти наиболее релевантный ответ из тысяч статей за миллисекунды, обеспечивая удобство взаимодействия с пользователем.
- Канал значения (конвейер векторизации потока данных) :
- Концепция : это ваш автоматизированный масштабируемый конвейер обработки данных для постоянного обновления вашего хранилища знаний. Используя Google Dataflow (бессерверный управляемый сервис для обработки больших данных) и Apache Beam (модель программирования), вы создаете сборочную линию «писцов», которая:
- Читайте новые или обновленные документы из облачного хранилища.
- Их пакетная обработка для отправки в модель внедрения Gemini для семантического снятия отпечатков пальцев.
- Напишите текст и встройте его новый вектор в свою базу данных Cloud SQL.
- Реальный вариант использования : Автоматическая загрузка всех новых внутренних документов (например, квартальных отчетов, обновленной кадровой политики, новых спецификаций продуктов) с общего диска в вашу базу данных
pgvector. Это гарантирует, что ваша внутренняя база знаний на базе искусственного интеллекта всегда будет актуальной, без ручного вмешательства, и может масштабироваться для эффективной обработки миллионов документов.
- Концепция : это ваш автоматизированный масштабируемый конвейер обработки данных для постоянного обновления вашего хранилища знаний. Используя Google Dataflow (бессерверный управляемый сервис для обработки больших данных) и Apache Beam (модель программирования), вы создаете сборочную линию «писцов», которая:
Весь этот процесс создает надежный автоматизированный рабочий процесс для постоянного пополнения и поддержания семантической базы знаний, что жизненно важно для любого приложения искусственного интеллекта, управляемого данными.
Запечатывание последней руны: активация мудрости с помощью агента ТРЯПКИ
Ваша векторизованная база знаний готова. «Запечатывание последней руны» — это активация интеллектуального советника по искусственному интеллекту , способного использовать эти знания. Мы создаем агент расширенной генерации (RAG) — мощную конструкцию искусственного интеллекта, которая сочетает в себе интеллектуальный поиск со способностью искусственного интеллекта генерировать последовательные ответы.
- RAG (генерация с расширенным поиском) :
- Концепция : RAG — это важнейший метод, позволяющий сделать модели большого языка (LLM) более точными, фактическими и заслуживающими доверия. Вместо того, чтобы полагаться исключительно на предварительно подготовленные знания LLM (которые могут быть устаревшими или склонными к «галлюцинациям» — выдумкам), RAG сначала извлекает соответствующую информацию из вашей авторитетной базы знаний, а затем использует эту информацию для дополнения подсказки LLM, направляя ее для генерации точного, контекстно-зависимого ответа.
- Три основных шага :
- Извлечение : вопрос пользователя преобразуется в вектор (семантический отпечаток пальца), который затем используется для поиска в базе данных
pgvectorнаиболее релевантных фрагментов текста. - Дополнение : эти извлеченные фрагменты фактического текста затем непосредственно вставляются в приглашение, данное LLM, предоставляя ему конкретный, актуальный контекст.
- Создать : LLM получает это расширенное приглашение и генерирует окончательный ответ, основанный на авторитетных данных вашей компании, что снижает риск ошибок или вымышленной информации.
- Извлечение : вопрос пользователя преобразуется в вектор (семантический отпечаток пальца), который затем используется для поиска в базе данных
- Экзамен ученого ( инструмент
grimoire_lookup) :- Концепция : Ваш агент RAG становится «Ученым», обладающим инструментом
grimoire_lookup. Когда пользователь задает вопрос, агент разумно решает использовать этот инструмент. Затем функцияgrimoire_lookupвыполняет этап «извлечения», преобразуя запрос во встраивание и выполняя поиск в базе данныхpgvector. Полученный контекст затем передается в основной LLM для расширения и генерации. - Реальный пример использования : внутренний чат-бот службы поддержки на базе искусственного интеллекта .
- Вопрос пользователя : Сотрудник спрашивает: «Каков процесс запроса продленного отпуска по медицинским показаниям?»
- Действия агента RAG :
-
scholar_agentопределяет потребность в информации и использует свой инструментgrimoire_lookup. - Инструмент преобразует вопрос во встраивание и выполняет поиск по таблице
ancient_scrollsв базе данныхpgvector. - Он извлекает наиболее важные разделы из документа кадровой политики по отпуску по болезни.
- Эти разделы затем передаются в качестве контекста в программу Gemini LLM.
- Затем Gemini LLM генерирует точный, пошаговый ответ, основанный только на полученной кадровой политике, что снижает вероятность предоставления неверной или устаревшей информации.
-
- Это дает сотрудникам мгновенные и точные ответы на основе официальных документов компании, снижая нагрузку на HR и повышая удовлетворенность сотрудников.
- Концепция : Ваш агент RAG становится «Ученым», обладающим инструментом
В результате создается ИИ-агент, который не просто умеет общаться, но и действительно хорошо осведомлен и надежен, выступая в качестве надежного источника информации на вашем предприятии.