Tworzenie podstaw danych z użyciem metadanych Knowledge Catalog

1. Wprowadzenie

Modele generatywnej AI mają duże możliwości rozumowania, ale brakuje im kontekstu instytucjonalnego. Jeśli dyrektor zapyta agenta AI: „Jakie są nasze przychody w I kwartale?”, agent może znaleźć w jeziorze danych dziesiątki tabel o nazwie „przychody”. Niektóre z nich to rygorystyczne raporty finansowe, inne to szacunki marketingowe w czasie rzeczywistym, a wiele z nich to prawdopodobnie wycofane piaskownice.

Bez wyraźnego grounding agent AI wybierze tabelę na podstawie prostego podobieństwa nazw, co doprowadzi do „przekonująco błędnych” odpowiedzi opartych na 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 utworzysz bazę danych. Skonfigurujesz realistyczne, „nieuporządkowane” jezioro danych w BigQuery, 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 przetestować, czy agent ściśle przestrzega zasad zarządzania danymi.

Możesz przeczytać drugą część tej serii, która opisuje, jak wdrożyć prototyp lokalnego 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, wielopoziomowe jezioro danych za pomocą skryptu konfiguracyjnego;
• Projektuj i rejestruj niestandardowe szablony metadanych (typy aspektów) w Knowledge Catalog, aby odróżniać oficjalne produkty danych od nieprzetworzonych tabel 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 wiersza poleceń AGY jest wstępnie zainstalowany w Cloud Shell).
• Podstawowa wiedza i znajomość BigQuery i Knowledge Catalog.

Kluczowe pojęcia

• 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 odróżnieniu od tagów z dowolnym tekstem aspekty wymuszają silne typowanie (typy wyliczeniowe, wartości logiczne), dzięki czemu są niezawodne w ocenie przez maszyny.

2. Konfiguracja i wymagania

Uruchamianie Cloud Shell

Chociaż Google Cloud można obsługiwać zdalnie z laptopa, w tym ćwiczeniu wykorzystasz Google Cloud Shell, czyli środowisko wiersza poleceń działające 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 ćwiczeniu można wykonać w przeglądarce. Nie musisz niczego instalować.

Inicjowanie środowiska

Otwórz Cloud Shell i ustaw zmienne projektu, aby mieć pewność, że wszystkie polecenia będą kierowane do właściwej infrastruktury.

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

Włącz interfejsy API

Włącz usługi Google Cloud niezbędne do wykonania tej instrukcji.

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 rzeczywistym świecie rzadko są czyste. Aby zasymulować rzeczywistość, potrzebujemy kombinacji „oficjalnych” składnic danych i niezaufanych tabel „piaskownicy”.

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

1. Ustaw skrypt konfiguracyjny jako wykonywalny i uruchom go. Spowoduje to utworzenie trzech zbiorów danych BigQuery (finance_mart, marketing_prod, analyst_sandbox) i wypełnienie ich tabel danymi próbkowanymi.

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żdy stół 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, który jest szablonem metadanych o silnym typowaniu, z możliwością wielokrotnego użycia.

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

Sprawdzanie schematu aspektu

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

cat aspect_template.json

Zobaczysz tę strukturę 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ę, że ten schemat wymusza ścisłe typy danych, takie jak enum dla poziomu krytyczności (GOLD_CRITICAL, SILVER_STANDARD, BRONZE_ADHOC) i bool dla is_certified. Dzięki temu metadane pozostają uporządkowane i w formacie czytelnym dla komputerów.

Rejestrowanie typu aspektu

Uruchom to polecenie gcloud, aby zarejestrować ten szablon w rejestrze Knowledge Catalog.

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. Zastosuj zarządzanie

To kluczowy etap inżynieryjny. Obecnie tabele finance_mart.fin_monthly_closing_internal i analyst_sandbox.tmp_data_dump_v2_final_real wyglądają identycznie dla LLM. 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 rozróż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 Knowledge Catalog muszą być unikalne globalnie (poprzedzone identyfikatorem projektu). Skrypt ./generate_payloads.sh będzie dynamicznie generować 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 faktycznie stosujemy, aby wyjaśnić ten proces. Uruchom to polecenie, aby zobaczyć strukturę wewnętrznego ładunku finansowego:

cat aspect_payloads/fin_internal.yaml

Wyświetlą się 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. ustawia flagę is_certified: true i przypisuje poziom GOLD_CRITICAL. Podanie LLM jasnych, ustrukturyzowanych reguł do oceny zamiast zgadywania na podstawie nazw tabel.

Teraz uruchom skrypt aplikacji. Spowoduje to przejście przez tabele BigQuery i wykonanie polecenia gcloud dataplex entries update w celu dołączenia tych sztywnych metadanych.

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

