Tworzenie podstawy danych za pomocą metadanych Dataplex

1. Wprowadzenie

Modele generatywnej AI są skuteczne w wyciąganiu wniosków, 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 data lake 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 doprowadzi do uzyskania „przekonująco błędnych” odpowiedzi pochodzących z niezweryfikowanych danych.

Te warsztaty programistyczne są częścią dwuczęściowej serii, w której pokazujemy, jak tworzyć agenta generatywnej AI uwzględniającego zasady.

W tej pierwszej części zbudujesz podstawy danych. Skonfigurujesz realistyczne, „nieuporządkowane” jezioro danych w BigQuery, zastosujesz sztywne tagi metadanych (aspekty Dataplex), aby odróżnić prawidłowe dane od szumu, i użyjesz interfejsu Gemini CLI do lokalnego testowania, czy LLM ściśle przestrzega reguł zarządzania.

(Drugą część tej serii, która opisuje, jak wdrożyć ten lokalny prototyp w bezpiecznej aplikacji internetowej klasy korporacyjnej za pomocą protokołu Model Context Protocol (MCP) i Cloud Run, znajdziesz tutaj. 👉 Przeczytaj część 2)

Wymagania wstępne

• Projekt Google Cloud z włączonymi płatnościami.
• Podstawowa wiedza i znajomość usług BigQuery, Dataplex Universal Catalog i Terraform.
• Dostęp do Google Cloud Shell.

Czego się nauczysz

• wdrożyć realistyczne, wielowarstwowe jezioro danych za pomocą Terraform;
• Zaprojektuj w Dataplex ścisłe szablony metadanych (typy aspektów), aby odróżnić oficjalne dane rozumiane jako produkt od nieprzetworzonych tabel w piaskownicy.
• Przed napisaniem kodu aplikacji sprawdź lokalnie reguły zarządzania za pomocą interfejsu wiersza poleceń Gemini.

Czego potrzebujesz

• Dostęp do Google Cloud Shell
• Terraform (wstępnie zainstalowany w Cloud Shell).
• Interfejs wiersza poleceń Gemini (zainstalowany wstępnie w Cloud Shell).

Kluczowe pojęcia

• Dataplex Universal Catalog:ujednolicona usługa zarządzania metadanymi. Używamy go do wzbogacania metadanych technicznych (schematów) o kontekst biznesowy (zarządzanie).
• Typ aspektu: szablon metadanych strukturalnych. W przeciwieństwie do tagów w formie tekstu dowolnego aspekty wymuszają silne typowanie (wyliczenia, wartości logiczne), dzięki czemu są niezawodne w ocenie przez maszyny.

2. Konfiguracja i wymagania

Uruchamianie Cloud Shell

Z Google Cloud można korzystać zdalnie na laptopie, ale w tym module praktycznym będziesz używać 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łączyć interfejsy API,

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

gcloud services enable \
  artifactregistry.googleapis.com \
  bigqueryunified.googleapis.com \
  cloudaicompanion.googleapis.com \
  cloudbuild.googleapis.com \
  cloudresourcemanager.googleapis.com \
  datacatalog.googleapis.com \
  run.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

Budowanie „nieuporządkowanego” jeziora danych

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

Do wdrożenia tego środowiska użyjemy Terraform. Konfiguracja obejmuje 2 zadania:

• Infrastruktura: tworzy typy aspektów Dataplex oraz zbiory danych i tabele BigQuery.
• Wczytywanie danych: uruchamia zadania BigQuery INSERT, aby natychmiast po utworzeniu wypełnić tabele przykładowymi danymi.

1. Przejdź do katalogu terraform i go zainicjuj.

cd terraform
terraform init

2. Zastosuj konfigurację. Może to potrwać około minuty.

terraform apply -var="project_id=${PROJECT_ID}" -var="region=${REGION}" -auto-approve

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. Stosowanie 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 danych dotyczących zarządzania

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

cd ..
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 uruchomimy skrypt, przyjrzyjmy się temu, co właściwie stosujemy, 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 określa kontekst biznesowy, np. ustawia flagę is_certified na wartość „true” i przypisuje poziom GOLD_CRITICAL. Nadawanie AI jasnych, strukturalnych 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 (opcjonalnie)

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

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

3. Na stronie ze szczegółami tabeli znajdź sekcję „Opcjonalne tagi i aspekty” u dołu strony.
4. Znajdziesz tam aspekt official-data-product-spec. Sprawdź, czy wartości pasują do zastosowanego przez nas scenariusza „Gold Internal”.

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.

4. Konfigurowanie i tworzenie prototypu agenta

Zanim utworzymy aplikację internetową (co zrobimy w części 2), sprawdzimy lokalnie naszą logikę zarządzania. Musimy zainstalować rozszerzenie Dataplex i skonfigurować prompt systemowy.

Instalowanie rozszerzenia

Zainstaluj rozszerzenie Dataplex w Cloud Shell. Poprosimy Cię o potwierdzenie i podanie szczegółów konfiguracji.

