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. Sie verwenden auch die Erweiterung „DB Context Enrichment“.

Weitere Informationen zu Kontextgruppen finden Sie unter Kontextgruppen.

So erstellen Sie eine Agent-Kontextdatei:

  • Umgebung vorbereiten
  • Zielgerichtete Vorlagen generieren
  • Zielgerichtete 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

Erforderliche Rollen und Berechtigungen

executesql-Berechtigung 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 Google Cloud und authentifizieren Sie sich dann mit der IAM-Authentifizierung bei der Datenbank.

Datenbank für die Wertsuche vorbereiten

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

  1. Damit die Cloud SQL for MySQL-Instanz semantische Wertesuchen ausfü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. Vektorspalte zum Speichern von Stadteinbettungen erstellen

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

    4. Vektoreinbettungen für Städtenamen generieren und speichern

      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 die Suche nach Trigrammwerten zu aktivieren.

    1. Aktivieren Sie das Flag ngram_token_size.

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

    2. FULLTEXT-Index für Trigramm-Abgleich für den Flughafennamen erstellen

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

Umgebung vorbereiten

Sie können Kontextset-Dateien in jeder lokalen Entwicklungsumgebung oder IDE erstellen. So bereiten Sie die Umgebung vor:

  • Gemini CLI installieren
  • DB Context Enrichment-Erweiterung installieren
  • Datenbankverbindung einrichten

Gemini CLI installieren

Informationen zur Installation der Gemini CLI finden Sie unter Erste Schritte mit der Gemini CLI.

MCP-Erweiterung für die Kontextanreicherung der Datenbank installieren

Die Erweiterung „DB Context Enrichment“ bietet einen geführten, interaktiven Workflow zum Generieren von strukturiertem NL2SQL-Kontext aus Ihren Datenbankschemas.

Weitere Informationen zum Installieren der Erweiterung „DB Context Enrichment“ finden Sie unter Erweiterung „DB Context Enrichment“.

So installieren Sie die Erweiterung „DB Context Enrichment“:

  1. Installieren Sie die Gemini CLI-Erweiterung „DB Context Enrichment“:

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

  2. (Optional) Aktualisieren Sie die Erweiterung „DB Context Enrichment“.

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

    gemini extensions list

    Achten Sie darauf, dass die Version 0.4.2 oder höher ist. Führen Sie den folgenden Befehl aus, um die Erweiterung „DB Context Enrichment“ zu aktualisieren:

      gemini extensions update mcp-db-context-enrichment

    Führen Sie den folgenden Befehl aus, um die Erweiterung „DB Context Enrichment“ zu aktualisieren oder 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 die Datenbankverbindung 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 Nutzeranmeldedaten 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 für die Kontextanreicherung der Datenbank: verwendet Anmeldedaten zur Authentifizierung und zum Aufrufen der Gemini API.

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

gcloud auth application-default login

tools.yaml-Datei konfigurieren

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

In der Datei tools.yaml werden die 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, die Ihnen beim Generieren der Konfiguration helfen.

  1. Gemini CLI starten:

    gemini

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

    /skills

  3. Geben Sie einen Prompt wie help me setup the database connection ein. Der Skill führt Sie durch das Erstellen der Datei tools.yaml in Ihrem aktuellen Arbeitsverzeichnis.

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

    /mcp reload

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

Kontext generieren

Die zuvor installierten Erweiterungen ermöglichen es der Gemini CLI, Sie beim Erstellen von Kontext in Form einer JSON-Datei zu unterstützen.

Zielgerichtete Vorlagen generieren

Wenn Sie ein bestimmtes Abfragepaar als Abfragevorlage in den Kontextsatz aufnehmen möchten, können Sie den Befehl /generate_targeted_templates verwenden. Weitere Informationen zu Vorlagen finden Sie unter Kontextsets.

So fügen Sie dem Kontextset eine Abfragevorlage hinzu:

  1. Starten Sie die Gemini CLI im selben Verzeichnis:

    gemini

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

  3. Prüfen Sie, ob die MCP-Toolbox und die Erweiterung zur Datenbankanreicherung 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 in die Abfragevorlage ein.

  7. Sehen Sie sich die generierte Abfragevorlage an. Sie können die Abfragevorlage entweder als Kontextset-Datei speichern oder an eine vorhandene Kontextset-Datei anhängen.

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

Weitere Informationen zur Kontextset-Datei und zur Abfragevorlage finden Sie unter Kontextsets.

Zielgerichtete Facetten generieren

Wenn Sie ein bestimmtes Abfragepaar als Attribut zur Kontextset-Datei hinzufügen möchten, können Sie den Befehl /generate_targeted_facets verwenden.

So fügen Sie der Kontextset-Datei ein Attribut 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. Sehen Sie sich die generierte Facette an. Sie können die Facette entweder in einer Kontextset-Datei speichern oder an eine vorhandene Kontextset-Datei anhängen.

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

Weitere Informationen zur Kontextset-Datei und zu Facetten finden Sie unter Kontextsets.

Suchanfragen für Werte generieren

Wenn Sie Wertesuchen generieren möchten, in denen angegeben wird, 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 die Wertsuche vorbereiten aus.

So erstellen Sie einen Wertindex:

  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 „Standard“ aus, um MySQL 8.0 auszuwählen.

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

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

    Ersetzen Sie Folgendes:

    • TABLE_NAME: Die Tabelle, in der die Spalte mit dem Konzepttyp vorhanden ist.
    • COLUMN_NAME: Der Spaltenname, der dem Konzepttyp zugeordnet ist.
    • CONCEPT_TYPE: Der Konzepttyp, den Sie definieren möchten, z. B. City name.

    • MATCH_FUNCTION: Die Abgleichsfunktion, die für die Wertsuche verwendet werden soll. Sie können eine der folgenden Funktionen verwenden:

      • EXACT_STRING_MATCH: Für den exakten Abgleich von zwei String-Werten. Am besten für eindeutige IDs, Codes und Primärschlüssel geeignet.
      • TRIGRAM_STRING_MATCH: Für den unscharfen Abgleich, bei dem die normalisierte Trigramm-Distanz berechnet wird. Am besten für Nutzersuchen und Namenskorrekturen geeignet. Damit Sie TRIGRAM_STRING_MATCH verwenden können, müssen Sie Ihre Datenbank vorbereiten, um die N-Gramm-Indexierung zu unterstützen.
      • SEMANTIC_SIMILARITY_MATCH: Für die semantische Suche nach Stringwerten. Optimal für sprachübergreifende Suchen und Synonymsuche. Eine Liste der unterstützten Modelle finden Sie unter Unterstützte Google-Modelle. Wenn Sie SEMANTIC_SIMILARITY_MATCH verwenden möchten, müssen Sie Ihre Datenbank vorbereiten, um Vektoreinbettungen zu unterstützen.

    • DESCRIPTION: (Optional) Die Beschreibung der Wertsuchanfrage.

  2. Fügen Sie bei Bedarf weitere Wertesuchen hinzu. Wenn Sie keine zusätzlichen Wertindexe hinzufügen, wird die vorlagenbasierte SQL-Generierung mit dem nächsten Schritt fortgesetzt.

  3. Sehen Sie sich die generierten Wertesuchen an. Sie können den Kontextsatz entweder als Kontextsatzdatei speichern oder an eine vorhandene Kontextsatzdatei anhängen.

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

Weitere Informationen zum Wertindex finden Sie unter Kontextsets – Übersicht.

Optional: Bulk-Vorlagen generieren

Wenn Sie die Kontextset-Datei automatisch auf Grundlage 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. Bei der vorlagenbasierten SQL-Generierung werden Sie anhand Ihres Datenbankschemas durch eine Reihe von Fragen geführt, in denen Sie die Datenbankinformationen bestätigen und Berechtigungen für den Zugriff auf das Datenbankschema erteilen.

  3. Sehen Sie sich die generierte Abfragevorlage an. Sie können die Vorlage entweder genehmigen oder ein Frage-Antwort-Paar 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. Sehen Sie sich die generierte Abfragevorlage an. Sie können die Abfragevorlage entweder als Kontextset-Datei 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 Datei mit dem Kontextset, ähnlich wie my-cluster-psc-primary_postgres_templates_20251104111122.json, wird in dem Verzeichnis gespeichert, in dem Sie die Befehle ausgeführt haben.

Weitere Informationen zur Datei mit Kontextsets finden Sie unter Übersicht über Kontextsets.

Nächste Schritte