Criar conjuntos de contexto usando a CLI do Gemini

MySQL   |  PostgreSQL   |  SQL Server

Visualizar

Este recurso está sujeito aos "Termos da Pré-GA" nos Termos Gerais de Serviço dos Termos Específicos de Serviço e aos Termos Adicionais para Produtos Pré-lançamento de IA Generativa. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições das fases de lançamento.

Este documento descreve como usar a CLI do Gemini e a caixa de ferramentas do MCP para criar arquivos de contexto do agente. Esses arquivos contêm modelos, facetas e pesquisas de valores que fornecem contexto para gerar consultas SQL em linguagem natural. Você também vai usar a extensão de aprimoramento de contexto do banco de dados.

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

Para criar um arquivo de contexto do agente, siga estas etapas gerais:

• Preparar o ambiente
• Gerar modelos segmentados
• Gerar facetas segmentadas
• Gerar pesquisas de valores segmentadas
• Opcional. Gerar modelos em massa

Antes de começar

Conclua os pré-requisitos a seguir antes de criar um agente.

Ativar serviços obrigatórios

Ative os seguintes serviços para seu projeto:

• API Data Analytics com Gemini
• API Gemini para Google Cloud
• API Dataplex Universal Catalog

Preparar uma instância do Cloud SQL

Verifique se você tem acesso a uma instância do Cloud SQL ou crie uma. Para mais informações, consulte Criar instâncias para o Cloud SQL.

Este tutorial exige que você tenha um banco de dados na instância do Cloud SQL. Para mais informações, consulte Criar um banco de dados na instância do Cloud SQL

Papéis e permissões necessárias

• Adicione um usuário do IAM ou uma conta de serviço à instância. Para mais informações, consulte Gerenciar usuários com a autenticação de banco de dados do IAM para o Cloud SQL.
• Conceda os papéis cloudsql.studioUser, cloudsql.instanceUser e geminidataanalytics.queryDataUser ao usuário do IAM no nível do projeto. Para mais informações, consulte Adicionar uma vinculação de política do IAM a um projeto.
• Você também precisa conceder privilégios de banco de dados somente leitura a um usuário do IAM ou a uma conta de serviço fazendo login como um usuário com privilégios de superusuário, como o usuário postgres.
  
  GRANT SELECT ON ALL TABLES IN SCHEMA public TO USER_NAME;
  
  Substitua USER_NAME pelo endereço de e-mail do usuário. É necessário usar aspas em torno do e-mail porque ele contém caracteres especiais (@ e .).
  
  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.

Conceder permissão executesql à instância do Cloud SQL

Para conceder a permissão executesql à instância do Cloud SQL e ativar a API Cloud SQL Data, execute o seguinte comando:

gcloud config set project PROJECT_ID
gcloud components update
gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API

Substitua o seguinte:

• PROJECT_ID: o ID do seu Google Cloud projeto.
• INSTANCE_ID: o ID da sua instância do Cloud SQL.

Para executar as etapas deste tutorial, faça login no Google Cloud e autentique o banco de dados usando a autenticação do IAM.

Preparar o ambiente

É possível criar arquivos de conjunto de contexto em qualquer ambiente de desenvolvimento local ou IDE. Para preparar o ambiente, siga estas etapas:

• Instalar a CLI do Gemini
• Instalar a extensão de aprimoramento de contexto do banco de dados
• Configurar a conexão do banco de dados

Instalar a CLI do Gemini

Para instalar a CLI do Gemini, consulte Começar a usar a CLI do Gemini.

Instalar a extensão do MCP de aprimoramento de contexto do banco de dados

A extensão de aprimoramento de contexto do banco de dados oferece um fluxo de trabalho guiado e interativo para gerar contexto NL2SQL estruturado dos esquemas de banco de dados.

Para mais informações sobre como instalar a extensão de aprimoramento de contexto do banco de dados, consulte Extensão de aprimoramento de contexto do banco de dados.

Para instalar a extensão de aprimoramento de contexto do banco de dados, siga estas etapas:

1. Instale a extensão da CLI do Gemini de aprimoramento de contexto do banco de dados:

   gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment

   Observação: a extensão exige uma chave da API Gemini na instalação para autenticar com a API Gemini e ativar a geração de contexto. Para mais informações sobre como encontrar sua chave de API, consulte Usar chaves da API Gemini.

2. (Opcional) Atualize a extensão de aprimoramento de contexto do banco de dados.

   Para verificar a versão instalada da extensão, execute o seguinte comando:

   gemini extensions list

   Verifique se a versão é 0.4.2 ou mais recente. Para atualizar a extensão de aprimoramento de contexto do banco de dados, execute o seguinte comando:

     gemini extensions update mcp-db-context-enrichment

   Para atualizar a extensão de aprimoramento de contexto do banco de dados ou substituir a GEMINI_API_KEY, execute o seguinte comando:

   gemini extensions config mcp-db-context-enrichment GEMINI_API_KEY

   Substitua GEMINI_API_KEY pela sua chave da API Gemini.

