Inspecter et appeler un agent de données

Ce document explique comment inspecter un agent et mettre à jour son fichier de contexte. Vous pouvez inspecter un agent pour tester sa capacité à générer des requêtes SQL à partir de questions en langage naturel. Si une requête générée n'est pas précise, vous pouvez mettre à jour le contexte de l'agent.

Pour en savoir plus sur les agents de données, consultez Présentation des agents de données.

Avant de commencer

Assurez-vous qu'un agent de données a déjà été créé et que le contexte de l'agent a été importé dans l'agent de données. Pour en savoir plus, consultez Gérer les agents de données dans Spanner Studio.

Inspecter un agent de données

Pour inspecter un agent de données, procédez comme suit :

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

    Accéder à Spanner

  2. Sélectionnez une instance dans la liste, puis sélectionnez une base de données.

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

  4. Dans le volet Explorateur, à côté de Agents de données, cliquez sur Afficher les actions.

  5. Cliquez sur Inspecter l'agent.

  6. Dans l'éditeur de requête, cliquez sur Générer du code SQL pour ouvrir le panneau M'aider à coder.

  7. Saisissez une question en langage naturel pour générer une requête SQL, puis cliquez sur Générer.

  8. Vérifiez l'exactitude de la requête SQL.

Télécharger et mettre à jour le contexte d'un agent de données

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 de contexte de l'agent existant. Vous pouvez ensuite examiner et mettre à jour le modèle de requête, puis réimporter le fichier de contexte mis à jour dans l'agent.

Pour télécharger et mettre à jour le contexte d'un agent de données, procédez comme suit :

  1. Dans le volet Explorateur, à côté de Agents de données, cliquez sur Afficher les actions.
  2. Cliquez sur Télécharger le fichier de contexte de l'agent.
  3. Suivez les étapes décrites dans Créer des contextes à l'aide de Gemini CLI pour mettre à jour le contexte avec des paires de requêtes supplémentaires.
  4. Dans le volet Explorateur, à côté de votre agent de données, cliquez sur Afficher les actions.
  5. Cliquez sur Modifier l'agent.
  6. Cliquez sur Parcourir dans la section Importer le fichier de contexte de l'agent, puis sélectionnez le fichier de contexte de l'agent mis à jour.
  7. Cliquez sur Enregistrer pour mettre à jour le contexte de l'agent.

Une fois que vous êtes satisfait de l'exactitude de vos réponses, vous pouvez utiliser le point de terminaison QueryData pour connecter votre application à l'agent de données.

Trouver l'ID de contexte de l'agent

Pour connecter une application de données à l'agent de données, vous avez besoin de l'ID de contexte de l'agent.

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

    Accéder à Spanner

  2. Sélectionnez une instance dans la liste, puis sélectionnez une base de données.

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

  4. Dans le volet Explorateur, à côté de Agents de données, cliquez sur Afficher les actions.

  5. Cliquez sur Modifier l'agent.

  6. Notez l'ID de contexte dans ID de contexte de l'agent. Le format de l'ID de contexte de l'agent est semblable à projects/cloud-db-nl2sql/locations/us-east1/contextSets/bdf_pg_all_templates.

Associer l'agent de données à l'application

Définissez l'ID de contexte de l'agent dans l'appel de méthode QueryData pour fournir un contexte créé pour les sources de données de base de données telles qu'AlloyDB, Spanner, Cloud SQL et Cloud SQL pour PostgreSQL. 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 inspecté l'agent de données, vous pouvez faire référence à la source de données de la base de données dans votre appel QueryData.

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

L'exemple suivant montre une requête QueryData utilisant la source de données de base de données spanner_reference. Le champ agent_context_reference.context_set_id permet de créer un lien vers le contexte pré-rédigé stocké dans la base de données.

{
  "parent": "projects/cloud-db-nl2sql/locations/us-central1",
  "prompt": "How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.",
  "context": {
    "datasource_references": [
      {
        "spanner_reference" {
          "database_reference" {
            "engine": "GOOGLE_SQL"
            "project_id": "cloud-db-nl2sql"
            "region": "us-central1"
            "instance_id": "evalbench"
            "database_id": "financial"
          },
          "agent_context_reference": {
            "context_set_id": "projects/cloud-db-nl2sql/locations/us-east1/contextSets/bdf_pg_all_templates"
          }
        }
      }
    ]
  },
  "generation_options": {
    "generate_query_result": true,
    "generate_natural_language_answer": true,
    "generate_disambiguation_question": true,
    "generate_explanation": true
  }
}

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.
      • spanner_reference : obligatoire lors de l'interrogation de la base de données. Ce champ change en fonction de la base de données que vous interrogez.
        • database_reference : spécifie les informations liées à votre instance de base de données.
          • engine : dialecte SQL de la base de données. Définissez la valeur sur GOOGLE_SQL pour les bases de données Spanner.
          • project_id : ID de projet de l'instance de base de données.
          • region : région de l'instance Spanner.
          • instance_id : ID d'instance de l'instance Spanner.
          • database_id : ID de la base de données.
        • agent_context_reference : liens vers le contexte créé dans la base de données.
          • context_set_id : ID complet du contexte de l'agent stocké dans la base de données. Exemple :projects/cloud-db-nl2sql/locations/us-east1/contextSets/bdf_gsql_gemini_all_templates
  • generationOptions : 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 définie sur "true", une réponse en langage naturel est générée.
    • generate_explanation : facultatif. Si la valeur est "true", une explication de la requête SQL est générée.
    • generate_disambiguation_question : facultatif. Si la valeur est "true", des questions de clarification sont générées si la requête est ambiguë.

Exemple de réponse QueryData

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

{
  "generated_query": "-- 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",
  "intent_explanation": "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.",
  "query_result": {
    "columns": [
      {
        "name": "count"
      }
    ],
    "rows": [
      {
        "values": [
          {
            "value": "2"
          }
        ]
      }
    ],
    "total_row_count": 1
  },
  "natural_language_answer": "There are 2 accounts in Prague that are eligible for loans."
}

Étapes suivantes