Gemini CLI-Agent zum Testen des Datenkontexts verwenden

KI-Agents können Schlussfolgerungen ziehen, aber sie haben kein Wissen über Ihr Unternehmen. Stellen Sie sich vor, Sie fragen einen Agenten: „Wie hoch ist unser Umsatz im ersten Quartal?“ Ohne Anleitung wählt der Agent möglicherweise aus Dutzenden von Tabellen mit dem Namen „Umsatz“ in Ihren Datenbanken aus, von offiziellen Berichten bis hin zu unübersichtlichen Testdaten. Wenn der Agent die Tabelle mit dem ähnlichsten Namen auswählt, kann er überzeugend falsche Antworten auf der Grundlage nicht überprüfter Quellen zurückgeben.

Die Metadatenanreicherung ist die Lösung für dieses Kontextproblem. In dieser Anleitung richten Sie Aspekte ein, die diesen Kontext bereitstellen, und verwenden die Gemini CLI, um den Datenkontext zu testen und zu prüfen, ob ein Agent seine Antworten genau auf vertrauenswürdigen, zertifizierten Daten begründen kann.

Ziele

• Erstellen Sie einen realistischen Data Lake für Tests.
• Verwenden Sie Knowledge Catalog Aspekte, um Ihre „Gold“-Daten zu kennzeichnen und sie von Testdaten zu unterscheiden.
• Testen Sie Ihren Datenkontext lokal mit der Gemini CLI.

Hinweis

Bevor Sie beginnen, führen Sie die folgenden Schritte aus:

• Wählen Sie ein Google Cloud Projekt für diese Anleitung aus.
• Prüfen Sie, ob die Abrechnung aktiviert ist für Ihr Projekt.

Um diese Anleitung abzuschließen, sollten Sie außerdem grundlegende Kenntnisse in BigQuery, Knowledge Catalog und Terraform haben.

Umgebung vorbereiten

In dieser Anleitung wird Google Cloud Shell verwendet, eine Befehlszeilenumgebung, die in der Cloud ausgeführt wird.

1. Klicken Sie in der Google Cloud Console in der Symbolleiste rechts oben auf Cloud Shell aktivieren. Die Bereitstellung und Verbindung mit der Umgebung dauert einen kleinen Moment.

2. Legen Sie in Cloud Shell die Variablen PROJECT_ID und REGION fest, damit alle zukünftigen Befehle auf Ihr spezifisches Google Cloud Projekt ausgerichtet sind.

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

3. Aktivieren Sie die erforderlichen Google Cloud Dienste.

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

4. Klonen Sie das Google Cloud DevRel Demos-Repository.

   Laden Sie den Infrastrukturcode und die Skripts von GitHub herunter. Verwenden Sie eine Sparse-Auscheckung, um nur den Ordner abzurufen, den Sie für diese Anleitung benötigen.

   # 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 you need for this tutorial
   git sparse-checkout set data-analytics/governance-context
   cd data-analytics/governance-context
   

Data Lake erstellen

Um die Dinge realistisch zu gestalten, benötigen Sie eine Mischung aus offiziellen Daten und unzuverlässigen, unübersichtlichen Daten. Verwenden Sie Terraform und die vorkonfigurierten Terraform-Konfigurationsdateien aus dem Tutorial-Repository, um dies schnell einzurichten.

Die Terraform-Konfiguration umfasst zwei Aufgaben:

• Richtet die Knowledge Catalog-Aspekttypen (Metadatenvorlagen), die BigQuery-Datasets und ‑Tabellen ein, einschließlich finance_mart.fin_monthly_closing_internal und analyst_sandbox.tmp_data_dump_v2_final_real.
• Lädt Beispieldaten in die Tabellen.

1. Öffnen Sie das 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
   

Sie haben jetzt einen nicht verwalteten Data Lake. Für einen KI-Agenten sehen die Tabellen in Ihrem Data Lake genau gleich aus, da sie nur Objekte mit Spalten sind. Um dieses Problem zu beheben, müssen Sie im nächsten Schritt Governance anwenden.

Governance anwenden

