Instala y configura la Caja de herramientas de MCP para las bases de datos de la IA generativa y las aplicaciones agentes en AlloyDB

1. Descripción general

MCP Toolbox for Databases 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 se encarga de las complejidades, como la agrupación de conexiones, la autenticación y mucho más. Te ayuda a crear herramientas de IA generativa que permiten que tus agentes accedan a los datos de tu base de datos. La caja de herramientas proporciona lo siguiente:

Desarrollo simplificado: Integra herramientas a tu agente con menos de 10 líneas de código, reutiliza herramientas entre varios agentes o frameworks y, luego, implementa nuevas versiones de las herramientas con mayor facilidad.

Mejor rendimiento: Prácticas recomendadas, como la agrupación de conexiones, la autenticación y mucho más.

Seguridad mejorada: 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 necesidad de volver a implementar tu aplicación.

Qué compilarás

Como parte de este lab, crearás una aplicación que usa una herramienta para realizar una consulta simple de la base de datos (AlloyDB) que se puede invocar desde tu agente o la aplicación de IA generativa. Para ello, deberás

  1. Instala MCP Toolbox para bases de datos
  2. Configura la herramienta (diseñada para realizar una tarea en AlloyDB) en el servidor de Toolbox.
  3. Implementa MCP Toolbox para bases de datos en Cloud Run
  4. Prueba la herramienta con su extremo de Cloud Run implementado
  5. Compila la función de Cloud Run para invocar la caja de herramientas

Requisitos

  • Un navegador, como Chrome o Firefox.
  • Un proyecto de Google Cloud con la facturación habilitada (los pasos se indican en la siguiente sección)

2. Antes de comenzar

Crea un proyecto

  1. En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.
  2. 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.
  3. 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.

Imagen del botón Activar Cloud Shell

  1. Una vez que te conectes a Cloud Shell, verifica si ya te autenticaste y si el proyecto está configurado con el ID del proyecto correcto con el siguiente comando:
gcloud auth list
  1. En Cloud Shell, ejecuta el siguiente comando para confirmar que el comando gcloud conoce tu proyecto.
gcloud config list project
  1. Si tu proyecto no está configurado, usa el siguiente comando para hacerlo:
gcloud config set project <YOUR_PROJECT_ID>
  1. Habilita las APIs requeridas ejecutando los siguientes comandos uno por uno en tu terminal de Cloud Shell:

También hay un solo comando para ejecutar lo que se indica a continuación, pero, si eres usuario de una cuenta de prueba, es posible que tengas problemas de cuota cuando intentes habilitar estos elementos de forma masiva. Por eso, los comandos se muestran 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. Para ello, busca cada producto o usa este vínculo.

Si olvidas alguna API, siempre puedes habilitarla durante el curso 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 contener 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 los que se cargará el conjunto de datos de comercio electrónico.

Crea un clúster y una instancia

  1. Navega por la página de AlloyDB en Cloud Console.

Una forma sencilla de encontrar la mayoría de las páginas en la consola de Cloud es buscarlas con la barra de búsqueda de la consola.

  1. Selecciona CREATE CLUSTER en esa página:

f76ff480c8c889aa.png

  1. 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 si clonas 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"
  • Conexiones: "default"

538dba58908162fb.png

  1. Cuando selecciones la red predeterminada, verás una pantalla como la que se muestra a continuación. Selecciona CONFIGURAR CONEXIÓN.
    7939bbb6802a91bf.png
  2. Allí, selecciona "Usar un rango de IP asignado automáticamente" y haz clic en Continuar. Después de revisar la información, selecciona CREAR CONEXIÓN. 768ff5210e79676f.png
  3. Una vez que configures tu red, podrás continuar con la creación del clúster. Haz clic en CREAR CLÚSTER para completar la configuración del clúster como se muestra a continuación:

e06623e55195e16e.png

Asegúrate de cambiar el ID de instancia a "

vector-instance"

.

Ten en cuenta que la creación del clúster tardará alrededor de 10 minutos. Una vez que se complete correctamente, deberías ver una pantalla que muestre el resumen del clúster que acabas de crear.

4. Transferencia de datos

Ahora es momento de agregar una tabla con los datos de la tienda. Navega a AlloyDB, selecciona el clúster principal y, luego, AlloyDB Studio:

847e35f1bf8a8bd8.png

Es posible que debas esperar a que termine de crearse la instancia. Una vez que se complete, 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 autentiques correctamente en AlloyDB Studio, podrás ingresar comandos 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.

91a86d9469d499c4.png

Puedes ingresar comandos para AlloyDB en ventanas del editor, y usar las opciones Ejecutar, Formatear y Borrar según sea necesario.

Habilitar extensiones

