1. Введение
Модели генеративного ИИ — мощные средства рассуждения, но им не хватает институционального контекста. Если руководитель спросит у ИИ-агента: «Какова наша выручка за первый квартал?», агент может обнаружить десятки таблиц с названием «выручка» в вашем хранилище данных. Некоторые из них представляют собой точные финансовые отчеты, другие — оценки маркетинговых показателей в реальном времени, а многие, вероятно, являются устаревшими тестовыми средами.
Без явного обоснования агент ИИ выберет стол на основе простого сходства названий, что приведет к « убедительно неверным » ответам, полученным из непроверенных данных.
Данный практический урок является частью двухсерийного цикла, посвященного созданию ИИ-агента, учитывающего особенности управления.
В первой части вы создадите основу для работы с данными. Вы настроите реалистичное, "неупорядоченное" озеро данных в BigQuery, примените строгие метатеги (аспекты каталога знаний) для различения достоверных данных от шума и используете CLI Antigravity (AGY) для локальной проверки того, строго ли агент соблюдает ваши правила управления данными.
Вы можете прочитать вторую часть этой серии, в которой рассказывается о том, как развернуть локальный прототип агента в защищенном веб-приложении корпоративного уровня с использованием протокола контекста модели (MCP) и Cloud Run. 👉 Читать часть 2
Что вы узнаете
- Разверните реалистичное многоуровневое озеро данных с помощью скрипта настройки.
- Разрабатывайте и регистрируйте пользовательские шаблоны метаданных ( типы аспектов ) в Каталоге знаний, чтобы отличать официальные продукты данных от необработанных таблиц в песочнице.
- Перед написанием кода приложения проверьте правила управления данными локально с помощью интерфейса командной строки AGY .
Что вам понадобится
- Проект Google Cloud с включенной функцией выставления счетов.
- Доступ к Google Cloud Shell (интерфейс командной строки AGY предустановлен в Cloud Shell).
- Базовое понимание и знакомство с BigQuery и Knowledge Catalog .
Ключевые понятия
- Каталог знаний: Единая служба управления метаданными. Мы используем его для обогащения технических метаданных (схем) бизнес-контекстом (управлением).
- Тип аспекта : структурированный шаблон метаданных. В отличие от тегов свободного текста, аспекты обеспечивают строгую типизацию (перечисления, логические значения), что делает их надежными для машинной оценки.
2. Настройка и требования
Запустить Cloud Shell
Хотя Google Cloud можно управлять удаленно с ноутбука, в этом практическом занятии вы будете использовать Google Cloud Shell — среду командной строки, работающую в облаке.
В консоли Google Cloud нажмите на значок Cloud Shell на панели инструментов в правом верхнем углу:
Подготовка и подключение к среде займут всего несколько минут. После завершения вы должны увидеть что-то подобное:
Эта виртуальная машина содержит все необходимые инструменты разработки. Она предоставляет постоянный домашний каталог объемом 5 ГБ и работает в облаке Google, что значительно повышает производительность сети и аутентификацию. Вся работа в этом практическом задании может выполняться в браузере. Вам не нужно ничего устанавливать.
Инициализация среды
Откройте Cloud Shell и настройте переменные проекта, чтобы все команды были направлены на правильную инфраструктуру.
export PROJECT_ID=$(gcloud config get-value project)
gcloud config set project $PROJECT_ID
export REGION="us-central1"
Включить API
Для выполнения следующей инструкции необходимо включить соответствующие службы Google Cloud.
gcloud services enable \
bigquery.googleapis.com \
dataplex.googleapis.com
Клонируйте репозиторий
Получите код инфраструктуры и скрипты автоматизации из репозитория GitHub. Чтобы сэкономить место на диске в Cloud Shell, мы загрузим только ту папку, которая необходима для этой лабораторной работы.
# Perform a shallow clone to get only the latest repository structure without the full history
git clone --depth 1 --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/devrel-demos.git
cd devrel-demos
# Specify and download only the folder we need for this lab
git sparse-checkout set data-analytics/governance-context
cd data-analytics/governance-context
Создайте "неупорядоченное" озеро данных.
В реальных условиях данные редко бывают чистыми. Для имитации реальности нам необходимо сочетание «официальных» хранилищ данных и ненадежных «песочниц».
Для развертывания наборов данных и таблиц BigQuery мы будем использовать скрипт установки.
- Сделайте скрипт установки исполняемым и запустите его. Это создаст три набора данных BigQuery (
finance_mart,marketing_prod,analyst_sandbox) и заполнит их таблицы примерами данных.
chmod +x ./setup_bq_tables.sh
./setup_bq_tables.sh
Контрольная точка : Теперь у вас есть полностью заполненное, но совершенно неуправляемое озеро данных. Для ИИ каждая таблица выглядит совершенно одинаково.
3. Создание шаблона управления данными (тип аспекта)
Теперь мы определим некоторые правила управления данными. В Knowledge Catalog это делается путем создания типа аспекта , который представляет собой многократно используемый шаблон метаданных со строгой типизацией.
Мы зарегистрируем этот шаблон с помощью интерфейса командной строки gcloud , чтобы вы могли увидеть, как он определен.
Проверьте схему аспектов.
Чтобы увидеть определение схемы, выведите содержимое файла aspect_template.json .
cat aspect_template.json
В результате вы увидите следующую структуру JSON:
{
"name": "OfficialDataProductSpec",
"type": "record",
"recordFields": [
{
"name": "product_tier",
"type": "enum",
"enumValues": [
{ "name": "GOLD_CRITICAL", "index": 1 },
{ "name": "SILVER_STANDARD", "index": 2 },
{ "name": "BRONZE_ADHOC", "index": 3 }
],
...
},
{
"name": "is_certified",
"type": "bool",
...
}
]
}
Обратите внимание, как эта схема обеспечивает строгие типы данных, такие как enum для уровня критичности ( GOLD_CRITICAL , SILVER_STANDARD , BRONZE_ADHOC ) и логическое значение bool для is_certified . Это гарантирует, что метаданные останутся структурированными и машиночитаемыми.
Зарегистрируйте тип аспекта
Выполните следующую команду gcloud , чтобы зарегистрировать этот шаблон в реестре вашего каталога знаний.
gcloud dataplex aspect-types create official-data-product-spec \
--location="${REGION}" \
--project="${PROJECT_ID}" \
--description="Defines the comprehensive profile of a data product for governance agents." \
--display-name="Official Data Product Spec" \
--metadata-template-file-name="aspect_template.json"
4. Применение принципов управления
Это критически важный этап проектирования. В настоящее время таблицы finance_mart.fin_monthly_closing_internal и analyst_sandbox.tmp_data_dump_v2_final_real выглядят идентично LLM. Это просто объекты со столбцами.
Как инженер по управлению данными, вы должны прикрепить к этим таблицам аспект (сертифицированную метку метаданных), чтобы различать их. В реальной корпоративной среде это можно автоматизировать с помощью конвейеров CI/CD. Мы смоделируем эту автоматизацию с помощью скриптов.
Сгенерировать полезную нагрузку управления
Ключи аспектов каталога знаний должны быть уникальными в глобальном масштабе (с префиксом в виде идентификатора вашего проекта). Скрипт ./generate_payloads.sh будет динамически генерировать файлы метаданных YAML.
chmod +x ./generate_payloads.sh
./generate_payloads.sh
Выход:
В результате создается папка "./aspect_payloads", содержащая 4 YAML-файла, определяющих сценарии управления (Gold/Internal, Gold/Public, Silver/Realtime, Bronze/Sandbox).
Применяйте параметры с помощью командной строки.
Прежде чем запускать скрипт, давайте разберемся, что именно мы используем, чтобы упростить процесс. Выполните следующую команду, чтобы увидеть структуру внутренних финансовых данных:
cat aspect_payloads/fin_internal.yaml
Здесь отобразится следующее содержимое.
your-project-id.us-central1.official-data-product-spec:
data:
product_tier: GOLD_CRITICAL
data_domain: FINANCE
usage_scope: INTERNAL_ONLY
update_frequency: DAILY_BATCH
is_certified: true
Обратите внимание, как этот YAML-файл явно определяет бизнес-контекст, например, устанавливая флаг is_certified : true и назначая уровень GOLD_CRITICAL . Это дает LLM четкие, структурированные правила для оценки, вместо того чтобы просто гадать, основываясь на именах таблиц.
Теперь запустите скрипт приложения. Он перебирает таблицы BigQuery и выполняет команду gcloud dataplex entries update чтобы добавить эти необходимые метаданные.
chmod +x ./apply_governance.sh
./apply_governance.sh
Проверка (необязательно)
Прежде чем продолжить, убедитесь, что метаданные были корректно применены в консоли.
- Откройте страницу « Каталог знаний » в консоли Google Cloud. Если вы не видите «Каталог знаний» в левом навигационном меню, воспользуйтесь строкой поиска в верхней части окна консоли Google Cloud, введите «Каталог знаний» и выберите результат в разделе «Лучшие результаты» или «Продукты и страницы».
- Найдите таблицу
fin_monthly_closing_internal. В результатах поиска должна отобразиться соответствующая таблица BigQuery. Щелкните по названию таблицы, чтобы перейти на страницу с ее подробными сведениями.
- На странице с подробными сведениями о таблице найдите раздел « Дополнительные теги и аспекты », расположенный внизу.
- Вы найдете раздел
official-data-product-spec». Убедитесь, что значения соответствуют сценарию « Gold Internal », который мы применили.
Теперь вы подтвердили, что технически идентичные таблицы BigQuery ( fin_monthly_closing_internal и tmp_data_dump_v2_final_real ) логически различаются машиночитаемыми метаданными.
5. Настройка и создание прототипа агента.
Прежде чем создавать приложение (что мы сделаем во второй части), мы проверим нашу логику управления данными локально. Нам необходимо установить плагин Knowledge Catalog и настроить навык агента.
Установите расширение
В Cloud Shell установите плагин Knowledge Catalog. Вам потребуется подтвердить установку и указать параметры настройки.
export DATAPLEX_PROJECT="${PROJECT_ID}"
agy plugin install https://github.com/gemini-cli-extensions/dataplex
Проверьте навыки агента.
Навык агента представляет собой статический, многократно используемый файл определения, расположенный в .agents/skills/knowledge_catalog_governance/SKILL.md . Он содержит логику, которая преобразует абстрактные человеческие правила (например, «Мне нужны безопасные данные») в строгие технические запросы.
Изучите файл, чтобы понять алгоритм, которому мы обучаем ИИ:
cat .agents/skills/knowledge_catalog_governance/SKILL.md
Обратите внимание, что модель явно указана на необходимость строгого соблюдения цикла «Фаза 1» (проверка метаданных) и «Фаза 2» (выполнение запроса). Модель должна обнаружить и проверить метаданные, прежде чем формировать какой-либо SQL-запрос.
Запустите агента и протестируйте сценарии.
Запустите сессию AGY CLI. Она автоматически обнаружит и загрузит навык из каталога .agents/skills .
agy
Примечание: Возможно, будет загружено несколько контекстных файлов. Это нормально. Интерфейс командной строки загружает локальный навык для правил, специфичных для этого проекта, а также инструкции по умолчанию для самого плагина «Каталог знаний».
Проверьте установку
Введите /mcp чтобы убедиться, что плагин Knowledge Catalog активен. Вы должны увидеть knowledge-catalog в списке активных плагинов с доступными инструментами.
/mcp
Ожидаемый результат:
MCP Servers
...
> ✓ knowledge-catalog Tools: search_entries, lookup_context, lookup_entry
Тестовые сценарии (прототипирование)
Вставьте следующие подсказки в запущенную сессию агента по очереди, чтобы убедиться, что они соответствуют вашим правилам.
- Сценарий А (подтверждение данных финансового директора):
"We are preparing the deck for an internal Board of Directors meeting next week. I need the numbers to be absolutely finalized, trustworthy, and kept strictly confidential. Which table is safe to use?"
Ожидаемый результат: Агент автоматически обнаруживает ваш активный проект и регион с помощью своих инструментов, запрашивает информацию fin_monthly_closing_internal , поскольку она семантически соответствует GOLD_CRITICAL (точно) и INTERNAL_ONLY (заседание совета директоров) в своем аспекте, и рекомендует его.
- Сценарий B (публичное раскрытие информации):
"I need to share our quarterly financial summary with an external consulting firm. It is critical that we do not leak any raw or internal metrics. Which dataset is officially scrubbed and explicitly approved for external sharing?"
Ожидается: Агент должен обойти внутреннюю ежемесячную таблицу и выбрать исключительно fin_quarterly_public_report , поскольку это единственный актив с меткой EXTERNAL_READY .
- Сценарий C (оперативные потребности):
"My dashboard needs to show what's happening right now with our ad spend. I can't wait for the overnight load. What do you recommend?"
Ожидаемый результат: Агент выбирает mkt_realtime_campaign_performance поскольку этот параметр определяет частоту обновления REALTIME_STREAMING , отдавая ей приоритет перед уровнем GOLD_CRITICAL финансовых данных.
- Сценарий D (эксперимент в песочнице):
"I'm just playing around with some new ML models and need a lot of raw data. It doesn't need to be perfect, just a sandbox environment."
Ожидаемый результат: Агент выбирает tmp_data_dump_v2_final_real поскольку он семантически соответствует BRONZE_ADHOC (исходные данные) и is_certified: false (среда песочницы) в своем аспекте.
(Для выхода из сессии AGY введите /exit или /quit)
6. Поздравляем! Что дальше?
Вы успешно создали управляемую базу данных и доказали, что ИИ может строго следовать вашим правилам метаданных, используя локальный прототип CLI!
Вы достигли контрольной точки. Пожалуйста, выберите следующий шаг:
Вариант А: Я хочу прямо сейчас перейти ко второй части!
Если вы готовы превратить этот локальный прототип в безопасное веб-приложение производственного уровня, используя протокол контекста модели (MCP) и Cloud Run:
👉 Ссылка на вторую часть Codelab
Вариант Б: Я выполню часть 2 позже, или я хотел бы завершить только часть 1.
Если вы хотите сегодня же прекратить использование облачных сервисов и избежать дополнительных расходов, вам следует оптимизировать свои ресурсы.
Не волнуйтесь! Во второй части мы предоставим «быстрый скрипт», который полностью восстановит среду из первой части всего за 2 минуты, чтобы вы могли продолжить работу с того места, где остановились.
👉 Перейдите к разделу уборки.
7. Уборка (только для варианта B)
Если вы остановились здесь, уничтожьте ресурсы, чтобы избежать дополнительных расходов.
Уничтожьте озеро данных.
Если вы в данный момент находитесь в сеансе командной строки AGY, выйдите из него, дважды нажав Ctrl+C или введя /quit . Затем выполните следующие команды:
chmod +x ./cleanup_data_lake.sh
./cleanup_data_lake.sh
Удалите плагин AGY CLI и локальные файлы.
agy plugin uninstall dataplex
cd ~
rm -rf ~/devrel-demos