Como instalar e configurar a Toolbox para seus aplicativos de IA generativa e agentes no AlloyDB

1. Visão geral

O Gen AI Toolbox for Databases é 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 pooling de conexões, autenticação e muito mais.

Segurança aprimorada:autenticação integrada para acesso mais seguro aos dados.

Observabilidade de ponta a ponta: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 precisar implantar novamente o aplicativo.

O que você vai criar

Como parte deste laboratório, você vai criar um aplicativo que usa uma ferramenta para realizar uma consulta simples de banco de dados (AlloyDB) que pode ser invocada pelo seu agente ou pelo aplicativo de IA generativa. Para isso, você vai precisar

1. Instalar a Toolbox
2. Configurar a ferramenta (projetada para realizar uma tarefa no AlloyDB) no servidor da Caixa de ferramentas
3. Implantar a Toolbox no Cloud Run
4. Testar a ferramenta com o endpoint implantado do Cloud Run
5. Criar a função do Cloud Run para invocar a Toolbox

Requisitos

• Use um navegador, como o Chrome ou o Firefox.
• Um projeto do Google Cloud com o faturamento ativado (etapas na próxima seção).

2. Antes de começar

Criar um projeto

1. No console do Google Cloud, na página de seletor de projetos, selecione ou crie um projeto do Google Cloud.
2. Confira se o faturamento está ativado para seu projeto do Cloud. Saiba como verificar se o faturamento está ativado em um projeto.
3. Você vai usar o Cloud Shell, um ambiente de linha de comando executado no Google Cloud. Clique em "Ativar o Cloud Shell" na parte de cima do console do Google Cloud.

4. Depois de se conectar ao Cloud Shell, verifique se você já está autenticado e se o projeto está definido com o ID correto usando o seguinte comando:

gcloud auth list

5. Execute o comando a seguir no Cloud Shell para confirmar se o comando gcloud sabe sobre seu projeto.

gcloud config list project

6. Se o projeto não estiver definido, use este comando:

gcloud config set project <YOUR_PROJECT_ID>

7. Ative as APIs necessárias executando os comandos a seguir um por um no terminal do Cloud Shell:

Há também um único comando para executar o procedimento abaixo, mas se você for um usuário de conta de teste, poderá encontrar problemas de cota ao tentar ativar em massa. É por isso que os comandos são separados 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, vamos usar o AlloyDB como o 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

1. 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 é pesquisar usando a barra de pesquisa do console.

2. Selecione CREATE CLUSTER nessa página:

3. Uma tela como esta vai aparecer. Crie um cluster e uma instância com os seguintes valores (verifique se os valores 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"

4. Ao selecionar a rede padrão, uma tela como a mostrada abaixo será exibida. Selecione CONFIGURAR CONEXÃO.
   
5. Em seguida, selecione "Usar um intervalo de IP alocado automaticamente" e clique em "Continuar". Depois de analisar as informações, selecione "CRIAR CONEXÃO".
6. Depois que a rede estiver configurada, você poderá continuar a criar 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 leva cerca de 10 minutos. Depois que a criação for concluída, uma tela vai mostrar uma visão geral do cluster que você acabou de criar.

4. Ingestão de dados

Agora é hora de adicionar uma tabela com os dados da loja. Acesse o AlloyDB, selecione o cluster principal e o AlloyDB Studio:

Talvez seja necessário aguardar a conclusão da criação da instância. Quando terminar, faça login no AlloyDB usando as credenciais que você criou durante a criação do cluster. Use os seguintes dados para autenticação no PostgreSQL:

• Nome de usuário : "postgres"
• Banco de dados : "postgres"
• Senha : "alloydb"

Depois de fazer a autenticação no AlloyDB Studio, os comandos SQL poderão ser inseridos no editor. É possível adicionar várias janelas do Editor usando o sinal de adição à direita da última janela.

É possível inserir comandos para o AlloyDB nas janelas do editor usando as opções Executar, Formatar e Limpar conforme necessário.

Ativar extensões

Para criar este app, vamos usar as extensões pgvector e google_ml_integration. A extensão pgvector permite armazenar e pesquisar embeddings de vetor. A extensão google_ml_integration fornece funções que você usa para acessar os endpoints de previsão da Vertex AI e receber previsões no 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)) ;