Para compilar esta app, usaremos las extensiones pgvector y google_ml_integration. La extensión pgvector te permite almacenar y buscar embeddings de vectores. La extensión google_ml_integration proporciona funciones que usas para acceder a los extremos de predicción de Vertex AI y obtener predicciones en SQL. Habilita estas extensiones ejecutando los siguientes DDL:

CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;

Si quieres verificar las extensiones que se habilitaron en tu base de datos, ejecuta este comando de SQL:

select extname, extversion from pg_extension;

Crea una tabla

Crea una tabla con la siguiente declaración DDL:

CREATE TABLE toys ( id VARCHAR(25), name VARCHAR(25), description VARCHAR(20000), quantity INT, price FLOAT, image_url VARCHAR(200), text_embeddings vector(768)) ;

Si el comando anterior se ejecuta correctamente, podrás ver la tabla en la base de datos.

Transfiere datos

Para este lab, tenemos datos de prueba de alrededor de 72 registros en este archivo SQL. Contiene los campos id, name, description, quantity, price, image_url. Los demás campos se completarán más adelante en el lab.

Copia las líneas o las instrucciones de inserción desde allí, 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 llamada prendas. Selecciona los dos puntos verticales (⋮) para ver la opción de consultar la tabla. Se abrirá una instrucción SELECT en una nueva pestaña del editor.

cfaa52b717f9aaed.png

Otorgar permiso

Ejecuta la siguiente instrucción para otorgar derechos de ejecución en la función embedding al usuario postgres:

GRANT EXECUTE ON FUNCTION embedding TO postgres;

Otorga el rol 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 embeddings para el contexto

Es mucho más fácil para las computadoras procesar números que texto. Un sistema de embeddings convierte el texto en una serie de números de punto flotante, llamados embeddings de vectores, que deberían representar el texto, sin importar cómo se exprese, qué idioma use, etcétera.

Por ejemplo, una ubicación junto al mar podría llamarse "junto al agua", "frente a la playa", "camina desde tu habitación hasta el océano", "sur la mer", "на берегу океана", etcétera. Todos estos términos se ven diferentes, pero su significado semántico o, en la terminología del aprendizaje automático, sus incorporaciones deberían estar muy cerca unas de otras.

Ahora que los datos y el contexto están listos, ejecutaremos el código SQL para agregar los embeddings de la descripción del producto a la tabla en el campo embedding. Puedes usar una variedad de modelos de embedding. Usamos text-embedding-005 de Vertex AI. Asegúrate de usar el mismo modelo de incorporación en todo el proyecto.

Nota: Si usas un proyecto antiguo de Google Cloud, es posible que debas seguir usando versiones anteriores del modelo de embedding de texto, como textembedding-gecko.

Vuelve a la pestaña AlloyDB Studio y escribe el siguiente DML:

UPDATE toys set text_embeddings = embedding( 'text-embedding-005', description);

Vuelve a mirar la tabla toys para ver algunas incorporaciones. Asegúrate de volver a ejecutar la instrucción SELECT para ver los cambios.

SELECT id, name, description, price, quantity, image_url, text_embeddings FROM toys;

Esto debería devolver el vector de embeddings, que se ve como un array de números de punto flotante, para la descripción del juguete, como se muestra a continuación:

7d32f7cd7204e1f3.png

Nota: Los proyectos de Google Cloud creados recientemente en el nivel gratuito pueden tener problemas de cuota en cuanto a la cantidad de solicitudes de incorporación permitidas por segundo para los modelos de Embedding. Te sugerimos que uses una consulta de filtro para el ID y, luego, elijas de forma selectiva de 1 a 5 registros, y así sucesivamente, mientras generas la incorporación.

6. Realiza una búsqueda de vectores

Ahora que la tabla, los datos y los embeddings están listos, realicemos la búsqueda de vectores en tiempo real para el texto de búsqueda del usuario.

Supongamos que el usuario pregunta lo siguiente:

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

Para encontrar coincidencias, ejecuta 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;

Analicemos esta consulta en detalle:

En esta consulta,

  1. El texto de búsqueda del usuario es: "I want a white plush teddy bear toy with a floral pattern.".
  2. Lo convertimos en embeddings 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.
  3. "<=>" representa el uso del método de distancia SIMILITUD DEL COSENO. Puedes encontrar todas las medidas de similitud disponibles en la documentación de pgvector.
  4. Convertimos el resultado del método de incorporación al tipo de vector para que sea compatible con los vectores almacenados en la base de datos.
  5. 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:

fa7f0fc3a4c68804.png

Como puedes observar en los resultados, las coincidencias son bastante cercanas al texto de búsqueda. Intenta cambiar el texto para ver cómo cambian los resultados.