export DATAPLEX_PROJECT="${PROJECT_ID}"

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

(Wpisz Y, aby zaakceptować instalację, a gdy pojawi się prośba, wpisz identyfikator projektu).

Zdefiniuj plik zasad

Plik GEMINI.md zawiera logikę, która tłumaczy abstrakcyjne reguły (np. „Potrzebuję bezpiecznych danych”) na rygorystyczne wyszukiwania techniczne.

Ten plik jest obecnie ogólny. Agent musi dokładnie wiedzieć, w którym projekcie Google Cloud ma szukać, aby nie generować tabel z publicznego internetu ani innych kontekstów.

1. Wstaw PROJECT_ID do pliku zasad.

envsubst < GEMINI.md > GEMINI.md.tmp && mv GEMINI.md.tmp GEMINI.md

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

cat GEMINI.md

Zwróć uwagę na 2 rzeczy w tym pliku:

1. Zakres projektu: sprawdź etap 2. Sprawdź, czy projectid:${PROJECT_ID} został zastąpiony rzeczywistym identyfikatorem projektu (e.g., projectid:my-lab-project). Jeśli ta zmienna nie zostanie zastąpiona, agent będzie przeszukiwać wszystkie projekty, do których masz dostęp, co może prowadzić do nieprawidłowych odpowiedzi.
2. Algorytm: zwróć uwagę na logikę fazy 1 i fazy 2. Wyraźnie instruujemy model, aby nie zgadywał kodu SQL. Najpierw musi wyszukać prawidłową definicję tagu (etap 1), a dopiero potem dane (etap 2).

Uruchom agenta i przetestuj scenariusze

Rozpocznij sesję interfejsu wiersza poleceń Gemini, tym razem wczytując zasady zarządzania jako kontekst systemowy.

gemini

Uwaga: może się zdarzyć, że załaduje się kilka plików kontekstowych (np. GEMINI.md i inne). To zupełnie normalne. Interfejs CLI wczytuje lokalny plik GEMINI.md z regułami dla tego projektu oraz domyślne instrukcje dotyczące samego rozszerzenia Dataplex.

Weryfikowanie instalacji

Wpisz /mcp desc, aby potwierdzić, że rozszerzenie Dataplex jest aktywne. Powinien być widoczny serwer MCP dataplex jako skonfigurowany serwer MCP z dostępnymi narzędziami.

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. Aby umożliwić płynne testowanie, kliknij „Zezwól na używanie narzędzia podczas tej sesji”.

• 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: zapytania fin_monthly_closing_internal, ponieważ w aspekcie semantycznie pasuje do GOLD_CRITICAL (dokładne) i INTERNAL_ONLY (posiedzenie zarządu).

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

Oczekiwana odpowiedź: agent wybiera mkt_realtime_campaign_performance, ponieważ określa ona 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 wynik: agent wybiera tmp_data_dump_v2_final_real, ponieważ w aspekcie jest on semantycznie zgodny z BRONZE_ADHOC (dane pierwotne) i is_certified: false (środowisko piaskownicy).

(Aby zakończyć sesję Gemini, wpisz /quit)

⚠️ Uwaga: wersja beta (stan na luty 2026 r.)

Dodatek Dataplex do interfejsu wiersza poleceń Gemini i jego podstawowe narzędzia MCP Toolbox są obecnie w wersji beta (przed wersją 1.0).

Jest to rozwijający się projekt open source, więc od czasu do czasu możesz napotkać nieoczekiwane zachowania, ciche przekroczenia limitu czasu (np. zwracanie wartości null) lub zmiany powodujące błędy. Google nie gwarantuje jeszcze pełnej stabilności tej usługi w przypadku zastosowań produkcyjnych.

Jeśli napotkasz problemy, które nie zostały omówione w tym samouczku, zajrzyj do oficjalnego repozytorium GitHub, aby sprawdzić najnowsze aktualizacje, otwarte problemy lub przesłać opinię.

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

Teraz osiągasz 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 MCP (Model Context Protocol) 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 potrzebne będą bieżące dane i ustawienia Dataplex.

Opcja B: zrobię część 2 później lub chciałem(-am) tylko ukończyć 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 szybkiej ścieżki”, 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 Czyszczenie.

6. Czyszczenie (tylko w przypadku opcji B)

Jeśli na tym kończysz, usuń zasoby, aby uniknąć opłat.

Usuwanie jeziora danych (Terraform)

Jeśli korzystasz obecnie ze środowiska interfejsu wiersza poleceń Gemini, zamknij sesję, naciskając dwukrotnie Ctrl+C lub wpisując /quit. Następnie uruchom te polecenia:

cd ~/devrel-demos/data-analytics/governance-context/terraform
terraform destroy -var="project_id=${PROJECT_ID}" -var="region=${REGION}" -auto-approve

Odinstalowywanie dodatku do interfejsu wiersza poleceń Gemini i usuwanie plików lokalnych

gemini extensions uninstall dataplex
cd ~
rm -rf ~/devrel-demos