O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Test QueryData

Neste documento, descrevemos como testar o QueryData e atualizar o arquivo de conjunto de contexto. É possível testar a capacidade do QueryData de gerar consultas SQL com base em perguntas em linguagem natural. Se uma consulta gerada não for precisa, atualize o arquivo do conjunto de contexto.

Para saber mais sobre conjuntos de contexto, consulte Visão geral dos conjuntos de contexto.

Antes de começar

Verifique se você criou um conjunto de contextos no Knowledge Catalog e fez upload do arquivo do conjunto de contextos para ele. Para mais informações, consulte Gerenciar conjuntos de contexto no AlloyDB Studio.

Para baixar, atualizar e fazer upload de arquivos de conjunto de contexto, verifique se o usuário do IAM tem o papel de Editor do Dataplex Catalog (roles/dataplex.catalogEditor) ou Administrador do Dataplex Catalog (roles/dataplex.catalogAdmin) no projeto. Para mais informações, consulte Permissões de conjuntos de contexto.

Testar QueryData

Para testar um QueryData, siga estas etapas:

No console do Google Cloud , acesse a página do AlloyDB.

Acessar o AlloyDB
Selecione um cluster na lista.
No menu de navegação, clique em AlloyDB Studio.
Faça login no Studio usando a autenticação do Identity and Access Management.
No painel Explorador, clique em Ver ações ao lado do conjunto de contexto que você está usando.
Clique em Contexto de teste definido.
No editor de consultas, clique em Gerar SQL usando o QueryData com: CONTEXT_SET_NAME para abrir o painel de geração de consultas.
Insira uma pergunta em linguagem natural no painel de geração de consultas para gerar uma consulta SQL e clique em Gerar.
Verifique se a consulta SQL está correta. Clique em Inserir para adicionar a consulta ao editor.

Fazer o download e atualizar um conjunto de contexto

Se você não estiver satisfeito com a consulta SQL gerada para uma pergunta em linguagem natural, faça o download do arquivo de conjunto de contexto atual. Em seguida, revise e atualize o modelo de consulta e faça upload do arquivo de conjunto de contexto atualizado para o conjunto de contexto no Knowledge Catalog.

Para baixar e atualizar um conjunto de contexto, siga estas etapas:

No painel Explorador, clique em Ver ações ao lado do conjunto de contexto que você está usando.
Clique em Baixar arquivo de contexto.
Siga as etapas em Criar conjuntos de contexto usando o agente de engenharia de contexto para atualizar o contexto com mais pares de consulta.
No painel Explorador, clique em Ver ações ao lado do conjunto de contexto que você está usando.
Clique em Editar conjunto de contexto.
Clique em Procurar na seção Fazer upload do arquivo de contexto e selecione o arquivo de conjunto de contexto atualizado.
Clique em Salvar para atualizar o conjunto de contexto.

Quando estiver satisfeito com a precisão das respostas, transmita o ID do conjunto de contexto para o endpoint QueryData sem estado nas solicitações do seu aplicativo.

Encontrar o ID do conjunto de contextos

Para referenciar o conjunto de contextos criado e armazenado no Knowledge Catalog ao chamar o endpoint QueryData sem estado do seu aplicativo, você precisa do ID do conjunto de contextos.

No console do Google Cloud , acesse a página do AlloyDB.

Acessar o AlloyDB
Selecione um cluster na lista.
No menu de navegação, clique em AlloyDB Studio.
Faça login no Studio usando a autenticação do Identity and Access Management.
No painel Explorador, clique em Ver ações ao lado do conjunto de contexto que você está usando.
Clique em Editar conjunto de contexto.
Anote o nome do recurso do conjunto de contexto em ID do conjunto de contexto. O endpoint QueryData aceita os dois formatos de nome de recurso de conjunto de contexto no Knowledge Catalog:
- Formato de seis segmentos: projects/PROJECT_ID/locations/LOCATION/contextSets/CONTEXT_SET_ID, como projects/data-agents-project/locations/us-central1/contextSets/bdf_pg_all_templates
- Formato de 8 segmentos: projects/PROJECT_ID/locations/LOCATION/contextSetGroups/GROUP_ID/contextSets/CONTEXT_SET_ID@VERSION (por exemplo, @v1)

Conectar o QueryData ao seu aplicativo

