Tester QueryData

Ce document explique comment tester QueryData et mettre à jour le fichier d'ensemble de contexte. Vous pouvez tester la capacité de QueryData à générer des requêtes SQL à partir de questions en langage naturel. Si une requête générée n'est pas exacte, vous pouvez mettre à jour le fichier d'ensemble de contexte.

Pour en savoir plus sur les ensembles de contextes, consultez Présentation des ensembles de contextes.

Avant de commencer

Assurez-vous d'avoir créé un ensemble de contextes dans Knowledge Catalog et d'y avoir importé votre fichier d'ensemble de contextes. Pour en savoir plus, consultez Gérer les ensembles de contexte dans AlloyDB Studio.

Pour télécharger, mettre à jour et importer des fichiers d'ensemble de contexte, assurez-vous que l'utilisateur IAM dispose du rôle Éditeur de catalogue Dataplex (roles/dataplex.catalogEditor) ou Administrateur de catalogue Dataplex (roles/dataplex.catalogAdmin) sur le projet. Pour en savoir plus, consultez Autorisations des ensembles de contextes.

Tester QueryData

Pour tester un QueryData, procédez comme suit :

  1. Dans la console Google Cloud , accédez à la page AlloyDB.

    Accéder à AlloyDB

  2. Sélectionnez un cluster dans la liste.

  3. Dans le menu de navigation, cliquez sur AlloyDB Studio.

  4. Connectez-vous à Studio à l'aide de l'authentification Identity and Access Management.

  5. Dans le volet Explorateur, cliquez sur Afficher les actions à côté de l'ensemble de contexte que vous utilisez.

  6. Cliquez sur Tester l'ensemble de contextes.

  7. Dans l'éditeur de requête, cliquez sur Générer du code SQL à l'aide de QueryData avec : CONTEXT_SET_NAME pour ouvrir le panneau de génération de requêtes.

  8. Saisissez une question en langage naturel dans le panneau de génération de requêtes pour générer une requête SQL, puis cliquez sur Générer.

  9. Vérifiez l'exactitude de la requête SQL. Cliquez sur Insérer pour ajouter la requête à l'éditeur.

Télécharger et mettre à jour un ensemble de contextes

Si vous n'êtes pas satisfait de la requête SQL générée pour une question en langage naturel, téléchargez le fichier d'ensemble de contexte existant. Vous pouvez ensuite examiner et mettre à jour le modèle de requête, puis importer le fichier d'ensemble de contexte mis à jour dans l'ensemble de contexte de Knowledge Catalog.

Pour télécharger et mettre à jour un ensemble de contextes, procédez comme suit :

  1. Dans le volet Explorateur, cliquez sur Afficher les actions à côté de l'ensemble de contexte que vous utilisez.
  2. Cliquez sur Télécharger le fichier de contexte.
  3. Suivez la procédure décrite dans Créer des ensembles de contextes à l'aide de l'agent d'ingénierie contextuelle pour mettre à jour le contexte avec des paires de requêtes supplémentaires.
  4. Dans le volet Explorateur, cliquez sur Afficher les actions à côté de l'ensemble de contexte que vous utilisez.
  5. Cliquez sur Modifier l'ensemble de contextes.
  6. Cliquez sur Parcourir dans la section Importer un fichier de contexte, puis sélectionnez le fichier d'ensemble de contexte mis à jour.
  7. Cliquez sur Enregistrer pour mettre à jour l'ensemble de contextes.

Une fois que vous êtes satisfait de la précision de vos réponses, vous pouvez transmettre l'ID de l'ensemble de contexte au point de terminaison QueryData sans état dans les requêtes de votre application.

Trouver l'ID de l'ensemble de contextes