Se o comando acima for executado com sucesso, você poderá acessar a tabela no banco de dados.

Ingerir dados

Para este 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 mais tarde no laboratório.

Copie as linhas/instruções de inserção e cole em uma guia de editor em branco e selecione EXECUTAR.

Para conferir o conteúdo da tabela, expanda a seção "Explorador" até encontrar a tabela "apparels". Selecione o triponto (⋮) para ver 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 digite 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 processar texto. Um sistema de embeddings converte texto em uma série de números de ponto flutuante, chamados de embeddings de vetor, que devem representar o texto, não importa como ele é escrito, qual idioma ele usa etc.

Por exemplo, um local à beira-mar pode ser chamado de "à beira-mar", "em frente à praia", "a pé do mar", "sur la mer", "на берегу океана" etc. Todos esses termos parecem diferentes, mas o significado semântico ou a terminologia de machine learning deles deve ser muito semelhante.

Agora que os dados e o contexto estão prontos, vamos executar o SQL para adicionar as incorporações da descrição do produto à tabela no campo embedding. Há vários modelos de embedding que podem ser usados. Estamos usando text-embedding-005 da Vertex AI. Use o mesmo modelo de incorporação 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);

Confira a tabela toys novamente para ver 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 vai retornar o vetor de incorporação, que se parece com uma matriz de flutuações, para a descrição do brinquedo, conforme mostrado abaixo:

Observação:os projetos do Google Cloud recém-criados no nível sem custo financeiro podem ter problemas de cota em relação ao 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 e escolha seletivamente de 1 a 5 registros e assim por diante ao gerar a incorporação.

6. Realizar a pesquisa de vetor

Agora que a tabela, os dados e os embeddings estão prontos, vamos realizar a pesquisa de vetor em tempo real para o texto de pesquisa do usuário.

Suponha que o usuário pergunte:

"I want a white plush teddy bear toy with a floral pattern".

Para encontrar correspondências para isso, execute 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;

Vamos analisar essa consulta em detalhes:

Nesta consulta,

1. O texto de pesquisa do usuário é: "I want a white plush teddy bear toy with a floral pattern."
2. Estamos convertendo em embeddings no método embedding() usando o modelo: text-embedding-005. Esta etapa é semelhante à anterior, em que aplicamos a função de incorporação a todos os itens da tabela.
3. "<=>" representa o uso do método de distância COSINE SIMILARITY. Todas as medidas de similaridade disponíveis estão disponíveis na documentação do pgvector.
4. Estamos convertendo o resultado do método de embedding em um tipo de vetor para que ele seja compatível com os vetores armazenados no banco de dados.
5. LIMIT 5 representa que queremos extrair 5 vizinhos mais próximos para o texto de pesquisa.

O resultado é parecido com este:

Como você pode observar nos resultados, as correspondências são muito próximas do texto da pesquisa. Tente mudar o texto para conferir como os resultados mudam.

7. Como preparar o AlloyDB para a interação com a Toolbox

Para preparar a configuração da Toolbox, vamos ativar a conectividade de IP público na nossa instância do AlloyDB para que a nova ferramenta possa acessar o banco de dados.

1. Acesse sua instância do AlloyDB, clique em EDIT e acesse a página "Editar instância principal".
2. Acesse a seção "Conectividade de IP público", marque a caixa de seleção "Ativar IP público" e insira o endereço IP da sua máquina do Cloud Shell.
3. Para conferir o IP da sua máquina do Cloud Shell, acesse o terminal do Cloud Shell e digite "ifconfig". No resultado, identifique o endereço de inet eth0 e substitua os dois últimos dígitos por 0.0 com um tamanho de máscara "/16". Por exemplo, "XX.XX.0.0/16", em que XX são números.
4. Cole esse IP na caixa de texto "Redes" das redes externas autorizadas da página de edição da instância.

5. Clique em ATUALIZAR INSTÂNCIA quando terminar.

Essa operação leva alguns minutos.

8. Instalação da caixa de ferramentas

1. Você pode criar uma pasta de projeto para armazenar os detalhes da ferramenta. Neste caso, como estamos trabalhando com dados de uma loja de brinquedos, vamos criar uma pasta chamada "toystore" e navegar até ela. Acesse o terminal do Cloud Shell e verifique se o projeto está selecionado e mostrado no prompt do terminal. Execute o comando abaixo no terminal do Cloud Shell:

