Kontexte mit der Gemini-Befehlszeile erstellen

MySQL   |  PostgreSQL   |  SQL Server

Vorschau : Daten-Agents

Diese Funktion unterliegt den Bedingungen für Pre‑GA-Angebote im Abschnitt „Allgemeine Dienstbedingungen“ der dienstspezifischen Nutzungsbedingungen und den Zusatzbedingungen für Vorschauprodukte auf Basis von generativer KI. Pre-GA‑Funktionen stehen in der vorliegenden Form zur Verfügung und bieten möglicherweise nur eingeschränkten Support. Weitere Informationen finden Sie in den Beschreibungen der Produkteinführungsphasen.

Informationen zum Zugriff auf diesen Release finden Sie auf der Seite Zugriffs anforderung.

In diesem Dokument wird beschrieben, wie Sie mit der Gemini CLI und der MCP-Toolbox Agent-Kontextdateien erstellen. Diese Dateien enthalten Vorlagen und Facetten, die Kontext für das Generieren von SQL-Abfragen aus natürlicher Sprache liefern. Sie verwenden auch den MCP-Server zur DB-Kontextanreicherung.

Weitere Informationen zu Daten-Agents finden Sie unter Übersicht über Daten-Agents.

So erstellen Sie eine Agent-Kontextdatei:

• Umgebung vorbereiten
• Zielgerichtete Vorlagen generieren
• Zielgerichtete Facetten generieren
• Optional. Bulk-Vorlagen generieren

Hinweis

Erfüllen Sie die folgenden Voraussetzungen, bevor Sie einen Agent erstellen.

Erforderliche Dienste aktivieren

Aktivieren Sie die folgenden Dienste für Ihr Projekt:

• Gemini Data Analytics API
• Gemini für die Google Cloud API

Cloud SQL-Instanz vorbereiten

Prüfen Sie, ob Sie Zugriff auf eine vorhandene Cloud SQL-Instanz haben, oder erstellen Sie eine neue. Weitere Informationen finden Sie unter Instanzen für Cloud SQL erstellen.

Erforderliche Rollen und Berechtigungen

• Fügen Sie der Instanz einen IAM-Nutzer oder ein Dienstkonto hinzu. Weitere Informationen finden Sie unter Nutzer mit IAM-Datenbankauthentifizierung für Cloud SQL verwalten.
• Weisen Sie dem IAM-Nutzer auf Projektebene die Rollen cloudsql.studioUser und cloudsql.instanceUser zu. Weitere Informationen finden Sie unter IAM-Richtlinienbindung für ein Projekt hinzufügen.
• Sie müssen einem IAM-Nutzer oder Dienstkonto auch Datenbankberechtigungen gewähren, indem Sie sich als Nutzer postgres anmelden.
  
  GRANT ALL ON SCHEMA public TO public;.
  
  Weitere Informationen finden Sie unter Datenbankberechtigungen für einen einzelnen IAM-Nutzer oder ein einzelnes Dienstkonto gewähren.

Berechtigung executesql für Cloud SQL-Instanz gewähren

Führen Sie den folgenden Befehl aus, um der Cloud SQL-Instanz die Berechtigung executesql zu gewähren und die Cloud SQL Data API zu aktivieren:

gcloud components update
gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API

Ersetzen Sie INSTANCE_ID durch die ID Ihrer Cloud SQL-Instanz.

Melden Sie sich an, um die Schritte in dieser Anleitung auszuführen, und authentifizieren Sie sich dann mit der IAM-Authentifizierung bei der Datenbank.Google Cloud

Umgebung vorbereiten

Sie können Agent-Kontextdateien in jeder lokalen Entwicklungsumgebung oder IDE erstellen. Führen Sie die folgenden Schritte aus, um die Umgebung vorzubereiten:

• Gemini CLI installieren
• MCP-Toolbox installieren und einrichten
• MCP-Server zur DB-Kontextanreicherung installieren und einrichten

Gemini CLI installieren