Dies ist der wichtigste Teil der Einrichtung. Im Moment sehen Ihre beiden Tabellen für einen KI-Agenten identisch aus. Um sie zu unterscheiden, wenden Sie Aspekte an. Das sind wie zertifizierte Metadatenlabels, die dem Agenten den benötigten Kontext liefern. In diesem Abschnitt verwenden Sie zwei Skripts: eines zum Generieren der Metadaten und ein weiteres zum Anwenden auf Ihre Tabellen.

Governance-Nutzlasten generieren

Terraform hat die Aspekttypen bereits eingerichtet. Jetzt müssen Sie die Daten generieren, um sie zu füllen.

Führen Sie das Skript ./generate_payloads.sh aus, um ein Verzeichnis aspect_payloads/ zu erstellen. Das Verzeichnis enthält vier YAML-Dateien, die verschiedene Governance-Szenarien definieren, die Sie im nächsten Schritt anwenden.

Kehren Sie zum Stammverzeichnis des Tutorial-Verzeichnisses zurück und führen Sie das Skript ./generate_payloads.sh aus:

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

Aspekte anwenden

1. Bevor Sie das Skript apply_governance.sh ausführen, sehen Sie sich die Daten an, die an Ihre Tabellen angehängt werden. Führen Sie den folgenden Befehl aus, um die für Ihre internen Finanzdaten definierten Metadaten zu sehen:

   cat aspect_payloads/fin_internal.yaml
   

   Die YAML-Datei definiert den geschäftlichen Kontext für die Tabelle:

   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 die Daten explizit als is_certified: true gekennzeichnet und der Stufe GOLD_CRITICAL zugewiesen sind. Dadurch erhält der KI-Agent klare, strukturierte Regeln, die er befolgen muss.

2. Führen Sie das Skript apply_governance.sh aus. Dieses Skript durchläuft Ihre BigQuery-Tabellen und verwendet die gcloud CLI, um die Metadaten aus Ihren YAML-Nutzlasten auf jede Tabelle zu „stempeln“.

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

Metadaten überprüfen

Bevor Sie fortfahren, prüfen Sie, ob das Skript die Aspekte korrekt angewendet hat.

1. Öffnen Sie in der Google Cloud Console die Seite Knowledge Catalog. Sie können die Suchleiste oben verwenden, um sie zu finden.
2. Suchen Sie nach fin_monthly_closing_internal. Wählen Sie in den Ergebnissen den Tabellennamen aus, um die Detailseite zu öffnen.
3. Suchen Sie im Abschnitt Optionale Tags und Aspekte nach dem Aspekt official-data-product-spec. Prüfen Sie, ob die Werte mit dem angewendeten Szenario „Gold Internal“ übereinstimmen.

Sie haben jetzt Metadaten verwendet, um diese Tabellen zu unterscheiden, und Ihrem KI-Agenten eine Möglichkeit gegeben, dasselbe zu tun.

Datenkontext mit der Gemini CLI testen

Bevor Sie eine vollständige Webanwendung erstellen, können Sie Ihre Governance-Logik lokal mit einer Model Context Protocol-Umgebung (MCP) testen. In dieser Konfiguration fungiert die Gemini CLI als Client (die Schnittstelle, mit der Sie kommunizieren) und die Knowledge Catalog-Erweiterung als lokaler Server.

Knowledge Catalog-Erweiterung installieren

Installieren Sie in Cloud Shell die Knowledge Catalog-Erweiterung.

export DATAPLEX_PROJECT="${PROJECT_ID}"

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

Regeln definieren

Die Konfigurationsdatei GEMINI.md enthält Logik, die deklarative Regeln wie „Ich benötige sichere Daten“ in präzise Suchanfragen umwandelt, die nur Tabellen mit den richtigen Governance-Labels zurückgeben.

Im Moment ist die Konfigurationsdatei nur eine Vorlage. Sie müssen Ihre spezifische Google Cloud Projekt-ID zu den Regeln hinzufügen, damit die CLI beim Ausführen korrekt auf Ihre verwalteten Daten ausgerichtet ist.

1. Fügen Sie der Konfigurationsdatei Ihre PROJECT_ID hinzu.

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

