Criar conjuntos de contexto usando a CLI do Gemini

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.

Observação sobre a interface PostgreSQL: Os exemplos neste tópico são destinados a bancos de dados de dialeto GoogleSQL. Esse recurso não oferece suporte à interface PostgreSQL.

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 valor 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 valor 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 Spanner

• Verifique se uma instância do Spanner está disponível. Para mais informações, consulte Criar uma instância.
• Crie um banco de dados na instância em que você vai criar as tabelas. Para mais informações, consulte Criar um banco de dados na instância do Spanner

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

Papéis e permissões necessárias

• Adicione um usuário do IAM ou uma conta de serviço ao cluster. Para mais informações, consulte Aplicar papéis do IAM.
• Conceda os papéis spanner.databaseReader 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.
• Conceda papéis e permissões ao usuário do IAM para envolvidos no projeto para os bancos de dados necessários.

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 Como 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, configure as credenciais de autenticação e defina as fontes e ferramentas do banco de dados.

Configurar o Application Default Credentials

Você precisa configurar o 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 de dados e as ferramentas 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 a sobrecarga, 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. Você pode salvar o modelo de consulta como um arquivo de conjunto de contexto ou anexá-lo a um arquivo de conjunto de contexto existente.

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. Você pode salvar o atributo em um arquivo de conjunto de contexto ou adicioná-lo ao final de um arquivo de conjunto de contexto existente.

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 valor

Se você quiser gerar pesquisas de valor 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 spanner para selecionar o Spanner como o mecanismo de banco de dados.

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

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

   Substitua:

   • 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 valor. Use uma das seguintes funções:

     • EXACT_STRING_MATCH: para correspondência exata de dois valores de string. Melhor para IDs, códigos e chaves primárias exclusivos.
     • TRIGRAM_STRING_MATCH: para correspondência aproximada que calcula a distância normalizada do trigrama. Melhor para pesquisas de usuários e correção de nomes.

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

2. Adicione outras pesquisas de valor 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 valor geradas. Você pode salvar o conjunto de contexto como um arquivo de conjunto de contexto ou anexá-lo a um arquivo de conjunto de contexto existente.

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. Você pode aprovar o modelo ou atualizar um par de consultas que 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. Você pode salvar o modelo de consulta como um arquivo de conjunto de contexto ou anexá-lo a um arquivo de contexto existente.

7. Depois de aprovar o modelo de consulta, você pode criar um novo arquivo de modelo ou anexar os pares de consultas a um arquivo de modelo existente. 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 Spanner Studio
• Saiba como testar um conjunto de contexto.