Criar conjuntos de contexto usando a CLI do Gemini

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, aspectos e pesquisas de valor que fornecem contexto para gerar consultas SQL em linguagem natural. Você também vai usar a extensão de enriquecimento 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 refinamentos segmentados
  • 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:

Preparar uma instância do Cloud SQL

Papéis e permissões necessárias

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

Para conceder a permissão executesql à instância do Cloud SQL e ativar a API Data do Cloud SQL, 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 projeto do Google Cloud .
  • INSTANCE_ID: o ID da sua instância do Cloud SQL.
Para realizar as etapas deste tutorial, faça login em Google Cloud e autentique o banco de dados usando a autenticação do IAM.

Preparar o banco de dados para pesquisas de valor

Para usar pesquisas semânticas e de valor de trigrama, configure sua instância do Cloud SQL para MySQL para oferecer suporte a embeddings de vetor e indexação de n-gramas.

  1. Para permitir que a instância do Cloud SQL para MySQL faça pesquisas de valor semântico, ative as seguintes flags.

    1. Ative a flag cloudsql_vector.

      gcloud sql instances patch INSTANCE_NAME --database-flags=cloudsql_vector=on

    2. Ative a flag enable-google-ml-integration para permitir que a instância do Cloud SQL para MySQL se integre à Vertex AI.

      gcloud sql instances patch INSTANCE_NAME --enable-google-ml-integration

    3. Criar uma coluna de vetor para armazenar embeddings de cidades

      ALTER TABLE `airports` 
ADD COLUMN `city_embedding` VECTOR(768);

    4. Gerar e armazenar embeddings de vetor para nomes de cidades

      UPDATE `airports` 
SET `city_embedding` = mysql.ml_embedding('text-embedding-005', `city`) 
WHERE `city` IS NOT NULL;

  2. Para permitir que a instância do Cloud SQL para MySQL faça pesquisas de valores de trigramas, siga estas etapas.

    1. Ative a flag ngram_token_size.

      gcloud sql instances patch INSTANCE_NAME --database-flags=ngram_token_size=3

    2. Crie um índice FULLTEXT para correspondência de trigramas no nome do aeroporto

      CREATE FULLTEXT INDEX `idx_ngram_airports_name` 
ON `airports`(`name`) 
WITH PARSER ngram;

Preparar o ambiente

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

  • Instalar a CLI do Gemini
  • Instalar a extensão de enriquecimento de contexto do banco de dados
  • Configurar conexão de 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 MCP de enriquecimento de contexto do banco de dados

A extensão de enriquecimento de contexto do banco de dados oferece um fluxo de trabalho guiado e interativo para gerar contexto estruturado de NL2SQL com base nos esquemas do banco de dados.

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

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

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

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

  2. (Opcional) Atualize a extensão de enriquecimento 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 enriquecimento de contexto do banco de dados, execute o seguinte comando:

      gemini extensions update mcp-db-context-enrichment

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

    gemini extensions config mcp-db-context-enrichment GEMINI_API_KEY

    Substitua GEMINI_API_KEY pela sua chave de API Gemini.

Configurar a conexão de banco de dados

A extensão exige a conexão com o banco de dados para gerar contexto, 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

É necessário configurar o Application Default Credentials (ADC) para fornecer credenciais de usuário a 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 enriquecimento 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 MCP Toolbox e definida no arquivo de configuração tools.yaml.

O arquivo tools.yaml especifica a origem do banco 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.

  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 MCP Toolbox.

Gerar contexto

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

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 enriquecimento de 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.

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

  7. Revise 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 refinamentos segmentados

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

Para adicionar uma faceta 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.

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

  4. Revise a faceta gerada. É possível salvar a faceta em um arquivo de conjunto de contexto ou anexá-la 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 e as facetas do conjunto de contexto, consulte Visão geral dos conjuntos de contexto.

Gerar consultas de pesquisa de valor

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

Conclua as etapas em Preparar o banco de dados para pesquisas de valor.

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

  1. Execute o comando /generate_targeted_value_searches:

    /generate_targeted_value_searches
  1. Insira mysql para selecionar o MySQL como o mecanismo de banco de dados. Selecione "Padrão" para escolher o MySQL 8.0.

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

    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 valores. Você pode 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 de trigramas. Ideal para pesquisas de usuários e correção de nomes. Para usar o TRIGRAM_STRING_MATCH, prepare seu banco de dados para oferecer suporte à indexação de n-gramas.
      • SEMANTIC_SIMILARITY_MATCH: para pesquisa semântica em valores de string. Ideal para pesquisas entre idiomas e de sinônimos. Para uma lista de modelos compatíveis, consulte Modelos do Google compatíveis. Para usar o SEMANTIC_SIMILARITY_MATCH, prepare seu banco de dados para oferecer suporte a embeddings de vetor.

    • 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 para a próxima etapa.

  3. Revise as pesquisas de valor geradas. Você pode salvar o conjunto de contexto como um arquivo 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 automaticamente modelos em massa, 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 modelos orienta você por 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.

  3. Revise 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.

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

  6. Revise 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 atual.

  7. Depois de aprovar o modelo de consulta, você pode criar um arquivo de modelo ou anexar os pares de consulta a um arquivo de modelo existente. O modelo de consulta é salvo como um arquivo JSON no seu 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 conjuntos de contexto, consulte Visão geral dos conjuntos de contexto.

A seguir