Configurar a conexão do banco de dados

A extensão exige a conexão do banco de dados para a geração de contexto para buscar esquemas e executar instruções SQL. Para permitir que a extensão interaja com seu banco de dados, é necessário configurar as credenciais de autenticação e definir as fontes e ferramentas do banco de dados.

Configurar o Application Default Credentials

É necessário configurar Application Default Credentials (ADC) para fornecer credenciais de usuário para dois componentes principais:

• Servidor MCP da caixa de ferramentas: usa credenciais para se conectar ao banco de dados, buscar esquemas e executar SQL para validação.
• Extensão de aprimoramento de contexto do banco de dados: usa credenciais para autenticar e chamar a API Gemini.

Execute os seguintes comandos no terminal para autenticar:

gcloud auth application-default login

Configurar o arquivo tools.yaml

A extensão exige uma conexão de banco de dados para a geração de contexto, que é compatível com a caixa de ferramentas do MCP e definida no arquivo de configuração tools.yaml.

O arquivo tools.yaml especifica a fonte e as ferramentas do banco de dados necessárias para buscar esquemas ou executar SQL. A extensão vem com habilidades de agente pré-instaladas para ajudar você a gerar a configuração.

**Observação** :se essa conexão não for estabelecida, a extensão vai retornar mensagens de erro, como "Erro ao descobrir ferramentas da mcp_toolbox", e a geração de contexto não vai funcionar.

1. Inicie a CLI do Gemini:

   gemini

2. Verifique se as habilidades estão ativas digitando na CLI do Gemini:

   /skills

3. Digite um comando como help me setup the database connection. A habilidade orienta você na criação do arquivo tools.yaml no diretório de trabalho atual.

4. Execute o seguinte comando na CLI do Gemini para aplicar a configuração tools.yaml ao servidor MCP da caixa de ferramentas.

   /mcp reload

Para mais informações sobre como configurar manualmente o arquivo tools.yaml, consulte Configuração da caixa de ferramentas do MCP.

Gerar contexto

As extensões instaladas anteriormente permitem que a CLI do Gemini ajude você a criar contexto na forma de um arquivo JSON.

Observação: a CLI do Gemini pode acessar seus arquivos locais para reduzir sobrecargas, como especificar locais exatos de arquivos nos diretórios locais. Por exemplo, se uma etapa no fluxo de trabalho da CLI do Gemini pedir informações que podem ser encontradas no arquivo tools.yaml, você poderá pedir ao Gemini para use tools.yaml ou responder com um comando como look it up.

Gerar modelos segmentados

Se você quiser adicionar um par de consultas específico como um modelo de consulta ao conjunto de contexto, use o comando /generate_targeted_templates. Para mais informações sobre modelos, consulte Visão geral dos conjuntos de contexto

Para adicionar um modelo de consulta ao conjunto de contexto, siga estas etapas:

1. No mesmo diretório, inicie a CLI do Gemini:

   gemini

2. Conclua a configuração de autenticação da CLI do Gemini.

3. Verifique se a caixa de ferramentas do MCP e a extensão de aprimoramento do banco de dados estão prontas para uso:

   /mcp reload

4. Execute o comando /generate_targeted_templates:

   /generate_targeted_templates

5. Insira a consulta em linguagem natural que você quer adicionar ao modelo de consulta.

6. Insira a consulta SQL correspondente ao modelo de consulta.

7. Analise o modelo de consulta gerado. É possível salvar o modelo de consulta como um arquivo de conjunto de contexto ou anexá-lo a um arquivo de conjunto de contexto.

O arquivo de conjunto de contexto semelhante a my-cluster-psc-primary_postgres_templates_20251104111122.json é salvo no diretório em que você executou os comandos.

Para mais informações sobre o arquivo de conjunto de contexto e o modelo de consulta, consulte Visão geral dos conjuntos de contexto.

Gerar facetas segmentadas

Se você quiser adicionar um par de consultas específico como um atributo ao arquivo de conjunto de contexto, use o comando /generate_targeted_facets.

Para adicionar um atributo ao arquivo de conjunto de contexto, siga estas etapas:

1. Execute o comando /generate_targeted_facets:

   /generate_targeted_facets

2. Insira a consulta em linguagem natural que você quer adicionar ao modelo de consulta.

3. Insira a consulta SQL correspondente ao modelo de consulta.

