Tworzenie podstaw danych z użyciem metadanych Knowledge Catalog

1. Wprowadzenie

Modele generatywnej AI są potężnymi narzędziami do wnioskowania, ale brakuje im kontekstu instytucjonalnego. Jeśli menedżer zapyta agenta AI: „Jakie są nasze przychody w I kwartale?”, agent może znaleźć w Twoim jeziorze danych dziesiątki tabel o nazwie „przychody”. Niektóre z nich to rzetelne raporty finansowe, inne to szacunki marketingowe w czasie rzeczywistym, a wiele z nich to prawdopodobnie wycofane piaskownice.

Bez wyraźnego uzasadnienia agent AI wybierze tabelę na podstawie prostego podobieństwa nazw, co prowadzi do „przekonująco błędnych” odpowiedzi pochodzących z niezweryfikowanych danych.

To ćwiczenie jest częścią dwuczęściowej serii, w której pokazujemy, jak utworzyć agenta AI uwzględniającego zasady zarządzania.

W tej pierwszej części zbudujesz podstawy danych. Skonfigurujesz w BigQuery realistyczne, „nieuporządkowane” jezioro danych, zastosujesz sztywne tagi metadanych (aspekty Knowledge Catalog), aby odróżnić prawidłowe dane od szumu, i użyjesz interfejsu wiersza poleceń Antigravity (AGY), aby lokalnie sprawdzić, czy agent ściśle przestrzega reguł zarządzania danymi.

Możesz przeczytać drugą część tej serii, w której opisujemy, jak wdrożyć lokalny prototyp agenta w bezpiecznej aplikacji internetowej klasy korporacyjnej przy użyciu protokołu Model Context Protocol (MCP) i Cloud Run. 👉 Przeczytaj część 2

Czego się nauczysz

• wdrożyć realistyczne, wielowarstwowe jezioro danych za pomocą skryptu konfiguracyjnego,
• Zaprojektuj i zarejestruj w Knowledge Catalog niestandardowe szablony metadanych (typy aspektów), aby odróżnić oficjalne usługi danych od surowych tabel w piaskownicy.
• Zanim napiszesz kod aplikacji, sprawdź lokalnie reguły zarządzania danymi za pomocą interfejsu wiersza poleceń AGY.

Czego potrzebujesz

• projekt Google Cloud z włączonymi płatnościami;
• Dostęp do Google Cloud Shell (interfejs AGY CLI jest wstępnie zainstalowany w Cloud Shell).
• Podstawowa wiedza o BigQuery i Knowledge Catalog.

Kluczowych pojęć

• Knowledge Catalog: ujednolicona usługa zarządzania metadanymi. Używamy go do wzbogacania metadanych technicznych (schematów) o kontekst biznesowy (zarządzanie).
• Typ aspektu: szablon uporządkowanych metadanych. W przeciwieństwie do tagów w formie tekstu swobodnego aspekty wymuszają silne typowanie (wyliczenia, wartości logiczne), dzięki czemu są wiarygodne dla maszyn.

2. Konfiguracja i wymagania

Uruchamianie Cloud Shell

Z Google Cloud można korzystać zdalnie na laptopie, ale w tym ćwiczeniu użyjesz Google Cloud Shell, czyli środowiska wiersza poleceń działającego w chmurze.

W konsoli Google Cloud kliknij ikonę Cloud Shell na pasku narzędzi w prawym górnym rogu:

Uzyskanie dostępu do środowiska i połączenie się z nim powinno zająć tylko kilka chwil. Po zakończeniu powinno wyświetlić się coś takiego:

Ta maszyna wirtualna zawiera wszystkie potrzebne narzędzia dla programistów. Zawiera również stały katalog domowy o pojemności 5 GB i działa w Google Cloud, co znacznie zwiększa wydajność sieci i usprawnia proces uwierzytelniania. Wszystkie zadania w tym laboratorium możesz wykonać w przeglądarce. Nie musisz niczego instalować.

Inicjowanie środowiska

