QueryData in eine Anwendung einbinden

In dieser Anleitung wird beschrieben, wie Sie QueryData in Cloud SQL for MySQL mit der Google Cloud Console einrichten und verwenden und in Ihre Anwendung einbinden. Hier erfahren Sie, wie Sie die Kontextset-Datei erstellen, ein Kontextset erstellen, das die Kontextset-Datei verwendet, mit der MCP Toolbox die QueryData API aufrufen, um SQL-Abfragen für Fragen in natürlicher Sprache zu generieren, und das Ganze in Ihre Anwendung einbinden.

Weitere Informationen finden Sie unter Übersicht über QueryData.

Ziele

  • Datenbanktabellen erstellen und mit Daten füllen
  • Kontextset-Datei mit der Gemini CLI und der MCP-Toolbox erstellen
  • Kontextgruppe erstellen und Kontextgruppendatei hochladen.
  • QueryData testen und SQL-Abfragen in Studio generieren
  • Integrieren Sie QueryData in Ihre Anwendung mit dem Tool Gemini Data Analytics QueryData in der MCP Toolbox.
  • LLM-Antworten mit Wertsuchanfragen fundieren

Kosten

In diesem Dokument verwenden Sie die folgenden kostenpflichtigen Komponenten von Google Cloud:

Mit dem Preisrechner können Sie eine Kostenschätzung für Ihre voraussichtliche Nutzung vornehmen.

Neuen Nutzern von Google Cloud steht möglicherweise eine kostenlose Testversion zur Verfügung.

Löschen Sie die von Ihnen erstellten Ressourcen, um weitere Kosten zu vermeiden, wenn Sie die Aufgaben in diesem Dokument abgeschlossen haben. Weitere Informationen finden Sie unter Bereinigen.

Hinweis

Erfüllen Sie die folgenden Voraussetzungen, bevor Sie ein Kontextset 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.

Schema und Tabellen für flights und airports erstellen

In diesem Abschnitt erstellen Sie die Datenbanktabellen flights und airports für dieses Tutorial.

  1. Rufen Sie in der Google Cloud Console die Seite „Cloud SQL“ auf.

    Zu Cloud SQL

  2. Wählen Sie eine Instanz aus der Liste aus.

  3. Klicken Sie im Navigationsmenü auf Cloud SQL Studio.

  4. Melden Sie sich mit der Identity and Access Management-Authentifizierung in Studio an.

  5. Klicken Sie auf Authentifizieren. Im Bereich „Explorer“ wird eine Liste der Objekte in Ihrer Datenbank angezeigt.

  6. Klicken Sie auf Neuer SQL-Editor-Tab oder Neuer Tab, um einen neuen Tab zu öffnen.

  7. Führen Sie die folgende SQL-Anweisung aus, um die Tabelle und das Schema airports zu erstellen:

    CREATE TABLE IF NOT EXISTS airports (
  id INT PRIMARY KEY,
  iata TEXT,
  name TEXT,
  city TEXT,
  country TEXT
  );

  8. Erstellen Sie die Tabelle flights und das Schema:

    CREATE TABLE IF NOT EXISTS flights (
  id INT PRIMARY KEY,
  airline VARCHAR(10),
  flight_number INT,
  departure_airport VARCHAR(5),
  arrival_airport VARCHAR(5),
  departure_time TIMESTAMP,
  arrival_time TIMESTAMP,
  departure_gate VARCHAR(10),
  arrival_gate VARCHAR(10)
);

flights- und airports-Tabellen ausfüllen

In diesem Abschnitt füllen Sie die Tabellen flights und airports mit den bereitgestellten SQL-Scripts.

  1. Füllen Sie die Tabelle airports aus.

  2. Füllen Sie die Tabelle flights aus.

  3. Führen Sie die folgende Abfrage aus, um zu prüfen, ob die Tabellen gefüllt sind:

    SELECT * FROM flights LIMIT 10;
SELECT * FROM airports LIMIT 10;

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;

Kontextset in Studio erstellen

In diesem Abschnitt erstellen Sie einen Kontextsatz mit dem Namen flights-assistant. Für diesen Kontextsatz wurde keine Kontextsatzdatei hochgeladen.

  1. Rufen Sie in der Google Cloud Console die Seite „Cloud SQL“ auf.

    Zu Cloud SQL

  2. Wählen Sie eine Instanz aus der Liste aus.

  3. Klicken Sie im Navigationsmenü auf Cloud SQL Studio.

  4. Melden Sie sich mit der IAM-Authentifizierung in Studio an.

  5. Klicken Sie im Explorer-Bereich neben Kontextsets auf Aktionen ansehen.

  6. Klicken Sie auf Kontextgruppe erstellen.

  7. Geben Sie unter Name des Kontextsets flights-assistant ein.

  8. Klicken Sie auf Erstellen.

QueryData in Studio testen

In diesem Abschnitt verwenden Sie den flights-assistant-Kontext, der durch Fragen in natürlicher Sprache festgelegt wurde, um eine SQL-Abfrage zu generieren. Da für den Kontextsatz keine Kontextsatzdatei hochgeladen wurde, generiert QueryData auch nach dem Stellen einer Frage mit Kontext wie nighttime traffic eine suboptimale Abfrage.

  1. Klicken Sie im Explorer-Bereich neben Ihrem Kontextset auf Aktionen ansehen.
  2. Klicken Sie auf Test context set (Kontext festlegen testen).
  3. Klicken Sie im Abfrageeditor auf SQL mit QueryData generieren mit: flights-assistant.

  4. Geben Sie die folgende Frage in natürlicher Sprache ein, um eine SQL-Abfrage zu generieren, und klicken Sie auf Generieren.

    Find flights from SFO to JFK.

    Prüfen Sie die SQL-Abfrage. QueryData generiert für diese eindeutige Frage den richtigen SQL-Code.

      SELECT
    *
  FROM
    "flights"
  WHERE
    "departure_airport" = 'SFO' AND "arrival_airport" = 'JFK';

  5. Klicken Sie im Fenster SQL mit QueryData generieren mit: flights-assistant auf Bearbeiten.

  6. Geben Sie die folgende Frage in natürlicher Sprache ein, um eine SQL-Abfrage zu generieren, und klicken Sie auf Aktualisieren.

    Tell me flights that can help me beat nighttime traffic if traveling from New York

    Die Datenbank kann den Begriff nighttime-Traffic nicht interpretieren. Das kann verhindern, dass eine SQL-Abfrage generiert wird, oder dazu führen, dass eine Abfrage generiert wird, in der der Begriff ignoriert wird, wie in der folgenden Abfrage zu sehen ist.

    -- The database schema does not contain information about traffic.
-- Returning all flights departing from New York airports.
SELECT
  f.airline,
  f.flight_number,
  a.name AS departure_airport_name,
  f.departure_time,
  b.name AS arrival_airport_name,
  f.arrival_time
FROM
  flights AS f
JOIN
  airports AS a
  ON f.departure_airport = a.iata
JOIN
  airports AS b
  ON f.arrival_airport = b.iata
WHERE
  a.city = 'New York'
ORDER BY
  f.departure_time;

  7. Klicken Sie im Fenster SQL mit QueryData generieren mit: flights-assistant auf Bearbeiten.

  8. Geben Sie die folgende Frage in natürlicher Sprache ein, um eine SQL-Abfrage zu generieren, und klicken Sie auf Aktualisieren.

    Find flights heading into Manhattan

    Die Logik für den Kontextsatz generiert eine Anfrage, um einen Flughafen mit „Manhattan“ im Namen zu finden. Da es in der Datenbank keinen solchen Flughafen oder keine solche Stadt gibt, werden bei der Abfrage keine Zeilen zurückgegeben.

    SELECT
  `skybot`.`flights`.*
FROM
  `skybot`.`flights`
JOIN
  `skybot`.`airports`
ON
  `skybot`.`flights`.`arrival_airport` = `skybot`.`airports`.`iata`
WHERE
  `skybot`.`airports`.`city` = 'Manhattan';

Kontext für die Kontextgruppe generieren

In diesem Abschnitt erstellen Sie eine Kontextdatei, mit der die Abfragefunktionen des Kontextsets verbessert werden.

Umgebung einrichten

Bevor Sie mit dem Generieren von Kontext beginnen können, müssen Sie Ihre Umgebung vorbereiten.

So richten Sie Ihre Umgebung ein:

  1. Installieren Sie die Gemini CLI. Weitere Informationen finden Sie in der Gemini-Befehlszeile – Kurzanleitung.
  2. Installieren Sie die gcloud CLI.

  3. Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) einrichten Führen Sie im Terminal die folgenden Befehle aus, um sich zu authentifizieren und Ihr Projekt auszuwählen:

    gcloud auth application-default login

  4. Installieren Sie die Erweiterung „DB Context Enrichment“, die Workflows für die Kontexterstellung enthält.

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

    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

  5. 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.

  6. Starten Sie die Gemini CLI in Ihrem Terminal.

    gemini

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

  8. Richten Sie eine Datenbankverbindung ein. 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.

    Wenn Sie die tools.yaml-Konfigurationsdatei in Ihrem aktuellen Verzeichnis erstellen möchten, geben Sie einen Prompt wie Help me set up the database connection ein und folgen Sie der Anleitung des Skills. Weitere Informationen zur tools.yaml-Datei finden Sie in der Dokumentation zur MCP Toolbox.

  9. Führen Sie den folgenden Befehl in der Gemini CLI aus, um die Konfiguration neu zu laden, nachdem die Datei tools.yaml erstellt wurde:

    /mcp reload

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

    /mcp list

Vorlagenkontext generieren

Um das Problem aus dem vorherigen Abschnitt zu beheben, bei dem nighttime traffic nicht von QueryData erkannt wurde, definieren Sie den Begriff in der Kontextdatei als Traffic zwischen 5:00 PM und 7:00 PM.

So generieren Sie den Vorlagenkontext:

  1. Führen Sie den Befehl /generate_targeted_templates aus und folgen Sie dem Workflow:

    /generate_targeted_templates

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

    Tell me flights that can help me beat nighttime traffic if traveling from New York

  3. Geben Sie eine entsprechende SQL-Abfrage an, die Sie der Abfragevorlage hinzufügen möchten. In dieser Abfragevorlage wird der Begriff nighttime als zwischen 5:00 PM und 7:00 PM auftretend definiert.

    SELECT
  f.airline,
  f.flight_number,
  a.name AS airport_name,
  f.departure_time
FROM
  flights f
JOIN
  airports a
  ON f.departure_airport = a.iata
WHERE
  a.city = 'New York'
  AND (
    EXTRACT(HOUR FROM f.departure_time) < 17
    OR EXTRACT(HOUR FROM f.departure_time) >= 19
  )
ORDER BY
  f.departure_time;

  4. Drücken Sie die Eingabetaste. Gemini wandelt Ihre Eingabe in ein bestimmtes Format um, das die Leistung des Kontextsets bei einer Vielzahl von Nutzeranfragen verbessert. Weitere Informationen finden Sie unter Kontextsets.

    Optional können Sie den /generate_bulk_templates-Workflow ausführen, damit die Gemini CLI mehr Kontext generiert, indem sie Ihr Datenbankschema scannt und zugehörigen Kontext vorschlägt.

  5. Sehen Sie sich die generierte Abfragevorlage an. Sie können die Abfragevorlage entweder als neue Kontextdatei für den Agenten speichern oder an eine vorhandene Kontextdatei für den Agenten anhängen.

  6. Wählen Sie die Option zum Erstellen einer neuen Kontextdatei für KI-Agenten aus. Gemini erstellt im selben Verzeichnis eine Datei mit dem Namen INSTANCE_ID_DATABASE_ID_context_set_TIMESTAMP.json mit folgendem Inhalt:

    {
  "templates": [
    {
      "nl_query": "Tell me flights that can help me beat nighttime traffic if traveling from New York",
      "sql": "SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = 'New York' AND (EXTRACT(HOUR FROM f.departure_time) < 17 OR EXTRACT(HOUR FROM f.departure_time) >= 19) ORDER BY f.departure_time;",
      "intent": "Tell me flights that can help me beat nighttime traffic if traveling from New York",
      "manifest": "Tell me flights that can help me beat nighttime traffic if traveling from a given city",
      "parameterized": {
        "parameterized_sql": "SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = ? AND (EXTRACT(HOUR FROM f.departure_time) < 17 OR EXTRACT(HOUR FROM f.departure_time) >= 19) ORDER BY f.departure_time;",
        "parameterized_intent": "Tell me flights that can help me beat nighttime traffic if traveling from ?"
      }
    }
  ]
}

Kontext für die Suche nach Werten generieren

In diesem Abschnitt generieren Sie einen Kontext für die Wertsuche, damit die Logik für den Kontextsatz Wertausdrücke bestimmten Werten zuordnen kann, die in Ihren Datenbankspalten gespeichert sind. Wenn ein Nutzer beispielsweise nach „Flügen nach Manhattan“ fragt, wird zuerst „Manhattan“ als Wertphrase extrahiert. Die semantische Ähnlichkeitssuche ordnet „Manhattan“ dann „New York“ zu, das in der Spalte airports.city gespeichert ist.

So generieren Sie den Kontext für die Wertesuche:

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

    /generate_targeted_value_searches

  2. Geben Sie mysql ein, um MySQL als Datenbank auszuwählen.

  3. Geben Sie die MySQL-Version ein, die Sie verwenden möchten. Wählen Sie default aus, um MySQL 8.0 auszuwählen.

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

    Table: airports
Column: name
Concept: airport name
Match Function: TRIGRAM_STRING_MATCH

  5. Wiederholen Sie den Vorgang für den semantischen Abgleich.

    Table: airports
Column: city
Concept: airport city
Match Function: SEMANTIC_STRING_MATCH
Column Embedding: city_embedding

  6. Bestätigen Sie, dass Sie die Definition für die Wertsuche generieren möchten.

  7. Überprüfen Sie die generierte Definition für die Wertsuche. Sie können die Definition der Wertsuche entweder als neue Kontextset-Datei speichern oder an eine vorhandene Kontextset-Datei anhängen.

  8. Wählen Sie die Option aus, um die Daten an eine vorhandene Kontextset-Datei anzuhängen. Dadurch wird die Definition der Wertsuche der Kontextdatei hinzugefügt, die im vorherigen Abschnitt erstellt wurde.

  9. Geben Sie die Datenbankinstanz und den Datenbanknamen ein, für die die Kontextset-Datei generiert wurde.

    Die vorhandene Kontextdatei wird mit der Definition für die Wertsuche aktualisiert. Gemini erstellt im selben Verzeichnis eine Datei mit dem Namen INSTANCE_ID_DATABASE_ID_context_set_TIMESTAMP.json mit folgendem Inhalt:

      {
"templates": [
  {
    "nl_query": "Tell me flights that can help me beat nighttime traffic if traveling from New York",
    "sql": "SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = 'New York' AND (EXTRACT(HOUR FROM f.departure_time) < 17 OR EXTRACT(HOUR FROM f.departure_time) >= 19) ORDER BY f.departure_time;",
    "intent": "Tell me flights that can help me beat nighttime traffic if traveling from New York",
    "manifest": "Tell me flights that can help me beat nighttime traffic if traveling from a given city",
    "parameterized": {
      "parameterized_sql": "SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = ? AND (EXTRACT(HOUR FROM f.departure_time) < 17 OR EXTRACT(HOUR FROM f.departure_time) >= 19) ORDER BY f.departure_time;",
      "parameterized_intent": "Tell me flights that can help me beat nighttime traffic if traveling from ?"
    }
  }
],
"facets": [],
"value_searches": [
  {
    "query": "SELECT * FROM (  WITH TrigramMetrics AS (    SELECT T.`name` AS original_value,     MATCH(T.`name`) AGAINST($value IN NATURAL LANGUAGE MODE) AS raw_score     FROM `airports` AS T     WHERE MATCH(T.`name`) AGAINST($value IN NATURAL LANGUAGE MODE) > 0     ORDER BY raw_score DESC LIMIT 10  ),   NormalizationParams AS (    SELECT MAX(raw_score) AS max_score     FROM TrigramMetrics  )   SELECT original_value AS value, 'name' AS `columns`,   'airport city' AS concept_type,   (CASE WHEN n.max_score > 0 THEN (1 - (m.raw_score / n.max_score)) ELSE 0 END) AS distance,   JSON_OBJECT() AS context   FROM TrigramMetrics m, NormalizationParams n) AS wrapped_query ",
    "concept_type": "airport city",
    "description": null
  },
  {
    "query": "SELECT * FROM (  WITH search_embedding AS (    SELECT mysql.ml_embedding('text-embedding-005', $value) AS val  )   SELECT T.`city` AS value, 'city' AS `columns`,   'airport name' AS concept_type,   COSINE_DISTANCE(T.`city_embedding`, search_embedding.val) AS distance,   JSON_OBJECT() AS context   FROM `airports` AS T, search_embedding   WHERE T.`city_embedding` IS NOT NULL) AS wrapped_query ",
    "concept_type": "airport name",
    "description": null
  }
]
}

Kontextset-Datei in QueryData hochladen

In diesem Abschnitt laden Sie die Kontextset-Datei in QueryData hoch, damit die SQL-Generierungsfunktionen von QueryData für Ihre Datenbank verbessert werden.

Führen Sie die folgenden Schritte aus, um den Kontext hochzuladen:

  1. Rufen Sie in der Google Cloud Console die Seite „Cloud SQL“ auf.

    Zu Cloud SQL

  2. Wählen Sie eine Instanz aus der Liste aus.

  3. Klicken Sie im Navigationsmenü auf Cloud SQL Studio.

  4. Melden Sie sich mit der Identity and Access Management-Authentifizierung in Studio an.

  5. Klicken Sie im Explorer-Bereich neben Kontextsets auf das Symbol Aktionen ().

  6. Klicken Sie auf Kontextgruppe bearbeiten.

  7. Optional: Bearbeiten Sie die Beschreibung des Kontextsets.

  8. Klicken Sie im Abschnitt Kontextset-Datei hochladen auf Durchsuchen und wählen Sie die zuvor generierte Kontextset-Datei aus.

  9. Klicken Sie auf Speichern.

SQL-Abfrage mit QueryData generieren

In diesem Abschnitt verwenden Sie die von Ihnen hochgeladene Kontextdatei, um Fragen in natürlicher Sprache zu stellen. So können Sie prüfen, ob QueryData Definitionen für Begriffe wie nighttime traffic und andere ähnliche Begriffe richtig versteht und anwendet.

So generieren Sie SQL-Abfragen:

  1. Klicken Sie im Bereich Explorer neben Ihrem Kontextset auf Aktionen ansehen.
  2. Klicken Sie auf Test context set (Kontext festlegen testen).
  3. Klicken Sie im Abfrageeditor auf SQL mit QueryData generieren mit: Assistent für Flüge.

  4. Geben Sie die folgende Frage in natürlicher Sprache ein, um eine SQL-Abfrage zu generieren, und klicken Sie auf Generieren.

    Tell me flights that can help me beat nighttime traffic if traveling from New York

    Die generierte SQL-Abfrage sieht in etwa so aus:

    SELECT
  f.airline,
  f.flight_number,
  a.name AS airport_name,
  f.departure_time
FROM
  flights f
JOIN
  airports a ON f.departure_airport = a.iata
WHERE
  a.city = 'New York'
  AND (
    EXTRACT(HOUR FROM f.departure_time) < 17
    OR EXTRACT(HOUR FROM f.departure_time) >= 19
  )
ORDER BY
  f.departure_time;

    Das ist dieselbe Frage, die Sie dem Kontext von QueryData hinzugefügt haben. QueryData kann den Begriff nighttime traffic jetzt korrekt interpretieren.

    Obwohl der Kontext aus einer bestimmten Frage stammt, wird er von QueryData verwendet, um die SQL-Generierung für eine Vielzahl ähnlicher Fragen zu verbessern.

  5. Klicken Sie im Fenster SQL mit QueryData generieren mit: flights-assistant auf Bearbeiten.

  6. Geben Sie die folgende ähnliche Frage ein, um eine SQL-Abfrage zu generieren, und klicken Sie auf Aktualisieren.

    What are the flights that can help me avoid evening traffic if departing from Boston

    Da in der Frage der Begriff nighttime traffic durch einen ähnlichen Begriff, evening traffic, ersetzt wird, liefert QueryData eine konsistente Antwort auf diese Frage, indem dieselbe Interpretation angewendet wird.

    Die generierte SQL-Abfrage sieht in etwa so aus:

    -- What are the flights that can help me avoid evening traffic if departing from Boston
SELECT
  f.airline,
  f.flight_number,
  a.name AS airport_name,
  f.departure_time
FROM
  flights f
JOIN
  airports a
ON
  f.departure_airport = a.iata
WHERE
  a.city = 'Boston'
  AND (
    EXTRACT(HOUR FROM f.departure_time) < 17
    OR EXTRACT(HOUR FROM f.departure_time) >= 19
  )
ORDER BY
  f.departure_time;

  7. Klicken Sie im Fenster SQL mit QueryData generieren mit: flights-assistant auf Bearbeiten.

  8. Klicken Sie im Fenster SQL mit QueryData generieren mit: flights-assistant auf Bearbeiten.

  9. Geben Sie die folgende Frage ein, um eine SQL-Abfrage zu generieren, und klicken Sie auf Aktualisieren.

    Find flights heading into Manhattan

    Die generierte SQL-Abfrage sieht in etwa so aus:

    SELECT
  *
FROM `skybot`.`flights` AS t1
INNER JOIN `skybot`.`airports` AS t2
  ON t1.`arrival_airport` = t2.`iata`
WHERE t2.`city` = 'New York';

    QueryData kann jetzt mithilfe des semantischen Abgleichs genau interpretieren, dass sich „Manhattan“ auf „New York“ in der Datenbank bezieht.

QueryData in Ihre Anwendung einbinden

In diesem Abschnitt erstellen Sie einen QueryData-Agent für eine Anwendung zur Flugsuche. Dieser QueryData-Agent bietet eine dialogorientierte Schnittstelle für die Tabellen flights und airports, die Sie zuvor erstellt haben. Außerdem wird erläutert, wie Sie diesen QueryData-Agenten mit dem Agent Development Kit (ADK), dem Gemini Data Analytics QueryData MCP-Tool und dem auf die Verbesserung der Antwortqualität ausgerichteten Kontext erstellen und in Ihre Anwendung einbinden.

  1. Laden Sie die MCP Toolbox-Version 0.31.0 oder höher herunter. Die MCP-Toolbox macht den QueryData-Agent als Tool verfügbar, mit dem Anwendungen eine Verbindung herstellen können. Die MCP-Toolbox unterscheidet sich von der MCP-Toolbox-Gemini CLI-Erweiterung, die Sie zuvor installiert haben und mit der Kontext generiert wird.

  2. Richten Sie Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) ein.

    gcloud auth application-default login

  3. Suchen Sie die Kontextgruppe-ID. Weitere Informationen zum Suchen der Kontextgruppe-ID finden Sie unter Kontextgruppe-ID finden.

  4. Erstellen Sie die tools.yaml-Konfiguration, um mit der MCP-Toolbox eine Verbindung zum QueryData-Agent herzustellen. Weitere Informationen finden Sie unter Gemini Data Analytics-Quelle und Gemini Data Analytics-Tool „QueryData“.

    kind: source
name: gda-api-source
type: cloud-gemini-data-analytics
projectId: "PROJECT_ID"
---
kind: tool
name: cloud_gda_query_tool
type: cloud-gemini-data-analytics-query
source: gda-api-source
description: Use this tool to send natural language queries to the Gemini Data Analytics API and receive SQL, natural language answers, and explanations.
location: "REGION_ID"
context:
  datasourceReferences:
    cloudSqlReference:
      databaseReference:
        engine: "MYSQL"
        projectId: "PROJECT_ID"
        region: "REGION_ID"
        instanceId: "INSTANCE_ID"
        databaseId: "DATABASE_ID"
      agentContextReference:
        contextSetId: "CONTEXT_SET_ID"
generationOptions:
  generateQueryResult: true
  generateNaturalLanguageAnswer: true
  generateExplanation: true
  generateDisambiguationQuestion: true

    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.
    • CONTEXT_SET_ID: Die ID des Kontextsets. Weitere Informationen zum Suchen der Kontextgruppe-ID finden Sie unter Kontextgruppe-ID finden.

  5. Führen Sie den MCP Toolbox-Server mit der Datei tools.yaml aus.

    ./toolbox --config "tools.yaml"

  6. Erstellen Sie eine ADK-Anwendung, die das Gemini Data Analytics QueryData-Tool mit dem Python SDK der MCP Toolbox aufruft. Weitere Informationen zur Verwendung des Python SDK der MCP Toolbox finden Sie in der Kurzanleitung für die Toolbox und zur Verwendung des Python ADK in der Kurzanleitung für das ADK.

    1. Erstellen Sie ein Verzeichnis zum Speichern der Anwendung, z. B. flight-assistant-app.

    2. Wechseln Sie in das Verzeichnis flight-assistant-app.

      mkdir flight-assistant-app
cd flight-assistant-app

    3. Führen Sie die folgenden Befehle im Verzeichnis flight-assistant-app aus, um eine virtuelle Umgebung zu erstellen und die erforderlichen Komponenten zu installieren.

      python3 -m venv .venv
source .venv/bin/activate
pip install toolbox-core
pip install google-genai
pip install google-adk

    4. ADK-Agent einrichten

      1. Erstellen Sie einen ADK-Agent.

        adk create my_agent

      2. Wählen Sie das gemini-2.5-flash-Modell aus.

      3. Wählen Sie Google AI aus und geben Sie Ihren Gemini API-Schlüssel ein. Weitere Informationen zum Suchen Ihres API-Schlüssels finden Sie unter Gemini API-Schlüssel verwenden.

    5. Ersetzen Sie den Inhalt der Datei agent.py durch den folgenden Beispielcode für die Flight Data Assistant-Anwendung.

      from typing import cast

from google.adk.agents.llm_agent import Agent
from google.adk.agents.llm_agent import ToolUnion

from toolbox_core import ToolboxSyncClient

TOOLBOX_URL = "http://127.0.0.1:5000"

INSTRUCTION = """
# ROLE
You are a friendly and factual flight data assistant. Your goal is to help users find the best flights for their needs by providing accurate information with a helpful, professional tone.
- use the Query Data Tool to answer the user's question, if the tool fails to generate a valid query, ask the user to clarify their question.

# OPERATIONAL CONSTRAINTS
- TOOL LIMITATION: You only have access to the Query Data Tool. Do not claim to have capabilities beyond what this tool provides.
- TRANSPARENCY POLICY: Maintain a seamless user experience. Never mention that you are using a tool, querying a database, or generating SQL. Frame all responses as your own direct assistance.
- SCOPE MANAGEMENT: If a user asks for something beyond your capabilities, politely state that you cannot perform that specific task. Guide the user towards what you can help with.

# COMMUNICATION STYLE
- Be concise and scannable when listing answers.
- Maintain a helpful, professional persona.

=====

# QUERY DATA TOOL

Inputs:
1. query: A natural language formulation of a database query.

Outputs: (all optional)
1. disambiguation_question: Clarification questions or comments where the tool needs the users' input.
2. generated_query: The generated query for the user query.
3. intent_explanation: An explanation for why the tool produced `generated_query`.
4. query_result: The result of executing `generated_query`.
5. natural_language_answer: The natural language answer that summarizes the `query` and `query_result`.

Usage guidance:
1. If `disambiguation_question` is produced, then solicit the needed inputs from the user and try the tool with a new `query` that has the needed clarification.
2. If `natural_language_answer` is produced, use `intent_explanation` and `generated_query` to see if you need to clarify any assumptions for the user.
3. If the tool output indicates failure or empty results, explain that clearly using the provided reasoning.
"""

client = ToolboxSyncClient(TOOLBOX_URL)

mcp_tool = client.load_tool("cloud_gda_query_tool")

root_agent = Agent(
    model="gemini-2.5-flash",
    name="root_agent",
    instruction=INSTRUCTION,
    tools=cast(list[ToolUnion], [mcp_tool]),
)

  7. Führen Sie die folgenden Befehle im Verzeichnis flight-assistant-app aus, um die Anwendung zu starten und unter http://127.0.0.1:8000 auf den ADK-Webserver zuzugreifen.

    adk web --port 8000

  8. Geben Sie einen beliebigen Text ein, z. B. hello, um mit dem KI-Agenten zu interagieren.

    Der ADK-Agent beantwortet allgemeine Fragen und ruft die erforderlichen MCP-Tools auf.

  9. Geben Sie die folgende Frage zum Flug ein.

    How many flights depart from the west side?

    Das MCP-Tool wird aufgerufen, um diese Frage zu beantworten. Da der Begriff the west jedoch mehrdeutig ist und keine Flughäfen angibt, gibt das MCP-Tool eine Frage zur Klärung zurück, die der Agent verwendet, um eine Antwort zu erstellen.

    I cannot determine how many flights depart from the 'west side' as the database does not contain information about which airports are considered to be on the 'west side'. However, I can help you with questions like:

1. How many flights depart from a specific airport?

2. What are the departure airports for all flights?

3. How many flights depart from each airport? Would you like to rephrase your question based on these options?

  10. Geben Sie eine Frage ein, die der für den Agenten generierten Abfragevorlage ähnelt.

    Help me find flights from San Francisco that avoid the evening rush hour.

    Anhand des zuvor hinzugefügten QueryData-Kontexts weiß das MCP-Tool, dass evening traffic zwischen 17:00 und 19:00 Uhr stattfindet. Das MCP-Tool gibt die zugehörigen Daten zurück, die der Agent zum Erstellen seiner Antwort verwendet.

    Here are the flights departing from San Francisco that avoid the evening rush hour (defined as 5 PM to 7 PM):

* UA 1532 departing at 05:50:00
* UA 1158 departing at 05:57:00
* CY 922 departing at 06:38:00
* OO 5441 departing at 07:08:00
* UA 616 departing at 07:14:00
* AA 24 departing at 07:14:00
* B6 434 departing at 08:00:00
* AA 242 departing at 08:18:00
* UA 1739 departing at 08:22:00
* OO 6336 departing at 08:32:00
* US 1784 departing at 08:47:00
* DL 1631 departing at 09:00:00
* DL 1106 departing at 09:06:00
* OO 5427 departing at 09:06:00
* CY 352 departing at 09:25:00

  11. Geben Sie eine Frage basierend auf dem Konzepttyp ein, den Sie dem Agentenkontext hinzugefügt haben.

    Find flights heading into Manhattan

    Anhand des zuvor hinzugefügten Kontextes für die Wertsuche versteht der Agent, dass sich Manhattan auf die Stadt New York bezieht, und gibt die zugehörigen Daten zurück, die der Agent zum Erstellen seiner Antwort verwenden kann.

    There are 6 flights heading into New York City, specifically arriving at JFK airport, which serves Manhattan.

Here are the details for these flights:

AA 24 from SFO, departing 2025-01-01 07:14:00 and arriving 2025-01-01 15:46:00.
UA 758 from SFO, departing 2025-01-02 07:07:00 and arriving 2025-01-02 15:53:00.
AA 24 from SFO, departing 2025-01-02 07:06:00 and arriving 2025-01-02 15:29:00.
DL 2040 from SFO, departing 2025-01-02 15:09:00 and arriving 2025-01-02 23:20:00.
DL 1370 from SFO, departing 2025-01-02 23:04:00 and arriving 2025-01-03 07:36:00.
CY 34 from SFO, departing 2025-01-02 23:15:00 and arriving 2025-01-03 07:54:00.

Agent-Leistung iterieren

In der ADK-Web-UI können Sie die Anfrage und Antwort des MCP-Tools „Gemini Data Analytics QueryData“ prüfen. Anhand dieser Antwort können Sie die Tool-Antworten wie die generierte SQL-Abfrage, das Ergebnis-Set, die Erklärung der Intention, die Frage zur Begriffsklärung und die Antwort in natürlicher Sprache ansehen, um die Richtigkeit der Antworten Ihres KI-Agenten zu bestätigen.

Klicken Sie beispielsweise für den zuvor eingegebenen Text How many flights depart from the west side? auf die Blase des KI-Agenten. Erweitern Sie im linken Navigationsbereich auf dem Tab Ereignis das functionResponse, um die folgende Antwort zu sehen.

"{"disambiguationQuestion": ["[NOT_ENOUGH_INFO] The database schema does not
contain information about which airports are on the 'west side'. Therefore, I
cannot determine how many flights depart from the west side.Possible alternative
questions: 1. How many flights depart from a specific airport? 2. What are the
departure airports for all flights? 3. How many flights depart from each
airport?"]}"

Antwortgenauigkeit verbessern

Sie können die Genauigkeit der Antworten des Gemini Data Analytics-Tools „QueryData“ kontinuierlich verbessern, indem Sie zusätzlichen Kontext hinzufügen. Verwenden Sie die Gemini CLI, um Kontext zu generieren, und laden Sie dann die aktualisierte Kontextset-Datei in den vorhandenen flights-assistant-QueryData-Agenten hoch. Weitere Informationen finden Sie unter Kontexte mit der Gemini-Befehlszeile erstellen. Die Konsole übernimmt neuen Kontext sofort nach dem Hochladen, sodass Sie die Genauigkeit des Agents ohne Ausfallzeiten der Anwendung verbessern können.

Mehrere Agenten

In Ihrer Entwicklungsumgebung können Sie A/B-Tests für mehrere QueryData-Agent-Kontexte durchführen, indem Sie Tools in Ihrer tools.yaml-Datei unterschiedliche Namen zuweisen. Sie können beispielsweise eindeutige tools.yaml-Konfigurationen erstellen, indem Sie zwei cloud-gemini-data-analytics-query-Tools mit unterschiedlichen Namen definieren, z. B. cloud_gda_query_tool_v1 und cloud_gda_query_tool_v2. Mit dieser Einrichtung können Sie Anwendungslogik implementieren, mit der die erforderliche Kontextversion programmatisch ausgewählt wird, indem Sie den entsprechenden Toolnamen auswählen.

Im folgenden Beispiel tools.yaml sehen Sie, wie Sie mehrere QueryData-Agents für eine Datenbankquelle einrichten:

kind: source
name: gda-api-source
type: cloud-gemini-data-analytics
projectId: <var>PROJECT_ID</var>
---
kind: tool
name: cloud_gda_query_tool_v1
type: cloud-gemini-data-analytics-query
source: gda-api-source
context:
  datasourceReferences:
    <var>DB_SOURCE</var>:
      databaseReference: ...
      agentContextReference:
        contextSetId: "V1_YOUR_CONTEXT_SET_ID"
generationOptions: ...
---
kind: tool
name: cloud_gda_query_tool_v2
type: cloud-gemini-data-analytics-query
source: gda-api-source
context:
  datasourceReferences:
    <var>DB_SOURCE</var>:
      databaseReference: ...
      agentContextReference:
        contextSetId: "V2_YOUR_CONTEXT_SET_ID"
generationOptions: ...

Ersetzen Sie Folgendes:

  • PROJECT_ID: Ihre Google Cloud Projekt-ID
  • V1_YOUR_CONTEXT_SET_ID: Die Kontextset-ID für Version 1.
  • V2_YOUR_CONTEXT_SET_ID: Die Kontextgruppe-ID für Version 2

Bereinigen

In den folgenden Abschnitten erfahren Sie, wie Sie diese Ressourcen und Objekte löschen.

Kontextgruppe löschen

Bevor Sie die Instanz löschen, müssen Sie den erstellten Kontextsatz löschen.

  1. Rufen Sie in der Google Cloud Console die Seite „Cloud SQL“ auf.

    Zu Cloud SQL

  2. Wählen Sie eine Instanz aus der Liste aus.

  3. Klicken Sie im Navigationsmenü auf Cloud SQL Studio.

  4. Melden Sie sich mit der Identity and Access Management-Authentifizierung in Studio an.

  5. Klicken Sie im Explorer-Bereich neben Ihrem Kontextset auf Aktionen ansehen.

  6. Geben Sie im Fenster Kontextgruppe löschen flight-assistant in das Bestätigungsfeld ein.

  7. Klicken Sie auf Bestätigen.

Instanz löschen

Wenn Sie die Instanz löschen, die Sie im Abschnitt Vorbereitung erstellt haben, werden auch alle von Ihnen erstellten Objekte gelöscht.

  1. Rufen Sie in der Google Cloud Console die Seite „Cloud SQL“ auf.

    Zu Cloud SQL

  2. Wählen Sie eine Instanz aus der Liste aus.

  3. Klicken Sie auf Löschen.

  4. Bestätigen Sie, dass Sie die Instanz löschen möchten, indem Sie den Instanznamen eingeben und auf Löschen klicken.

Nächste Schritte