Weryfikacja (opcjonalnie)

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 nie widzisz opcji „Knowledge Catalog” w menu nawigacyjnym po lewej stronie, użyj paska wyszukiwania u góry okna konsoli Google Cloud, wpisz „Knowledge Catalog” i wybierz wynik w sekcji „Najlepsze wyniki” lub „Usługi i strony”.
2. Wyszukaj: fin_monthly_closing_internal W wynikach powinna pojawić się tabela BigQuery. Kliknij nazwę tabeli, aby otworzyć stronę z informacjami o niej.

3. Na stronie z informacjami o tabeli znajdź na dole sekcję „Opcjonalne tagi i aspekty”.
4. Znajdziesz aspekt official-data-product-spec. Sprawdź, czy wartości są zgodne z zastosowanym scenariuszem „Gold Internal”.

Wiesz już, że tabele BigQuery (fin_monthly_closing_internal i tmp_data_dump_v2_final_real), które są identyczne pod względem technicznym, są logicznie rozróżniane przez metadane w formacie czytelnym dla komputerów.

5. Konfigurowanie i prototypowanie agenta

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

Instalowanie rozszerzenia

W Cloud Shell zainstaluj wtyczkę Knowledge Catalog. Poprosi 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ść agenta to statyczny plik definicji wielokrotnego użytku, który znajduje się w folderze .agents/skills/knowledge_catalog_governance/SKILL.md. Zawiera logikę, która przekłada abstrakcyjne reguły ludzkie (np. „Potrzebuję bezpiecznych danych”) na rygorystyczne 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 on model, aby postępował zgodnie ze ścisłą pętlą fazy 1 (weryfikacja metadanych) i fazy 2 (wykonywanie zapytania). Przed utworzeniem kodu SQL model musi wykryć i zweryfikować metadane.

Uruchamianie agenta i testowanie scenariuszy

Rozpocznij sesję interfejsu wiersza poleceń AGY. Automatycznie wykryje i załaduje umiejętność z katalogu .agents/skills.

agy

Uwaga: możesz zobaczyć, że wczytywanych jest kilka plików kontekstu. To zupełnie normalne. Interfejs wiersza poleceń wczytuje lokalną umiejętność dla reguł tego projektu oraz domyślne instrukcje dla samej wtyczki Knowledge Catalog.

Zweryfikuj instalację

Wpisz /mcp, aby potwierdzić, że wtyczka Knowledge Catalog jest aktywna. Wtyczka knowledge-catalog powinna być widoczna jako aktywna wraz 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?"

Oczekiwany wynik: agent automatycznie wykrywa aktywny projekt i region za pomocą swoich narzędzi, wysyła zapytanie do fin_monthly_closing_internal, ponieważ semantycznie pasuje do GOLD_CRITICAL (dokładne) i INTERNAL_ONLY (spotkanie zarządu) w aspekcie, i rekomenduje go.

• Scenariusz 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ć wyłącznie fin_quarterly_public_report, ponieważ jest to jedyny zasób 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?"

Oczekiwany wynik: agent wybiera mkt_realtime_campaign_performance, ponieważ identyfikuje częstotliwość aktualizacji REALTIME_STREAMING, traktując ją priorytetowo w stosunku do poziomu GOLD_CRITICAL danych finansowych.

• Scenariusz D (eksperymenty 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 wynik: agent wybiera tmp_data_dump_v2_final_real, ponieważ semantycznie pasuje do BRONZE_ADHOC (nieprzetworzone dane) i is_certified: false (środowisko piaskownicy) w aspekcie.

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

6. Gratulacje! Co dalej?

Udało Ci się utworzyć zarządzaną bazę danych i udowodnić, że AI może ściśle przestrzegać reguł dotyczących metadanych, korzystając z lokalnego prototypu CLI.

Dotarliśmy do punktu kontrolnego. 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 za pomocą protokołu Model Context Protocol (MCP) i Cloud Run:

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

⚠️ STOP: nie wykonuj poniższych czynności związanych z czyszczeniem. W części 2 będziesz potrzebować bieżących danych i ustawień Knowledge Catalog.

Opcja B: Część 2 wykonam później lub chcę ukończyć 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 przyspieszający”, który w ciągu zaledwie 2 minut całkowicie odtworzy środowisko z części 1, dzięki czemu będzie można kontynuować pracę od miejsca, w którym została przerwana.

👉 Przejdź do sekcji dotyczącej czyszczenia.

7. Czyszczenie (tylko w przypadku opcji B)

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

Zniszczenie jeziora danych

Jeśli jesteś obecnie w sesji interfejsu wiersza poleceń AGY, zakończ 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