QueryData testen

In diesem Dokument wird beschrieben, wie Sie QueryData testen und die Kontextdatei aktualisieren. Sie können die Fähigkeit von QueryData testen, SQL-Abfragen aus Fragen in natürlicher Sprache zu generieren. Wenn eine generierte Abfrage nicht korrekt ist, können Sie die Kontextset-Datei aktualisieren.

Weitere Informationen zu Kontextgruppen finden Sie unter Kontextgruppen – Übersicht.

Hinweis

Sie müssen ein Kontextset in Knowledge Catalog erstellt und die Kontextset-Datei in das Kontextset hochgeladen haben. Weitere Informationen finden Sie unter Kontextsätze in AlloyDB Studio verwalten.

Wenn Sie Kontextset-Dateien herunterladen, aktualisieren und hochladen möchten, muss der IAM-Nutzer die Rolle „Dataplex Catalog Editor“ (roles/dataplex.catalogEditor) oder „Dataplex Catalog Admin“ (roles/dataplex.catalogAdmin) für das Projekt haben. Weitere Informationen finden Sie unter Berechtigungen für Kontextgruppen.

QueryData testen

So testen Sie ein QueryData-Objekt:

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

    Zu AlloyDB

  2. Wählen Sie einen Cluster aus der Liste aus.

  3. Klicken Sie im Navigationsmenü auf AlloyDB Studio.

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

  5. Klicken Sie im Bereich Explorer neben dem von Ihnen verwendeten Kontextsatz auf Aktionen ansehen.

  6. Klicken Sie auf Kontextset testen.

  7. Klicken Sie im Abfrageeditor auf SQL mit QueryData generieren mit: CONTEXT_SET_NAME, um den Bereich für die Abfragegenerierung zu öffnen.

  8. Geben Sie im Bereich für die Abfragegenerierung eine Frage in natürlicher Sprache ein, um eine SQL-Abfrage zu generieren, und klicken Sie auf Generieren.

  9. Prüfen Sie die SQL-Abfrage auf Richtigkeit. Klicken Sie auf Einfügen, um die Abfrage dem Editor hinzuzufügen.

Kontextset herunterladen und aktualisieren

Wenn Sie mit der generierten SQL-Abfrage für eine Frage in natürlicher Sprache nicht zufrieden sind, laden Sie die vorhandene Kontextdatei herunter. Anschließend können Sie die Abfragevorlage prüfen und aktualisieren und die aktualisierte Kontextsatzdatei in den Kontextsatz in Knowledge Catalog hochladen.

So laden Sie einen Kontextsatz herunter und aktualisieren ihn:

  1. Klicken Sie im Bereich Explorer neben dem von Ihnen verwendeten Kontextsatz auf Aktionen ansehen.
  2. Klicken Sie auf Kontextdatei herunterladen.
  3. Folgen Sie der Anleitung unter Kontextsets mit dem Context-Engineering-Agenten erstellen, um den Kontext mit zusätzlichen Abfragepaaren zu aktualisieren.
  4. Klicken Sie im Bereich Explorer neben dem von Ihnen verwendeten Kontextsatz auf Aktionen ansehen.
  5. Klicken Sie auf Kontextgruppe bearbeiten.
  6. Klicken Sie im Abschnitt Kontextdatei hochladen auf Durchsuchen und wählen Sie die aktualisierte Kontextdatei aus.
  7. Klicken Sie auf Speichern, um den Kontextsatz zu aktualisieren.

Wenn Sie mit der Genauigkeit der Antworten zufrieden sind, können Sie die Kontext-Set-ID in Anfragen von Ihrer Anwendung an den zustandslosen QueryData-Endpunkt übergeben.

Kontextset-ID ermitteln

Wenn Sie den zustandslosen QueryData-Endpunkt von Ihrer Anwendung aus aufrufen, benötigen Sie die Kontextset-ID, um auf das von Ihnen erstellte Kontextset zu verweisen, das im Knowledge Catalog gespeichert ist.

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

    Zu AlloyDB

  2. Wählen Sie einen Cluster aus der Liste aus.

  3. Klicken Sie im Navigationsmenü auf AlloyDB Studio.

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

  5. Klicken Sie im Bereich Explorer neben dem von Ihnen verwendeten Kontextsatz auf Aktionen ansehen.

  6. Klicken Sie auf Kontextgruppe bearbeiten.

  7. Notieren Sie sich den Ressourcennamen des Kontextsets in Kontextset-ID. Der Endpunkt QueryData unterstützt die folgenden beiden Ressourcennamenformate für Kontextsets in Knowledge Catalog:

    • 6-Segment-Format: projects/PROJECT_ID/locations/LOCATION/contextSets/CONTEXT_SET_ID, z. B. projects/data-agents-project/locations/us-central1/contextSets/bdf_pg_all_templates
    • 8-Segment-Format: projects/PROJECT_ID/locations/LOCATION/contextSetGroups/GROUP_ID/contextSets/CONTEXT_SET_ID@VERSION (z. B. @v1)

QueryData mit Ihrer Anwendung verbinden

Legen Sie die Kontext-Set-ID im Methodenaufruf QueryData fest, um erstellten Kontext aus Knowledge Catalog für Datenbankdatenquellen wie AlloyDB, Spanner, Cloud SQL for MySQL, Cloud SQL for PostgreSQL, Firestore und Bigtable bereitzustellen. Weitere Informationen finden Sie unter Kontext für Daten-Agenten für Datenbank-Datenquellen definieren.