Informationen zum Installieren der Gemini CLI finden Sie unter Erste Schritte mit der Gemini CLI. Installieren Sie die Gemini CLI in einem separaten Verzeichnis, das auch zum Installieren der MCP-Toolbox und des MCP-Servers zur DB-Kontextanreicherung verwendet wird.

MCP-Toolbox installieren und einrichten

1. Installieren Sie im selben Verzeichnis, in dem Sie die Gemini CLI installiert haben, die Gemini CLI-Erweiterung für die MCP-Toolbox:

   gemini extensions install https://github.com/gemini-cli-extensions/mcp-toolbox

2. Erstellen Sie im selben Verzeichnis, in dem Sie die MCP-Toolbox installiert haben, eine Konfigurationsdatei tools.yaml, um die Datenbankverbindung zu konfigurieren:

     sources:
       my-cloud-sql-pg-source:
         kind: cloud-sql-postgres
         project: PROJECT_ID
         region: REGION_ID
         instance: INSTANCE_ID
         database: DATABASE_ID
         user: USER_NAME
         password: PASSWORD
   

   Ersetzen Sie Folgendes:

   • PROJECT_ID: Ihre Google Cloud Projekt-ID
   • REGION_ID: Die Region Ihrer Cloud SQL-Instanz, z. B. us-central1
   • INSTANCE_ID: Die ID Ihrer Cloud SQL-Instanz
   • DATABASE_ID: Der Name der Datenbank, zu der eine Verbindung hergestellt werden soll
   • USER_NAME: Der Datenbanknutzer Weitere Informationen zum Festlegen dieses Werts finden Sie unter Quellen in der MCP-Toolbox.
   • PASSWORD: Das Passwort für den Datenbanknutzer Weitere Informationen zum Festlegen dieses Werts finden Sie unter Quellen in der MCP-Toolbox.

3. Prüfen Sie, ob die Datei tools.yaml richtig konfiguriert ist:

   ./toolbox --tools-file "tools.yaml"

MCP-Server zur DB-Kontextanreicherung installieren

Der MCP-Server zur DB-Kontextanreicherung bietet einen geführten, interaktiven Workflow zum Generieren strukturierter NL2SQL-Vorlagen aus Ihren Datenbankschemas. Er basiert auf der MCP-Toolbox-Erweiterung für die Datenbankverbindung. Weitere Informationen zum Installieren des MCP-Servers zur DB-Kontextanreicherung finden Sie unter MCP-Server zur DB-Kontextanreicherung.

So installieren Sie den MCP-Server zur DB-Kontextanreicherung:

1. Installieren Sie im selben Verzeichnis, in dem Sie die Gemini CLI installiert haben, den Python-Paketinstaller uv mit pip.

   pip install uv

   Wenn pip nicht installiert ist, installieren Sie es zuerst.

2. Installieren Sie den MCP-Server zur DB-Kontextanreicherung.

   gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment

Der Server verwendet die Gemini API für die Generierung. Exportieren Sie Ihren API-Schlüssel als Umgebungsvariable. Weitere Informationen zum Abrufen Ihres API-Schlüssels finden Sie unter Gemini API-Schlüssel verwenden.

Gemini API-Schlüssel exportieren:

export GEMINI_API_KEY="YOUR_API_KEY"

Ersetzen Sie YOUR_API_KEY durch Ihren Gemini API-Schlüssel.

Zielgerichtete Vorlagen generieren

Wenn Sie dem Agent-Kontext ein bestimmtes Abfragepaar als Abfragevorlage hinzufügen möchten, können Sie den Befehl /generate_targeted_templates verwenden. Weitere Informationen zu Vorlagen finden Sie unter Übersicht über Daten-Agents.

So fügen Sie dem Agent-Kontext eine Abfragevorlage hinzu:

1. Starten Sie Gemini im selben Verzeichnis, in dem Sie die Gemini CLI installiert haben:

   gemini

2. Führen Sie die Einrichtung der Gemini CLI-Authentifizierung aus.

3. Prüfen Sie, ob die MCP-Toolbox und die Erweiterung zur Datenbankanreicherung einsatzbereit sind:

   /mcp list

4. Führen Sie den Befehl /generate_targeted_templates aus:

   /generate_targeted_templates

