In diesem Dokument wird beschrieben, wie Sie QueryData für Spanner Graph testen, indem Sie die Methode QueryData der konversationellen Analyse API aufrufen, und wie Sie die Kontextdatei aktualisieren. Sie können die Fähigkeit von QueryData testen, GQL-Abfragen (Graph Query Language) aus Fragen in natürlicher Sprache zu generieren. Wenn eine generierte GQL-Abfrage nicht korrekt ist, können Sie die Kontextdatei aktualisieren.
Weitere Informationen zu Kontextgruppen für Spanner Graph finden Sie unter Kontextgruppen – Übersicht.
Hinweis
- Achten Sie darauf, dass in Ihrer Spanner-Datenbank das Eigenschaftsgrafikschema
FinGraphund Beispieldaten konfiguriert sind. Eine Anleitung zum Erstellen des SchemasFinGraphund zum Einfügen der Beispieldaten finden Sie unter Spanner Graph einrichten und abfragen. - Prüfen Sie, ob bereits ein Kontextsatz erstellt und die Kontextsatzdatei in die Datenbank hochgeladen wurde. Weitere Informationen finden Sie unter Kontextsätze in Spanner Studio verwalten.
- Installieren und initialisieren Sie die Google Cloud CLI.
ID des vorhandenen Kontextsets ermitteln
Wenn Sie QueryData mit Ihrem Kontextset testen oder eine Datenanwendung mit QueryData verbinden möchten, benötigen Sie die Kontextset-ID.
Rufen Sie in der Google Cloud Console die Seite „Spanner“ auf.
Wählen Sie eine Instanz aus der Liste und dann eine Datenbank aus.
Klicken Sie im Navigationsmenü auf Spanner Studio.
Klicken Sie im Bereich Explorer neben dem verwendeten Kontextset auf Aktionen ansehen.
Klicken Sie auf Kontextgruppe bearbeiten.
Notieren Sie sich die Kontextset-ID unter Kontextset-ID. Das Format der Kontext-Set-ID ähnelt
projects/my-project/locations/us-central1/contextSets/fingraph-assistant.
QueryData mit HTTP POST testen
Wenn Sie QueryData für Spanner Graph testen möchten, senden Sie eine QueryData-HTTP-POST-Anfrage, die das Feld graph_ids und Ihre Kontextsatz-ID enthält:
Erstellen Sie eine Datei mit dem Namen
request.jsonund dem folgendem Inhalt:{ "prompt": "Find everyone that Dana transferred money to, along with the account IDs and transfer amounts.", "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 } }
Ersetzen Sie Folgendes:
PROJECT_ID: Projekt-ID in Google Cloud .INSTANCE_ID: Ihre Spanner-Instanz-ID.DATABASE_ID: Ihre Spanner-Datenbank-ID.CONTEXT_SET_ID: die vollständige ID des Kontextsets, die Sie unter ID des Kontextsets ermitteln notiert haben.
Senden Sie diese Anfrage:
curl -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 @request.json
Prüfen Sie in der Antwort das Feld
generatedQuery(GRAPH FinGraph MATCH ...) auf Richtigkeit und das FeldqueryResultauf die zurückgegebenen Zeilen.
Wenn Sie andere Fragen testen möchten, ändern Sie den Wert prompt in request.json und senden Sie die Anfrage noch einmal. Wenn Sie sehen möchten, wie sich QueryData ohne erstellten Kontext verhält, entfernen Sie das Objekt agent_context_reference.
Wenn Sie prüfen möchten, ob QueryData Ihren Kontextsatz verwendet, stellen Sie eine Frage, die davon abhängt (z. B. „Wem gehört das Konto für schlechte Zeiten?“), und vergleichen Sie die Antworten mit und ohne das agent_context_reference-Objekt. Ohne den Kontext filtert QueryData möglicherweise nach 'rainy day' und gibt keine Zeilen zurück. Wenn der Kontext festgelegt ist, wird nach 'Rainy Day Fund' gefiltert und Dana zurückgegeben.
Vorhandenes Kontextset herunterladen und aktualisieren
Wenn die Testantworten zeigen, dass die generierte GQL-Abfrage für eine Frage in natürlicher Sprache verbessert werden muss, laden Sie die vorhandene Kontextsatzdatei herunter. Anschließend können Sie die GQL-Abfragevorlagen, Facetten oder Wertsuchen prüfen und aktualisieren und die aktualisierte Kontextsatzdatei in den Kontextsatz hochladen.
So laden Sie einen Kontextsatz herunter und aktualisieren ihn:
- Klicken Sie im Bereich Explorer neben Ihrem Kontextsatz auf Aktionen ansehen.
- Klicken Sie auf Kontextdatei herunterladen.
- Folgen Sie der Anleitung unter Kontextsets mit dem Context-Engineering-Agenten erstellen, um das Kontextset mit zusätzlichen Paaren aus natürlicher Sprache und GQL-Abfragen zu aktualisieren.
- Klicken Sie im Bereich Explorer neben dem verwendeten Kontextsatz auf Aktionen ansehen.
- Klicken Sie auf Kontextgruppe bearbeiten.
- Klicken Sie im Abschnitt Kontextsatzdatei hochladen auf Durchsuchen und wählen Sie die aktualisierte Kontextsatzdatei aus.
- Klicken Sie auf Speichern, um den Kontextsatz zu aktualisieren.
- Testen Sie QueryData noch einmal, um die generierte GQL-Abfrage zu prüfen.
Wenn Sie mit der Genauigkeit der Antworten zufrieden sind, können Sie den Endpunkt QueryData verwenden, um Ihre Anwendung mit dem Kontextset zu verbinden.
QueryData mit Ihrer Anwendung verbinden
Legen Sie die Kontext-Set-ID und das Ziel-graph_ids im Methodenaufruf QueryData fest, um den erstellten Kontext bereitzustellen und die GQL-Abfragegenerierung für Spanner Graph zu aktivieren. Weitere Informationen zur Verwendung von QueryData mit Datenbank-Datenquellen finden Sie unter Kontext für Daten-Agenten für Datenbank-Datenquellen definieren. Ein Beispiel, in dem eine Agentenanwendung über ein benutzerdefiniertes HTTP-Tool, das die QueryData REST API aufruft, mit QueryData verbunden wird, finden Sie unter QueryData in eine Anwendung einbinden.
Beispiel für eine QueryData-Anfrage mit selbst erstelltem Kontext
Das folgende Beispiel zeigt eine QueryData-Anfrage mit der Datenbankdatenquelle spanner_reference für den Attributgraphen FinGraph. Sie müssen graph_ids in spanner_reference.database_reference angeben, damit QueryData Ihren Eigenschaftsgraphen als Ziel verwendet und GQL-Abfragen generiert. Das Feld agent_context_reference.context_set_id verweist auf den in der Datenbank gespeicherten, vordefinierten Kontext:
{ "parent": "projects/my-project/locations/global", "prompt": "Find everyone that Dana transferred money to, along with the account IDs and transfer amounts.", "context": { "datasource_references": { "spanner_reference": { "database_reference": { "engine": "GOOGLE_SQL", "project_id": "my-project", "instance_id": "my-instance", "database_id": "fin-graph-db", "graph_ids": [ "FinGraph" ] }, "agent_context_reference": { "context_set_id": "projects/my-project/locations/us-central1/contextSets/fingraph-assistant" } } } }, "generation_options": { "generate_query_result": true, "generate_natural_language_answer": true, "generate_disambiguation_question": true, "generate_explanation": true } }
Der Anfragetext enthält die folgenden Felder:
parent: Optional. Das Projekt und der Standort der Anfrage im Formatprojects/PROJECT_ID/locations/LOCATION. Verwenden Sie dasselbe Projekt und denselben Standort wie in der Anfrage-URL.prompt: Die Frage des Endnutzers in natürlicher Sprache.context: Enthält Informationen zu den Datenquellen.datasource_references: Gibt die Datenquelle an. Dieses Feld ist ein Objekt, keine Liste.spanner_reference: Erforderlich, wenn eine Spanner-Datenbank abgefragt wird.database_reference: Gibt Informationen zu Ihrer Spanner-Datenbank und Ihren Eigenschaftsgraphen an.engine: Der Dialekt der Datenbank. Legen Sie für Spanner Graph-DatenbankenGOOGLE_SQLfest.project_id: Die Projekt-ID der Cloud Spanner-Instanz.instance_id: Die Instanz-ID der Spanner-Instanz.database_id: Die ID der Spanner-Datenbank.graph_ids: Erforderlich für Spanner Graph. Eine Liste der Namen von Attributgraphen in der Datenbank, die abgefragt werden sollen (z. B.["FinGraph"]). Wenn Siegraph_idsangeben, wird QueryData angewiesen, GQL-Abfragen für die angegebenen Attributgraphen zu generieren. Wenn Siegraph_idsweglassen, generiert QueryData stattdessen nur relationale SQL-Abfragen für die zugrunde liegenden Tabellen.
agent_context_reference: Links zu verfasstem Kontext in der Datenbank.context_set_id: Die vollständige Kontextsatz-ID des in der Datenbank gespeicherten Kontexts, z. B.projects/my-project/locations/us-central1/contextSets/fingraph-assistant.
generation_options: Konfiguriert den Typ der zu generierenden Ausgabe.generate_query_result: Legen Sietruefest, um die generierte GQL-Abfrage auszuführen und die Abfrageergebnisse zurückzugeben.generate_natural_language_answer: Optional. Wenn auftruefestgelegt, wird eine Antwort in natürlicher Sprache generiert, die die Abfrageergebnisse zusammenfasst.generate_explanation: Optional. Wenn auftruegesetzt, wird eine Erklärung der GQL-Abfrage generiert.generate_disambiguation_question: Optional. Wenn auftruegesetzt, werden Fragen zur Mehrdeutigkeitsauflösung generiert, wenn der Prompt in natürlicher Sprache mehrdeutig ist.
QueryData-Beispielantwort
Das folgende Beispiel zeigt eine erfolgreiche Antwort auf einen QueryData-Aufruf für das Attributdiagramm FinGraph. Die REST API gibt Feldnamen in camelCase zurück, z. B. generatedQuery und queryResult. Da die GQL-Generierung nicht deterministisch ist, können sich die generierte Abfrage, die Spaltennamen und der Antworttext zwischen den Aufrufen unterscheiden.
{
"generatedQuery": "GRAPH `FinGraph` MATCH (p:`Person` {`name`: 'Dana'})-[:`Owns`]->(src:`Account`)-[t:`Transfers`]->(dst:`Account`) MATCH (p_recipient:`Person`)-[:`Owns`]->(dst) RETURN DISTINCT p_recipient.`name` AS recipient_name, dst.`id` AS recipient_account_id, t.`amount` AS transfer_amount",
"intentExplanation": "To find everyone Dana transferred money to, we identify the person named Dana and locate the accounts they own. We trace the transfer relationships from Dana's accounts to any destination accounts, identifying the specific amounts sent and the IDs of those receiving accounts. Finally, we find the individuals who own those receiving accounts to present their names along with the account details and transfer amounts.",
"queryResult": {
"columns": [
{
"name": "recipient_name",
"type": "STRING"
},
{
"name": "recipient_account_id",
"type": "INT64"
},
{
"name": "transfer_amount",
"type": "FLOAT64"
}
],
"rows": [
{
"values": [
{
"value": "Alex"
},
{
"value": "7"
},
{
"value": "500"
}
]
},
{
"values": [
{
"value": "Lee"
},
{
"value": "16"
},
{
"value": "200"
}
]
}
],
"totalRowCount": "2"
},
"naturalLanguageAnswer": "Based on the transaction records, Dana transferred money to the following recipients:\n\n* **Alex**: Account ID **7**, with a transfer amount of **500**\n* **Lee**: Account ID **16**, with a transfer amount of **200**"
}