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

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 informações úteis para responder a perguntas sobre suas fontes de dados.

Nesta página, descrevemos como fornecer contexto criado para fontes de dados de banco de dados usando o método QueryData. Para fontes de dados de banco de dados, como AlloyDB, GoogleSQL para Spanner, Cloud SQL e Cloud SQL para PostgreSQL, você fornece o contexto criado definindo e armazenando o contexto no banco de dados e, em seguida, referenciando-o 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 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.