1. Einführung
Modelle, die auf generativer KI basieren, sind leistungsstarke Argumentierer, aber ihnen fehlt 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 detaillierte Finanzberichte, andere sind Marketing-Schätzungen in Echtzeit und viele sind wahrscheinlich veraltete Sandboxes.
Ohne explizite Fundierung wählt ein KI-Agent eine Tabelle basierend auf der einfachen Namensähnlichkeit aus, was zu "überzeugend falschen" Antworten führt, die aus nicht überprüften Daten abgeleitet wurden.
Dieses Codelab ist Teil einer zweiteiligen Reihe, in der Sie erfahren, wie Sie einen Governance-basierten KI-Agenten erstellen.
Im ersten Teil erstellen Sie eine Datengrundlage. Sie richten einen realistischen, „unordentlichen“ Data Lake in BigQuery ein, wenden starre Metadatentags (Knowledge Catalog-Aspekte) an, um gültige Daten von Rauschen zu unterscheiden, und verwenden die Antigravity (AGY) CLI, um lokal zu testen, ob der Agent Ihre Data-Governance-Regeln strikt einhält.
Im zweiten Teil dieser Reihe erfahren Sie, wie Sie den lokalen Agentenprototyp mithilfe des Model Context Protocol (MCP) und Cloud Run in einer sicheren Webanwendung auf Enterprise-Niveau bereitstellen. 👉 Teil 2 lesen
Lerninhalte
- Einen realistischen, mehrstufigen Data Lake mithilfe eines Setupskripts bereitstellen.
- Benutzerdefinierte Metadatenvorlagen (Aspekttypen) in Knowledge Catalog entwerfen und registrieren, um offizielle Datenprodukte von rohen Sandbox-Tabellen zu unterscheiden.
- Data-Governance-Regeln lokal mit der AGY CLI überprüfen, bevor Sie Anwendungscode schreiben.
Voraussetzungen
- Google Cloud-Projekt mit aktivierter Abrechnungsfunktion.
- Zugriff auf Google Cloud Shell (die AGY CLI ist in Cloud Shell vorinstalliert).
- Grundkenntnisse in BigQuery und Knowledge Catalog.
Wichtige Konzepte
- Knowledge Catalog:Der einheitliche Dienst zur Metadatenverwaltung. Wir verwenden ihn, um technische Metadaten (Schemas) mit geschäftlichem Kontext (Governance) anzureichern.
- Aspekttyp: Eine strukturierte Metadatenvorlage. Im Gegensatz zu Tags mit freiem Text erzwingen Aspekte eine starke Typisierung (Aufzählungen, boolesche Werte), sodass sie für Maschinen zuverlässig 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, verwenden Sie in diesem Codelab Google Cloud Shell, eine Befehlszeilenumgebung, die in der Cloud ausgeführt wird.
Klicken Sie in der Google Cloud Console in der Symbolleiste rechts oben auf das Cloud Shell-Symbol:
Die Bereitstellung und Verbindung mit der Umgebung sollte nur wenige Augenblicke dauern. Wenn der Vorgang abgeschlossen ist, sollte Folgendes angezeigt werden:
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 \
bigquery.googleapis.com \
dataplex.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 erforderlichen 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
„Unordentlichen“ Data Lake erstellen
Datenumgebungen in der Praxis sind 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 ein Setupscript, um die BigQuery-Datasets und ‑Tabellen bereitzustellen.
- Machen Sie das Setupscript ausführbar und führen Sie es aus. Dadurch werden drei BigQuery-Datasets (
finance_mart,marketing_prod,analyst_sandbox) erstellt und ihre Tabellen mit Beispieldaten gefüllt.
chmod +x ./setup_bq_tables.sh
./setup_bq_tables.sh
Checkpoint: 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. Vorlage für Data-Governance erstellen (Aspekttyp)
Jetzt definieren wir einige Data-Governance-Regeln. In Knowledge Catalog erfolgt dies durch das Erstellen eines Aspekttyps, einer wiederverwendbaren, stark typisierten Metadatenvorlage.
Wir registrieren diese Vorlage mit der gcloud CLI, damit Sie sehen können, wie sie definiert ist.
Aspektschema prüfen
Geben Sie den Inhalt von aspect_template.json aus, um die Schemadefinition zu sehen.
cat aspect_template.json
Es wird die folgende JSON-Struktur angezeigt:
{
"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",
...
}
]
}
Beachten Sie, dass dieses Schema strenge Datentypen erzwingt, z. B. enum für die Kritikalitätsstufe (GOLD_CRITICAL, SILVER_STANDARD, BRONZE_ADHOC) und bool für is_certified. So bleiben die Metadaten strukturiert und maschinenlesbar.
Aspekttyp registrieren
Führen Sie den folgenden gcloud-Befehl aus, um diese Vorlage in Ihrer Knowledge Catalog-Registrierung zu registrieren.
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. Governance anwenden
Dies ist der entscheidende technische Schritt. Derzeit sehen die Tabelle finance_mart.fin_monthly_closing_internal und analyst_sandbox.tmp_data_dump_v2_final_real für ein LLM identisch aus. Es sind nur Objekte mit Spalten.
Als Governance-Engineer müssen Sie diesen Tabellen einen Aspekt (ein zertifiziertes Metadatenlabel) zuweisen, um sie zu unterscheiden. In einem echten Unternehmen würden Sie dies über CI/CD-Pipelines automatisieren. Wir simulieren diese Automatisierung mit Skripts.
Governance-Nutzlasten generieren
Knowledge Catalog-Aspektschlüssel müssen global eindeutig sein (mit Ihrer Projekt-ID präfixiert). Das Skript ./generate_payloads.sh generiert dynamisch die YAML-Metadatendateien.
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 definiert sind (Gold/Internal, Gold/Public, Silver/Realtime, Bronze/Sandbox).
Aspekte mit der CLI anwenden
Bevor wir das Skript ausführen, sehen wir uns an, was wir tatsächlich 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
Es wird der folgende Inhalt 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
Beachten Sie, dass in diesem YAML der geschäftliche Kontext explizit definiert ist, z. B. durch Festlegen des Flags is_certified: true und Zuweisen der Stufe GOLD_CRITICAL. So erhält das LLM klare, strukturierte Regeln zur Auswertung, anstatt nur anhand von Tabellennamen zu raten.
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 vor dem Fortfahren, ob die Metadaten in der Console korrekt angewendet wurden.
- Öffnen Sie in der Google Cloud Console die Seite Knowledge Catalog. Wenn Sie „Knowledge Catalog“ im linken Navigationsmenü nicht sehen, verwenden Sie die Suchleiste oben im Google Cloud Console-Fenster, geben Sie „Knowledge Catalog“ ein und wählen Sie das Ergebnis unter „Top-Ergebnisse“ oder „Produkte und Seiten“ aus.
- 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.
- Suchen Sie auf der Detailseite der Tabelle unten nach dem Abschnitt Optionale Tags und Aspekte.
- Dort finden Sie den Aspekt
official-data-product-spec. Prüfen Sie, ob die Werte mit dem angewendeten Szenario "Gold Internal" übereinstimmen.
Sie haben jetzt bestätigt, dass technisch identische BigQuery-Tabellen (fin_monthly_closing_internal und tmp_data_dump_v2_final_real) durch maschinenlesbare Metadaten logisch unterschieden werden.
5. Agenten konfigurieren und Prototyp erstellen
Bevor wir eine Anwendung erstellen (was wir in Teil 2 tun), überprüfen wir unsere Data-Governance-Logik lokal. Wir müssen das Knowledge Catalog-Plug-in installieren und die Agenten-Skill konfigurieren.
Erweiterung installieren
Installieren Sie in Cloud Shell das Knowledge Catalog-Plug-in. Sie werden zur Bestätigung und zur Eingabe Ihrer Einrichtungsinformationen aufgefordert.
export DATAPLEX_PROJECT="${PROJECT_ID}"
agy plugin install https://github.com/gemini-cli-extensions/dataplex
Agenten-Skill prüfen
Die Agenten-Skill ist eine statische, wiederverwendbare Definitionsdatei in .agents/skills/knowledge_catalog_governance/SKILL.md. Sie enthält die Logik, die abstrakte menschliche Regeln (z.B. „Ich brauche sichere Daten“) in strenge technische Suchvorgänge übersetzt.
Sehen Sie sich die Datei an, um den Algorithmus zu verstehen, den wir der KI beibringen:
cat .agents/skills/knowledge_catalog_governance/SKILL.md
Beachten Sie, dass das Modell explizit angewiesen wird, einen strengen Schleifendurchlauf in Phase 1 (Metadatenüberprüfung) und Phase 2 (Abfrageausführung) zu befolgen. Das Modell muss die Metadaten ermitteln und überprüfen, bevor es SQL-Code erstellt.
Agenten starten und Szenarien testen
Starten Sie die AGY CLI-Sitzung. Die Skill wird automatisch aus dem Verzeichnis .agents/skills ermittelt und geladen.
agy
Hinweis: Möglicherweise werden mehrere Kontextdateien geladen. Das ist normal. Die CLI lädt die lokale Skill für die spezifischen Regeln dieses Projekts sowie die Standardanweisungen für das Knowledge Catalog-Plug-in selbst.
Installation prüfen
Geben Sie /mcp ein, um zu bestätigen, dass das Knowledge Catalog-Plug-in aktiv ist. „knowledge-catalog“ sollte als aktives Plug-in mit den verfügbaren Tools aufgeführt sein.
/mcp
Erwartete Ausgabe:
MCP Servers
...
> ✓ knowledge-catalog Tools: search_entries, lookup_context, lookup_entry
Testszenarien (Prototyping)
Fügen Sie die folgenden Prompts einzeln in die laufende Agentensitzung ein, um zu prüfen, ob sie Ihren Regeln entspricht.
- 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:Der Agent ermittelt automatisch Ihr aktives Projekt und Ihre aktive Region aus seinen Tools, fragt fin_monthly_closing_internal ab, da es semantisch mit GOLD_CRITICAL (genau) und INTERNAL_ONLY (Vorstandssitzung) in seinem Aspekt übereinstimmt, und empfiehlt es.
- Szenario B (öffentliche 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 unbedingt fin_quarterly_public_report auswählen, da dies das einzige Asset ist, das mit EXTERNAL_READY getaggt ist.
- Szenario C (betriebliche Anforderungen):
"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 Updatehäufigkeit REALTIME_STREAMING erkennt und diese gegenüber der Stufe GOLD_CRITICAL der Finanzdaten priorisiert.
- Szenario D (Sandbox-Experimente):
"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 semantisch mit BRONZE_ADHOC (Rohdaten) und is_certified: false (Sandbox-Umgebung) in seinem Aspekt übereinstimmt.
(Geben Sie /exit oder /quit ein, um die AGY-Sitzung zu beenden.)
6. Das wars! Sie haben das Lab erfolgreich abgeschlossen. Nächste Schritte
Sie haben erfolgreich eine kontrollierte Datengrundlage erstellt und nachgewiesen, dass eine KI Ihre Metadatenregeln mithilfe eines lokalen CLI-Prototyps 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 mithilfe des Model Context Protocol (MCP) und Cloud Run in eine sichere Webanwendung auf Produktionsniveau umzuwandeln:
Option B: Ich werde Teil 2 später bearbeiten oder wollte nur Teil 1 abschließen.
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-Skript“ bereit, mit dem diese Umgebung aus Teil 1 in nur zwei Minuten vollständig neu erstellt wird, sodass Sie genau dort weitermachen können, wo Sie aufgehört haben.
👉 Zum Abschnitt zur Bereinigung
7. Bereinigen (nur für Option B)
Wenn Sie hier aufhören, löschen Sie die Ressourcen, um Gebühren zu vermeiden.
Data Lake löschen
Wenn Sie sich derzeit in der AGY CLI-Sitzung befinden, beenden Sie sie, indem Sie Ctrl+C zweimal drücken oder /quit eingeben. Führen Sie dann die folgenden Befehle aus:
chmod +x ./cleanup_data_lake.sh
./cleanup_data_lake.sh
AGY CLI-Plug-in deinstallieren und lokale Dateien entfernen
agy plugin uninstall dataplex
cd ~
rm -rf ~/devrel-demos