1. Introducción
En este codelab, se proporciona una guía para comenzar a usar el servidor de MCP de Google Cloud para AlloyDB, habilitarlo como parte del conjunto de herramientas de un agente de IA y usarlo como parte de la aplicación.
Requisitos previos
- Conocimientos básicos sobre Google Cloud y la consola
- Habilidades básicas de la interfaz de línea de comandos y de Cloud Shell
Qué aprenderás
- Cómo crear un clúster de AlloyDB y, luego, importar datos de muestra
- Cómo habilitar la API de acceso a los datos de AlloyDB
- Cómo habilitar el MCP de Google Cloud para AlloyDB NL
- Cómo agregar Google Cloud MCP para AlloyDB a tu agente de ADK
- Cómo usar Google Cloud MCP para AlloyDB en una aplicación
- Cómo usar agentes con AlloyDBMCP para el análisis
Requisitos
- Una cuenta de Google Cloud y un proyecto de Google Cloud
- Un navegador web, como Chrome, que admita la consola de Google Cloud y Cloud Shell
2. Configuración y requisitos
Configuración del proyecto
- Accede a la consola de Google Cloud. Si aún no tienes una cuenta de Gmail o de Google Workspace, debes crear una.
Usar una cuenta personal en lugar de una cuenta laboral o educativa
- Crea un proyecto nuevo o reutiliza uno existente. Para crear un proyecto nuevo en la consola de Google Cloud, haz clic en el botón Seleccionar un proyecto en el encabezado, lo que abrirá una ventana emergente.
En la ventana Select a project, presiona el botón New Project, que abrirá un cuadro de diálogo para el proyecto nuevo.
En el cuadro de diálogo, ingresa el nombre del proyecto que prefieras y elige la ubicación.
- El Nombre del proyecto es el nombre visible de los participantes de este proyecto. El nombre del proyecto no se usa en las APIs de Google y se puede cambiar en cualquier momento.
- El ID del proyecto es único en todos los proyectos de Google Cloud y es inmutable (no se puede cambiar después de configurarlo). La consola de Google Cloud genera automáticamente un ID único, pero puedes personalizarlo. Si no te gusta el ID generado, puedes generar otro aleatorio o proporcionar el tuyo para verificar su disponibilidad. En la mayoría de los codelabs, deberás hacer referencia al ID del proyecto, que suele identificarse con el marcador de posición PROJECT_ID.
- Recuerda que hay un tercer valor, un número de proyecto, que usan algunas APIs. Obtén más información sobre estos tres valores en la documentación.
Habilitar facturación
Configura una cuenta de facturación personal
Si configuraste la facturación con créditos de Google Cloud, puedes omitir este paso.
Para configurar una cuenta de facturación personal, ve aquí para habilitar la facturación en la consola de Cloud.
Algunas notas:
- Completar este lab debería costar menos de USD 3 en recursos de Cloud.
- Puedes seguir los pasos al final de este lab para borrar recursos y evitar cargos adicionales.
- Los usuarios nuevos pueden acceder a la prueba gratuita de USD 300.
Inicia Cloud Shell
Si bien Google Cloud y Spanner se pueden operar de manera remota desde tu laptop, en este codelab usarás Google Cloud Shell, un entorno de línea de comandos que se ejecuta en la nube.
En Google Cloud Console, haz clic en el ícono de Cloud Shell en la barra de herramientas en la parte superior derecha:
También puedes presionar G y, luego, S. Esta secuencia activará Cloud Shell si estás en la consola de Google Cloud o usas este vínculo.
El aprovisionamiento y la conexión al entorno deberían tomar solo unos minutos. Cuando termine el proceso, debería ver algo como lo siguiente:
Esta máquina virtual está cargada con todas las herramientas de desarrollo que necesitarás. Ofrece un directorio principal persistente de 5 GB y se ejecuta en Google Cloud, lo que permite mejorar considerablemente el rendimiento de la red y la autenticación. Todo tu trabajo en este codelab se puede hacer en un navegador. No es necesario que instales nada.
3. Antes de comenzar
Habilitar API
Para usar AlloyDB, Compute Engine, servicios de redes y Vertex AI, debes habilitar sus respectivas APIs en tu proyecto de Google Cloud.
En la terminal de Cloud Shell, asegúrate de que tu ID del proyecto esté configurado:
gcloud config get-value project
Debería mostrar el ID de tu proyecto de Google.
Configura la variable de entorno PROJECT_ID:
PROJECT_ID=$(gcloud config get-value project)
Habilita todos los servicios necesarios con el siguiente comando:
gcloud services enable alloydb.googleapis.com \
compute.googleapis.com \
cloudresourcemanager.googleapis.com \
servicenetworking.googleapis.com \
aiplatform.googleapis.com \
discoveryengine.googleapis.com
Resultado esperado
student@cloudshell:~ (test-project-001-402417)$ gcloud config set project test-project-001-402417
Updated property [core/project].
student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-14650]
student@cloudshell:~ (test-project-001-402417)$
student@cloudshell:~ (test-project-001-402417)$ gcloud services enable alloydb.googleapis.com \
compute.googleapis.com \
cloudresourcemanager.googleapis.com \
servicenetworking.googleapis.com \
aiplatform.googleapis.com \
discoveryengine.googleapis.com
Operation "operations/acat.p2-4470404856-1f44ebd8-894e-4356-bea7-b84165a57442" finished successfully.
4. Implementa AlloyDB
Crea un clúster de AlloyDB y una instancia principal. Puedes implementarlo con una secuencia de comandos preparada que implementará todos los recursos necesarios o puedes hacerlo paso a paso por tu cuenta siguiendo la documentación.
Implementa AlloyDB con una secuencia de comandos automatizada
Este enfoque usa una secuencia de comandos automatizada para implementar el clúster de AlloyDB y proporcionar la información necesaria para comenzar a trabajar con los recursos implementados.
En la terminal de Cloud Shell, ejecuta el comando para clonar la secuencia de comandos de implementación desde el repositorio.
REPO_NAME="codelabs"
REPO_URL="https://github.com/GoogleCloudPlatform/$REPO_NAME"
SOURCE_DIR="alloydb-ai-mcp"
git clone --no-checkout --filter=blob:none --depth=1 $REPO_URL
cd $REPO_NAME
git sparse-checkout set $SOURCE_DIR
git checkout
cd $SOURCE_DIR
Ejecuta la secuencia de comandos de implementación.
./deploy_alloydb.sh
La secuencia de comandos tardará un tiempo en ejecutarse, por lo general, entre 5 y 7 minutos. Luego, como resultado, debería proporcionar información sobre tu clúster de AlloyDB implementado. Ten en cuenta que tu contraseña será diferente. Regístrala en algún lugar para usarla más adelante.
... <redacted> ... Creating primary instance: alloydb-aip-01-pr (8 vCPUs for TRIAL cluster) Operation ID: operation-1765988049916-646282264938a-bddce198-9f248715 Creating instance...done. ---------------------------------------- Deployment Process Completed Cluster: alloydb-aip-01 (TRIAL) Instance: alloydb-aip-01-pr Region: us-central1 Initial Password: JBBoDTgixzYwYpkF (if new cluster) ----------------------------------------
También puedes ver el clúster nuevo y la instancia principal en la consola web.
5. Prepara la base de datos
Debes habilitar la integración de Vertex AI para usar funciones y operadores de IA, habilitar la API de acceso a los datos y crear una base de datos para el conjunto de datos de muestra.
Otorga los permisos necesarios a AlloyDB
Agrega permisos de Vertex AI al agente de servicio de AlloyDB.
Abre otra pestaña de Cloud Shell con el signo "+" en la parte superior.
En la nueva pestaña de Cloud Shell, ejecuta lo siguiente:
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"
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/discoveryengine.viewer"
Resultado esperado en la consola:
student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=$(gcloud config get-value project) Your active configuration is: [cloudshell-11039] student@cloudshell:~ (test-project-001-402417)$ 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" Updated IAM policy for project [test-project-001-402417]. bindings: - members: - serviceAccount:service-4470404856@gcp-sa-alloydb.iam.gserviceaccount.com role: roles/aiplatform.user - members: ... < redacted > etag: BwYIEbe_Z3U= version: 1
Habilita la API de Data Access
Debes habilitar la API de Data Access en el clúster de AlloyDB para poder usar herramientas de MCP como execute_sql.
En la misma pestaña de la terminal, ejecuta lo siguiente.
PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
ADBCLUSTER=alloydb-aip-01
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://alloydb.googleapis.com/v1alpha/projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER/instances/$ADBCLUSTER-pr?updateMask=dataApiAccess \
-d '{
"dataApiAccess": "ENABLED",
}'
Update Instance Flags
Para usar las funciones avanzadas de IA en AlloyDB, debemos habilitar algunas marcas de la base de datos. Después de habilitar la API de Data Access, es posible que la instancia tarde unos minutos en mostrarse lista para los próximos cambios. Consulta el estado de la instancia en la consola para asegurarte de que tenga la marca de verificación verde.
En la misma pestaña de la terminal, ejecuta lo siguiente.
PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
ADBCLUSTER=alloydb-aip-01
gcloud beta alloydb instances update $ADBCLUSTER-pr \
--database-flags=google_ml_integration.enable_model_support=on,google_ml_integration.enable_ai_query_engine=on,google_ml_integration.enable_preview_ai_functions=on \
--region=$REGION \
--cluster=$ADBCLUSTER \
--project=$PROJECT_ID \
--update-mode=FORCE_APPLY
Habilita MCP
El siguiente paso es habilitar el servidor de MCP de Google Cloud para AlloyDB en tu proyecto. De forma predeterminada, el MCP no está habilitado y es una de las múltiples capas de protección, incluida la autenticación y autorización de IAM, la API de acceso a los datos y los roles dentro de tu clúster.
En la misma pestaña de la terminal, ejecuta lo siguiente.
PROJECT_ID=$(gcloud config get-value project)
gcloud beta services mcp enable alloydb.googleapis.com \
--project=$PROJECT_ID
Cierra la pestaña con el comando de ejecución “exit” en la pestaña:
exit
Conéctate a AlloyDB Studio
En los siguientes capítulos, todos los comandos de SQL que requieren conexión a la base de datos se pueden ejecutar en AlloyDB Studio. T
Navega a la página Clústeres en AlloyDB para PostgreSQL.
Haz clic en la instancia principal para abrir la interfaz de la consola web de tu clúster de AlloyDB.
Luego, haz clic en AlloyDB Studio a la izquierda:
Elige la base de datos postgres, el usuario postgres y proporciona la contraseña que anotamos cuando creamos el clúster. Luego, haz clic en el botón "Autenticar".
Si la contraseña no funciona o olvidaste anotarla, puedes cambiarla. Consulta la documentación para saber cómo hacerlo.
Se abrirá la interfaz de AlloyDB Studio. Para ejecutar los comandos en la base de datos, haz clic en la pestaña "Untitled Query" (Consulta sin título) que se encuentra a la derecha.
Se abre una interfaz en la que puedes ejecutar comandos de SQL.
Crea la base de datos
Guía de inicio rápido para crear una base de datos
En el editor de AlloyDB Studio, ejecuta el siguiente comando.
Crea la base de datos:
CREATE DATABASE quickstart_db
Resultado esperado:
Statement executed successfully
Conéctate a quickstart_db
Comprueba si se creó tu base de datos conectándote a ella. Vuelve a conectarte al estudio con el botón para cambiar de usuario o base de datos.
En la lista desplegable, selecciona la nueva base de datos quickstart_db y usa el mismo usuario y contraseña que antes.
Se abrirá una nueva conexión en la que podrás trabajar con objetos de la base de datos quickstart_db. Allí podrás examinar el esquema y los datos que importaste.
6. Datos de muestra
Ahora debes crear objetos en la base de datos y cargar datos. Usarás un conjunto de datos ficticio de la empresa Cymbal Shipping. Contiene datos ficticios sobre bienes, camiones, solicitudes y viajes de camiones, además de conductores ficticios.
Crear un bucket de Storage
Usarás el SDK de Google (gcloud) para importar datos de nuestro repositorio clonado a la base de datos de AlloyDB, por lo que deberás crear un bucket de almacenamiento para ello y otorgar acceso a la cuenta de servicio de AlloyDB. Como alternativa, siempre puedes intentar hacerlo con la consola web, como se describe en la documentación.
En la terminal de Google Cloud Shell, ejecuta el siguiente comando:
PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
gcloud storage buckets create gs://$PROJECT_ID-import --project=$PROJECT_ID --location=$REGION
gcloud storage buckets add-iam-policy-binding gs://$PROJECT_ID-import --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" --role=roles/storage.objectViewer
Carga de datos
El siguiente paso es cargar los datos. Nuestro volcado de SQL se encuentra en la carpeta del repositorio clonado. En el siguiente comando, se supone que usaste tu directorio principal como punto de partida cuando clonaste el repositorio en el paso anterior mientras creabas el clúster de AlloyDB.
Copia el volcado de SQL comprimido en el nuevo bucket de almacenamiento:
REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-mcp"
cd ~/$REPO_NAME/$SOURCE_DIR
gcloud storage cp ~/$REPO_NAME/$SOURCE_DIR/postgres_dump.sql.gz gs://$PROJECT_ID-import
Luego, carga los datos en la base de datos quickstart_db:
PROJECT_ID=$(gcloud config get-value project)
CLUSTER_NAME=alloydb-aip-01
REGION=us-central1
gcloud alloydb clusters import $CLUSTER_NAME --region=us-central1 --database=quickstart_db --gcs-uri=gs://$PROJECT_ID-import/postgres_dump.sql.gz --project=$PROJECT_ID --sql
El comando cargará el conjunto de datos de muestra en la base de datos quickstart_db. Puedes verificar las tablas y los registros con AlloyDB Studio.
7. Trabaja con el agente de datos
Comencemos con un agente de IA de muestra creado con el ADK de Google para Python y mostremos cómo configurarlo para que funcione con el servidor de MCP de Google Cloud para AlloyDB.
Verifica el código fuente del agente
En el repositorio clonado, revisa el código del agente con el editor de Google Cloud Shell.
REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-mcp"
edit ~/$REPO_NAME/$SOURCE_DIR/cymbal_logistic/data_agent/agent.py
En el agente, puedes ver que tenemos una sección para el servidor de MCP de Google Cloud para AlloyDB. Proporcionamos un extremo como MCP_SERVER_URL, autenticación, ID del proyecto y lo agregamos al conjunto de herramientas de MCP.
# Google Cloud MCP Server for AlloyDB
MCP_SERVER_URL = "https://alloydb.googleapis.com/mcp"
creds, project_id = default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
if not creds.valid:
creds.refresh(GoogleAuthRequest())
print(f"Authenticated as project: {project_id}")
# 2. Configure MCP Toolset
# We use StreamableHTTPConnectionParams to pass the auth header
headers = {
"Authorization": f"Bearer {creds.token}",
"X-Goog-User-Project": project_id
}
connection_params = StreamableHTTPConnectionParams(
url=MCP_SERVER_URL,
headers=headers,
timeout=300.0,
sse_read_timeout=600.0
)
mcp_toolset = McpToolset(connection_params=connection_params)
En el código del agente, el conjunto de herramientas de MCP se incluye como parámetro tools para el agente. También hay nombres de clústeres y de instancias, la región y la base de datos como variables para la instrucción del agente.
MODEL_ID = "gemini-3-flash-preview"
cluster_name="alloydb-aip-01"
instance_name="alloydb-aip-01-pr"
location="us-central1"
database_name="quickstart_db"
# Agent configuration
root_agent = Agent(
model=MODEL_ID,
name='root_agent',
description='A helpful assistant for analyst requests.',
instruction=f"""
Answer user questions to the best of your knowledge using provided tools.
Do not try to generate non-existent data but use the grounded data from the database.
When you answer questions about Cymbal Logistic activity
use the toolset to run query in the AlloyDB cluster {cluster_name} instance {instance_name} in the location {location}
in the project {project_id} in the database {database_name}
Use ai schema to use AI functions and models like gemini-3-flash-preview with the functions from the schema.
""",
tools=[mcp_toolset],
)
El servicio de MCP de Google Cloud para AlloyDB tiene un conjunto predefinido de herramientas. Si deseas enumerar todas las herramientas disponibles, puedes usar el comando curl desde la terminal de la consola de Cloud Shell con el siguiente comando. Además, siempre puedes consultar la referencia más reciente del servidor de MCP de Google Cloud para AlloyDB en la documentación.
curl -s -X POST http://alloydb.googleapis.com/mcp \
-H "Content-Type: application/json" \
-d @- <<EOF | jq -r '.result.tools[].name'
{
"id": "my_id_01",
"jsonrpc": "2.0",
"method": "tools/list"
}
EOF
Inicia el agente
Ahora puedes iniciar el agente en modo interactivo con la interfaz web del ADK de Google. La interfaz web del ADK proporciona una forma conveniente de probar y solucionar problemas de los flujos de trabajo de los agentes.
Primero, instalemos todos los paquetes necesarios para Python con el administrador de paquetes uv.
REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-mcp"
cd ~/$REPO_NAME/$SOURCE_DIR/cymbal_logistic
uv sync
Cuando se instalen todos los paquetes, deberás agregar un archivo .env al directorio del agente para indicarle que use Vertex AI en todas las comunicaciones con los modelos de IA.
echo "GOOGLE_GENAI_USE_VERTEXAI=true" > data_agent/.env
echo "GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project -q)" >> data_agent/.env
echo "GOOGLE_CLOUD_LOCATION=global" >> data_agent/.env
Luego, puedes iniciar el agente
uv run adk web --allow_origins 'regex:https://.*\.cloudshell\.dev'
Deberías ver un resultado como el siguiente con el extremo http://127.0.0.1:8000 .
Puedes hacer clic en esa URL en Cloud Shell y se abrirá una ventana de vista previa en una pestaña separada del navegador en la que podrás elegir el data_agent en la lista desplegable de la izquierda.
En la interfaz web del ADK, puedes publicar tus preguntas en la parte inferior derecha y ver el flujo de ejecución completo, incluidos los registros de cada paso en el lado derecho.
8. Prueba el MCP de AlloyDB con el agente
El agente te permite hacer preguntas de forma libre en lenguaje natural, y el agente usará el servidor MCP de Google Cloud para AlloyDB como herramienta para responderlas. Las preguntas se publican en la parte inferior derecha y la respuesta con todas las llamadas a las herramientas aparecerá en la parte superior.
Trabajas con datos operativos de una empresa de envíos que tiene información sobre solicitudes de envío, camiones, conductores y viajes realizados por los conductores. La primera pregunta se refiere a la cantidad de viajes realizados en febrero de 2026.
En el campo de entrada de la parte inferior derecha, escribe lo siguiente y presiona Intro.
Hello, can you tell me how many trips we've done in February this year?
El agente ejecutará varias llamadas a herramientas para identificar las tablas correctas en el esquema y la estructura de la tabla antes de ejecutar la sentencia de SQL correcta para obtener los datos adecuados.
Finalmente, producirá el resultado después de crear la consulta adecuada y ejecutarla en la base de datos.
Según los registros de nuestra base de datos, se completaron 108 viajes en febrero de 2026.
Puedes ver lo que hace cada llamada a la herramienta haciendo clic en la ejecución de la herramienta. Por ejemplo, esta es la consulta que se ejecutó para obtener nuestros resultados.
Ahora, haz que la solicitud sea más complicada y pide que se comparen los resultados con los del mes anterior.
How is it in comparison in numbers and mileage with the January?
Devuelve el resultado ejecutando diferentes consultas que analizan los resultados y proporcionan una diferencia en la cantidad de viajes y el kilometraje.
In comparison to January 2026, February saw a slight decrease in both the number of trips and the total mileage: January 2026: 114 trips with a total mileage of 185,597 km. February 2026: 108 trips with a total mileage of 177,893 km. This represents a decrease of 6 trips and 7,704 km in mileage for February compared to January.
Prueba otras solicitudes simples con la interfaz web del ADK y observa cómo ejecuta diferentes búsquedas para obtener los resultados.
Para detener el agente, presiona ctrl+c en la terminal. Puedes cerrar la pestaña del navegador con la interfaz web del ADK.
Ahora puedes probar una aplicación de ejemplo y ver cómo se puede usar como herramienta para los analistas de datos.
9. Aplicación de muestra
En el mismo repositorio clonado, tenemos una aplicación de muestra para nuestra empresa de logística Cymbol. La aplicación usa el framework de Python Mesop de Google .
Puedes analizar el código de la aplicación abriendo el archivo app.py en el editor de Cloud Shell.
REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-mcp"
edit ~/$REPO_NAME/$SOURCE_DIR/cymbal_logistic/app.py
En el código, usamos una función para pasar una instrucción nueva con variables a nuestro agente de datos. El motivo es poder configurarlo en la interfaz si decidimos llamar a una base de datos o instancia diferente. Aquí se muestran la definición de la función y la instrucción.
def run_query_sync(request_text, cluster_name, location, instance_name, database_name, project_id, session_id, summary):
local_runner = FrontendRunner()
instruction = f"""
Answer user questions to the best of your knowledge using provided tools.
Do not try to generate non-existent data but use the grounded data from the database.
When you answer questions about Cymbal Logistic activity
use the toolset to run query in the AlloyDB cluster {cluster_name} instance {instance_name} in the location {location}
in the project {project_id} in the database {database_name}
Use ai schema to use AI functions and models like gemini-3-flash-preview with the functions from the schema.
"""
...
Después de examinar el código, presiona el botón "terminal" para iniciar y probar nuestra aplicación. La aplicación se iniciará en el puerto 8080. Si quieres cambiar el puerto, ajusta el comando cambiando el valor del puerto.
En Cloud Shell, ejecuta el siguiente comando:
REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-mcp"
cd ~/$REPO_NAME/$SOURCE_DIR/cymbal_logistic
uv run mesop app.py --port=8080
Luego, haz clic en http://localhost:8080 para usar la vista previa en la Web en Google Cloud Shell.
Se abrirá una pestaña nueva en el navegador con la interfaz de la aplicación.
Haz clic en la casilla de verificación “Habilitar salida de depuración” en la esquina superior derecha y escribe una pregunta como la siguiente.
What was the average speed for each driver last month? List top 5 fasters drivers ranking them by the average speed. Show the name, distance and average speed for each of them.
Luego, presiona el botón Submit Request.
El agente trabajará tras bambalinas y producirá el resultado y la información de depuración con todas las búsquedas ejecutadas por nuestro conjunto de herramientas de MCP. Revisa las consultas para ver el flujo de trabajo.
Puedes probar las capacidades de los agentes y las apps haciendo diferentes preguntas analíticas.
Hasta ahora, pudiste realizar algunas tareas básicas de análisis y descubrimiento con el agente y el MCP. En el siguiente capítulo, intentarás usar funciones más avanzadas de AlloyDB.
10. Funciones de AlloyDB AI
Las funciones potenciadas por IA de AlloyDB permiten el filtrado y la clasificación inteligentes de datos de texto y multimodales (en particular, imágenes) y aportan el poder de Gemini a tus consultas. En particular, las funciones AI.IF y AI.RANK de AlloyDB AI pueden aparecer en sentencias de SQL junto con operadores convencionales de SQL (filtros, uniones, agregación, etcétera).
Antes de usar las funciones de IA, examinamos una búsqueda y agregaciones con los métodos "clásicos". Prueba la siguiente instrucción.
Can you analyze the activity for the last 5 months and evaluate drivers for the most positive customer feedbacks. Give me top 5 drivers listing names, distance and years of experience for each driver.
Puede encontrar la columna "calificación" en la tabla con los comentarios de los clientes y usarla para identificar a los conductores con la mejor calificación. Luego, usó la información para obtener más detalles sobre los conductores.
SELECT
d.first_name || ' ' || d.last_name as driver_name,
SUM(sr.distance_km) as total_distance,
d.experience_years,
COUNT(cf.feedback_id) as positive_feedback_count
FROM drivers d
JOIN truck_trips tt ON d.driver_id = tt.driver_id
JOIN customer_feedback cf ON tt.trip_id = cf.trip_id
JOIN shipping_requests sr ON tt.request_id = sr.request_id
WHERE tt.arrival_time >= '2025-12-01'
AND tt.arrival_time < '2026-05-01'
AND cf.rating >= 4
GROUP BY d.driver_id, d.first_name, d.last_name, d.experience_years
ORDER BY positive_feedback_count DESC, total_distance DESC
LIMIT 5;
Sin embargo, técnicamente, la calificación puede incluir o no todos los parámetros que queremos evaluar. Para ello, podemos usar las funciones IA de AlloyDB.
Operadores AI.RANK
La función ai.rank() califica qué tan bien un documento responde una búsqueda determinada. Se puede usar para clasificar o reclasificar los resultados de la búsqueda. Puedes obtener más información sobre los operadores en la documentación.
Modifica la solicitud y pide explícitamente que se use AI.RANK durante el análisis para evaluar los impulsores en función de su rendimiento y profesionalismo.
Can you find the top 5 fastest drivers in the last month and rank them by the feedback using the AI.RANK function? Give me top drivers names, distance, years of experience and rank for each driver.
El comando puede tardar un poco más, ya que el agente debe descubrir cómo usar la función AI.RANK, obtener los datos y aplicar AI.RANK para ordenar la información de manera adecuada. Al final, deberías obtener la lista de conductores clasificados por el modelo y la lista de búsquedas ejecutadas.
Esa consulta puede tardar un tiempo en ejecutarse según la ruta que elija el modelo. En la ventana de depuración, puedes ver la consulta exacta que se ejecutó para obtener la información sobre los conductores.
WITH fastest_drivers AS (
SELECT
d.driver_id,
d.first_name || ' ' || d.last_name as driver_name,
d.experience_years,
SUM(sr.distance_km) as total_distance,
AVG(sr.distance_km / (NULLIF(EXTRACT(EPOCH
FROM (tt.arrival_time - tt.departure_time)), 0) / 3600)) as avg_speed,
COALESCE(STRING_AGG(cf.feedback_text, ' | '), 'No feedback') as feedbacks,
ROW_NUMBER() OVER (
ORDER BY AVG(sr.distance_km / (NULLIF(EXTRACT(EPOCH
FROM (tt.arrival_time - tt.departure_time)), 0) / 3600)) DESC) - 1 as row_idx
FROM drivers d
JOIN truck_trips tt ON d.driver_id = tt.driver_id
JOIN shipping_requests sr ON tt.request_id = sr.request_id
LEFT
JOIN customer_feedback cf ON tt.trip_id = cf.trip_id
WHERE tt.arrival_time >= '2026-04-04'
AND tt.arrival_time IS NOT NULL
AND tt.departure_time IS NOT NULL
AND tt.arrival_time > tt.departure_time
GROUP BY d.driver_id, d.first_name, d.last_name, d.experience_years
ORDER BY avg_speed DESC
LIMIT 5
)
SELECT
f.driver_name,
f.total_distance,
f.experience_years,
f.avg_speed,
f.feedbacks,
(SELECT r.score
FROM ai.rank(
'semantic-ranker-fast-004',
'excellent customer service, professional, friendly, fast,
and reliable delivery reviews',
ARRAY[f.feedbacks],
1
) r
LIMIT 1) as feedback_score
FROM fastest_drivers f
ORDER BY feedback_score DESC;
Puedes seguir probando la aplicación y examinar las búsquedas para ver cómo el agente llega a los resultados finales.
Con esto, finaliza el lab. Espero que hayas podido revisar todos los ejemplos y aprender a usar el servicio de MCP de Google Cloud para AlloyDB. Para que tu MCP funcione para la empresa, tiene sentido combinarlo con las funciones de NL2SQL de AlloyDB que se describen en la documentación de AlloyDB. Puedes probarlo con el codelab sobre cómo generar instrucciones SQL para AlloyDB.
11. Limpia el entorno
Para evitar cargos inesperados, es una práctica recomendada limpiar los recursos temporales. La forma más confiable es borrar el proyecto en el que probaste el flujo de trabajo. Sin embargo, de manera opcional, puedes limitar tu uso borrando recursos individuales, como AlloyDB.
Cuando termines el lab, destruye las instancias y el clúster de AlloyDB.
Borra el clúster de AlloyDB y todas las instancias
Si usaste la versión de prueba de AlloyDB No borres el clúster de prueba si planeas probar otros labs y recursos con él. No podrás crear otro clúster de prueba en el mismo proyecto.
El clúster se destruye con la opción force que también borra todas las instancias que pertenecen al clúster.
En Cloud Shell, define el proyecto y las variables de entorno si te desconectaste y se perdieron todos los parámetros de configuración anteriores:
gcloud config set project <your project id>
export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01
export PROJECT_ID=$(gcloud config get-value project)
Borra el clúster:
gcloud alloydb clusters delete $ADBCLUSTER --region=$REGION --force
Resultado esperado en la consola:
student@cloudshell:~ (test-project-001-402417)$ gcloud alloydb clusters delete $ADBCLUSTER --region=$REGION --force All of the cluster data will be lost when the cluster is deleted. Do you want to continue (Y/n)? Y Operation ID: operation-1697820178429-6082890a0b570-4a72f7e4-4c5df36f Deleting cluster...done.
Borra las copias de seguridad de AlloyDB
Borra todas las copias de seguridad de AlloyDB del clúster:
for i in $(gcloud alloydb backups list --filter="CLUSTER_NAME: projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER" --format="value(name)" --sort-by=~createTime) ; do gcloud alloydb backups delete $(basename $i) --region $REGION --quiet; done
Resultado esperado en la consola:
student@cloudshell:~ (test-project-001-402417)$ for i in $(gcloud alloydb backups list --filter="CLUSTER_NAME: projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER" --format="value(name)" --sort-by=~createTime) ; do gcloud alloydb backups delete $(basename $i) --region $REGION --quiet; done Operation ID: operation-1697826266108-60829fb7b5258-7f99dc0b-99f3c35f Deleting backup...done.
12. Felicitaciones
Felicitaciones por completar el codelab.
Temas abordados
- Cómo crear un clúster de AlloyDB y, luego, importar datos de muestra
- Cómo habilitar la API de acceso a los datos de AlloyDB
- Cómo habilitar el MCP de Google Cloud para AlloyDB NL
- Cómo agregar Google Cloud MCP para AlloyDB a tu agente de ADK
- Cómo usar Google Cloud MCP para AlloyDB en una aplicación
- Cómo usar agentes con AlloyDBMCP para el análisis
13. Encuesta
Resultado: