In dieser Anleitung wird beschrieben, wie Sie QueryData in Spanner Graph mit der Google Cloud Console einrichten und verwenden und in Ihre Anwendung einbinden. Sie erfahren, wie Sie den Property-Graphen FinGraph einrichten, mit dem Context-Engineering-Agenten eine Kontextset-Datei in der Graph Query Language (GQL) erstellen, ein Kontextset in Spanner Studio erstellen, QueryData testen, indem Sie die QueryData-Methode in der Conversational Analytics API mit konfiguriertem graph_ids aufrufen, und ein benutzerdefiniertes HTTP-Tool in der MCP Toolbox verwenden, um eine Agent-Anwendung mit QueryData zu verbinden.
Weitere Informationen finden Sie unter QueryData – Übersicht.
Ziele
- Erstellen Sie das Attributdiagrammschema
FinGraphund füllen Sie es mit Beispieldiagrammdaten. - Erstellen Sie mithilfe des Kontext-Engineering-Agenten eine Kontextset-Datei für
FinGraph. - Erstellen Sie ein Kontextset und laden Sie die Kontextset-Datei in Spanner Studio hoch.
- Testen Sie QueryData und generieren Sie GQL-Abfragen, indem Sie die
QueryDataREST API mitgraph_idsinspanner_referenceaufrufen. - Integrieren Sie QueryData in Ihre Anwendung, indem Sie ein benutzerdefiniertes HTTP-Tool in der MCP Toolbox verwenden, das die
QueryDataREST API aufruft. - Fundieren Sie LLM-Antworten in Ihren Grafikdaten mithilfe von Abfragevorlagen, Abfragefacetten und
GRAPH_TABLE-Wert-Suchanfragen.
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
Bevor Sie einen Kontextsatz erstellen, müssen Sie die folgenden Voraussetzungen erfüllen:
Erforderliche Dienste aktivieren
Aktivieren Sie die folgenden Dienste für Ihr Projekt:Spanner-Instanz vorbereiten
- Prüfen Sie, ob eine Spanner-Instanz verfügbar ist. Weitere Informationen finden Sie unter Instanz erstellen.
- Erstellen Sie in Ihrer Instanz eine Datenbank, in der Sie die Tabellen erstellen. Weitere Informationen finden Sie unter Datenbank auf der Spanner-Instanz erstellen.
Erforderliche Rollen und Berechtigungen
- Fügen Sie der Instanz einen IAM-Nutzer oder ein Dienstkonto hinzu. Weitere Informationen finden Sie unter IAM-Rollen anwenden.
- Weisen Sie dem IAM-Nutzer auf Projektebene die Rollen
roles/spanner.databaseReader,roles/serviceusage.serviceUsageConsumerundroles/geminidataanalytics.queryDataUserzu. Weitere Informationen finden Sie unter IAM-Richtlinienbindung für ein Projekt hinzufügen. - Wenn Sie Kontextgruppen erstellen, hochladen und verwalten möchten, weisen Sie dem IAM-Nutzer auf Projektebene die Rolle „Dataplex Catalog Editor“ (
roles/dataplex.catalogEditor) oder „Dataplex Catalog Admin“ (roles/dataplex.catalogAdmin) zu. Weitere Informationen finden Sie unter Berechtigungen für Kontextgruppen. - Weisen Sie dem IAM-Nutzer auf Projektebene Rollen und Berechtigungen für die erforderlichen Datenbanken zu.
FinGraph-Schema erstellen und Grafikdaten einfügen
In diesem Tutorial wird das Finanz-Property-Graph-Dataset FinGraph verwendet, das Person- und Account-Knoten modelliert, die durch Owns- (PersonOwnAccount) und Transfers-Kanten (AccountTransferAccount) verbunden sind.
Führen Sie die folgenden Schritte aus dem Einrichtungsleitfaden für Spanner Graph aus, um das Schema FinGraph zu erstellen und die Grafikdaten in Ihrer Spanner-Datenbank zu füllen:
- Folgen Sie der Anleitung unter Graphdatenbank mit einem Schema erstellen, um die Tabellen
Person,Account,PersonOwnAccountundAccountTransferAccountsowie die Definition des Property GraphsFinGraphzu erstellen. - Folgen Sie der Anleitung unter Grafikdaten einfügen, um die Beispielpersonen (
Alex,DanaundLee), Konten (7,16und20), Kontoinhaberkanten und Geldtransferkanten inFinGrapheinzufügen.
Kontextset erstellen
Erstellen Sie ein leeres Kontextset mit dem Namen fingraph-assistant. Später in dieser Anleitung laden Sie eine Kontextsatzdatei in diesen Bucket hoch.
Rufen Sie in der Google Cloud Console die Seite „Spanner“ auf.
Wählen Sie Ihre Instanz aus der Liste und dann die Datenbank aus, die
FinGraphenthält.Klicken Sie im Navigationsmenü auf Spanner Studio.
Klicken Sie im Bereich Explorer neben Kontextsätze auf Aktionen ansehen.
Klicken Sie auf Kontextgruppe erstellen.
Geben Sie im Feld Name des Kontextsets den Wert
fingraph-assistantein.Klicken Sie auf Erstellen.
QueryData ohne Kontext testen
In diesem Abschnitt rufen Sie die QueryData REST API auf, um GQL-Abfragen für Fragen in natürlicher Sprache ohne Kontext zu generieren. Ohne Kontext kann QueryData Fragen beantworten, die sich direkt auf das Schema FinGraph beziehen. Es kann jedoch keine benutzerdefinierte Geschäftsterminologie wie high-risk transfers interpretieren oder Unterschiede bei der Wertformatierung wie Czech Republic im Vergleich zu Czech_Republic auflösen.
Legen Sie im Terminal die folgenden Umgebungsvariablen fest:
export PROJECT_ID="PROJECT_ID" export INSTANCE_ID="INSTANCE_ID" export DATABASE_ID="DATABASE_ID"
Ersetzen Sie Folgendes:
PROJECT_ID: Projekt-ID in Google Cloud .INSTANCE_ID: Ihre Spanner-Instanz-ID.DATABASE_ID: die ID der Datenbank, dieFinGraphenthält.
Erstellen Sie ein Hilfsskript mit dem Namen
query_data.sh, das eine Frage an dieQueryDataREST API sendet, wobeigraph_idsaufFinGraphgesetzt ist. Wenn die UmgebungsvariableCONTEXT_SET_IDfestgelegt ist, sendet das Script auch Ihre Kontextsatz-ID:cat > query_data.sh <<'EOF' #!/bin/bash # Usage: ./query_data.sh "NATURAL_LANGUAGE_QUESTION" if [[ -n "${CONTEXT_SET_ID}" ]]; then AGENT_CONTEXT=", \"agent_context_reference\": {\"context_set_id\": \"${CONTEXT_SET_ID}\"}" fi curl -sS -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "x-goog-user-project: ${PROJECT_ID}" \ "https://geminidataanalytics.googleapis.com/v1beta/projects/${PROJECT_ID}/locations/global:queryData" \ -d @- <<JSON { "prompt": "$1", "context": { "datasource_references": { "spanner_reference": { "database_reference": { "engine": "GOOGLE_SQL", "project_id": "${PROJECT_ID}", "instance_id": "${INSTANCE_ID}", "database_id": "${DATABASE_ID}", "graph_ids": ["FinGraph"] }${AGENT_CONTEXT} } } }, "generation_options": { "generate_query_result": true, "generate_natural_language_answer": true, "generate_explanation": true } } JSON EOF chmod +x query_data.shDas Skript fügt Ihre Frage unverändert in den Anfragetext ein. Verwenden Sie daher keine doppelten Anführungszeichen (
") in der Frage.Stellen Sie eine Frage, die sich direkt auf das Schema
FinGraphbezieht:./query_data.sh "Find everyone that Dana transferred money to, along with the account IDs and transfer amounts."
Prüfen Sie in der Antwort die Felder
generatedQueryundqueryResult. Für diese eindeutige Frage generiert QueryData eine GQL-Abfrage, die etwa so aussieht:GRAPH FinGraph MATCH (p:Person {name: 'Dana'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account), (recipient:Person)-[:Owns]->(dst) RETURN recipient.name AS recipient_name, dst.id AS recipient_account_id, t.amount AS transfer_amount;Dies gibt Ergebnisse wie die folgenden zurück:
+----------------+----------------------+-----------------+ | recipient_name | recipient_account_id | transfer_amount | +----------------+----------------------+-----------------+ | Alex | 7 | 500 | | Lee | 16 | 200 | +----------------+----------------------+-----------------+Stellen Sie eine Frage, die den Unternehmensbegriff
high-risk transfersenthält:./query_data.sh "Find all high-risk transfers initiated by Alex"
Da im
FinGraph-Schema nicht definiert ist, was einehigh-risk transferist (was in Ihrer Geschäftslogik eine Überweisung von200oder mehr auf ein gesperrtes Konto bedeutet, wobeiis_blocked = true), wendet QueryData entweder die Filter für gesperrte Konten und Betragsschwellenwerte nicht an oder wendet seine eigene Interpretation des Begriffs an. QueryData könnte beispielsweise einen Betragsschwellenwert erfinden, der keine Zeilen zurückgibt, oder den Begriff ignorieren und eine Abfrage wie die folgende generieren:-- Returning transfers initiated by Alex because 'high-risk' is not defined in the schema. GRAPH FinGraph MATCH (p:Person {name: 'Alex'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account) RETURN src.id AS source_account_id, dst.id AS destination_account_id, t.amount AS transfer_amount, t.order_number;Dadurch werden beide Übertragungen von Alex zurückgegeben, einschließlich der Übertragung von
100, die den Schwellenwert nicht erreicht:+-------------------+------------------------+-----------------+-----------------+ | source_account_id | destination_account_id | transfer_amount | order_number | +-------------------+------------------------+-----------------+-----------------+ | 7 | 16 | 300 | 304330008004315 | | 7 | 16 | 100 | 304120005529714 | +-------------------+------------------------+-----------------+-----------------+Stellen Sie eine Frage, die sich auf ein Land bezieht:
./query_data.sh "Find accounts owned by people from Czech Republic"
Ohne Kontext oder Wertverknüpfung generiert QueryData eine GQL-Abfrage, die nach
'Czech Republic'mit einem Leerzeichen filtert. Da das AttributPerson.countryinFinGraphden Wert als'Czech_Republic'mit einem Unterstrich speichert, gibt die Abfrage keine Zeilen zurück:GRAPH FinGraph MATCH (p:Person {country: 'Czech Republic'})-[:Owns]->(a:Account) RETURN p.name AS owner_name, a.id AS account_id, a.nick_name;
Kontext für das Kontextset generieren
In diesem Abschnitt bereiten Sie Ihre lokale Umgebung vor und verwenden den Kontext-Engineering-Agenten, um eine Kontextset-Datei (context_set.json) für den Eigenschaftsgraphen FinGraph in Ihrer Spanner-Datenbank zu erstellen.
Umgebung einrichten
So richten Sie Ihre Umgebung für den Kontext-Engineering-Agenten ein:
- Installieren Sie die Antigravity CLI. Weitere Informationen finden Sie unter Erste Schritte mit Antigravity CLI.
- Installieren Sie die Google Cloud CLI.
Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) einrichten Führen Sie im Terminal den folgenden Befehl aus, um sich zu authentifizieren:
gcloud auth application-default loginStarten Sie in Ihrem Terminal die Antigravity CLI:
agyRichten Sie die Datenbankverbindung für Ihre Spanner-Datenbank ein. Geben Sie einen Prompt ein, der explizit angibt, dass Sie Kontext für die Property-Graphen in Ihrer Spanner-Datenbank generieren, und der den Namen des Property-Graphen
FinGraphenthält, damit der Agent den GQL-spezifischen Kontext-Engineering-Workflow auslöst:Help me set up the database connection for the FinGraph property graph in my Spanner database.Folgen Sie der Anleitung des KI-Agenten, um
autoctx/tools.yamlundautoctx/state.mdzu erstellen. Öffnen Sie dannautoctx/state.mdund prüfen Sie, ob der Abschnitt## Active Databasedie Zeile- **Graph Ids**: ["FinGraph"]enthält. Der Kontext-Engineering-Agent liest die Namen der Eigenschaftsgraphen aus dieser Zeile, wenn er Bewertungskonfigurationen generiert. Weitere Informationen zutools.yamlfinden Sie in der Dokumentation zur MCP Toolbox.Führen Sie den folgenden Befehl in der Antigravity CLI aus, um die Konfiguration nach dem Erstellen von
autoctx/tools.yamlneu zu laden:/mcpWählen Sie
toolboxund dannRestartaus.Prüfen Sie, ob die MCP Toolbox und das Plug-in für den Context Engineering-Agenten verbunden und einsatzbereit sind:
/mcp
GQL-Vorlagenkontext generieren
Um das Problem zu beheben, dass QueryData den Geschäftsbegriff high-risk transfers nicht erkannt hat, definieren Sie high-risk transfers in der Kontextsatzdatei als Überweisungen von 200 oder mehr, die an ein gesperrtes Konto (dst.is_blocked = true) gesendet wurden.
So generieren Sie den GQL-Vorlagenkontext:
Geben Sie den folgenden Prompt in das Agenten-Framework ein und geben Sie an, dass
FinGraphein Property-Graph in Ihrer Spanner-Datenbank ist:For the FinGraph property graph in my Spanner database, generate a GQL template for the question: "Find all high-risk transfers initiated by Alex" with the following GQL query: GRAPH FinGraph MATCH (p:Person {name: 'Alex'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;Der Agent wandelt Ihre Eingabe in eine parametrisierte GQL-Vorlage um, die für alle Personennamen gilt. Weitere Informationen finden Sie unter Kontextsätze – Übersicht.
Prüfen Sie die generierte GQL-Abfragevorlage und geben Sie dann den Prompt
Save it to context_set.jsonein. Der Agent erstelltcontext_set.jsonin Ihrem Verzeichnis mit folgendem Inhalt:{ "templates": [ { "nl_query": "Find all high-risk transfers initiated by Alex", "sql": "GRAPH FinGraph MATCH (p:Person {name: 'Alex'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;", "intent": "Find all high-risk transfers initiated by Alex", "manifest": "Find all high-risk transfers initiated by a given person", "parameterized": { "parameterized_sql": "GRAPH FinGraph MATCH (p:Person {name: ?})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;", "parameterized_intent": "Find all high-risk transfers initiated by ?" } } ] }
Suchkontext für Facetten und Werte generieren
In diesem Abschnitt fügen Sie context_set.json ein GQL-Attribut und zwei GRAPH_TABLE-Wert-Suchanfragen hinzu. Die Vorlage, die Sie im vorherigen Abschnitt hinzugefügt haben, beantwortet Fragen, die dieselbe Struktur haben wie „Finde alle von Alex initiierten Übertragungen mit hohem Risiko“. Die Facette erfasst das Muster für gesperrte Konten, sodass QueryData es auch auf Fragen anwenden kann, die nicht mit der Vorlage übereinstimmen, z. B. „Finde alle Geldtransfers, an denen ein gesperrtes Konto beteiligt ist“. Mit der Wertsuche kann QueryData Wertphrasen wie Czech Republic dem gespeicherten Wert Czech_Republic in Person.country zuordnen und Konto-Spitznamen in Account.nick_name unabhängig von der Groß-/Kleinschreibung abgleichen.
Geben Sie den folgenden Prompt in das Agenten-Framework ein und geben Sie an, dass
FinGraphein Property-Graph in Ihrer Spanner-Datenbank ist:For the FinGraph property graph in my Spanner database, generate a GQL facet with the GQL clause "MATCH (account:Account)-[transfer:Transfers]-(:Account {is_blocked: true})" for intent "transfers involving a blocked account". Then generate two GRAPH_TABLE value searches on FinGraph: one on Person.country that ignores case and treats underscores as spaces, with concept type "Person country", and one on Account.nick_name that ignores case, with concept type "Account nickname". Validate the value search queries against the database, and then append the facet and value searches to context_set.json.Sehen Sie sich die aktualisierte Datei
context_set.jsonan, die jetzt die GQL-Vorlage, die GQL-Facette und die Definitionen für die Wertsuche enthält:{ "templates": [ { "nl_query": "Find all high-risk transfers initiated by Alex", "sql": "GRAPH FinGraph MATCH (p:Person {name: 'Alex'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;", "intent": "Find all high-risk transfers initiated by Alex", "manifest": "Find all high-risk transfers initiated by a given person", "parameterized": { "parameterized_sql": "GRAPH FinGraph MATCH (p:Person {name: ?})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;", "parameterized_intent": "Find all high-risk transfers initiated by ?" } } ], "facets": [ { "sql_snippet": "MATCH (account:Account)-[transfer:Transfers]-(:Account {is_blocked: true})", "intent": "transfers involving a blocked account", "manifest": "transfers involving a blocked account", "parameterized": { "parameterized_sql_snippet": "MATCH (account:Account)-[transfer:Transfers]-(:Account {is_blocked: true})", "parameterized_intent": "transfers involving a blocked account" } } ], "value_searches": [ { "query": "SELECT value, columns, concept_type, distance, context FROM GRAPH_TABLE(FinGraph MATCH (p:Person) WHERE LOWER(REPLACE(p.country, '_', ' ')) = LOWER(REPLACE($value, '_', ' ')) RETURN DISTINCT p.country AS value, 'FinGraph.Person.country' AS columns, 'Person country' AS concept_type, 0 AS distance, JSON '{}' AS context)", "concept_type": "Person country", "description": "Match for country names on Person nodes in FinGraph that ignores case and treats underscores as spaces" }, { "query": "SELECT value, columns, concept_type, distance, context FROM GRAPH_TABLE(FinGraph MATCH (a:Account) WHERE LOWER(a.nick_name) = LOWER($value) RETURN DISTINCT a.nick_name AS value, 'FinGraph.Account.nick_name' AS columns, 'Account nickname' AS concept_type, 0 AS distance, JSON '{}' AS context)", "concept_type": "Account nickname", "description": "Case-insensitive match for account nicknames on Account nodes in FinGraph" } ] }Bei jeder Wertsuche wird der Operator
GRAPH_TABLEverwendet, um ein Knotenlabel inFinGraphabzugleichen. Zurückgegeben werden der gespeicherte Attributwert, der Attributspeicherort (FinGraph.Person.country), der Konzepttyp, eine Distanz von0für eine Übereinstimmung und ein leerer JSON-Kontext. Weitere Informationen finden Sie unter Suchanfragen für Werte.
Kontextsatzdatei in QueryData hochladen
In diesem Abschnitt laden Sie die Datei context_set.json in den Kontextsatz fingraph-assistant in Spanner Studio hoch.
Rufen Sie in der Google Cloud Console die Seite „Spanner“ auf.
Wählen Sie Ihre Instanz aus der Liste und dann Ihre Spanner-Datenbank aus.
Klicken Sie im Navigationsmenü auf Spanner Studio.
Klicken Sie im Bereich Explorer neben Ihrem
fingraph-assistant-Kontextsatz auf Aktionen ansehen.Klicken Sie auf Kontextgruppe bearbeiten.
Optional: Bearbeiten Sie die Beschreibung der Kontextgruppe.
Klicken Sie im Abschnitt Kontextsatzdatei hochladen auf Durchsuchen und wählen Sie die von Ihnen generierte
context_set.json-Datei aus.Klicken Sie auf Speichern.
GQL-Abfragen mit QueryData generieren
In diesem Abschnitt rufen Sie die QueryData REST API mit dem Kontext fingraph-assistant auf, um zu prüfen, ob QueryData Geschäftsbegriffe wie high-risk transfers korrekt übersetzt und Czech Republic in GQL-Abfragen in Czech_Republic auflöst.
- Suchen Sie die Kontextset-ID für
fingraph-assistant. Eine Anleitung finden Sie unter Kontextsatz-ID ermitteln. Legen Sie die Umgebungsvariable
CONTEXT_SET_IDfest, damitquery_data.shIhren Kontextsatz sendet:export CONTEXT_SET_ID="CONTEXT_SET_ID"
Ersetzen Sie
CONTEXT_SET_IDdurch die vollständige Kontext-Set-ID, z. B.projects/my-project/locations/us-central1/contextSets/fingraph-assistant.Stelle die Frage zu Überweisungen mit hohem Risiko noch einmal:
./query_data.sh "Find all high-risk transfers initiated by Alex"
Die generierte GQL-Abfrage wendet jetzt den Filter für blockierte Zielkonten (
is_blocked: true) und den Schwellenwert für den Betrag (t.amount >= 200) an:GRAPH FinGraph MATCH (p:Person {name: 'Alex'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;Dadurch wird die Übertragung von
100durch Alex an das blockierte Konto16ausgeschlossen und es werden Ergebnisse wie die folgenden zurückgegeben:+------------------------+-----------------+ | destination_account_id | transfer_amount | +------------------------+-----------------+ | 16 | 300 | +------------------------+-----------------+Stellen Sie eine ähnliche Frage für
Dana:./query_data.sh "What are the high-risk transfers initiated by Dana?"
Da die GQL-Vorlage in
context_set.jsonparametrisiert ist ({name: ?}), wendet QueryData dieselbehigh-risk transfers-Definition aufDanaan:GRAPH FinGraph MATCH (p:Person {name: 'Dana'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;Dadurch wird die Übertragung von
500durch Dana an das nicht blockierte Konto7ausgeschlossen und es werden Ergebnisse wie die folgenden zurückgegeben:+------------------------+-----------------+ | destination_account_id | transfer_amount | +------------------------+-----------------+ | 16 | 200 | +------------------------+-----------------+Stellen Sie die Frage nach dem Land noch einmal:
./query_data.sh "Find accounts owned by people from Czech Republic"
QueryData führt die Suche nach dem Wert
Person countryaus, verknüpftCzech Republicmit dem gespeicherten WertCzech_Republicund generiert eine Abfrage, die etwa so aussieht:GRAPH FinGraph MATCH (p:Person {country: 'Czech_Republic'})-[:Owns]->(a:Account) RETURN p.name AS owner_name, a.id AS account_id, a.nick_name;Dies gibt Ergebnisse wie die folgenden zurück:
+------------+------------+----------------+ | owner_name | account_id | nick_name | +------------+------------+----------------+ | Dana | 20 | Rainy Day Fund | +------------+------------+----------------+Stellen Sie eine Frage, die die Facette „blocked-account“ verwendet:
./query_data.sh "Find all money transfers involving a blocked account."
QueryData verwendet die Facette, um Übertragungen in beide Richtungen abzugleichen, die das gesperrte Konto
16betreffen, und gibt vier Übertragungen zurück.
QueryData in Ihre Anwendung einbinden
In diesem Abschnitt erstellen Sie eine Konversations-KI-Daten-Agenten-Anwendung für FinGraph mit dem Agent Development Kit (ADK), der MCP Toolbox und Ihrem fingraph-assistant-Kontextset. Wenn Sie die GQL-Abfragegenerierung für Spanner Graph aktivieren möchten, definieren Sie in Ihrer tools.yaml-Datei ein benutzerdefiniertes HTTP-Tool, das die QueryData REST API mit graph_ids in spanner_reference.database_reference aufruft.
- Laden Sie die MCP Toolbox in Version 1.4.0 oder höher herunter. Die MCP Toolbox stellt die
QueryDataREST API als MCP-Tool bereit, mit dem Anwendungen eine Verbindung herstellen können. Richten Sie Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) ein:
gcloud auth application-default loginErstellen Sie eine
tools.yaml-Konfigurationsdatei, die eine HTTP-Quelle für die konversationelle Analyse-API und ein HTTP-Tool definiert, das die MethodeQueryDataaufruft. Geben Sie im Anfragetext unterspanner_reference.database_referencedas Feldgraph_ids(auf["FinGraph"]festgelegt) an:kind: source name: gda-rest-source type: http baseUrl: https://geminidataanalytics.googleapis.com timeout: 120s headers: Authorization: Bearer ${GDA_ACCESS_TOKEN} Content-Type: application/json x-goog-user-project: ${PROJECT_ID} --- kind: tool name: fingraph_query_data_tool type: http source: gda-rest-source method: POST path: /v1beta/projects/${PROJECT_ID}/locations/global:queryData description: Use this tool to send natural language questions about the FinGraph property graph to the QueryData API and receive GQL queries, query results, natural language answers, and explanations. requestBody: | { "parent": "projects/${PROJECT_ID}/locations/global", "prompt": {{json .query}}, "context": { "datasource_references": { "spanner_reference": { "database_reference": { "engine": "GOOGLE_SQL", "project_id": "${PROJECT_ID}", "instance_id": "${INSTANCE_ID}", "database_id": "${DATABASE_ID}", "graph_ids": ["FinGraph"] }, "agent_context_reference": { "context_set_id": "${CONTEXT_SET_ID}" } } } }, "generation_options": { "generate_query_result": true, "generate_natural_language_answer": true, "generate_explanation": true, "generate_disambiguation_question": true } } bodyParams: - name: query type: string description: A natural language question about the FinGraph property graph.Die MCP Toolbox ersetzt die
${...}-Verweise durch die Werte der entsprechenden Umgebungsvariablen, wenn sietools.yamllädt, und ersetzt{{json .query}}durch die Frage, die der Agent an das Tool sendet, codiert als JSON-String.Legen Sie im Terminal, in dem Sie die MCP Toolbox ausführen, die Umgebungsvariablen fest, auf die
tools.yamlverweist:export PROJECT_ID="PROJECT_ID" export INSTANCE_ID="INSTANCE_ID" export DATABASE_ID="DATABASE_ID" export CONTEXT_SET_ID="CONTEXT_SET_ID" export GDA_ACCESS_TOKEN="$(gcloud auth application-default print-access-token)"
Ersetzen Sie Folgendes:
PROJECT_ID: Projekt-ID in Google Cloud .INSTANCE_ID: die ID Ihrer Cloud Spanner-Instanz.DATABASE_ID: die ID der Spanner-Datenbank, dieFinGraphenthält.CONTEXT_SET_ID: die vollständige Kontext-Set-ID vonfingraph-assistant.
Führen Sie den MCP Toolbox-Server mit der Datei
tools.yamlaus:./toolbox --config "tools.yaml"Erstellen Sie eine ADK-Anwendung, die das Tool
fingraph_query_data_toolüber das MCP Toolbox Python SDK aufruft:Erstellen Sie ein Verzeichnis für die Anwendung, z. B.
fingraph-assistant-app, und wechseln Sie dorthin:mkdir fingraph-assistant-appcd fingraph-assistant-appErstellen Sie eine virtuelle Umgebung und installieren Sie die erforderlichen Pakete:
python3 -m venv .venvsource .venv/bin/activatepip install toolbox-corepip install google-genaipip install google-adkADK-Agenten erstellen:
adk create my_agentWählen Sie das Modell
gemini-2.5-flashaus, wählen Sie Google AI aus und geben Sie Ihren Gemini API-Schlüssel ein. Weitere Informationen finden Sie unter Gemini API-Schlüssel verwenden.Ersetzen Sie den Inhalt von
my_agent/agent.pydurch den folgenden Beispielcode für die Financial Graph 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 factual financial graph data assistant for FinGraph. Your goal is to help users analyze account ownership, money transfers, and risk patterns by providing accurate information with a helpful, professional tone. - Always call the Query Data Tool first to answer questions about the graph data, including questions with domain-specific terms (such as "high-risk"), because the tool resolves domain definitions against the database context. Ask the user to clarify only if the tool returns a disambiguation question or fails to generate a valid query. # 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 GQL. 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 and guide the user toward 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 graph database query. Outputs: (all optional) 1. disambiguationQuestion: Clarification questions or comments where the tool needs the user's input. 2. generatedQuery: The generated GQL query for the user query. 3. intentExplanation: An explanation for why the tool produced `generatedQuery`. 4. queryResult: The result of executing `generatedQuery`. 5. naturalLanguageAnswer: The natural language answer that summarizes the `query` and `queryResult`. Usage guidance: 1. If `disambiguationQuestion` is produced, solicit the needed inputs from the user and try the tool with a new `query` that includes the clarification. 2. If `naturalLanguageAnswer` is produced, use `intentExplanation` and `generatedQuery` 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("fingraph_query_data_tool") root_agent = Agent( model="gemini-2.5-flash", name="root_agent", instruction=INSTRUCTION, tools=cast(list[ToolUnion], [mcp_tool]), )
Starten Sie den ADK-Webserver unter
http://127.0.0.1:8000:adk web --port 8000Geben Sie in der ADK-Web-UI eine Frage ein, die mehrere Schritte im Diagramm erfordert:
Who did Dana transfer money to, and what were the amounts?Der KI-Agent ruft das
fingraph_query_data_tool-Tool auf, das die Frage an dieQueryData-REST API sendet, wobeigraph_idsaufFinGraphgesetzt ist. QueryData führt die generierte GQL-Abfrage aus und der Agent gibt eine Antwort ähnlich der folgenden zurück:Dana transferred money from account 20 to the following recipients: * Alex (account 7): 500 * Lee (account 16): 200Geben Sie eine Frage ein, die die GQL-Vorlage
high-risk transfersverwendet, die Sie dem Kontextset hinzugefügt haben:What are the high-risk transfers initiated by Alex?Basierend auf der GQL-Vorlage in
fingraph-assistantidentifiziert QueryData Überweisungen von mindestens200auf ein gesperrtes Konto und der Agent gibt eine Antwort ähnlich der folgenden zurück:Here is the high-risk transfer initiated by Alex (transfers of 200 or more to a blocked account): * Blocked destination account 16: amount 300
Leistung des KI-Agenten iterieren
In der ADK-Web-UI können Sie die Anfrage- und Antwortnutzlasten des fingraph_query_data_tool-Tools prüfen. Maximieren Sie im Navigationsbereich auf dem Tab Ereignis den Eintrag functionResponse, um die generierte GQL-Abfrage FinGraph (generatedQuery), queryResult, intentExplanation, disambiguationQuestion und naturalLanguageAnswer zu prüfen. Die QueryData REST API gibt diese Feldnamen in camelCase zurück.
Antwortgenauigkeit optimieren
Sie können die Accuracy der Antworten von QueryData kontinuierlich verbessern, indem Sie GQL-Vorlagen, Facetten und Wertsuchen hinzufügen. Verwenden Sie den Kontext-Engineering-Agenten, um aktualisierten Kontext für den Eigenschaftsgraphen FinGraph in Ihrer Spanner-Datenbank zu generieren und zu bewerten. Laden Sie dann die aktualisierte Kontextdatei in Spanner Studio hoch. Weitere Informationen finden Sie unter Kontextsätze in Spanner Studio verwalten.
Mehrere KI-Agenten
In Ihrer Entwicklungsumgebung können Sie A/B-Tests für mehrere Spanner Graph-Kontextsätze durchführen, indem Sie mehrere HTTP-Tools in Ihrer tools.yaml-Datei definieren (z. B. fingraph_query_data_tool_v1 und fingraph_query_data_tool_v2). Im Anfragetext jedes Tools wird graph_ids auf ["FinGraph"] und ein anderer context_set_id festgelegt.
Bereinigen
Löschen Sie die von Ihnen erstellten Ressourcen, um weitere Kosten zu vermeiden, wenn Sie diese Anleitung abgeschlossen haben.
Kontextset löschen
Bevor Sie die Spanner-Datenbank oder -Instanz löschen, müssen Sie das Kontextset fingraph-assistant löschen:
Rufen Sie in der Google Cloud Console die Seite „Spanner“ auf.
Wählen Sie Ihre Instanz aus der Liste und dann Ihre Spanner-Datenbank aus.
Klicken Sie im Navigationsmenü auf Spanner Studio.
Klicken Sie im Bereich Explorer neben
fingraph-assistantauf Aktionen anzeigen.Klicken Sie auf Kontextgruppe löschen, geben Sie
fingraph-assistantin das Bestätigungsfeld ein und klicken Sie auf Bestätigen.
Datenbank und Instanz löschen
Wenn Sie den Property-Graphen FinGraph, die Cloud Spanner-Datenbank und die Cloud Spanner-Instanz löschen möchten, folgen Sie der Anleitung unter Cloud Spanner Graph einrichten und abfragen: Bereinigen.
Nächste Schritte
- Weitere Informationen zu Kontextgruppen für Spanner Graph
- Kontextsets mit dem Context-Engineering-Agenten erstellen
- Selbst erstellten Kontext für Datenbank-Datenquellen definieren