Datengrundlage mit Dataplex-Metadaten aufbauen

1. Einführung

Modelle, die auf generativer KI basieren, können zwar hervorragend Schlussfolgerungen ziehen, aber es fehlt ihnen der institutionelle Kontext. Wenn eine Führungskraft einen KI-Agenten fragt: „Wie hoch ist unser Umsatz im ersten Quartal?“, findet der Agent möglicherweise Dutzende von Tabellen mit dem Namen „Umsatz“ in Ihrem Data Lake. Einige sind strenge Finanzberichte, andere Marketing-Schätzungen in Echtzeit und viele sind wahrscheinlich eingestellte Sandboxes.

Ohne explizite Fundierung wählt ein KI-Agent eine Tabelle basierend auf einer einfachen Namensähnlichkeit aus, was zu „überzeugend falschen“ Antworten führt, die aus nicht überprüften Daten abgeleitet werden.

Dieses Codelab ist Teil einer zweiteiligen Reihe, in der es darum geht, wie Sie einen Governance-konformen GenAI-Agent erstellen.

In diesem ersten Teil erstellen Sie die Datengrundlage. Sie richten einen realistischen, „unordentlichen“ Data Lake in BigQuery ein, wenden strenge Metadatentags (Dataplex-Aspekte) an, um gültige Daten von Rauschen zu unterscheiden, und verwenden die Gemini CLI, um lokal zu testen, ob das LLM Ihre Governance-Regeln strikt einhält.

Im zweiten Teil dieser Reihe erfahren Sie, wie Sie diesen lokalen Prototyp mithilfe des Model Context Protocol (MCP) und Cloud Run in einer sicheren Webanwendung für Unternehmen bereitstellen. 👉 Teil 2 lesen)

Voraussetzungen

• Google Cloud-Projekt mit aktivierter Abrechnungsfunktion.
• Grundlegendes Verständnis und Vertrautheit mit BigQuery, Dataplex Universal Catalog und Terraform.
• Zugriff auf Google Cloud Shell

Lerninhalte

• Mit Terraform einen realistischen, mehrstufigen Data Lake bereitstellen.
• Entwerfen Sie strenge Metadatenvorlagen (Aspekttypen) in Dataplex, um offizielle Datenprodukte von Rohdaten-Sandbox-Tabellen zu unterscheiden.
• Prüfen Sie Governance-Regeln lokal mit der Gemini CLI, bevor Sie Anwendungscode schreiben.

Voraussetzungen

• Zugriff auf Google Cloud Shell
• Terraform (in Cloud Shell vorinstalliert).
• Gemini CLI (in Cloud Shell vorinstalliert)

Wichtige Konzepte

• Dataplex Universal Catalog:Der einheitliche Dienst zur Metadatenverwaltung. Wir verwenden sie, um technische Metadaten (Schemas) mit geschäftlichem Kontext (Governance) anzureichern.
• Aspekttyp:Eine Vorlage für strukturierte Metadaten. Im Gegensatz zu Tags mit Freitext erzwingen Aspekte eine starke Typisierung (Enumerationen, boolesche Werte), sodass sie zuverlässig von Maschinen ausgewertet werden können.

2. Einrichtung und Anforderungen

Cloud Shell starten

Während Sie Google Cloud von Ihrem Laptop aus per Fernzugriff nutzen können, wird in diesem Codelab Google Cloud Shell verwendet, eine Befehlszeilenumgebung, die in der Cloud ausgeführt wird.

Klicken Sie in der Google Cloud Console rechts oben in der Symbolleiste auf das Cloud Shell-Symbol:

Die Bereitstellung und Verbindung mit der Umgebung sollte nur wenige Augenblicke dauern. Anschließend sehen Sie in etwa Folgendes:

Diese virtuelle Maschine verfügt über sämtliche Entwicklertools, die Sie benötigen. Sie bietet ein Basisverzeichnis mit 5 GB nichtflüchtigem Speicher und läuft in Google Cloud, was die Netzwerkleistung und Authentifizierung erheblich verbessert. Alle Aufgaben in diesem Codelab können in einem Browser ausgeführt werden. Sie müssen nichts installieren.

Umgebung initialisieren

