Definir o contexto do agente de dados para fontes de dados de banco de dados

Nesta página, descrevemos como fornecer contexto criado para agentes de dados que usam fontes de dados de banco de dados com o método QueryData.

O contexto criado é uma orientação que os proprietários de agentes de dados podem fornecer para moldar o comportamento de um agente de dados e refinar as respostas da API. Um contexto criado eficaz fornece aos agentes de dados da API Conversational Analytics um contexto útil para responder a perguntas sobre suas fontes de dados.

Para fontes de dados de banco de dados, como AlloyDB, GoogleSQL para Spanner, Cloud SQL e Cloud SQL para PostgreSQL, primeiro defina e armazene o contexto no banco de dados e depois faça referência a ele na chamada QueryData.

Fornecer um contexto de alta precisão permite que a API gere consultas e respostas SQL mais precisas e relevantes.

Antes de começar

Você vai precisar de um agente de dados com o contexto dele enviado por upload para o banco de dados que quer consultar. Para mais informações, consulte Agentes de dados para AlloyDB, Agentes de dados para GoogleSQL para Spanner, Agentes de dados para Cloud SQL e Agentes de dados para Cloud SQL para PostgreSQL.
Ative a API Cloud SQL Data para sua instância da seguinte maneira:
```
  gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API
```
Substitua INSTANCE_ID pelo ID da sua instância do Cloud SQL ou do Cloud SQL para PostgreSQL.

Também é necessário conceder privilégios de banco de dados a um usuário do IAM ou a uma conta de serviço. Para mais informações, consulte Conceder privilégios de banco de dados a um usuário individual do IAM ou a uma conta de serviço no Cloud SQL e Conceder privilégios de banco de dados a um usuário individual do IAM ou a uma conta de serviço no Cloud SQL para PostgreSQL.

Fornecer contexto com o `QueryData`

Ao chamar o método QueryData, você fornece a fonte de dados e as informações de contexto no campo QueryDataRequest.context.datasourceReferences. Para fontes de banco de dados, use uma das seguintes opções:

alloydb para o AlloyDB para PostgreSQL
spanner_reference para GoogleSQL no Spanner
cloud_sql_reference para Cloud SQL e Cloud SQL para PostgreSQL

Nessas referências, você especifica o banco de dados e as tabelas usando o campo databaseReference. Para incluir o contexto criado, você também precisa fornecer um agentContextReference que aponte para um context_set_id.

Exemplo de solicitação `QueryData` com contexto criado

O exemplo a seguir mostra uma solicitação QueryData usando alloydb. O campo agent_context_reference.context_set_id é usado para vincular ao contexto pré-criado armazenado no banco de dados.

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 para 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 e Cloud SQL para 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
 }
}

O corpo da solicitação contém os seguintes campos:

prompt: a pergunta em linguagem natural do usuário final.
context: contém informações sobre as fontes de dados.
- datasource_references: especifica o tipo de fonte de dados.
  - alloydb: obrigatório ao consultar o banco de dados. Esse campo muda de acordo com o banco de dados consultado.
    - database_reference: especifica informações relacionadas à sua instância de banco de dados.
      - engine: o mecanismo de banco de dados ou o dialeto SQL. Opcional para o AlloyDB. Para bancos de dados do Spanner, defina como GOOGLE_SQL. Para instâncias do Cloud SQL, defina como MYSQL. Para instâncias do Cloud SQL para PostgreSQL, defina como POSTGRESQL.
      - project_id: o ID do projeto da instância de banco de dados.
      - region: a região da instância de banco de dados.
      - cluster_id: o ID do cluster da instância de banco de dados.
      - instance_id: o ID da instância do banco de dados.
      - database_id: o ID do banco de dados.
    - agent_context_reference: links para o contexto criado no banco de dados.
      - context_set_id: o ID do contexto do agente armazenado no banco de dados. Para mais informações sobre como encontrar o ID do conjunto de contexto, consulte Encontrar o ID do contexto do agente no AlloyDB, Encontrar o ID do contexto do agente no GoogleSQL para Spanner, Encontrar o ID do contexto do agente no Cloud SQL e Encontrar o ID do contexto do agente no Cloud SQL para PostgreSQL.
generationOptions: configura o tipo de saída a ser gerada.
- generate_query_result: defina como "true" para gerar e retornar os resultados da consulta.
- generate_natural_language_answer: opcional. Se definido como "true", gera uma resposta em linguagem natural.
- generate_explanation: opcional. Se definido como "true", gera uma explicação da consulta SQL.
- generate_disambiguation_question: opcional. Se definido como verdadeiro, gera perguntas de disambiguação se a consulta for ambígua.

Exemplo de resposta do `QueryData`

Confira um exemplo de resposta bem-sucedida de uma chamada 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."
}

Definir o contexto do agente de dados para fontes de dados de banco de dados Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.