Pour référencer l'ensemble de contextes que vous avez créé et stocké dans Knowledge Catalog lorsque vous appelez le point de terminaison sans état QueryData depuis votre application, vous avez besoin de l'ID de l'ensemble de contextes.

  1. Dans la console Google Cloud , accédez à la page AlloyDB.

    Accéder à AlloyDB

  2. Sélectionnez un cluster dans la liste.

  3. Dans le menu de navigation, cliquez sur AlloyDB Studio.

  4. Connectez-vous à Studio à l'aide de l'authentification Identity and Access Management.

  5. Dans le volet Explorateur, cliquez sur Afficher les actions à côté de l'ensemble de contexte que vous utilisez.

  6. Cliquez sur Modifier l'ensemble de contextes.

  7. Notez le nom de la ressource de l'ensemble de contextes dans ID de l'ensemble de contextes. Le point de terminaison QueryData accepte les deux formats de nom de ressource d'ensemble de contexte suivants dans Knowledge Catalog :

    • Format à six segments : projects/PROJECT_ID/locations/LOCATION/contextSets/CONTEXT_SET_ID, par exemple projects/data-agents-project/locations/us-central1/contextSets/bdf_pg_all_templates
    • Format à huit segments : projects/PROJECT_ID/locations/LOCATION/contextSetGroups/GROUP_ID/contextSets/CONTEXT_SET_ID@VERSION (par exemple, @v1)

Connecter QueryData à votre application

Définissez l'ID de l'ensemble de contexte dans l'appel de méthode QueryData pour fournir le contexte créé à partir de Knowledge Catalog pour les sources de données de base de données telles qu'AlloyDB, Spanner, Cloud SQL pour MySQL, Cloud SQL pour PostgreSQL, Firestore et Bigtable. Pour en savoir plus, consultez Définir le contexte de l'agent de données pour les sources de données de base de données.

Après avoir testé l'ensemble de contexte, vous pouvez référencer la source de données de la base de données et l'ensemble de contexte dans votre appel QueryData sans état.

Exemple de requête QueryData avec un contexte créé

L'exemple suivant envoie une requête QueryData sans état à l'aide de la source de données de base de données alloydb. Le champ agent_context_reference.context_set_id associe la requête à l'ensemble de contextes pré-rédigés stocké dans Knowledge Catalog, et non dans votre base de données :

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
  }
}'

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet Google Cloud utilisé pour la requête.
  • LOCATION : région de la requête, par exemple us-central1.
  • CLUSTER_ID : ID du cluster AlloyDB.
  • INSTANCE_ID : ID de l'instance AlloyDB.
  • DATABASE_ID : ID de la base de données.
  • CONTEXT_SET_ID : ID de votre ensemble de contextes.

Le corps de la requête contient les champs suivants :

  • prompt : question en langage naturel de l'utilisateur final.
  • context : contient des informations sur les sources de données.
    • datasource_references : spécifie le type de source de données.
      • alloydb : obligatoire lors de l'interrogation de la base de données.
        • database_reference : spécifie les informations liées à votre instance de base de données.
          • cluster_id : ID de cluster de l'instance de base de données.
          • project_id : ID du projet de l'instance de base de données.
          • region : région de l'instance AlloyDB.
          • instance_id : ID de l'instance AlloyDB.
          • database_id : ID de la base de données.
        • agent_context_reference : associe la requête QueryData sans état à l'ensemble de contexte que vous avez créé et qui est stocké dans Knowledge Catalog, et non dans votre base de données.
          • context_set_id : nom complet de la ressource de l'ensemble de contextes stocké dans Knowledge Catalog. Vous pouvez spécifier le format à six segments, projects/PROJECT_ID/locations/LOCATION/contextSets/CONTEXT_SET_ID, ou le format à huit segments, projects/PROJECT_ID/locations/LOCATION/contextSetGroups/GROUP_ID/contextSets/CONTEXT_SET_ID@VERSION (par exemple, @v1).
  • generation_options : configure le type de sortie à générer.
    • generate_query_result : définissez cette option sur "true" pour générer et renvoyer les résultats de la requête.
    • generate_natural_language_answer : facultatif. Si la valeur est "true", génère une réponse en langage naturel.
    • generate_explanation : facultatif. Si la valeur est définie sur "true", génère une explication de la requête SQL.
    • generate_disambiguation_question : facultatif. Si la valeur est "true", génère des questions de désambiguïsation si la requête est ambiguë.

Exemple de réponse QueryData

Voici un exemple de réponse réussie à un appel QueryData :

{
  "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
  }
}

Étapes suivantes