Öffnen Sie Cloud Shell und legen Sie Ihre Projektvariablen fest, damit alle Befehle auf die richtige Infrastruktur ausgerichtet sind.

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

APIs aktivieren

Aktivieren Sie die erforderlichen Google Cloud-Dienste, um die folgende Anleitung auszuführen.

gcloud services enable \
  artifactregistry.googleapis.com \
  bigqueryunified.googleapis.com \
  cloudaicompanion.googleapis.com \
  cloudbuild.googleapis.com \
  cloudresourcemanager.googleapis.com \
  datacatalog.googleapis.com \
  run.googleapis.com

Repository klonen

Rufen Sie den Infrastrukturcode und die Automatisierungsskripts aus dem GitHub-Repository ab. Um Speicherplatz in Cloud Shell zu sparen, laden wir nur den für dieses Lab benötigten Ordner herunter.

# 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

Data Lake mit unstrukturierten Daten erstellen

Die Umgebung für reale Daten ist selten sauber. Um die Realität zu simulieren, benötigen wir eine Mischung aus „offiziellen“ Data Marts und nicht vertrauenswürdigen „Sandbox“-Tabellen.

Wir verwenden Terraform, um diese Umgebung bereitzustellen. Die Konfiguration umfasst zwei Aufgaben:

• Infrastruktur:Erstellt Dataplex-Aspekttypen und BigQuery-Datasets/-Tabellen.
• Daten laden:Führt BigQuery-INSERT-Jobs aus, um die Tabellen unmittelbar nach der Erstellung mit Beispieldaten zu füllen.

1. Wechseln Sie zum Verzeichnis terraform und initialisieren Sie es.

cd terraform
terraform init

2. Wenden Sie die Konfiguration an. Das kann bis zu einer Minute dauern.

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

Prüfpunkt: Sie haben jetzt einen vollständig gefüllten, aber völlig unkontrollierten Data Lake. Für eine KI sieht jede Tabelle genau gleich aus.

3. Governance anwenden

Dies ist der entscheidende Entwicklungsschritt. Derzeit sehen die Tabellen finance_mart.fin_monthly_closing_internal und analyst_sandbox.tmp_data_dump_v2_final_real für ein LLM identisch aus. Es handelt sich lediglich um Objekte mit Spalten.

Als Governance Engineer müssen Sie diesen Tabellen ein Aspect (ein zertifiziertes Metadatenlabel) zuweisen, um sie zu unterscheiden. In einem echten Unternehmen würden Sie dies über CI/CD-Pipelines automatisieren. Wir werden diese Automatisierung mit Skripten simulieren.

Governance-Nutzlasten generieren

Dataplex-Aspektschlüssel müssen global eindeutig sein (mit Ihrer Projekt-ID als Präfix). Mit dem Skript ./generate_payloads.sh werden die YAML-Metadatendateien dynamisch generiert.

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

Ausgabe:

Dadurch wird ein Ordner „./aspect_payloads“ mit vier YAML-Dateien erstellt, in denen die Governance-Szenarien (Gold/Internal, Gold/Public, Silver/Realtime, Bronze/Sandbox) definiert sind.

Aspekte über die Befehlszeile anwenden

Bevor wir das Skript ausführen, sehen wir uns an, was wir eigentlich anwenden, um den Prozess zu entmystifizieren. Führen Sie den folgenden Befehl aus, um die Struktur der internen Finanznutzlast zu sehen:

cat aspect_payloads/fin_internal.yaml

Dort werden die folgenden Inhalte angezeigt.

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

In diesem YAML-Code wird der geschäftliche Kontext explizit definiert, z. B. durch Festlegen des Flags is_certified: true und Zuweisen der GOLD_CRITICAL-Stufe. Der KI werden klare, strukturierte Regeln für die Bewertung an die Hand gegeben, anstatt dass sie nur anhand von Tabellennamen Vermutungen anstellt.

Führen Sie nun das Anwendungsskript aus. Dadurch werden die BigQuery-Tabellen durchlaufen und der Befehl gcloud dataplex entries update ausgeführt, um diese starren Metadaten anzuhängen.

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

Überprüfung (optional)

Prüfen Sie, bevor Sie fortfahren, ob die Metadaten in der Konsole korrekt angewendet wurden.