Nachdem Sie den Kontextsatz getestet haben, können Sie in Ihrem zustandslosen QueryData-Aufruf auf die Datenbankdatenquelle und den Kontextsatz verweisen.

Beispiel für eine QueryData-Anfrage mit selbst erstelltem Kontext

Im folgenden Beispiel wird eine zustandslose QueryData-Anfrage mit der alloydb-Datenbankdatenquelle gesendet. Das Feld agent_context_reference.context_set_id verknüpft die Anfrage mit dem von Ihnen erstellten Kontextset, das im Knowledge Catalog und nicht in Ihrer Datenbank gespeichert ist:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "x-goog-user-project: PROJECT_ID" \
  -H "Content-Type: application/json" \
  https://geminidataanalytics.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION:queryData \
  -d '{
  "prompt": "How many accounts in the Prague region are eligible for loans? A3 contains the data of region.",
  "context": {
    "datasource_references": {
      "alloydb": {
        "database_reference": {
          "project_id": "PROJECT_ID",
          "region": "LOCATION",
          "cluster_id": "CLUSTER_ID",
          "instance_id": "INSTANCE_ID",
          "database_id": "DATABASE_ID"
        },
        "agent_context_reference": {
          "context_set_id": "projects/PROJECT_ID/locations/LOCATION/contextSets/CONTEXT_SET_ID"
        }
      }
    }
  },
  "generation_options": {
    "generate_query_result": true,
    "generate_natural_language_answer": true,
    "generate_disambiguation_question": true,
    "generate_explanation": true
  }
}'

Ersetzen Sie Folgendes:

  • PROJECT_ID: die ID des Google Cloud-Projekts, das für die Anfrage verwendet wird.
  • LOCATION: die Region für die Anfrage, z. B. us-central1.
  • CLUSTER_ID: die Cluster-ID des AlloyDB-Clusters.
  • INSTANCE_ID: Die Instanz-ID der AlloyDB-Instanz.
  • DATABASE_ID: die ID der Datenbank.
  • CONTEXT_SET_ID: die ID Ihres Kontext-Sets.

Der Anfragetext enthält die folgenden Felder:

  • prompt: Die Frage des Endnutzers in natürlicher Sprache.
  • context: Enthält Informationen zu den Datenquellen.
    • datasource_references: Gibt den Typ der Datenquelle an.
      • alloydb: Erforderlich, wenn die Datenbank abgefragt wird.
        • database_reference: Gibt Informationen zu Ihrer Datenbankinstanz an.
          • cluster_id: Die Cluster-ID der Datenbankinstanz.
          • project_id: Die Projekt-ID der Datenbankinstanz.
          • region: Die Region der AlloyDB-Instanz.
          • instance_id: Die Instanz-ID der AlloyDB-Instanz.
          • database_id: Die ID der Datenbank.
        • agent_context_reference: Verknüpft die zustandslose QueryData-Anfrage mit dem von Ihnen erstellten Kontextset, das im Knowledge Catalog und nicht in Ihrer Datenbank gespeichert ist.
          • context_set_id: Der vollständige Ressourcenname des im Knowledge Catalog gespeicherten Kontextsets. Sie können entweder das 6-Segment-Format projects/PROJECT_ID/locations/LOCATION/contextSets/CONTEXT_SET_ID oder das 8-Segment-Format projects/PROJECT_ID/locations/LOCATION/contextSetGroups/GROUP_ID/contextSets/CONTEXT_SET_ID@VERSION (z. B. @v1) angeben.
  • generation_options: Konfiguriert den Typ der zu generierenden Ausgabe.
    • generate_query_result: Legen Sie „true“ fest, um die Abfrageergebnisse zu generieren und zurückzugeben.
    • generate_natural_language_answer: Optional. Wenn auf „true“ gesetzt, wird eine Antwort in natürlicher Sprache generiert.
    • generate_explanation: Optional. Wenn diese Option auf „true“ gesetzt ist, wird eine Erklärung der SQL-Abfrage generiert.
    • generate_disambiguation_question: Optional. Wenn diese Option auf „true“ gesetzt ist, werden Fragen zur Mehrdeutigkeitsauflösung generiert, wenn die Abfrage mehrdeutig ist.

QueryData-Beispielantwort

Hier ist ein Beispiel für eine erfolgreiche Antwort auf einen QueryData-Aufruf:

{
  "generatedQuery": "-- Count the number of accounts in Prague that are eligible for loans\nSELECT\n  COUNT(DISTINCT \"loans\".\"account_id\")\nFROM \"loans\"\nJOIN \"district\" -- Join based on district ID\n  ON \"loans\".\"district_id\" = \"district\".\"district_id\"\nWHERE\n  \"district\".\"A3\" = 'Prague'; -- Filter for the Prague region",
  "intentExplanation": "The question asks for the number of accounts eligible for loans in the Prague region. I need to join the `district` table with the `loans` table to filter by region and count the distinct accounts. The `A3` column in the `district` table contains the region information, and I'll filter for 'Prague'. The `loans` table contains information about loans, including the `account_id` and `district_id`. I will join these two tables on their respective district IDs.",
  "queryResult": {
    "columns": [
      {
        "name": "count"
      }
    ],
    "rows": [
      {
        "values": [
          {
            "value": "2"
          }
        ]
      }
    ],
    "totalRowCount": "1"
  },
  "naturalLanguageAnswer": "There are 2 accounts in Prague that are eligible for loans.",
  "tokenUsage": {
    "inputTokenCount": 312,
    "outputTokenCount": 148
  }
}

Nächste Schritte