Esta página foi traduzida pela API Cloud Translation.

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 um contexto útil 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, 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

Um agente de dados com o contexto do agente enviado por upload para ele em um banco de dados existe. Para mais informações, consulte Agentes de dados para o AlloyDB, Agentes de dados para o GoogleSQL para Spanner, Agentes de dados para o Cloud SQL e Agentes de dados para o 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 AlloyDB para PostgreSQL,
spanner_reference para GoogleSQL para 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:
      - 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.