Acerca de este codelab
1. Descripción general
MCP Toolbox para bases de datos es un servidor de código abierto de Google que facilita la creación de herramientas de IA generativa para interactuar con bases de datos. Te permite desarrollar herramientas de forma más fácil, rápida y segura, ya que controla las complejidades, como el grupo de conexiones, la autenticación y mucho más. Te ayuda a compilar herramientas de IA generativa que permiten a tus agentes acceder a los datos de tu base de datos. Toolbox proporciona lo siguiente:
Desarrollo simplificado: Integra herramientas a tu agente en menos de 10 líneas de código, reutiliza herramientas entre varios agentes o frameworks, e implementa versiones nuevas de las herramientas con mayor facilidad.
Mejor rendimiento: Prácticas recomendadas, como agrupación de conexiones, autenticación y mucho más
Seguridad mejorada: La autenticación integrada para un acceso más seguro a tus datos.
Observabilidad de extremo a extremo: Métricas y seguimiento listos para usar con compatibilidad integrada para OpenTelemetry.
Toolbox se encuentra entre el framework de orquestación de tu aplicación y tu base de datos, y proporciona un plano de control que se usa para modificar, distribuir o invocar herramientas. Simplifica la administración de tus herramientas, ya que te proporciona una ubicación centralizada para almacenarlas y actualizarlas, lo que te permite compartirlas entre agentes y aplicaciones, y actualizarlas sin tener que volver a implementar la aplicación.
Qué compilarás
Como parte de este lab, compilarás una aplicación que usa una herramienta para realizar una consulta simple a una base de datos (AlloyDB) que se puede invocar desde tu agente o la aplicación de IA generativa. Para ello, deberás
- Instala la Caja de herramientas para bases de datos de MCP
- Configura la herramienta (que está diseñada para realizar una tarea en AlloyDB) en el servidor de Toolbox
- Implementa la Caja de herramientas de MCP para bases de datos en Cloud Run
- Probar la herramienta con su extremo de Cloud Run implementado
- Compila la Cloud Run Function para invocar la Caja de herramientas
Requisitos
2. Antes de comenzar
Crea un proyecto
- En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.
- Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud. Obtén información sobre cómo verificar si la facturación está habilitada en un proyecto.
- Usarás Cloud Shell, un entorno de línea de comandos que se ejecuta en Google Cloud. Haz clic en Activar Cloud Shell en la parte superior de la consola de Google Cloud.
- Una vez que te conectes a Cloud Shell, usa el siguiente comando para comprobar si ya estás autenticado y si el proyecto está configurado con el ID correcto:
gcloud auth list
- En Cloud Shell, ejecuta el siguiente comando para confirmar que el comando gcloud conoce tu proyecto.
gcloud config list project
- Si tu proyecto no está configurado, usa el siguiente comando para hacerlo:
gcloud config set project <YOUR_PROJECT_ID>
- Para habilitar las APIs necesarias, ejecuta los siguientes comandos uno por uno en la terminal de Cloud Shell:
También hay un solo comando para ejecutar lo siguiente, pero si usas una cuenta de prueba, es posible que tengas problemas de cuota cuando intentes habilitarlos de forma masiva. Es por eso que los comandos se separan, uno por línea.
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
La alternativa al comando de gcloud es a través de la consola. Puedes buscar cada producto o usar este vínculo.
Si falta alguna API, puedes habilitarla durante el transcurso de la implementación.
Consulta la documentación para ver los comandos y el uso de gcloud.
3. Configuración de la base de datos
En este lab, usaremos AlloyDB como la base de datos para almacenar los datos de venta minorista. Utiliza clústeres para almacenar todos los recursos, como bases de datos y registros. Cada clúster tiene una instancia principal que proporciona un punto de acceso a los datos. Las tablas contendrán los datos reales.
Creemos un clúster, una instancia y una tabla de AlloyDB en la que se cargará el conjunto de datos de comercio electrónico.
Crea un clúster y una instancia
- Navega por la página de AlloyDB en la consola de Cloud.
Una manera fácil de encontrar la mayoría de las páginas en la consola de Cloud es buscarlas usando la barra de búsqueda de la consola.
- Selecciona CREATE CLUSTER (CREAR CLÚSTER) en esa página:
- Verás una pantalla como la que se muestra a continuación. Crea un clúster y una instancia con los siguientes valores (asegúrate de que los valores coincidan en caso de que clones el código de la aplicación desde el repositorio):
- ID del clúster: "
vector-cluster" - contraseña: "
alloydb" - Compatible con PostgreSQL 15
- Región: "
us-central1" - Herramientas de redes: “
default”
- Cuando selecciones la red predeterminada, verás una pantalla como la que se muestra a continuación. Selecciona CONFIGURAR CONEXIÓN.
- Allí, selecciona “Usar un rango de IP asignado automáticamente” y, luego, Continuar. Después de revisar la información, selecciona CREAR CONEXIÓN.
- Una vez que la red esté configurada, puedes continuar con la creación de tu clúster. Haz clic en CREAR CLÚSTER para completar la configuración del clúster, como se muestra a continuación:
Asegúrate de cambiar el ID de la instancia a “”.
vector-instance"
.
Ten en cuenta que la creación del clúster tardará alrededor de 10 minutos. Una vez que se complete de forma correcta, deberías ver una pantalla en la que se muestra la descripción general del clúster que acabas de crear.
4. Transferencia de datos
Ahora es el momento de agregar una tabla con los datos sobre la tienda. Navega a AlloyDB, selecciona el clúster principal y, luego, AlloyDB Studio:
Es posible que debas esperar a que termine de crearse la instancia. Una vez que se complete el proceso, accede a AlloyDB con las credenciales que creaste durante la creación del clúster. Usa los siguientes datos para autenticarte en PostgreSQL:
- Nombre de usuario: "
postgres" - Base de datos: "
postgres" - Contraseña: "
alloydb"
Una vez que te hayas autenticado correctamente en AlloyDB Studio, puedes ingresar los comandos de SQL en el editor. Puedes agregar varias ventanas del Editor con el signo más que se encuentra a la derecha de la última ventana.
Puedes ingresar comandos para AlloyDB en las ventanas del editor con las opciones Ejecutar, Formato y Borrar según sea necesario.
Habilita las extensiones
Para crear esta app, usaremos las extensiones pgvector y google_ml_integration. La extensión pgvector te permite almacenar y buscar incorporaciones de vectores. La extensión google_ml_integration proporciona funciones que puedes usar para acceder a los extremos de predicción de Vertex AI y obtener predicciones en SQL. Para habilitar estas extensiones, ejecuta los siguientes DDL:
CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;
Si quieres comprobar las extensiones que se habilitaron en tu base de datos, ejecuta este comando de SQL:
select extname, extversion from pg_extension;
Crear una tabla
Crea una tabla con la declaración DDL a continuación:
CREATE TABLE toys ( id VARCHAR(25), name VARCHAR(25), description VARCHAR(20000), quantity INT, price FLOAT, image_url VARCHAR(200), text_embeddings vector(768)) ;
Cuando se ejecute correctamente el comando anterior, deberías poder ver la tabla en la base de datos.
Transfiere datos
Para este lab, tenemos datos de prueba de aproximadamente 72 registros en este archivo SQL. Contiene los campos id, name, description, quantity, price, image_url. Los otros campos se completarán más adelante en el lab.
Copia las líneas o inserta las sentencias desde allí y, luego, pégalas en una pestaña del editor en blanco y selecciona EJECUTAR.
Para ver el contenido de la tabla, expande la sección Explorador hasta que veas la tabla denominada indumentaria. Selecciona el tricolon (⋮) para ver la opción Consultar la tabla. Se abrirá el enunciado SELECT en una nueva pestaña del editor.
Otorgar permiso
Ejecuta la siguiente sentencia para otorgar derechos de ejecución en la función embedding al usuario postgres:
GRANT EXECUTE ON FUNCTION embedding TO postgres;
Otorga la función de usuario de Vertex AI a la cuenta de servicio de AlloyDB
Ve a la terminal de Cloud Shell y ejecuta el siguiente 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. Crea incorporaciones para el contexto
Es mucho más fácil para las computadoras procesar números que procesar texto. Un sistema de incorporación convierte texto en una serie de números de punto flotante, llamados incorporaciones vectoriales, que deben representar el texto sin importar cómo esté redactado, el idioma que use, etcétera.
Por ejemplo, una ubicación junto al mar podría llamarse "en el agua", "frente a la playa", "caminar de tu habitación al océano", "sur la mer", " máx. esfuerzos inicios de la línea de productos, implementa., etc. Todos estos términos se ven diferentes, pero su significado semántico o la terminología de aprendizaje automático deben estar muy cerca entre sí.
Ahora que los datos y el contexto están listos, ejecutaremos SQL para agregar las incorporaciones de la descripción del producto a la tabla del campo embedding. Hay una variedad de modelos de incorporación que puedes usar. Usamos text-embedding-005 de Vertex AI. Asegúrate de usar el mismo modelo de incorporación durante todo el proyecto.
Nota: Si usas un proyecto antiguo de Google Cloud, es posible que debas seguir usando versiones anteriores del modelo de incorporación de texto, como textembedding-gecko.
Regresa a la pestaña AlloyDB Studio y escribe el siguiente DML:
UPDATE toys set text_embeddings = embedding( 'text-embedding-005', description);
Observa la tabla toys otra vez para ver algunas incorporaciones. Asegúrate de volver a ejecutar la sentencia SELECT para ver los cambios.
SELECT id, name, description, price, quantity, image_url, text_embeddings FROM toys;
Esto debería mostrar el vector de incorporaciones, que parece un array de números de punto flotante, para la descripción del juguete, como se muestra a continuación:
Nota: Los proyectos de Google Cloud creados recientemente bajo el nivel gratuito pueden tener problemas de cuota en lo que respecta a la cantidad de solicitudes de incorporación permitidas por segundo a los modelos de incorporación. Te sugerimos que uses una consulta de filtro para el ID y, luego, selecciones de 1 a 5 registros de forma selectiva y así sucesivamente mientras generas la incorporación.
6. Realizar búsqueda de vectores
Ahora que la tabla, los datos y las incorporaciones están listos, realicemos la búsqueda vectorial en tiempo real para el texto de búsqueda del usuario.
Supongamos que el usuario pregunta:
"I want a white plush teddy bear toy with a floral pattern".
Puedes encontrar coincidencias con esto ejecutando la siguiente consulta:
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;
Veamos esta consulta en detalle:
En esta consulta,
- El texto de búsqueda del usuario es: "
I want a white plush teddy bear toy with a floral pattern." - Lo convertiremos en incorporaciones en el método
embedding()con el modelo:text-embedding-005. Este paso debería resultarte familiar después del último, en el que aplicamos la función de incorporación a todos los elementos de la tabla. - "
<=>" representa el uso del método de distancia COSINE SIMILARITY. Puedes encontrar todas las medidas de similitud disponibles en la documentación de pgvector. - Estamos convirtiendo el resultado del método de incorporación en un tipo de vector para que sea compatible con los vectores almacenados en la base de datos.
- LIMIT 5 representa que queremos extraer 5 vecinos más cercanos para el texto de búsqueda.
El resultado se ve de la siguiente manera:
Como puedes observar en tus resultados, las coincidencias son bastante similares al texto de la búsqueda. Intenta cambiar el texto para ver cómo cambian los resultados.
7. Prepara AlloyDB para la interacción con la caja de herramientas
Como preparación para configurar Toolbox, habilitemos la conectividad de IP pública en nuestra instancia de AlloyDB para que la nueva herramienta pueda acceder a la base de datos.
- Ve a tu instancia de AlloyDB, haz clic en EDITAR y llega a la página Editar instancia principal.
- Ve a la sección Conectividad de IP pública, marca la casilla de verificación Habilitar IP pública y, luego, ingresa la dirección IP de tu máquina de Cloud Shell.
- Para obtener la IP de tu máquina de Cloud Shell, ve a la terminal de Cloud Shell y, luego, ingresa ifconfig. A partir del resultado, identifica la dirección inet eth0 y reemplaza los 2 últimos dígitos por 0.0 por un tamaño de máscara “/16”. Por ejemplo, el formato sería "XX.XX.0.0/16", donde XX son números.
- Pega esta IP en el cuadro de texto "Redes" de Redes externas autorizadas de la página Editar instancia.
- Cuando termines, haz clic en ACTUALIZAR INSTANCIA.
Tardará unos minutos en completarse.
8. Instalación de la Caja de herramientas para bases de datos de MCP
- Puedes crear una carpeta de proyecto para almacenar los detalles de la herramienta. En este caso, como estamos trabajando con los datos de la juguetería, crearemos una carpeta llamada “toystore” y navegaremos hacia ella. Navega a la Terminal de Cloud Shell y asegúrate de que tu proyecto esté seleccionado y se muestre en el mensaje de la terminal. Ejecuta el siguiente comando desde tu terminal de Cloud Shell:
mkdir toystore
cd toystore
- Ejecuta el siguiente comando para descargar y, luego, instalar la caja de herramientas en tu carpeta nueva:
# 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
- Cambia al editor de Cloud Shell. Expande la carpeta recién creada “toystore” y crea un archivo nuevo llamado tools.yaml. Copia el contenido que aparece a continuación. Reemplaza YOUR_PROJECT_ID y verifica si todos los demás detalles de la conexión son correctos.
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;
En esta herramienta, solo buscamos la coincidencia más cercana al texto de búsqueda del usuario (descripción personalizada del juguete) y mostramos su precio. También puedes modificarlo para encontrar el precio promedio de los 5 juguetes que mejor coincidan:
select avg(price) from ( SELECT price FROM juguetes ORDER BY text_embeddings <=> CAST(embedding(‘text-embedding-005', $1) AS vector(768)) LIMIT 5 ) como precio;
La definición de la herramienta ya está lista.
Si deseas obtener más detalles para configurar el archivo tools.yaml, consulta esta documentación.
- Ve a la terminal de Cloud Shell y, luego, ingresa el siguiente comando para iniciar el servidor de la caja de herramientas con la configuración de tus herramientas:
./toolbox --tools_file "tools.yaml"
- Ahora, si abres el servidor en un modo de vista previa en la Web en la nube, deberías poder ver el servidor de Toolbox en funcionamiento con tu nueva herramienta llamada
get-toy-price..
9. Implementación de Cloud Run de la Caja de herramientas de MCP para bases de datos
Implementémosla en Cloud Run para que puedas aprovechar esta herramienta.
- Sigue una por una las instrucciones de esta página hasta llegar al comando
gcloud run deploy toolboxque se encuentra en el tercer punto en la sección “Deploy to Cloud Run”. Necesitas la primera opción y no la segunda que sirve cuando usas un método de red de VPC. - Una vez que se implemente correctamente, recibirás un extremo implementado de Cloud Run del servidor de Toolbox. Pruébala con un comando CURL.
Sugerencias:
Sigue atentamente las instrucciones de la página y no te pierdas nada.
Ya está todo listo para que uses la herramienta recién implementada en tu aplicación agente.
10. Conecta tu app con la Caja de herramientas para bases de datos de MCP
En esta parte, compilaremos una aplicación pequeña para probar tu herramienta de modo que interactúe con las necesidades de la aplicación y recupere una respuesta.
- Navega a Google Colab y abre un notebook nuevo.
- Ejecuta el siguiente comando en tu 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)
- Deberías obtener el siguiente resultado:
Esta es la herramienta que se invoca explícitamente en una aplicación de Python que usa el kit de herramientas toolbox-langchain.
- Si deseas usar esta herramienta y vincularla a un agente dentro de una aplicación integrada en LangGraph, puedes hacerlo fácilmente con el kit de herramientas
langgraph. - Para ello, consulta los fragmentos de código.
11. ¡Llévalo a Cloud!
Unamos este fragmento de código de Python a Cloud Run Functions para hacerlo sin servidores.
- Copia el código fuente de la carpeta de repositorio de código para enviarlo a Cloud Functions.
- Ve a la consola de Cloud Run Functions y haz clic en CREAR FUNCIÓN.
- Mantenlo sin autenticar para la aplicación de demostración y selecciona el entorno de ejecución de Python 3.11 en la página siguiente.
- Copia los archivos
main.pyyrequirements.txtdel repositorio de origen que se compartió en el paso 1 y pégalos en los archivos correspondientes. - Reemplaza la URL del servidor en main.py por la URL de tu servidor.
- Implementa la función y obtendrás un extremo de REST para que se acceda a la herramienta de predicción de precios en la aplicación web de Toystore.
- Tu extremo debería verse de la siguiente manera:
https://us-central1-*****.cloudfunctions.net/toolbox-toys
- Puedes probarlo directamente en la consola de Cloud Functions si navegas a la pestaña PRUEBA y, luego, ingresas lo siguiente como entrada de solicitud:
{
"search": "White plush toy"
}
- Haz clic en PROBAR LA FUNCIÓN o ejecuta lo que elijas usar en la terminal de Cloud Shell. Deberías ver el resultado a la derecha debajo del título "Output":
12. Felicitaciones
¡Felicitaciones! Creaste con éxito una herramienta sólida y realmente modular que puede interactuar entre bases de datos, plataformas y frameworks de organización de la IA generativa para ayudarte a crear tu aplicación agente.