Cómo instalar y configurar Toolbox para tus aplicaciones de IA generativa y agentes en AlloyDB

1. Descripción general

Gen AI Toolbox for Databases es un servidor de código abierto de Google que facilita la compilació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 crear herramientas de IA generativa que permitan a tus agentes acceder a los datos de tu base de datos. Toolbox proporciona lo siguiente:

Desarrollo simplificado: Integra herramientas en tu agente en menos de 10 líneas de código, reutiliza herramientas entre varios agentes o frameworks, y, además, implementa nuevas versiones de 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 seguimientos 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, crearás una aplicación que use una herramienta para realizar una consulta simple a la base de datos (AlloyDB) que se pueda invocar desde tu agente o la aplicación de IA generativa. Para ello, deberás hacer lo siguiente:

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

Requisitos

  • Un navegador, como Chrome o Firefox.
  • Un proyecto de Google Cloud con la facturación habilitada (consulta los pasos 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, usa el siguiente comando para verificar si ya se te autenticó y si el proyecto está configurado con el ID correcto:
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. Ejecuta los siguientes comandos uno por uno en la terminal de Cloud Shell para habilitar las APIs requeridas:

También hay un solo comando para ejecutar lo siguiente, pero si eres usuario de una cuenta de prueba, es posible que tengas problemas de cuota cuando intentes habilitarlos de forma masiva. Por eso, los comandos se escriben 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 gcloud es a través de la consola. Para ello, busca cada producto o usa 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. Usa 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.

Crearé 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 a 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 siguiente. Crea un clúster y una instancia con los siguientes valores (asegúrate de que los valores coincidan en caso de que estés clonando el código de la aplicación desde el repositorio):
  • cluster id: "vector-cluster"
  • contraseña: "alloydb"
  • Compatible con PostgreSQL 15
  • Región: "us-central1"
  • Redes: “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 se configure la 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 la instancia a "

vector-instance"

.

Ten en cuenta que la creación del clúster tardará alrededor de 10 minutos. Una vez que se realice correctamente, deberías ver una pantalla que muestre 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 de la tienda. Navega a AlloyDB, selecciona el clúster principal y, luego, AlloyDB Studio:

847e35f1bf8a8bd8.png

Es posible que debas esperar a que se termine de crear 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 hayas autenticado 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 las ventanas del editor con las opciones Ejecutar, Formatear y Borrar según sea necesario.

Habilita las 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. 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 verificar las extensiones que se habilitaron en tu base de datos, ejecuta este comando SQL:

select extname, extversion from pg_extension;

Crea una tabla

Crea una tabla con la siguiente sentencia 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, deberías poder 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í 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 puedas ver la tabla llamada apparels. Selecciona los tres puntos (⋮) para ver la opción de consultar la tabla. Se abrirá una sentencia SELECT en una nueva pestaña del editor.

cfaa52b717f9aaed.png

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 el rol de usuario de Vertex AI a la cuenta de servicio de AlloyDB

Ve a la terminal de Cloud Shell y escribe 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

Para las computadoras, es mucho más fácil procesar números que procesar texto. Un sistema de incorporación convierte el texto en una serie de números de punto flotante, llamados incorporaciones de vectores, que deberían representar el texto, sin importar cómo esté redactado, qué idioma use, etcétera.

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

Ahora que los datos y el contexto están listos, ejecutaremos la sentencia SQL para agregar las incorporaciones de la descripción del producto a la tabla en el campo embedding. Existen varios modelos de incorporación que puedes usar. 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 de Google Cloud antiguo, 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 la 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 sentencia SELECT para ver los cambios.

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

Se debería mostrar el vector de incorporaciones, que se parece a un array de números de punto flotante, para la descripción del juguete, como se muestra a continuación:

7d32f7cd7204e1f3.png

Nota: Es posible que los proyectos de Google Cloud creados recientemente en el nivel gratuito tengan problemas de cuota en relación con 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, elijas de forma selectiva entre 1 y 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;

Veamos 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 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.
  3. "<=>" representa el uso del método de distancia COSINE SIMILARITY. Puedes encontrar todas las medidas de similitud disponibles en la documentación de pgvector.
  4. Convertimos 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.
  5. LIMIT 5 representa que queremos extraer 5 vecinos más cercanos para el texto de búsqueda.

El resultado se verá de la siguiente manera:

fa7f0fc3a4c68804.png

Como puedes observar en los resultados, las coincidencias son bastante cercanas 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 Toolbox

Para prepararnos 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 llega 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 escribe ifconfig. En el resultado, identifica la dirección inet 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 de 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 la caja de herramientas

  1. Puedes crear una carpeta de proyecto para almacenar los detalles de la herramienta. En este caso, como estamos trabajando en datos de una tienda de juguetes, crearemos una carpeta llamada “tienda de juguetes” y navegaremos en 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 Toolbox 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 del juguete personalizado) y mostramos su precio. También puedes modificarlo para encontrar el precio promedio de los 5 juguetes más cercanos que coincidan:

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 está todo listo con la definición de la herramienta.

Para obtener más detalles sobre la configuración de tools.yaml, consulta esta documentación.

  1. Activa la terminal de Cloud Shell y, luego, ingresa el siguiente comando para iniciar el servidor de toolbox con la configuración de tus herramientas:
./toolbox --tools_file "tools.yaml"
  1. Ahora, si abres el servidor en un 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 Toolbox en Cloud Run

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

  1. Sigue las instrucciones de esta página una por una hasta llegar al comando gcloud run deploy toolbox que se encuentra en el tercer 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 de tu servidor de Toolbox. Pruébala con un comando CURL.

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

10. Conecta tu app con Toolbox

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-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)
  1. Deberías ver 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 de LangGraph, puedes hacerlo fácilmente con el kit de herramientas de langgraph.
  2. Consulta los fragmentos de código para ello.

11. ¡Llévala a la nube!

Una vez que hayamos unido este fragmento de código de Python en una función de Cloud Run, la convertiremos en una función sin servidores.

  1. Copia la fuente de la carpeta del repositorio de código para enviarla a Cloud Functions.
  2. Ve a la consola de Cloud Run Functions y haz clic en CREAR FUNCIÓN.
  3. No lo autentiques para la aplicación de demostración 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 repositorio de origen que se compartió en el paso 1 y pégalos en los archivos correspondientes.
  5. Implementa la función y tendrás un extremo de REST para que la herramienta de predicción de precios pueda acceder a la aplicación web de la tienda de juguetes.
  6. Tu extremo debería verse de la siguiente manera:

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

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

{

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

}

  1. Haz clic en PROBAR LA FUNCIÓN o ejecútala en la terminal de Cloud Shell, según lo que elijas. Deberías ver el resultado a la derecha, debajo del título "Resultado":

d7ba57cf5e5ca553.png

12. ¡Felicitaciones!

¡Felicitaciones! Creaste correctamente una herramienta sólida y verdaderamente modular que puede interactuar entre bases de datos, plataformas y frameworks de orquestación de IA generativa para ayudarte a crear tu aplicación agentiva.