mkdir toystore

cd toystore

2. Execute o comando abaixo para fazer o download e instalar a Toolbox 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

3. Alterne para o editor do Cloud Shell. Abra a pasta "toystore" recém-criada 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;

Nesta ferramenta, estamos apenas encontrando a correspondência mais próxima ao texto de pesquisa do usuário (descrição de brinquedos personalizados) e retornando o preço. Você também pode modificar a consulta para encontrar o preço médio dos cinco brinquedos mais próximos:

select avg(price) from ( SELECT price FROM toys ORDER BY text_embeddings <=> CAST(embedding(‘text-embedding-005', $1) AS vector(768)) LIMIT 5 ) as price;

A definição da ferramenta está pronta.

Para mais detalhes sobre como configurar o arquivo tools.yaml, consulte esta documentação.

4. 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"

5. Agora, se você abrir o servidor em um modo de visualização da Web na nuvem, poderá ver o servidor da Toolbox em funcionamento com a nova ferramenta chamada get-toy-price..

9. Implantação do Toolbox no Cloud Run

Vamos implantar no Cloud Run para que você possa usar essa ferramenta.

1. Siga as instruções desta página uma por uma até chegar ao comando gcloud run deploy toolbox, que está no terceiro ponto da seção "Implantar no Cloud Run". Você precisa da primeira opção, e não da segunda, que é para quando você está usando um método de rede VPC.
2. Após a implantação, você vai receber um endpoint implantado do Cloud Run do seu servidor do Toolbox. Teste com um comando CURL.

Você já pode usar a ferramenta recém-implantada no seu aplicativo de agente!

10. Conectar seu app à caixa de ferramentas

Nesta parte, vamos criar um pequeno aplicativo para testar sua ferramenta e interagir com as necessidades do aplicativo e recuperar a resposta.

1. Acesse o Google Colab e abra um novo notebook.
2. Execute o seguinte no seu notebook

pip install toolbox-langchain
from toolbox_langchain import ToolboxClient

# Replace with your Toolbox service's URL
toolbox = ToolboxClient("https://toolbox-*****-uc.a.run.app")
tool = toolbox.load_tool("get-toy-price")

# Invoke the tool with a search text to pass as the parameter
result = tool.invoke({"description": "white plush toy"})

# Print result
print(result)

3. O resultado será parecido com este:

Esta é a ferramenta invocada explicitamente em um aplicativo Python que usa o kit de ferramentas toolbox-langchain.

4. Se você quiser usar essa ferramenta e vinculá-la a um agente em um aplicativo integrado do LangGraph, poderá fazer isso facilmente com o kit de ferramentas langgraph.
5. Consulte os snippets de código.

11. Leve para a nuvem!

Vamos agrupar este snippet de código Python em uma Função do Cloud Run para torná-lo sem servidor.

1. Copie a origem da pasta do repositório de código para levá-la ao Cloud Functions.
2. Acesse o console Cloud Run Functions e clique em CRIAR FUNÇÃO.
3. Não faça a autenticação para o aplicativo de demonstração e selecione o ambiente de execução do Python 3.11 na próxima página.
4. Copie os arquivos main.py e requirements.txt do repositório de origem compartilhado na etapa 1 e cole nos arquivos correspondentes.
5. Implante a função e você terá um endpoint REST para que a ferramenta de previsão de preços seja acessada no aplicativo da Web da toystore.
6. O endpoint vai ficar assim:

https://us-central1-*****.cloudfunctions.net/toolbox-toys

2. Para testar diretamente no console do Cloud Functions, acesse a guia "TESTING" e insira o seguinte como entrada de solicitação:

{

               "`search`"`:` "`White plush toy`"

}

3. Clique em TESTAR A FUNÇÃO ou execute no terminal do Cloud Shell, o que você escolher. O resultado vai aparecer à direita, sob o título "Saída":

12. Parabéns

Parabéns! Você criou uma ferramenta robusta e verdadeiramente modular que pode interagir com bancos de dados, plataformas e frameworks de orquestração de IA generativa para ajudar a criar seu aplicativo de agente.