Kontextsets mit der Gemini CLI erstellen

In diesem Dokument wird beschrieben, wie Sie mit der Gemini CLI und der MCP-Toolbox Kontextdateien für Agents erstellen. Diese Dateien enthalten Vorlagen, Facetten und Wertesuchen, die Kontext für das Generieren von SQL-Abfragen aus natürlicher Sprache liefern. Außerdem verwenden Sie die Erweiterung zur Anreicherung des DB-Kontexts.

Weitere Informationen zu Kontextmengen finden Sie in der Übersicht zu Kontextmengen.

So erstellen Sie eine Kontextdatei für einen Agent:

  • Umgebung vorbereiten
  • Gezielte Vorlagen generieren
  • Gezielte Facetten generieren
  • Gezielte Wertesuchen 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:

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.
  • Erstellen Sie in Ihrer Instanz eine Datenbank, in der Sie die Tabellen erstellen. Weitere Informationen finden Sie unter Datenbank auf der Cloud SQL-Instanz erstellen.

Erforderliche Rollen und Berechtigungen

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 config set project PROJECT_ID
gcloud components update
gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API
Ersetzen Sie Folgendes:
  • PROJECT_ID: Die ID Ihres Google Cloud Projekts.
  • INSTANCE_ID: 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

Datenbank für Wertesuchen vorbereiten

Wenn Sie semantische und Trigramm-Wertesuchen verwenden möchten, müssen Sie Ihre Cloud SQL for MySQL-Instanz so konfigurieren, dass sie Vektoreinbettungen und die N‑Gramm-Indexierung unterstützt.

  1. Damit die Cloud SQL for MySQL-Instanz semantische Wertesuchen durchführen kann, müssen Sie die folgenden Flags aktivieren.

    1. Aktivieren Sie das Flag cloudsql_vector.

      gcloud sql instances patch INSTANCE_NAME --database-flags=cloudsql_vector=on

    2. Aktivieren Sie das Flag enable-google-ml-integration, damit die Cloud SQL for MySQL-Instanz in Vertex AI eingebunden werden kann.

      gcloud sql instances patch INSTANCE_NAME --enable-google-ml-integration

    3. Erstellen Sie eine Vektorspalte zum Speichern von Einbettungen für Städte.

      ALTER TABLE `airports` 
ADD COLUMN `city_embedding` VECTOR(768);

    4. Generieren und speichern Sie Vektoreinbettungen für Städtenamen.

      UPDATE `airports` 
SET `city_embedding` = mysql.ml_embedding('text-embedding-005', `city`) 
WHERE `city` IS NOT NULL;

  2. Führen Sie die folgenden Schritte aus, um die Cloud SQL for MySQL-Instanz für Trigramm-Wertesuchen zu aktivieren.

    1. Aktivieren Sie das Flag ngram_token_size.

      gcloud sql instances patch INSTANCE_NAME --database-flags=ngram_token_size=3

    2. Erstellen Sie einen FULLTEXT-Index für den Flughafennamen, um Trigramme zu vergleichen.

      CREATE FULLTEXT INDEX `idx_ngram_airports_name` 
ON `airports`(`name`) 
WITH PARSER ngram;

Umgebung vorbereiten

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

  • Gemini CLI installieren
  • Erweiterung zur Anreicherung des DB-Kontexts installieren
  • Datenbankverbindung einrichten

Gemini CLI installieren

Informationen zum Installieren der Gemini CLI finden Sie unter Erste Schritte mit der Gemini CLI.

MCP-Erweiterung zur Anreicherung des DB-Kontexts installieren

Die Erweiterung zur Anreicherung des DB-Kontexts bietet einen geführten, interaktiven Workflow zum Generieren von strukturiertem NL2SQL-Kontext aus Ihren Datenbankschemas.

Weitere Informationen zum Installieren der Erweiterung zur Anreicherung des DB-Kontexts finden Sie unter Erweiterung zur Anreicherung des DB-Kontexts.

So installieren Sie die Erweiterung zur Anreicherung des DB-Kontexts:

  1. Installieren Sie die Gemini CLI-Erweiterung zur Anreicherung des DB-Kontexts:

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

  2. Optional: Aktualisieren Sie die Erweiterung zur Anreicherung des DB-Kontexts.

    Führen Sie den folgenden Befehl aus, um die installierte Version der Erweiterung zu prüfen:

    gemini extensions list

    Die Version muss 0.4.2 oder höher sein. Führen Sie den folgenden Befehl aus, um die Erweiterung zur Anreicherung des DB-Kontexts zu aktualisieren:

      gemini extensions update mcp-db-context-enrichment

    Führen Sie den folgenden Befehl aus, um die Erweiterung zur Anreicherung des DB-Kontexts zu aktualisieren oder den GEMINI_API_KEY zu ersetzen:

    gemini extensions config mcp-db-context-enrichment GEMINI_API_KEY

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

Datenbankverbindung einrichten

Für die Erweiterung ist eine Datenbankverbindung für die Kontextgenerierung erforderlich, um Schemas abzurufen und SQL-Anweisungen auszuführen. Damit die Erweiterung mit Ihrer Datenbank interagieren kann, müssen Sie Authentifizierungsanmeldedaten konfigurieren und Ihre Datenbankquellen und ‑tools definieren.

Standardanmeldedaten für Anwendungen konfigurieren