Defina o ID do conjunto de contexto na chamada de método QueryData para fornecer contexto criado pelo Knowledge Catalog para fontes de dados de banco de dados, como AlloyDB, Spanner, Cloud SQL para MySQL, Cloud SQL para PostgreSQL, Firestore e Bigtable. Para mais informações, consulte Definir o contexto do agente de dados para fontes de dados de banco de dados.

Depois de testar o conjunto de contexto, você pode referenciar a fonte de dados do banco de dados e o conjunto de contexto na chamada QueryData sem estado.

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

O exemplo a seguir envia uma solicitação QueryData sem estado usando a fonte de dados do banco de dados alloydb. O campo agent_context_reference.context_set_id vincula a solicitação ao conjunto de contexto pré-criado armazenado no Knowledge Catalog, não no banco de dados:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "x-goog-user-project: PROJECT_ID" \
  -H "Content-Type: application/json" \
  https://geminidataanalytics.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION:queryData \
  -d '{
  "prompt": "How many accounts in the Prague region are eligible for loans? A3 contains the data of region.",
  "context": {
    "datasource_references": {
      "alloydb": {
        "database_reference": {
          "project_id": "PROJECT_ID",
          "region": "LOCATION",
          "cluster_id": "CLUSTER_ID",
          "instance_id": "INSTANCE_ID",
          "database_id": "DATABASE_ID"
        },
        "agent_context_reference": {
          "context_set_id": "projects/PROJECT_ID/locations/LOCATION/contextSets/CONTEXT_SET_ID"
        }
      }
    }
  },
  "generation_options": {
    "generate_query_result": true,
    "generate_natural_language_answer": true,
    "generate_disambiguation_question": true,
    "generate_explanation": true
  }
}'

Substitua:

PROJECT_ID: o ID do projeto Google Cloud usado para a solicitação.
LOCATION: a região da solicitação, como us-central1.
CLUSTER_ID: o ID do cluster do AlloyDB.
INSTANCE_ID: o ID da instância do AlloyDB.
DATABASE_ID: o ID do banco de dados.
CONTEXT_SET_ID: o ID do conjunto de contexto.

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.
    - database_reference: especifica informações relacionadas à instância do banco de dados.
      - cluster_id: o ID do cluster da instância de banco de dados.
      - project_id: o ID do projeto da instância do banco de dados.
      - region: a região da instância do AlloyDB.
      - instance_id: o ID da instância do AlloyDB.
      - database_id: o ID do banco de dados.
    - agent_context_reference: vincula a solicitação QueryData sem estado ao conjunto de contexto criado e armazenado no Knowledge Catalog, não no banco de dados.
      - context_set_id: o nome completo do recurso do conjunto de contexto armazenado no Knowledge Catalog. É possível especificar o formato de seis segmentos, projects/PROJECT_ID/locations/LOCATION/contextSets/CONTEXT_SET_ID, ou o formato de oito segmentos, projects/PROJECT_ID/locations/LOCATION/contextSetGroups/GROUP_ID/contextSets/CONTEXT_SET_ID@VERSION (por exemplo, @v1).
generation_options: configura o tipo de saída a ser gerada.
- generate_query_result: defina como verdadeiro para gerar e retornar os resultados da consulta.
- generate_natural_language_answer: opcional. Se definido como verdadeiro, gera uma resposta em linguagem natural.
- generate_explanation: opcional. Se definido como verdadeiro, gera uma explicação da consulta SQL.
- generate_disambiguation_question: opcional. Se definido como verdadeiro, gera perguntas de desambiguação se a consulta for ambígua.

Exemplo de resposta `QueryData`

Veja um exemplo de resposta bem-sucedida de uma chamada QueryData:

{
  "generatedQuery": "-- 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",
  "intentExplanation": "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.",
  "queryResult": {
    "columns": [
      {
        "name": "count"
      }
    ],
    "rows": [
      {
        "values": [
          {
            "value": "2"
          }
        ]
      }
    ],
    "totalRowCount": "1"
  },
  "naturalLanguageAnswer": "There are 2 accounts in Prague that are eligible for loans.",
  "tokenUsage": {
    "inputTokenCount": 312,
    "outputTokenCount": 148
  }
}

A seguir

Saiba mais sobre os conjuntos de contexto.
Saiba como criar conjuntos de contexto usando o agente de engenharia de contexto.
Saiba como gerenciar conjuntos de contexto no AlloyDB Studio.