7. Preparación de 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.

  1. Ve a tu instancia de AlloyDB, haz clic en EDITAR y accede a la página Editar instancia principal.
  2. 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.
  3. Para obtener la IP de tu máquina de Cloud Shell, ve a la terminal de Cloud Shell y, luego, ingresa ifconfig. En el resultado, identifica la dirección inet de eth0 y reemplaza los últimos 2 dígitos por 0.0 con un tamaño de máscara "/16". Por ejemplo, se vería como "XX.XX.0.0/16", donde XX son números.
  4. Pega esta IP en el cuadro de texto “Redes” de las redes externas autorizadas en la página de edición de la instancia.

5f6e60e8dec2cea1.png

  1. Cuando termines, haz clic en ACTUALIZAR INSTANCIA.

Tardará unos minutos en completarse.

8. Instalación de MCP Toolbox para bases de datos

  1. Puedes crear una carpeta de proyecto para almacenar los detalles de la herramienta. En este caso, como trabajaremos con datos de una juguetería, crearemos una carpeta llamada "juguetería" y navegaremos a 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 la terminal de Cloud Shell:
mkdir toystore

cd toystore
  1. Ejecuta el siguiente comando para descargar e 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
  1. Activa el editor de Cloud Shell. Expande la carpeta recién creada "toystore" y crea un archivo nuevo llamado tools.yaml. Copia el siguiente contenido. 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 devolvemos su precio. También puedes modificarla para encontrar el precio promedio de los 5 juguetes con la coincidencia más cercana:

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;

¡Ya tienes todo listo con la definición de la herramienta!

Para obtener más detalles sobre cómo configurar tu archivo tools.yaml, consulta esta documentación.

  1. Activa 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"
  1. Ahora, si abres el servidor en modo de vista previa 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 MCP Toolbox para bases de datos

Implementémosla en Cloud Run para que puedas usar esta herramienta.

  1. Sigue las instrucciones de esta página una por una hasta que llegues al comando gcloud run deploy toolbox que se encuentra en el 3ᵉʳ punto de la sección "Implementa en Cloud Run". Necesitas la primera opción y no la segunda, que es para cuando usas un método de red de VPC.
  2. Una vez que se implemente correctamente, recibirás un extremo implementado de Cloud Run para tu servidor de Toolbox. Prueba con un comando CURL.

Sugerencias:

Sigue atentamente las instrucciones de la página y no te pierdas ningún paso.

Ya está todo listo para usar la herramienta que acabas de implementar en tu aplicación basada en agentes.

10. Conecta tu app a MCP Toolbox para bases de datos

En esta parte, compilaremos una pequeña aplicación para probar tu herramienta y que interactúe con las necesidades de la aplicación y recupere la respuesta.

  1. Navega a Google Colab y abre un notebook nuevo.
  2. Ejecuta lo siguiente 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)
  1. Deberías obtener un resultado como el siguiente:

5074f209a86c4f15.png

Esta es la herramienta que se invoca de forma explícita en una aplicación de Python que usa el kit de herramientas. toolbox-langchain.

  1. Si quieres 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.
  2. Consulta los fragmentos de código para obtener más información.

11. ¡Llévalo a la nube!

Unamos este fragmento de código de Python en una Cloud Run Function para que sea sin servidores.

  1. Copia la fuente de la carpeta del repo de código para llevarla a Cloud Functions.
  2. Ve a la consola de Cloud Run Functions y haz clic en CREAR FUNCIÓN.
  3. Mantén la aplicación de demostración sin autenticar y selecciona el entorno de ejecución de Python 3.11 en la página siguiente.
  4. Copia los archivos main.py y requirements.txt del repo fuente compartido en el paso 1 y pégalos en los archivos correspondientes.
  5. Reemplaza la URL del servidor en main.py por la tuya.
  6. Implementa la función y tendrás un extremo de REST para acceder a la herramienta de predicción de precios en la aplicación web de la juguetería.
  7. Tu extremo debería verse de la siguiente manera:

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

  1. Para probarla directamente en la consola de Cloud Functions, navega a la pestaña TESTING y, luego, ingresa lo siguiente como entrada de solicitud:

{

           "search": "White plush toy"

}

  1. Haz clic en PROBAR LA FUNCIÓN o ejecuta en la terminal de Cloud Shell lo que elijas usar. Deberías ver el resultado a la derecha, debajo del título "Output":

d7ba57cf5e5ca553.png

12. ¡Felicitaciones!

¡Felicitaciones! Creaste correctamente una herramienta sólida y verdaderamente modular que puede interactuar en bases de datos, plataformas y marcos de trabajo de organización de IA generativa para ayudarte a crear tu aplicación basada en agentes.