Otwórz Cloud Shell i ustaw zmienne projektu, aby mieć pewność, że wszystkie polecenia są kierowane do prawidłowej infrastruktury.

export PROJECT_ID=$(gcloud config get-value project)
gcloud config set project $PROJECT_ID
export REGION="us-central1"

Włącz interfejsy API

Aby wykonać poniższe instrukcje, włącz niezbędne usługi Google Cloud.

gcloud services enable \
  bigquery.googleapis.com \
  dataplex.googleapis.com

Klonowanie repozytorium

Pobierz kod infrastruktury i skrypty automatyzacji z repozytorium GitHub. Aby zaoszczędzić miejsce na dysku w Cloud Shell, pobierzemy tylko folder potrzebny w tym module.

# 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

Tworzenie „nieuporządkowanego” jeziora danych

Środowiska danych w rzeczywistości rzadko są czyste. Aby symulować rzeczywistość, potrzebujemy połączenia „oficjalnych” hurtowni danych i niezaufanych tabel „piaskownicy”.

Do wdrożenia zbiorów danych i tabel BigQuery użyjemy skryptu konfiguracji.

1. Ustaw skrypt konfiguracji jako wykonywalny i uruchom go. Spowoduje to utworzenie 3 zbiorów danych BigQuery (finance_mart, marketing_prod, analyst_sandbox) i wypełnienie ich tabel danymi przykładowymi.

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

Punkt kontrolny: masz teraz w pełni wypełnione, ale całkowicie niezarządzane jezioro danych. Dla AI każda tabela wygląda dokładnie tak samo.

3. Tworzenie szablonu zarządzania danymi (typu aspektu)

Teraz zdefiniujemy kilka reguł zarządzania danymi. W Knowledge Catalog odbywa się to przez utworzenie typu aspektu, czyli szablonu metadanych z możliwością wielokrotnego użycia i silnym typowaniem.

Zarejestrujemy ten szablon za pomocą gcloud interfejsu wiersza poleceń, aby pokazać, jak jest zdefiniowany.

Sprawdzanie schematu aspektu

Wyświetl zawartość aspect_template.json, aby zobaczyć definicję schematu.

cat aspect_template.json

Wyświetli się następująca struktura 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",
      ...
    }
  ]
}

Zwróć uwagę, jak ten schemat wymusza ścisłe typy danych, np. enum dla poziomu krytyczności (GOLD_CRITICAL, SILVER_STANDARD, BRONZE_ADHOC) i bool dla is_certified. Dzięki temu metadane pozostaną uporządkowane i czytelne dla maszyn.

Zarejestruj typ aspektu

Aby zarejestrować ten szablon w rejestrze Knowledge Catalog, uruchom to polecenie 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. Stosowanie zasad zarządzania

To kluczowy etap inżynieryjny. Obecnie tabele finance_mart.fin_monthly_closing_internal i analyst_sandbox.tmp_data_dump_v2_final_real wyglądają dla LLM identycznie. Są to po prostu obiekty z kolumnami.

Jako inżynier ds. zarządzania musisz dołączyć do tych tabel aspekt (certyfikowaną etykietę metadanych), aby je odróżnić. W prawdziwym przedsiębiorstwie można to zautomatyzować za pomocą potoków CI/CD. Zasymulujemy tę automatyzację za pomocą skryptów.

Generowanie ładunków zarządzania

Klucze aspektów w Knowledge Catalog muszą być unikalne globalnie (z prefiksem w postaci identyfikatora projektu). Skrypt ./generate_payloads.sh dynamicznie wygeneruje pliki metadanych YAML.

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

Dane wyjściowe:

Spowoduje to utworzenie folderu „./aspect_payloads” zawierającego 4 pliki YAML, które definiują scenariusze zarządzania (Gold/Internal, Gold/Public, Silver/Realtime, Bronze/Sandbox).

Stosowanie aspektów za pomocą interfejsu wiersza poleceń

Zanim uruchomisz skrypt, przyjrzyjmy się temu, co właściwie zastosujemy, aby wyjaśnić ten proces. Aby zobaczyć strukturę ładunku wewnętrznego finansowania, uruchom to polecenie:

cat aspect_payloads/fin_internal.yaml

Wyświetli ona te treści:

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

Zwróć uwagę, jak ten plik YAML wyraźnie definiuje kontekst biznesowy, np. ustawiając flagę is_certified na wartość „true” i przypisując poziom GOLD_CRITICAL. Podawanie LLM jasnych, uporządkowanych reguł oceny zamiast zgadywania na podstawie nazw tabel.

Teraz uruchom skrypt aplikacji. Ta funkcja iteruje tabele BigQuery i wykonuje polecenie gcloud dataplex entries update, aby dołączyć te sztywne metadane.

chmod +x ./apply_governance.sh
./apply_governance.sh

Weryfikacja (opcjonalna)

Zanim przejdziesz dalej, sprawdź, czy metadane zostały prawidłowo zastosowane w konsoli.

1. Otwórz stronę Knowledge Catalog w konsoli Google Cloud. Jeśli w menu nawigacyjnym po lewej stronie nie widzisz opcji „Knowledge Catalog”, użyj paska wyszukiwania u góry okna konsoli Google Cloud, wpisz „Knowledge Catalog” i wybierz wynik w sekcji „Najważniejsze wyniki” lub „Usługi i strony”.
2. Wyszukaj: fin_monthly_closing_internal W wynikach powinna się pojawić tabela BigQuery. Kliknij nazwę tabeli, aby otieść stronę z informacjami.

3. Na stronie z informacjami o tabeli znajdź sekcję „Opcjonalne tagi i aspekty” u dołu.
4. Znajdziesz tam aspekt official-data-product-spec. Sprawdź, czy wartości są zgodne ze scenariuszem „Gold Internal”, który został zastosowany.

Potwierdziliśmy, że technicznie identyczne tabele BigQuery (fin_monthly_closing_internal i tmp_data_dump_v2_final_real) są logicznie rozróżniane przez metadane odczytywane przez maszyny.

5. Konfigurowanie i tworzenie prototypu agenta

Zanim utworzymy aplikację (co zrobimy w części 2), sprawdzimy lokalnie logikę zarządzania danymi. Musimy zainstalować wtyczkę Knowledge Catalog i skonfigurować umiejętność agenta.

Instalowanie rozszerzenia

W Cloud Shell zainstaluj wtyczkę Knowledge Catalog. Poprosimy Cię o potwierdzenie i podanie szczegółów konfiguracji.

export DATAPLEX_PROJECT="${PROJECT_ID}"

agy plugin install https://github.com/gemini-cli-extensions/dataplex

Sprawdzanie umiejętności agenta

Umiejętność pracownika obsługi klienta to statyczny plik definicji wielokrotnego użytku znajdujący się w .agents/skills/knowledge_catalog_governance/SKILL.md. Zawiera logikę, która przekłada abstrakcyjne reguły (np. „Potrzebuję bezpiecznych danych”) na ścisłe wyszukiwania techniczne.

Sprawdź plik, aby zrozumieć algorytm, którego uczymy AI:

cat .agents/skills/knowledge_catalog_governance/SKILL.md

Zwróć uwagę, że wyraźnie instruuje model, aby postępował zgodnie z ściśle określonymi pętlami fazy 1 (weryfikacja metadanych) i fazy 2 (wykonywanie zapytań). Przed utworzeniem kodu SQL model musi wykryć i zweryfikować metadane.

Uruchom agenta i przetestuj scenariusze

Rozpocznij sesję interfejsu AGY CLI. Automatycznie wykryje i wczyta umiejętność z katalogu .agents/skills.

agy

Uwaga: może się zdarzyć, że załaduje się kilka plików kontekstowych. To zupełnie normalne. Interfejs CLI wczytuje lokalną usługę w przypadku konkretnych reguł tego projektu oraz domyślne instrukcje dotyczące samego wtyczki Katalog wiedzy.

Zweryfikuj instalację

