Esta página foi traduzida pela API Cloud Translation.

Defina o contexto do agente de dados para origens de dados de bases de dados

O contexto criado são orientações 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. O contexto criado eficazmente fornece aos agentes de dados da API Conversational Analytics contexto útil para responder a perguntas sobre as suas origens de dados.

Esta página descreve como fornecer contexto criado para origens de dados de bases de dados através do método QueryData. Para origens de dados de bases de dados, como o AlloyDB, o GoogleSQL para Spanner, o Cloud SQL e o Cloud SQL para PostgreSQL, fornece contexto criado definindo e armazenando primeiro o contexto na base de dados e, em seguida, fazendo referência ao mesmo na sua chamada QueryData.

O fornecimento de contexto de elevada precisão permite à API gerar respostas e consultas SQL mais precisas e relevantes.

Antes de começar

Existe um agente de dados com o contexto do agente carregado para o mesmo para uma base de dados. Para mais informações, consulte os artigos 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 a sua instância da seguinte forma:
```
  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 tem de conceder privilégios da base de dados a um utilizador do IAM ou a uma conta de serviço. Para mais informações, consulte os artigos Conceda privilégios de base de dados a um utilizador do IAM individual ou a uma conta de serviço no Cloud SQL e Conceda privilégios de base de dados a um utilizador do IAM individual ou a uma conta de serviço no Cloud SQL para PostgreSQL.

Disponibilizar contexto com `QueryData`

Quando chama o método QueryData, fornece a origem de dados e as informações de contexto no campo QueryDataRequest.context.datasourceReferences. Para origens de bases de dados, tem de usar uma das seguintes opções:

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

Nestas referências, especifica a base de dados e as tabelas através do campo databaseReference. Para incluir contexto criado pelo autor, também tem de fornecer um agentContextReference que aponte para um context_set_id.

Exemplo de pedido `QueryData` com contexto criado

O exemplo seguinte mostra um pedido QueryData através de alloydb. O campo agent_context_reference.context_set_id é usado para criar um link para o contexto pré-criado armazenado na base 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 do pedido contém os seguintes campos:

prompt: a pergunta em linguagem natural do utilizador final.
context: contém informações sobre as origens de dados.
- datasource_references: especifica o tipo de origem de dados.
  - alloydb: obrigatório ao consultar a base de dados. Este campo muda com base na base de dados que está a consultar.
    - database_reference: especifica informações relacionadas com a sua instância da base de dados.
      - engine:
      - project_id: o ID do projeto da instância da base de dados.
      - region: a região da instância da base de dados.
      - cluster_id: o ID do cluster da instância da base de dados.
      - instance_id: o ID da instância da base de dados.
      - database_id: o ID da base de dados.
    - agent_context_reference: links para o contexto criado na base de dados.
      - context_set_id: o ID do contexto do agente armazenado na base de dados. Para mais informações sobre como encontrar o ID do conjunto de contexto, consulte os artigos Encontre o ID do contexto do agente no AlloyDB, Encontre o ID do contexto do agente no GoogleSQL para Spanner, Encontre o ID do contexto do agente no Cloud SQL e Encontre o ID do contexto do agente no Cloud SQL para PostgreSQL.
generationOptions: configura o tipo de resultado a gerar.
- generate_query_result: definido como verdadeiro para gerar e devolver os resultados da consulta.
- generate_natural_language_answer: opcional. Se estiver definida como verdadeira, gera uma resposta em linguagem natural.
- generate_explanation: opcional. Se for definida como verdadeira, gera uma explicação da consulta SQL.
- generate_disambiguation_question: opcional. Se estiver definida como verdadeira, gera perguntas de desambiguação se a consulta for ambígua.

Exemplo de resposta `QueryData`

Segue-se um exemplo de uma 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."
}

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