Sobre este codelab
1. Visão geral
O MCP Toolbox para bancos de dados é um servidor de código aberto do Google que facilita a criação de ferramentas de IA generativa para interagir com bancos de dados. Ele permite que você desenvolva ferramentas de maneira mais fácil, rápida e segura, lidando com complexidades como agrupamento de conexões, autenticação e muito mais. Ele ajuda a criar ferramentas de IA generativa que permitem que seus agentes acessem dados no seu banco de dados. A caixa de ferramentas oferece:
Desenvolvimento simplificado:integre ferramentas ao seu agente em menos de 10 linhas de código, reutilize ferramentas entre vários agentes ou frameworks e implante novas versões de ferramentas com mais facilidade.
Melhor desempenho:práticas recomendadas, como pool de conexões, autenticação e muito mais.
Segurança reforçada:autenticação integrada para aumentar a segurança no acesso aos seus dados.
Observabilidade completa:métricas e rastreamento prontos para uso, com suporte integrado ao OpenTelemetry.
A caixa de ferramentas fica entre o framework de orquestração do aplicativo e o banco de dados, fornecendo um plano de controle usado para modificar, distribuir ou invocar ferramentas. Ele simplifica o gerenciamento das ferramentas, fornecendo um local centralizado para armazenar e atualizar ferramentas, permitindo que você compartilhe ferramentas entre agentes e aplicativos e atualize essas ferramentas sem necessariamente implantar novamente o aplicativo.
O que você vai criar
Como parte deste laboratório, você vai criar um aplicativo que usa uma ferramenta para executar uma consulta simples de banco de dados (AlloyDB) que pode ser invocada por seu agente ou aplicativo de IA generativa. Para isso, você
- Instalar a MCP Toolbox para bancos de dados
- Configurar a ferramenta (projetada para realizar uma tarefa no AlloyDB) no servidor da caixa de ferramentas
- Implante a caixa de ferramentas MCP para bancos de dados no Cloud Run
- testar a ferramenta com o endpoint do Cloud Run implantado
- Criar a função do Cloud Run para invocar a caixa de ferramentas
Requisitos
2. Antes de começar
Criar um projeto
- No console do Google Cloud, na página de seletor de projetos, selecione ou crie um projeto do Google Cloud.
- Confira se o faturamento está ativado para seu projeto do Cloud. Saiba como verificar se o faturamento está ativado em um projeto.
- Você vai usar o Cloud Shell, um ambiente de linha de comando em execução no Google Cloud. Clique em "Ativar o Cloud Shell" na parte de cima do console do Google Cloud.
- Após se conectar ao Cloud Shell, verifique se você já está autenticado e se o projeto está definido com o ID do projeto correto usando o seguinte comando:
gcloud auth list
- Execute o comando a seguir no Cloud Shell para confirmar se o comando gcloud sabe sobre seu projeto.
gcloud config list project
- Se o projeto não estiver definido, use este comando:
gcloud config set project <YOUR_PROJECT_ID>
- Execute os comandos a seguir, um por um, no terminal do Cloud Shell para ativar as APIs necessárias:
Há também um único comando para executar o código abaixo, mas se você usa uma conta de teste, talvez encontre problemas de cota ao tentar ativá-los em massa. É por isso que os comandos são destacados um por linha.
gcloud services enable alloydb.googleapis.com
gcloud services enable compute.googleapis.com
gcloud services enable cloudresourcemanager.googleapis.com
gcloud services enable servicenetworking.googleapis.com
gcloud services enable run.googleapis.com
gcloud services enable cloudbuild.googleapis.com
gcloud services enable cloudfunctions.googleapis.com
gcloud services enable aiplatform.googleapis.com
A alternativa ao comando gcloud é pelo console pesquisando cada produto ou usando este link.
Se alguma API for perdida, você poderá ativá-la durante a implementação.
Consulte a documentação para ver o uso e os comandos gcloud.
3. Configuração do banco de dados
Neste laboratório, usaremos o AlloyDB como banco de dados para armazenar os dados de varejo. Ele usa clusters para armazenar todos os recursos, como bancos de dados e registros. Cada cluster tem uma instância principal que fornece um ponto de acesso aos dados. As tabelas vão conter os dados reais.
Vamos criar um cluster, uma instância e uma tabela do AlloyDB em que o conjunto de dados de e-commerce será carregado.
Criar um cluster e uma instância
- Navegue pela página do AlloyDB no console do Cloud.
Uma maneira fácil de encontrar a maioria das páginas no console do Cloud é procurá-las usando a barra de pesquisa do console.
- Selecione CRIAR CLUSTER nesta página:
- Você verá uma tela como a mostrada abaixo. Crie um cluster e uma instância com os valores a seguir. Verifique se eles correspondem, caso você esteja clonando o código do aplicativo do repositório:
- ID do cluster: "
vector-cluster" - senha: "
alloydb" - Compatível com PostgreSQL 15
- Região: "
us-central1" - Rede: "
default"
- Ao selecionar a rede padrão, você verá uma tela como a mostrada abaixo. Selecione "Configurar conexão".
- Depois, selecione "Usar um intervalo de IP alocado automaticamente" e continue. Depois de conferir as informações, clique em CRIAR CONEXÃO.
- Depois que a rede estiver configurada, você poderá continuar criando o cluster. Clique em CRIAR CLUSTER para concluir a configuração do cluster, conforme mostrado abaixo:
Altere o ID da instância para "
vector-instance"
.
A criação do cluster levará cerca de 10 minutos. Depois disso, uma tela com a visão geral do cluster que você acabou de criar vai aparecer.
4. Ingestão de dados
Agora é hora de adicionar uma tabela com os dados sobre a loja. Navegue até o AlloyDB, selecione o cluster primário e depois o AlloyDB Studio:
Talvez seja necessário aguardar a conclusão da criação da instância. Depois disso, faça login no AlloyDB usando as credenciais geradas durante a criação do cluster. Use os seguintes dados para autenticar no PostgreSQL:
- Nome de usuário: "
postgres" - Banco de dados: "
postgres" - Senha: "
alloydb"
Depois da autenticação no AlloyDB Studio, os comandos SQL podem ser inseridos no Editor. É possível adicionar várias janelas do Editor usando o sinal de mais à direita da última janela.
É possível inserir comandos para o AlloyDB em janelas de edição usando as opções "Executar", "Formatar" e "Limpar", conforme necessário.
Ativar extensões
Para criar esse app, usaremos as extensões pgvector e google_ml_integration. A extensão pgvector permite armazenar e pesquisar embeddings de vetores. A extensão google_ml_integration fornece funções usadas para acessar endpoints de previsão da Vertex AI e receber previsões em SQL. Ative essas extensões executando os seguintes DDLs:
CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;
Se você quiser verificar as extensões que foram ativadas no seu banco de dados, execute este comando SQL:
select extname, extversion from pg_extension;
Criar uma tabela
Crie uma tabela usando a instrução DDL abaixo:
CREATE TABLE toys ( id VARCHAR(25), name VARCHAR(25), description VARCHAR(20000), quantity INT, price FLOAT, image_url VARCHAR(200), text_embeddings vector(768)) ;
Após a execução do comando acima, você vai conseguir acessar a tabela no banco de dados.
Ingerir dados
Neste laboratório, temos dados de teste de cerca de 72 registros neste arquivo SQL. Ele contém os campos id, name, description, quantity, price, image_url. Os outros campos serão preenchidos posteriormente no laboratório.
Copie as instruções de linha/inserir de lá e cole essas linhas em uma guia do editor em branco e selecione EXECUTAR.
Para acessar o conteúdo da tabela, expanda a seção "Explorador" até encontrar a tabela chamada "apparels". Selecione os três pontos (⋮) para conferir a opção de consultar a tabela. Uma instrução SELECT será aberta em uma nova guia do Editor.
Conceder permissão
Execute a instrução abaixo para conceder direitos de execução na função embedding ao usuário postgres:
GRANT EXECUTE ON FUNCTION embedding TO postgres;
Conceder o papel de usuário da Vertex AI à conta de serviço do AlloyDB
Acesse o terminal do Cloud Shell e execute o seguinte comando:
PROJECT_ID=$(gcloud config get-value project)
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
--role="roles/aiplatform.user"
5. Criar embeddings para o contexto
É muito mais fácil para os computadores processar números do que texto. Um sistema de embedding converte o texto em uma série de números de ponto flutuante, chamados de embeddings vetoriais, que devem representar o texto, independentemente de como ele é escrito, da linguagem usada etc.
Por exemplo, um local à beira-mar pode ser chamado de "na água", "praia", "caminhar do seu quarto até o mar", "sur la mer", "на Берега океана" etc. Esses termos são diferentes, mas o significado semântico ou a terminologia de aprendizado de máquina devem ser muito próximos entre si.
Agora que os dados e o contexto estão prontos, vamos executar o SQL para adicionar os embeddings da descrição do produto à tabela no campo embedding. Você pode usar vários modelos de embedding. Estamos usando text-embedding-005 da Vertex AI. Use o mesmo modelo de embedding em todo o projeto.
Observação: se você estiver usando um projeto antigo do Google Cloud, talvez seja necessário continuar usando versões mais antigas do modelo de incorporação de texto, como textembedding-gecko.
Volte para a guia do AlloyDB Studio e digite o seguinte DML:
UPDATE toys set text_embeddings = embedding( 'text-embedding-005', description);
Consulte a tabela toys novamente para conferir alguns embeddings. Execute novamente a instrução SELECT para conferir as mudanças.
SELECT id, name, description, price, quantity, image_url, text_embeddings FROM toys;
Isso retornará o vetor de embeddings, que parece uma matriz de pontos flutuantes, para a descrição do brinquedo, conforme mostrado abaixo:
Observação:projetos recém-criados do Google Cloud no nível sem custo financeiro podem ter problemas de cota quando se trata do número de solicitações de incorporação permitidas por segundo para os modelos de incorporação. Sugerimos que você use uma consulta de filtro para o ID, depois escolha seletivamente de 1 a 5 registros e assim por diante, gerando o embedding.
6. Realizar pesquisa de vetor
Agora que a tabela, os dados e os embeddings estão prontos, vamos realizar a pesquisa vetorial em tempo real pelo texto da pesquisa do usuário.
Suponha que o usuário pergunte:
"I want a white plush teddy bear toy with a floral pattern."
Você pode encontrar correspondências para isso executando a consulta abaixo:
select * from toys
ORDER BY text_embeddings <=> CAST(embedding('text-embedding-005', 'I want a white plush teddy bear toy with a floral pattern') as vector(768))
LIMIT 5;
Vejamos essa consulta em detalhes:
Nessa consulta,
- O texto da pesquisa do usuário é: "
I want a white plush teddy bear toy with a floral pattern." - Estamos fazendo a conversão para embeddings no método
embedding()usando o modelo:text-embedding-005. Esta etapa deve parecer familiar após a última, em que aplicamos a função de embedding a todos os itens da tabela. - "
<=>" representa o uso do método de distância COSINE SIMILARITY. Veja todas as medidas de similaridade disponíveis na documentação de pgvector. - Estamos convertendo o resultado do método de embedding em um tipo de vetor para torná-lo compatível com os vetores armazenados no banco de dados.
- LIMIT 5 representa que queremos extrair 5 vizinhos mais próximos para o texto da pesquisa.
O resultado será semelhante a este:
Como você pode observar nos seus resultados, as correspondências são muito próximas do texto de pesquisa. Tente mudar o texto para conferir como os resultados mudam.
7. Como preparar o AlloyDB para a interação da caixa de ferramentas
Ao preparar a caixa de ferramentas, vamos ativar a conectividade de IP público na instância do AlloyDB para que a nova ferramenta possa acessar o banco de dados.
- Acesse sua instância do AlloyDB, clique em EDITAR e acesse a página "Editar instância principal".
- Acesse a seção "Conectividade do IP público", marque a caixa de seleção "Ativar IP público" e digite o endereço IP da sua máquina do Cloud Shell.
- Para encontrar o IP da sua máquina do Cloud Shell, acesse o terminal do Cloud Shell e digite ifconfig. A partir do resultado, identifique o endereço eth0 inet e substitua os últimos dois dígitos por 0,0 pelo tamanho da máscara "/16". Por exemplo, "XX.XX.0.0/16", em que XX são números.
- Cole esse IP na caixa de texto "Redes" de redes externas autorizadas da página de edição de instâncias.
- Clique em ATUALIZAR INSTÂNCIA quando terminar.
Essa operação leva alguns minutos.
8. Caixa de ferramentas MCP para instalação de bancos de dados
- É possível criar uma pasta de projeto para armazenar os detalhes da ferramenta. Neste caso, como estamos trabalhando com dados de lojas de brinquedos, vamos criar uma pasta chamada "toystore" e navegar até ela. Navegue até o Terminal do Cloud Shell e verifique se o projeto está selecionado e exibido no prompt do terminal. Execute o comando abaixo no terminal do Cloud Shell:
mkdir toystore
cd toystore
- Execute o comando abaixo para fazer o download e instalar a caixa de ferramentas na nova pasta:
# see releases page for other versions
export VERSION=0.1.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
- Alterne para o editor do Cloud Shell. Expanda a pasta recém-criada "toystore" e crie um novo arquivo chamado tools.yaml. Copie o conteúdo abaixo. Substitua YOUR_PROJECT_ID e verifique se todos os outros detalhes da conexão estão corretos.
sources:
alloydb-toys:
kind: "alloydb-postgres"
project: "YOUR_PROJECT_ID"
region: "us-central1"
cluster: "vector-cluster"
instance: "vector-instance"
database: "postgres"
user: "postgres"
password: "alloydb"
tools:
get-toy-price:
kind: postgres-sql
source: alloydb-toys
description: Get the price of a toy based on a description.
parameters:
- name: description
type: string
description: A description of the toy to search for.
statement: |
SELECT price FROM toys
ORDER BY text_embeddings <=> CAST(embedding('text-embedding-005', $1) AS vector(768))
LIMIT 1;
Nessa ferramenta, estamos apenas encontrando a correspondência mais próxima com o texto de pesquisa do usuário (descrição do brinquedo personalizado) e retornando o preço. Também é possível modificá-la para encontrar o preço médio dos cinco brinquedos correspondentes mais próximos:
selecione avg(price) from ( SELECT price FROM toys ORDER BY text_embeddings <=> CAST(embedding(‘text-embedding-005', $1) ASvector(768)) LIMIT 5 ) como preço;
Está tudo pronto para a definição de ferramenta!
Para mais detalhes sobre como configurar o tools.yaml, consulte esta documentação.
- Alterne para o terminal do Cloud Shell e digite o seguinte comando para iniciar o servidor da caixa de ferramentas com a configuração das ferramentas:
./toolbox --tools_file "tools.yaml"
- Agora, se você abrir o servidor em um modo de visualização da Web na nuvem, verá o servidor da caixa de ferramentas funcionando com a nova ferramenta chamada
get-toy-price..
9. Implantação do Cloud Run da caixa de ferramentas MCP para bancos de dados
Vamos implantá-la no Cloud Run para que você possa colocar essa ferramenta em prática.
- Siga as instruções nesta página uma a uma até chegar ao comando
gcloud run deploy toolboxque está no 3o ponto da seção "Implantar no Cloud Run". Você precisa da primeira opção, e não da segunda, para quando estiver usando um método de rede VPC. - Após a implantação, você vai receber um endpoint implantado do Cloud Run do servidor da sua caixa de ferramentas. Teste com um comando CURL.
Dicas:
Siga as instruções na página com atenção e não perca.
Você já pode usar a ferramenta recém-implantada no seu aplicativo agrícola.
10. Conectar seu app com a MCP Toolbox para bancos de dados
Nesta parte, vamos criar um pequeno aplicativo para testar a ferramenta para interagir com as necessidades do aplicativo e recuperar respostas.
- Acesse o Google Colab e abra um novo notebook.
- Execute o seguinte no seu notebook
!pip install toolbox-core
from toolbox_core import ToolboxClient
# Replace with your Toolbox service's URL
toolbox = ToolboxClient("https://toolbox-*****-uc.a.run.app")
# This tool can be passed to your application!
tool = toolbox.load_tool("get-toy-price")
# If there are multiple tools
# These tools can be passed to your application!
# tools = await client.load_toolset("<<toolset_name>>")
# Invoke the tool with a search text to pass as the parameter
result = tool.invoke({"description": "white plush toy"})
# Print result
print(result)
- O resultado será semelhante a este:
Essa é a ferramenta invocada explicitamente em um aplicativo Python que usa o kit de ferramentas toolbox-langchain.
- Se você quiser usar essa ferramenta e vinculá-la a um agente em um aplicativo integrado ao LangGraph, faça isso facilmente com o kit de ferramentas
langgraph. - Consulte os snippets de código para saber mais.
11. Leve isso para a nuvem!
Vamos unir esse snippet de código do Python a uma função do Cloud Run para torná-lo sem servidor.
- Copie a origem da pasta do repositório de códigos para enviar isso ao Cloud Functions.
- Acesse o console do Cloud Run Functions e clique em CRIAR FUNÇÃO.
- Mantenha-o sem autenticação no aplicativo de demonstração e selecione o ambiente de execução do Python 3.11 na próxima página.
- Copie os arquivos
main.pyerequirements.txtdo repositório de origem compartilhado na etapa 1 e cole nos respectivos arquivos. - Substitua o URL do servidor em main.py pelo URL do servidor.
- Implante a função e você terá um endpoint REST para a ferramenta de previsão de preços a ser acessada no aplicativo da Web da toystore.
- Seu endpoint ficará assim:
https://us-central1-*****.cloudfunctions.net/toolbox-toys
- É possível testá-lo diretamente no console do Cloud Functions navegando até a guia "TESTE" e inserindo o seguinte como entrada de solicitação:
{
"search": "White plush toy"
}
- Clique em TESTAR A FUNÇÃO ou execute no terminal do Cloud Shell o que você quiser usar. Você verá o resultado à direita, abaixo do título "Output":
12. Parabéns
Parabéns! Você criou uma ferramenta robusta e realmente modular que pode interagir entre bancos de dados, plataformas e frameworks de orquestração de IA generativa para ajudar a criar seu aplicativo agente.