4. Analise o atributo gerado. É possível salvar o atributo em um arquivo de conjunto de contexto ou anexá-lo a um arquivo de conjunto de contexto.

O arquivo de conjunto de contexto semelhante a my-cluster-psc-primary_postgres_templates_20251104111122.json é salvo no diretório em que você executou os comandos.

Para mais informações sobre o arquivo de conjunto de contexto e as facetas, consulte Visão geral dos conjuntos de contexto

Gerar consultas de pesquisa de valores

Se você quiser gerar pesquisas de valores que especifiquem como o sistema deve pesquisar e corresponder valores específicos em um tipo de conceito, use o comando /generate_targeted_value_searches.

Para gerar um índice de valor, siga estas etapas:

1. Execute o comando /generate_targeted_value_searches:

   /generate_targeted_value_searches

1. Insira postgresql para selecionar o AlloyDB como o mecanismo de banco de dados.

2. Insira a versão do PostgreSQL que você quer usar. Selecione default para selecionar o PostgreSQL 16.

1. Insira a configuração de pesquisa de valores da seguinte maneira:

   Table name: TABLE_NAME
   Column name: COLUMN_NAME
   Concept type: CONCEPT_TYPE
   Match function: MATCH_FUNCTION
   Description: DESCRIPTION
   

   Substitua o seguinte:

   • TABLE_NAME: a tabela em que a coluna associada ao tipo de conceito existe.
   • COLUMN_NAME: o nome da coluna associada ao tipo de conceito.
   • CONCEPT_TYPE: o tipo de conceito que você quer definir, por exemplo, City name.

   • MATCH_FUNCTION: a função de correspondência a ser usada para a pesquisa de valores. É possível usar uma das seguintes funções:

     • EXACT_STRING_MATCH: para correspondência exata de dois valores de string. Ideal para IDs, códigos e chaves primárias exclusivos.
     • TRIGRAM_STRING_MATCH: para correspondência aproximada que calcula a distância normalizada do trigrama. Ideal para pesquisas de usuários e correção de nomes.
     • SEMANTIC_SIMILARITY_MATCH: para pesquisa semântica em valores de string. Ideal para pesquisas multilíngues e de sinônimos. Para uma lista de modelos compatíveis, consulte Modelos do Google compatíveis. Para usar SEMANTIC_SIMILARITY_MATCH, é necessário ativar a extensão vector e a google_ml_integration.

   • DESCRIPTION: (opcional) a descrição da consulta de pesquisa de valores.

2. Adicione outras pesquisas de valores conforme necessário. Se você pular a adição de outros índices de valor, a geração de SQL baseada em modelo vai passar para a próxima etapa.

3. Analise as pesquisas de valores geradas. É possível salvar o conjunto de contexto como um arquivo de conjunto de contexto ou anexá-lo a um arquivo de conjunto de contexto.

O arquivo de conjunto de contexto semelhante a my-cluster-psc-primary_postgres_templates_20251104111122.json é salvo no diretório em que você executou os comandos.

Para mais informações sobre o índice de valor, consulte Visão geral dos conjuntos de contexto

Opcional: gerar modelos em massa

Se você quiser gerar automaticamente o arquivo de conjunto de contexto com base no esquema e nos dados do banco de dados, use o comando /generate_bulk_templates.

Para gerar modelos em massa automaticamente, siga estas etapas:

1. Execute o comando /generate_bulk_templates:

   /generate_bulk_templates

2. Com base no esquema do banco de dados, a geração de SQL baseada em modelo orienta você em uma série de perguntas relacionadas à verificação das informações do banco de dados e à concessão de permissões para acessar o esquema do banco de dados.

3. Analise o modelo de consulta gerado. É possível aprovar o modelo ou atualizar um par de consultas que você quer revisar.

4. Insira a consulta em linguagem natural que você quer adicionar ao modelo de consulta.

5. Insira a consulta SQL correspondente ao modelo de consulta.

6. Analise o modelo de consulta gerado. É possível salvar o modelo de consulta como um arquivo de conjunto de contexto ou anexá-lo a um arquivo de contexto.

7. Depois de aprovar o modelo de consulta, é possível criar um novo arquivo de modelo ou anexar os pares de consultas a um arquivo de modelo. O modelo de consulta é salvo como um arquivo JSON no diretório local.

O arquivo de conjunto de contexto semelhante a my-cluster-psc-primary_postgres_templates_20251104111122.json é salvo no diretório em que você executou os comandos.

Para mais informações sobre o arquivo de conjunto de contexto, consulte Visão geral dos conjuntos de contexto.

A seguir

• Saiba mais sobre conjuntos de contexto.
• Saiba como criar ou excluir um conjunto de contexto no Cloud SQL Studio.
• Saiba como testar um conjunto de contexto.