2. Sehen Sie sich die Datei GEMINI.md an, um Ihre Änderungen zu prüfen und zu verstehen, wie der Datenkontext funktioniert:

   cat GEMINI.md
   

   Beachten Sie, dass die Regeln in der Datei in Phase 1 und Phase 2 unterteilt sind. Dadurch wird eine strenge Reihenfolge der Vorgänge erzwungen. Der Agent muss zuerst nach den richtigen Governance-Labels suchen (Phase 1), bevor er die Daten selbst bearbeiten darf (Phase 2). Diese „Zuerst suchen“-Logik verhindert, dass der Agent Tabellennamen errät oder Antworten aus nicht überprüften Quellen halluziniert.

   Prüfen Sie, ob Phase 2 Ihre tatsächliche Google Cloud Projekt-ID enthält. Wenn dies nicht der Fall ist, weiß der Agent nicht, wo er nach Ihren Daten suchen soll.

Gemini CLI starten und Szenarien testen

Starten Sie eine neue Gemini-Sitzung. Da Sie sich im Projektordner befinden, erkennt und lädt die CLI automatisch die lokale GEMINI.md 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 für die spezifischen Regeln dieses Projekts sowie die Standardanweisungen für die Knowledge Catalog-Erweiterung selbst.

Installation prüfen

Prüfen Sie, ob die Knowledge Catalog-Erweiterung aktiv ist. dataplex sollte in der Liste der konfigurierten MCP-Servertools angezeigt werden.

/mcp desc

Testen

Jetzt ist es an der Zeit, Ihren Datenkontext in Aktion zu sehen. Fügen Sie diese Prompts einzeln in die CLI ein.

Tipp: Die CLI fragt nach der Berechtigung zur Verwendung ihrer Tools. Wählen Sie "2. Tool für diese Sitzung zulassen aus, damit Sie nicht jeden einzelnen Schritt genehmigen müssen.

Szenario 1: „Gold“-Standarddaten finden

Prüfen Sie, ob die Gemini CLI die vertrauenswürdigsten Daten für eine wichtige Vorstandssitzung finden kann.

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?

Die CLI sollte die Rohdaten überspringen und fin_monthly_closing_internal finden. Dazu gleicht sie Ihre Anfrage nach „abgeschlossenen“ und „vertraulichen“ Daten mit den Tags GOLD_CRITICAL und INTERNAL_ONLY ab, die Sie zuvor angewendet haben.

Szenario 2: Öffentliche Offenlegung

Angenommen, Sie möchten Daten extern freigeben. Sie möchten sicherstellen, dass die CLI keine internen Geheimnisse preisgibt.

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?

Obwohl die interne Tabelle die meisten Details enthält, muss die CLI sie umgehen. Sie sollte Sie auf fin_quarterly_public_report verweisen, da dies die einzige Tabelle ist, die als EXTERNAL_READY gekennzeichnet ist.

Szenario 3: Betriebsbezogene Anforderungen in Echtzeit

Data Scientists benötigen oft die neuesten Informationen. Prüfen Sie, ob die Gemini CLI den Unterschied zwischen einem täglichen Batch und einem Livestream versteht.

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?

Die CLI sollte mkt_realtime_campaign_performance finden. Sie erkennt die Updatehäufigkeit REALTIME_STREAMING in den Metadaten.

Szenario 4: Sandbox-Erkundung

Manchmal ist „gut genug“ besser als „perfekt“. Prüfen Sie, ob die Gemini CLI die Rohdaten der Sandbox für einige experimentelle ML-Aufgaben finden kann.

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.

Die CLI sollte tmp_data_dump_v2_final_real finden. Sie weiß, dass dies die richtige Wahl ist, da sie der Stufe BRONZE_ADHOC entspricht und explizit mit is_certified: false gekennzeichnet ist.

Wenn Sie mit dem Testen fertig sind, können Sie die CLI-Sitzung beenden:

/quit

Bereinigen

Führen Sie die folgenden Schritte aus, um wiederkehrende Kosten zu vermeiden:

1. Löschen Sie die Terraform-Ressourcen.

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

2. Deinstallieren Sie die Knowledge Catalog-Erweiterung und entfernen Sie Ihre lokalen Demodateien.

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

Fazit

Sie haben eine solide Datengrundlage geschaffen, strengen Kontext mithilfe von Metadaten angewendet und mit der Gemini CLI geprüft, ob alles lokal funktioniert.