5. Geben Sie die Abfrage in natürlicher Sprache ein, die Sie der Abfragevorlage hinzufügen möchten.

6. Geben Sie die entsprechende SQL-Abfrage in die Abfragevorlage ein.

7. Prüfen Sie die generierte Abfragevorlage. Sie können die Abfragevorlage entweder als Agent-Kontextdatei speichern oder an eine vorhandene Kontextdatei anhängen.

Die Agent-Kontextdatei, ähnlich my-cluster-psc-primary_postgres_templates_20251104111122.json, wird in dem Verzeichnis gespeichert, in dem Sie die Befehle ausgeführt haben.

Weitere Informationen zur Kontextdatei und zur Abfragevorlage finden Sie unter Agent-Kontext.

Zielgerichtete Facetten generieren

Wenn Sie der Agent-Kontextdatei ein bestimmtes Abfragepaar als Facette hinzufügen möchten, können Sie den Befehl /generate_targeted_facets verwenden. Weitere Informationen zu Facetten finden Sie unter Übersicht über Daten-Agents.

So fügen Sie dem Agent-Kontext eine Facette hinzu:

1. Führen Sie den Befehl /generate_targeted_facets aus:

   /generate_targeted_facets

2. Geben Sie die Abfrage in natürlicher Sprache ein, die Sie der Abfragevorlage hinzufügen möchten.

3. Geben Sie die entsprechende SQL-Abfrage in die Abfragevorlage ein.

4. Prüfen Sie die generierte Facette. Sie können die Facette entweder in einer Agent-Kontextdatei speichern oder an eine vorhandene Kontextdatei anhängen.

Die Agent-Kontextdatei, ähnlich my-cluster-psc-primary_postgres_templates_20251104111122.json, wird in dem Verzeichnis gespeichert, in dem Sie die Befehle ausgeführt haben.

Weitere Informationen zur Kontextdatei und zu Facetten finden Sie unter Agent-Kontext.

Optional: Bulk-Vorlagen generieren

Wenn Sie die Agent-Kontextdatei automatisch anhand Ihres Datenbankschemas und Ihrer Daten generieren möchten, können Sie den Befehl /generate_bulk_templates verwenden.

So generieren Sie Bulk-Vorlagen automatisch:

1. Führen Sie den Befehl /generate_bulk_templates aus:

   /generate_bulk_templates

2. Basierend auf Ihrem Datenbankschema werden Sie bei der vorlagenbasierten SQL-Generierung durch eine Reihe von Fragen geführt, in denen Sie die Datenbankinformationen bestätigen und Berechtigungen für den Zugriff auf das Datenbankschema gewähren.

3. Prüfen Sie die generierte Abfragevorlage. Sie können die Vorlage entweder genehmigen oder ein Abfragepaar aktualisieren, das Sie überarbeiten möchten.

4. Geben Sie die Abfrage in natürlicher Sprache ein, die Sie der Abfragevorlage hinzufügen möchten.

5. Geben Sie die entsprechende SQL-Abfrage in die Abfragevorlage ein.

6. Prüfen Sie die generierte Abfragevorlage. Sie können die Abfragevorlage entweder als Agent-Kontextdatei speichern oder an eine vorhandene Kontextdatei anhängen.

7. Nachdem Sie die Abfragevorlage genehmigt haben, können Sie entweder eine neue Vorlagendatei erstellen oder die Abfragepaare an eine vorhandene Vorlagendatei anhängen. Die Abfragevorlage wird als JSON-Datei in Ihrem lokalen Verzeichnis gespeichert.

Die Agent-Kontextdatei, ähnlich my-cluster-psc-primary_postgres_templates_20251104111122.json, wird in dem Verzeichnis gespeichert, in dem Sie die Befehle ausgeführt haben.

Weitere Informationen zur Agent-Kontextdatei finden Sie unter Agent-Kontext.

Nächste Schritte

• Weitere Informationen zu Daten-Agents.
• Informationen zum Erstellen oder Löschen eines Daten-Agents in Cloud SQL Studio
• Informationen zum Prüfen und Aufrufen eines Daten-Agents.