QueryData testen

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

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.

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

    Spanner aufrufen

  2. Wählen Sie eine Instanz aus der Liste und dann eine Datenbank aus.

  3. Klicken Sie im Navigationsmenü auf Spanner Studio.

  4. Klicken Sie im Bereich Explorer neben dem verwendeten Kontextset auf Aktionen ansehen.

  5. Klicken Sie auf Kontextgruppe bearbeiten.

  6. 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:

  1. Erstellen Sie eine Datei mit dem Namen request.json und 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.
  2. 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
    
  3. Prüfen Sie in der Antwort das Feld generatedQuery (GRAPH FinGraph MATCH ...) auf Richtigkeit und das Feld queryResult auf 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:

  1. Klicken Sie im Bereich Explorer neben Ihrem Kontextsatz auf Aktionen ansehen.
  2. Klicken Sie auf Kontextdatei herunterladen.
  3. 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.
  4. Klicken Sie im Bereich Explorer neben dem verwendeten Kontextsatz auf Aktionen ansehen.
  5. Klicken Sie auf Kontextgruppe bearbeiten.
  6. Klicken Sie im Abschnitt Kontextsatzdatei hochladen auf Durchsuchen und wählen Sie die aktualisierte Kontextsatzdatei aus.
  7. Klicken Sie auf Speichern, um den Kontextsatz zu aktualisieren.
  8. 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 Format projects/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-Datenbanken GOOGLE_SQL fest.
          • 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 Sie graph_ids angeben, wird QueryData angewiesen, GQL-Abfragen für die angegebenen Attributgraphen zu generieren. Wenn Sie graph_ids weglassen, 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 Sie true fest, um die generierte GQL-Abfrage auszuführen und die Abfrageergebnisse zurückzugeben.
    • generate_natural_language_answer: Optional. Wenn auf true festgelegt, wird eine Antwort in natürlicher Sprache generiert, die die Abfrageergebnisse zusammenfasst.
    • generate_explanation: Optional. Wenn auf true gesetzt, wird eine Erklärung der GQL-Abfrage generiert.
    • generate_disambiguation_question: Optional. Wenn auf true gesetzt, 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**"
}

Nächste Schritte