Cette page a été traduite par l'API Cloud Translation.

Définir le contexte de l'agent de données pour les sources de données de base de données

Le contexte créé est une guidance que les propriétaires d'agents de données peuvent fournir pour façonner le comportement d'un agent de données et affiner les réponses de l'API. Un contexte créé efficace fournit à vos agents de données de l'API Conversational Analytics un contexte utile pour répondre aux questions sur vos sources de données.

Cette page explique comment fournir un contexte créé pour les sources de données de base de données à l'aide de la méthode QueryData. Pour les sources de données de base de données telles qu'AlloyDB, GoogleSQL pour Spanner, Cloud SQL et Cloud SQL pour PostgreSQL, vous fournissez un contexte créé en définissant et en stockant d'abord le contexte dans la base de données, puis en le référençant dans votre appel QueryData.

En fournissant un contexte très précis, vous permettez à l'API de générer des requêtes et des réponses SQL plus précises et pertinentes.

Avant de commencer

Un agent de données avec le contexte d'agent importé pour une base de données existe. Pour en savoir plus, consultez Agents de données pour AlloyDB, Agents de données pour GoogleSQL pour Spanner, Agents de données pour Cloud SQL et Agents de données pour Cloud SQL pour PostgreSQL.
Activez l'API Cloud SQL Data pour votre instance comme suit :
```
  gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API
```
Remplacez INSTANCE_ID par l'ID de votre instance Cloud SQL ou Cloud SQL pour PostgreSQL.

Vous devez également accorder des droits sur la base de données à un utilisateur ou à un compte de service IAM. Pour en savoir plus, consultez Accorder des droits sur une base de données à un utilisateur ou à un compte de service IAM individuel dans Cloud SQL et Accorder des droits sur une base de données à un utilisateur ou à un compte de service IAM individuel dans Cloud SQL pour PostgreSQL.

Fournir du contexte avec `QueryData`

Lorsque vous appelez la méthode QueryData, vous fournissez la source de données et les informations de contexte dans le champ QueryDataRequest.context.datasourceReferences. Pour les sources de données de base de données, vous devez utiliser l'une des options suivantes :

alloydb pour AlloyDB pour PostgreSQL,
spanner_reference pour GoogleSQL pour Spanner
cloud_sql_reference pour Cloud SQL et Cloud SQL pour PostgreSQL

Dans ces références, vous spécifiez la base de données et les tables à l'aide du champ databaseReference. Pour inclure le contexte de l'auteur, vous devez également fournir un agentContextReference qui pointe vers un context_set_id.

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

L'exemple suivant montre une requête QueryData utilisant alloydb. 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.

AlloyDB

{
  "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": [
      {
        "alloydb": {
          "database_reference": {
            "project_id": "cloud-db-nl2sql",
            "region": "us-central1",
            "cluster_id": "sqlgen-magic",
            "instance_id": "sqlgen-magic-primary",
            "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
  }
}

GoogleSQL pour Spanner

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

Cloud SQL et Cloud SQL pour PostgreSQL

{
  "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": [
      {
        "cloud_sql_reference": {
          "database_reference": {
            "engine": "MYSQL"
            "project_id": "cloud-db-nl2sql",
            "region": "us-central1",
            "instance_id": "sqlgen-magic-primary",
            "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.
  - alloydb : 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 :
      - project_id : ID de projet de l'instance de base de données.
      - region : région de l'instance de base de données.
      - cluster_id : ID du cluster de l'instance de base de données.
      - instance_id : ID de l'instance de la base de données.
      - 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 du contexte de l'agent stocké dans la base de données. Pour savoir comment trouver l'ID de l'ensemble de contexte, consultez Trouver l'ID de contexte de l'agent dans AlloyDB, Trouver l'ID de contexte de l'agent dans GoogleSQL pour Spanner, Trouver l'ID de contexte de l'agent dans Cloud SQL et Trouver l'ID de contexte de l'agent dans Cloud SQL pour PostgreSQL.
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."
}

Définir le contexte de l'agent de données pour les sources de données de base de données Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.