Sie müssen Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) konfigurieren, um Anmeldedaten für zwei Hauptkomponenten bereitzustellen:

  • Toolbox-MCP-Server: verwendet Anmeldedaten, um eine Verbindung zu Ihrer Datenbank herzustellen, Schemas abzurufen und SQL zur Validierung auszuführen.
  • Erweiterung zur Anreicherung des DB-Kontexts: verwendet Anmeldedaten zur Authentifizierung und zum Aufrufen der Gemini API.

Führen Sie die folgenden Befehle in Ihrem Terminal aus, um sich zu authentifizieren:

gcloud auth application-default login

Datei tools.yaml konfigurieren

Für die Erweiterung ist eine Datenbankverbindung für die Kontextgenerierung erforderlich, die von der MCP-Toolbox unterstützt und in der Konfigurationsdatei „tools.yaml“ definiert wird.

In der Datei tools.yaml werden Ihre Datenbankquelle und die Tools angegeben, die zum Abrufen von Schemas oder zum Ausführen von SQL erforderlich sind. Die Erweiterung enthält vorinstallierte Agent-Skills, mit denen Sie die Konfiguration generieren können.

  1. Starten Sie die Gemini CLI:

    gemini

  2. Prüfen Sie, ob die Skills aktiv sind, indem Sie Folgendes in die Gemini CLI eingeben: 

    /skills

  3. Geben Sie eine Eingabeaufforderung wie help me setup the database connection ein. Der Skill führt Sie durch die Erstellung der Datei tools.yaml in Ihrem aktuellen Arbeitsverzeichnis.

  4. Führen Sie den folgenden Befehl in der Gemini CLI aus, um die Konfiguration tools.yaml auf den Toolbox-MCP-Server anzuwenden:

    /mcp reload

Weitere Informationen zum manuellen Konfigurieren der Datei tools.yaml finden Sie unter MCP-Toolbox-Konfiguration.

Kontext generieren

Mit den zuvor installierten Erweiterungen kann die Gemini CLI Sie beim Erstellen von Kontext in Form einer JSON-Datei unterstützen.

Gezielte Vorlagen generieren

Wenn Sie ein bestimmtes Abfragepaar als Abfragevorlage zur Kontextmenge hinzufügen möchten, können Sie den Befehl /generate_targeted_templates verwenden. Weitere Informationen zu Vorlagen finden Sie in der Übersicht zu Kontextmengen.

So fügen Sie der Kontextmenge eine Abfragevorlage hinzu:

  1. Starten Sie die Gemini CLI im selben Verzeichnis:

    gemini

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

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

    /mcp reload

  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 für die Abfragevorlage ein.

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

Die Kontextmengendatei ä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 Kontextmengendatei und zur Abfragevorlage finden Sie in der Übersicht zu Kontextmengen.

Gezielte Facetten generieren

Wenn Sie ein bestimmtes Abfragepaar als Facette zur Kontextmengendatei hinzufügen möchten, können Sie den Befehl /generate_targeted_facets verwenden.

So fügen Sie der Kontextmengendatei 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 für die Abfragevorlage ein.

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

Die Kontextmengendatei ä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 Kontextmengendatei und zu Facetten finden Sie in der Übersicht zu Kontextmengen.

Abfragen für die Wertesuche generieren

Wenn Sie Wertesuchen generieren möchten, die angeben, wie das System nach bestimmten Werten innerhalb eines Konzepttyps suchen und diese abgleichen soll, können Sie den Befehl /generate_targeted_value_searches verwenden.

Führen Sie die Schritte unter Datenbank für Wertesuchen vorbereiten aus.

So generieren Sie einen Werteindex:

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

    /generate_targeted_value_searches
  1. Geben Sie mysql ein, um MySQL als Datenbankmodul auszuwählen. Wählen Sie „default“ aus, um MySQL 8.0 auszuwählen.

  1. Geben Sie die Konfiguration für die Wertesuche so ein:

    Table name: TABLE_NAME
Column name: COLUMN_NAME
Concept type: CONCEPT_TYPE
Match function: MATCH_FUNCTION
Description: DESCRIPTION

    Ersetzen Sie Folgendes:

  2. Fügen Sie bei Bedarf weitere Wertesuchen hinzu. Wenn Sie keine zusätzlichen Werteindizes hinzufügen, wird mit der vorlagenbasierten SQL-Generierung der nächste Schritt ausgeführt.

  3. Prüfen Sie die generierten Wertesuchen. Sie können die Kontextmenge entweder als Kontextmengendatei speichern oder an eine vorhandene Kontextmengendatei anhängen.

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

Weitere Informationen zum Werteindex finden Sie in der Übersicht zu Kontextmengen.

Optional: Bulk-Vorlagen generieren

Wenn Sie die Kontextmengendatei automatisch basierend auf Ihrem Datenbankschema und Ihren 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 führt Sie die vorlagenbasierte SQL-Generierung durch eine Reihe von Fragen zur Überprüfung der Datenbankinformationen und zum Gewähren von Berechtigungen für den Zugriff auf das Datenbankschema.

  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 für die Abfragevorlage ein.

  6. Prüfen Sie die generierte Abfragevorlage. Sie können die Abfragevorlage entweder als Kontextmengendatei speichern oder an eine vorhandene Kontextmengendatei 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 Kontextmengendatei ä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 Kontextmengendatei finden Sie in der Übersicht zu Kontextmengen.

Nächste Schritte