1. Öffnen Sie in der Google Cloud Console die Seite Dataplex Universal Catalog. Wenn Sie „Dataplex Universal Catalog“ nicht im linken Navigationsmenü sehen, verwenden Sie die Suchleiste oben im Google Cloud Console-Fenster, geben Sie „Dataplex“ ein und wählen Sie das Ergebnis unter „Top-Ergebnisse“ oder „Produkte und Seiten“ aus.
2. Suchen Sie nach fin_monthly_closing_internal. Die BigQuery-Tabelle sollte in den Ergebnissen aufgeführt sein. Klicken Sie auf den Tabellennamen, um die Detailseite aufzurufen.

3. Suchen Sie auf der Detailseite der Tabelle unten nach dem Abschnitt Optionale Tags und Aspekte.
4. Sie finden den Aspekt official-data-product-spec. Prüfen Sie, ob die Werte mit dem von uns angewendeten Szenario Gold Internal übereinstimmen.

Sie haben nun bestätigt, dass technisch identische BigQuery-Tabellen (fin_monthly_closing_internal und tmp_data_dump_v2_final_real) durch maschinenlesbare Metadaten logisch unterschieden werden.

4. Agent konfigurieren und Prototyp erstellen

Bevor wir eine Webanwendung erstellen (was wir in Teil 2 tun werden), prüfen wir unsere Governance-Logik lokal. Wir müssen die Dataplex-Erweiterung installieren und den Systemprompt konfigurieren.

Erweiterung installieren

Installieren Sie in Cloud Shell die Dataplex-Erweiterung. Sie werden um eine Bestätigung und um Ihre Einrichtungsdetails gebeten.

export DATAPLEX_PROJECT="${PROJECT_ID}"

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

Geben Sie „Y“ ein, um die Installation zu akzeptieren, und geben Sie Ihre Projekt-ID ein, wenn Sie dazu aufgefordert werden.

Richtliniendatei definieren

Die Datei GEMINI.md enthält die Logik, die abstrakte menschliche Regeln (z.B. „Ich brauche sichere Daten“) in strenge technische Suchvorgänge umgewandelt.

Diese Datei ist derzeit generisch. Der Agent muss genau wissen, in welchem Google Cloud-Projekt er suchen soll, damit er keine Tabellen aus dem öffentlichen Internet oder anderen Kontexten halluziniert.

1. Fügen Sie Ihre PROJECT_ID in die Richtliniendatei ein.

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

2. Sehen Sie sich die Datei an, um den Algorithmus zu verstehen, den wir der KI beibringen.

cat GEMINI.md

Beachten Sie in dieser Datei zwei Dinge:

1. Projektumfang:Siehe Phase 2. Achten Sie darauf, dass projectid:${PROJECT_ID} durch Ihre tatsächliche Projekt-ID (e.g., projectid:my-lab-project) ersetzt wurde. Wenn diese Variable nicht ersetzt wird, sucht der Agent in allen Projekten, auf die Sie Zugriff haben, was zu falschen Antworten führt.
2. Der Algorithmus:Beachten Sie die Logik für Phase 1 und Phase 2. Wir weisen das Modell explizit an, KEIN SQL zu erraten. Es muss zuerst nach der richtigen Tag-Definition gesucht werden (Phase 1) und erst dann nach Daten (Phase 2).

Agent starten und Szenarien testen

Starten Sie die Gemini CLI-Sitzung. Laden Sie dieses Mal Ihre Governance-Richtlinie als Systemkontext.

gemini

Hinweis: Möglicherweise werden mehrere Kontextdateien geladen, z.B. GEMINI.md und andere). Das ist normal. Die CLI lädt die lokale GEMINI.md-Datei für die spezifischen Regeln dieses Projekts sowie die Standardanleitung für die Dataplex-Erweiterung selbst.

Installation prüfen

Geben Sie /mcp desc ein, um zu bestätigen, dass die Dataplex-Erweiterung aktiv ist. dataplex sollte als konfigurierter MCP-Server mit verfügbaren Tools aufgeführt sein.

Testszenarien (Prototyping)

Fügen Sie die folgenden Prompts einzeln in die laufende Agentsitzung ein, um zu prüfen, ob der Agent Ihre Regeln einhält.