Wpisz /mcp, aby potwierdzić, że wtyczka Knowledge Catalog jest aktywna. knowledge-catalog powinna być widoczna jako aktywna wtyczka z dostępnymi narzędziami.

/mcp

Oczekiwane dane wyjściowe:

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

Scenariusze testowe (prototypowanie)

Wklejaj kolejno te prompty do uruchomionej sesji agenta, aby sprawdzić, czy przestrzega on Twoich reguł.

💡 Wskazówka: jeśli pojawi się prośba, wybierz „2. Tak, i zawsze zezwalaj na „knowledge-catalog/search_entries' w tej rozmowie”, aby umożliwić płynne testowanie.

• Scenariusz A (certyfikacja danych dyrektora finansowego):

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

Oczekiwane działanie: agent automatycznie wykrywa aktywny projekt i region na podstawie swoich narzędzi, wysyła zapytanie fin_monthly_closing_internal, ponieważ semantycznie pasuje ono do GOLD_CRITICAL (dokładne) i INTERNAL_ONLY (spotkanie zarządu) w aspekcie, i rekomenduje je.

• Przykład B (ujawnienie publiczne):

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

Oczekiwany wynik: agent musi pominąć miesięczną tabelę wewnętrzną i wybrać tylko fin_quarterly_public_report, ponieważ jest to jedyny komponent oznaczony tagiem EXTERNAL_READY.

• Scenariusz C (potrzeby operacyjne):

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

Oczekiwane działanie: agent wybiera mkt_realtime_campaign_performance, ponieważ określa on częstotliwość aktualizacji REALTIME_STREAMING, która jest ważniejsza niż poziom GOLD_CRITICAL danych finansowych.

• Scenariusz D (eksperymentowanie w piaskownicy):

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

Oczekiwany rezultat: agent wybiera tmp_data_dump_v2_final_real, ponieważ w jego aspekcie jest on semantycznie zgodny z BRONZE_ADHOC (dane pierwotne) i is_certified: false (środowisko piaskownicy).

(Aby zakończyć sesję AGY, wpisz /exit lub /quit)

6. Gratulacje! Co dalej?

Udało Ci się zbudować zarządzaną podstawę danych i udowodnić, że AI może ściśle przestrzegać reguł metadanych za pomocą lokalnego prototypu CLI.

Osiągnięto punkt kontrolny. Wybierz następny krok:

Opcja A: chcę od razu przejść do części 2.

Jeśli chcesz przekształcić ten lokalny prototyp w bezpieczną aplikację internetową klasy produkcyjnej przy użyciu protokołu Model Context Protocol (MCP) i Cloud Run:

👉 Link do ćwiczeń z programowania w części 2

⚠️ STOP: nie wykonuj czynności opisanych w sekcji „Procedura czyszczenia” poniżej. W części 2 będziesz potrzebować aktualnych danych i ustawień Knowledge Catalog.

Opcja B: część 2 wykonam później lub chciałem/chciałam wykonać tylko część 1.

Jeśli chcesz zakończyć pracę na dziś i uniknąć kosztów związanych z chmurą, wyczyść zasoby.

Bez obaw, W części 2 udostępnimy „skrypt szybkiego śledzenia”, który w zaledwie 2 minuty całkowicie odtworzy środowisko z części 1, dzięki czemu będziesz mieć możliwość kontynuowania pracy od miejsca, w którym została przerwana.

👉 Przejdź do sekcji czyszczenia.

7. Zwalnianie miejsca (tylko w przypadku opcji B)

Jeśli chcesz zakończyć ten samouczek, usuń zasoby, aby uniknąć opłat.

Usuwanie jeziora danych

Jeśli jesteś w sesji interfejsu AGY CLI, zamknij ją, naciskając dwukrotnie Ctrl+C lub wpisując /quit. Następnie uruchom te polecenia:

chmod +x ./cleanup_data_lake.sh
./cleanup_data_lake.sh

Odinstalowywanie wtyczki interfejsu wiersza poleceń AGY i usuwanie plików lokalnych

agy plugin uninstall dataplex
cd ~
rm -rf ~/devrel-demos