Создание основы для сбора данных с помощью метаданных Каталога знаний

1. Введение

Модели генеративного ИИ обладают мощными возможностями рассуждения, но им не хватает контекста организации. Если руководитель спросит ИИ-агента, каков доход за первый квартал, агент может найти в озере данных десятки таблиц с названием "доход". Некоторые из них – это строгие финансовые отчеты, другие – маркетинговые оценки в реальном времени, а многие, скорее всего, устаревшие песочницы.

Без явного заземления ИИ-агент выберет таблицу на основе простого сходства названий, что приведет к убедительно неверным ответам, полученным на основе непроверенных данных.

Эта практическая работа – первая из двух, посвященных созданию ИИ-агента, учитывающего требования к управлению.

В первой части вы создадите основу для данных. Вы настроите реалистичное, "неупорядоченное" озеро данных в BigQuery, примените жесткие теги метаданных (аспекты каталога знаний), чтобы отличить действительные данные от шума, и используете Antigravity (AGY) CLI для локального тестирования того, строго ли агент следует вашим правилам управления данными.

Вы можете прочитать вторую часть этой серии, в которой рассказывается, как развернуть прототип локального агента в безопасном веб-приложении корпоративного уровня с помощью Model Context Protocol (MCP) и Cloud Run. 👉 Читать часть 2

Что вы узнаете

• Разверните реалистичное многоуровневое озеро данных с помощью скрипта настройки.
• Разработайте и зарегистрируйте шаблоны специальных метаданных (типы аспектов) в каталоге знаний, чтобы отличать официальные продукты данных от необработанных таблиц в тестовой среде.
• Проверьте правила управления данными локально с помощью AGY CLI, прежде чем писать код приложения.

Что вам понадобится

• Проект Google Cloud с включенными платежными функциями.
• Доступ к Google Cloud Shell (интерфейс командной строки AGY предустановлен в Cloud Shell).
• Базовые знания о BigQuery и Knowledge Catalog.

Основные понятия

• Knowledge Catalog – единый сервис управления метаданными. Мы используем его, чтобы обогащать технические метаданные (схемы) бизнес-контекстом (управлением).
• Тип аспекта. Шаблон структурированных метаданных. В отличие от тегов со свободным текстом, аспекты обеспечивают строгую типизацию (перечисления, логические значения), что делает их надежными для оценки машинами.

2. Настройка и требования

Запустить Cloud Shell

Хотя Google Cloud можно управлять удаленно с ноутбука, в этой практической работе вы будете использовать Google Cloud Shell – среду командной строки, работающую в облаке.

В консоли Google Cloud нажмите на значок Cloud Shell на панели инструментов в правом верхнем углу.

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

На этой виртуальной машине установлены все необходимые инструменты разработки. Она предлагает постоянный домашний каталог объемом 5 ГБ и работает на платформе Google Cloud, что значительно повышает производительность сети и аутентификацию. Все действия в рамках этой практической работы можно выполнить в браузере. Ничего устанавливать не нужно.

Инициализация среды

Откройте 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 мы будем использовать скрипт настройки.

1. Сделайте скрипт настройки исполняемым и запустите его. Будут созданы три набора данных BigQuery (finance_mart, marketing_prod, analyst_sandbox), а их таблицы будут заполнены примерами данных.

chmod +x ./setup_bq_tables.sh
./setup_bq_tables.sh

Контрольная точка. Теперь у вас есть полностью заполненное, но совершенно не управляемое озеро данных. Для ИИ все таблицы выглядят одинаково.

3. Создание шаблона управления данными (тип аспекта)

Теперь мы определим некоторые правила управления данными. В Knowledge Catalog для этого создается тип аспекта – многократно используемый шаблон метаданных со строгой типизацией.

Мы зарегистрируем этот шаблон с помощью CLI 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. Это гарантирует, что метаданные останутся структурированными и машиночитаемыми.

Зарегистрируйте тип аспекта

Чтобы зарегистрировать этот шаблон в реестре Knowledge Catalog, выполните следующую команду 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. Мы смоделируем эту автоматизацию с помощью скриптов.

Создание полезных нагрузок для управления

Ключи аспектов Knowledge Catalog должны быть уникальными (с префиксом идентификатора проекта). Скрипт ./generate_payloads.sh динамически генерирует файлы метаданных YAML.

chmod +x ./generate_payloads.sh
./generate_payloads.sh

Результат

Будет создана папка ./aspect_payloads с четырьмя YAML-файлами, определяющими сценарии управления (Gold/Internal, Gold/Public, Silver/Realtime, Bronze/Sandbox).

Как применить аспекты с помощью CLI

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

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

Проверка (необязательно)

Прежде чем продолжить, убедитесь, что метаданные были правильно применены в консоли.

1. Откройте страницу Knowledge Catalog в консоли Google Cloud. Если вы не видите Knowledge Catalog в меню навигации слева, введите Knowledge Catalog в строке поиска вверху консоли Google Cloud и выберите результат в разделе "Лучшие результаты" или "Продукты и страницы".
2. Искать по запросу "fin_monthly_closing_internal". В результатах должна быть таблица BigQuery. Нажмите на название таблицы, чтобы перейти на страницу сведений о ней.

3. На странице сведений о таблице найдите раздел Необязательные теги и аспекты внизу.
4. Вы найдете аспект official-data-product-spec. Убедитесь, что значения соответствуют сценарию Gold Internal, который мы применили.

Вы убедились, что технически идентичные таблицы BigQuery (fin_monthly_closing_internal и tmp_data_dump_v2_final_real) логически различаются по машиночитаемым метаданным.

5. Настройте и протестируйте агент

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

Установите расширение

В 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

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

Подтвердить установку

Введите /mcp, чтобы убедиться, что плагин Knowledge Catalog активен. Вы увидите knowledge-catalog в списке активных плагинов с доступными инструментами.

/mcp

Ожидаемый результат:

MCP Servers
...
>  ✓ knowledge-catalog  Tools: search_entries, lookup_context, lookup_entry

Тестовые сценарии (прототипирование)

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

💡 Совет. Если появится запрос, выберите "2. Да, и всегда разрешайте knowledge-catalog/search_entries в этом чате, чтобы тестирование проходило без проблем.

• Сценарий А (подтверждение данных финансового директора):

"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 (собрание совета директоров) в его аспекте, и рекомендует его.

• Сценарий Б (публичное раскрытие информации)

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

• Сценарий В (операционные потребности):

"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 финансовых данных.

• Сценарий Г (эксперименты в тестовой среде)

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

Теперь вы достигли контрольной точки. Выберите, что сделать дальше:

Вариант А. Я хочу перейти к части 2 прямо сейчас!

Если вы готовы превратить этот локальный прототип в безопасное веб-приложение производственного уровня с помощью Model Context Protocol (MCP) и Cloud Run:

👉 Ссылка на вторую часть практической работы

⚠️ ВНИМАНИЕ! Не выполняйте описанные ниже действия по удалению. Текущие настройки данных и каталога знаний понадобятся вам во второй части.

Вариант Б. Я выполню часть 2 позже или мне нужно было выполнить только часть 1.

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

Не волнуйтесь! Во второй части мы предоставим вам скрипт, который за две минуты полностью воссоздаст среду из первой части, чтобы вы могли продолжить с того места, на котором остановились.

👉 Перейдите к разделу "Очистка".

7. Очистка (только для варианта Б)

Если вы не планируете продолжать, удалите ресурсы, чтобы избежать расходов.

Уничтожить озеро данных

Если вы находитесь в сеансе CLI 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