💡 Tipp: Wenn Sie dazu aufgefordert werden, wählen Sie „2. „Tool für diese Sitzung zulassen“ aus, um reibungslose Tests zu ermöglichen.

• Szenario A (Daten des CFO zertifizieren):

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

Erwartet:Anfragen fin_monthly_closing_internal, da sie semantisch mit GOLD_CRITICAL (richtig) und INTERNAL_ONLY (Vorstandssitzung) im Aspekt übereinstimmt.

• Szenario B (Offenlegung):

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

Erwartet:Der Agent muss die monatliche interne Tabelle umgehen und fin_quarterly_public_report auswählen, da dies das einzige Asset mit dem Tag EXTERNAL_READY ist.

• Szenario C (Betriebsanforderungen):

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

Erwartet:Der Agent wählt mkt_realtime_campaign_performance aus, da er die Aktualisierungshäufigkeit REALTIME_STREAMING erkennt und diese gegenüber der GOLD_CRITICAL-Stufe der Finanzdaten priorisiert.

• Szenario D (Sandbox-Tests):

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

Erwartet:Der Agent wählt tmp_data_dump_v2_final_real aus, da es in seinem Aspekt semantisch mit BRONZE_ADHOC (Rohdaten) und is_certified: false (Sandbox-Umgebung) übereinstimmt.

(Geben Sie /quit ein, um die Gemini-Sitzung zu beenden.)

⚠️ Hinweis: Betaversion (Stand: Februar 2026)

Die Dataplex-Erweiterung für die Gemini CLI und die zugrunde liegende MCP-Toolbox befinden sich derzeit in der Betaphase (vor Version 1.0).

Da es sich um ein sich ständig weiterentwickelndes Open-Source-Projekt handelt, kann es gelegentlich zu unerwartetem Verhalten, stillen Zeitüberschreitungen (z. B. Rückgabe von null) oder Breaking Changes kommen. Google kann noch keine vollständige Stabilität für die Produktionsnutzung garantieren.

Wenn Probleme auftreten, die in diesem Codelab nicht behandelt werden, sehen Sie bitte im offiziellen GitHub-Repository nach, ob es aktuelle Updates oder offene Probleme gibt, oder geben Sie Feedback.

5. Glückwunsch! Nächste Schritte

Sie haben erfolgreich eine verwaltete Datenbasis erstellt und mit einem lokalen CLI-Prototyp nachgewiesen, dass eine KI Ihre Metadatenregeln strikt einhalten kann.

Sie haben jetzt einen Checkpoint erreicht. Wählen Sie den nächsten Schritt aus:

Option A: Ich möchte jetzt mit Teil 2 fortfahren.

Wenn Sie bereit sind, diesen lokalen Prototyp mit dem Model Context Protocol (MCP) und Cloud Run in eine sichere Webanwendung für die Produktion umzuwandeln, gehen Sie so vor:

👉 Link zum Codelab für Teil 2

⚠️ ACHTUNG:Führen Sie die Bereinigungsschritte unten nicht aus. Für Teil 2 benötigen Sie Ihre aktuellen Daten und Dataplex-Einstellungen.

Option B: Ich möchte Teil 2 später bearbeiten oder ich wollte nur Teil 1 bearbeiten.

Wenn Sie für heute aufhören und Cloud-Kosten vermeiden möchten, sollten Sie Ihre Ressourcen bereinigen.

Keine Sorge! In Teil 2 stellen wir ein „Fast-Track-Script“ bereit, mit dem Sie diese Umgebung aus Teil 1 in nur 2 Minuten vollständig neu erstellen können, damit Sie genau dort weitermachen können, wo Sie aufgehört haben.

👉 Fahren Sie mit dem Abschnitt „Bereinigen“ fort.

6. Bereinigen (nur für Option B)

Wenn Sie an dieser Stelle aufhören, müssen Sie die Ressourcen löschen, damit keine Gebühren anfallen.

Datalake löschen (Terraform)

Wenn Sie sich gerade in der Gemini CLI-Umgebung befinden, beenden Sie die Sitzung, indem Sie zweimal Ctrl+C drücken oder /quit eingeben. Führen Sie dann die folgenden Befehle aus:

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

Gemini CLI-Erweiterung deinstallieren und lokale Dateien entfernen

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