Despliega un modelo YOLO preentrenado con Ultralytics en Vertex AI para inferencia

Esta guía te mostrará cómo crear un contenedor para un modelo YOLO26 preentrenado con Ultralytics, construir un servidor de inferencia con FastAPI y desplegar el modelo con dicho servidor en Google Cloud Vertex AI. La implementación de ejemplo cubrirá el caso de uso de detección de objetos para YOLO26, pero los mismos principios se aplican al usar otros modos YOLO.

Antes de empezar, necesitarás crear un proyecto en Google Cloud Platform (GCP). Obtienes 300 $ en créditos de GCP para usar de forma gratuita como nuevo usuario, y esta cantidad es suficiente para probar una configuración en ejecución que después podrás ampliar para cualquier otro caso de uso de YOLO26, incluyendo entrenamiento o inferencia por lotes y en streaming.

Qué aprenderás

1. Crear un backend de inferencia para el modelo YOLO26 de Ultralytics usando FastAPI.
2. Crear un repositorio en GCP Artifact Registry para almacenar tu imagen de Docker.
3. Construir y subir la imagen de Docker con el modelo a Artifact Registry.
4. Importar tu modelo en Vertex AI.
5. Crear un endpoint de Vertex AI y desplegar el modelo.

Requisitos previos

1. Instala Docker en tu máquina.
2. Instala el Google Cloud SDK y autentícate para usar la CLI de gcloud.
3. Se recomienda encarecidamente que consultes la Guía de inicio rápido de Docker para Ultralytics, ya que necesitarás extender una de las imágenes oficiales de Docker de Ultralytics mientras sigues esta guía.

Crear un backend de inferencia con FastAPI

Primero, debes crear una aplicación FastAPI que atienda las solicitudes de inferencia del modelo YOLO26. Esta aplicación gestionará la carga del modelo, el preprocesamiento de la imagen y la lógica de inferencia (predicción).

Fundamentos de cumplimiento de Vertex AI

Vertex AI espera que tu contenedor implemente dos endpoints específicos:

1. Endpoint de Salud (/health): Debe devolver el estado HTTP 200 OK cuando el servicio esté listo.

2. Endpoint de Predicción (/predict): Acepta solicitudes de predicción estructuradas con imágenes codificadas en base64 y parámetros opcionales. Se aplican límites de tamaño de carga útil dependiendo del tipo de endpoint.

   Las cargas útiles de solicitud para el endpoint /predict deben seguir esta estructura JSON:

   {
       "instances": [{ "image": "base64_encoded_image" }],
       "parameters": { "confidence": 0.5 }
   }

Estructura de carpetas del proyecto

La mayor parte de nuestra construcción ocurrirá dentro del contenedor de Docker, y Ultralytics también cargará un modelo YOLO26 preentrenado, por lo que puedes mantener la estructura de carpetas local simple:

YOUR_PROJECT/
├── src/
│   ├── __init__.py
│   ├── app.py              # Core YOLO26 inference logic
│   └── main.py             # FastAPI inference server
├── tests/
├── .env                    # Environment variables for local development
├── Dockerfile              # Container configuration
├── LICENSE                 # AGPL-3.0 License
└── pyproject.toml          # Python dependencies and project config

Crear pyproject.toml con dependencias

Para gestionar tu proyecto cómodamente, crea un archivo pyproject.toml con las siguientes dependencias:

[project]
name = "YOUR_PROJECT_NAME"
version = "0.0.1"
description = "YOUR_PROJECT_DESCRIPTION"
requires-python = ">=3.10,<3.13"
dependencies = [
   "ultralytics>=8.3.0",
   "fastapi[all]>=0.89.1",
   "uvicorn[standard]>=0.20.0",
   "pillow>=9.0.0",
]

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

• uvicorn se usará para ejecutar el servidor FastAPI.
• pillow se usará para el procesamiento de imágenes, pero no estás limitado solo a imágenes PIL: Ultralytics admite muchos otros formatos.

Crear lógica de inferencia con Ultralytics YOLO26

Ahora que tienes la estructura del proyecto y las dependencias configuradas, puedes implementar la lógica central de inferencia de YOLO26. Crea un archivo src/app.py que manejará la carga del modelo, el procesamiento de imágenes y la predicción, usando la API de Python de Ultralytics.

# src/app.py

from ultralytics import YOLO

# Model initialization and readiness state
model_yolo = None
_model_ready = False

def _initialize_model():
    """Initialize the YOLO model."""
    global model_yolo, _model_ready

    try:
        # Use pretrained YOLO26n model from Ultralytics base image
        model_yolo = YOLO("yolo26n.pt")
        _model_ready = True

    except Exception as e:
        print(f"Error initializing YOLO model: {e}")
        _model_ready = False
        model_yolo = None

# Initialize model on module import
_initialize_model()

def is_model_ready() -> bool:
    """Check if the model is ready for inference."""
    return _model_ready and model_yolo is not None

Esto cargará el modelo una vez cuando el contenedor arranque, y el modelo será compartido entre todas las solicitudes. Si tu modelo va a manejar una carga de inferencia pesada, se recomienda seleccionar un tipo de máquina con más memoria al importar un modelo en Vertex AI en un paso posterior.

A continuación, crea dos funciones de utilidad para el procesamiento de imágenes de entrada y salida con pillow. YOLO26 admite imágenes PIL de forma nativa.

def get_image_from_bytes(binary_image: bytes) -> Image.Image:
    """Convert image from bytes to PIL RGB format."""
    input_image = Image.open(io.BytesIO(binary_image)).convert("RGB")
    return input_image

def get_bytes_from_image(image: Image.Image) -> bytes:
    """Convert PIL image to bytes."""
    return_image = io.BytesIO()
    image.save(return_image, format="JPEG", quality=85)
    return_image.seek(0)
    return return_image.getvalue()

Finalmente, implementa la función run_inference que manejará la detección de objetos. En este ejemplo, extraeremos cuadros delimitadores (bounding boxes), nombres de clase y puntuaciones de confianza de las predicciones del modelo. La función devolverá un diccionario con las detecciones y los resultados sin procesar para su posterior tratamiento o anotación.

def run_inference(input_image: Image.Image, confidence_threshold: float = 0.5) -> Dict[str, Any]:
    """Run inference on an image using YOLO26n model."""
    global model_yolo

    # Check if model is ready
    if not is_model_ready():
        print("Model not ready for inference")
        return {"detections": [], "results": None}

    try:
        # Make predictions and get raw results
        results = model_yolo.predict(
            imgsz=640, source=input_image, conf=confidence_threshold, save=False, augment=False, verbose=False
        )

        # Extract detections (bounding boxes, class names, and confidences)
        detections = []
        if results and len(results) > 0:
            result = results[0]
            if result.boxes is not None and len(result.boxes.xyxy) > 0:
                boxes = result.boxes

                # Convert tensors to numpy for processing
                xyxy = boxes.xyxy.cpu().numpy()
                conf = boxes.conf.cpu().numpy()
                cls = boxes.cls.cpu().numpy().astype(int)

                # Create detection dictionaries
                for i in range(len(xyxy)):
                    detection = {
                        "xmin": float(xyxy[i][0]),
                        "ymin": float(xyxy[i][1]),
                        "xmax": float(xyxy[i][2]),
                        "ymax": float(xyxy[i][3]),
                        "confidence": float(conf[i]),
                        "class": int(cls[i]),
                        "name": model_yolo.names.get(int(cls[i]), f"class_{int(cls[i])}"),
                    }
                    detections.append(detection)

        return {
            "detections": detections,
            "results": results,  # Keep raw results for annotation
        }
    except Exception as e:
        # If there's an error, return empty structure
        print(f"Error in YOLO detection: {e}")
        return {"detections": [], "results": None}

Opcionalmente, puedes añadir una función para anotar la imagen con cuadros delimitadores y etiquetas usando el método de trazado integrado de Ultralytics. Esto será útil si deseas devolver imágenes anotadas en la respuesta de predicción.

def get_annotated_image(results: list) -> Image.Image:
    """Get annotated image using Ultralytics built-in plot method."""
    if not results or len(results) == 0:
        raise ValueError("No results provided for annotation")

    result = results[0]
    # Use Ultralytics built-in plot method with PIL output
    return result.plot(pil=True)

Crear un servidor de inferencia HTTP con FastAPI

Ahora que tienes la lógica central de inferencia de YOLO26, puedes crear una aplicación FastAPI para servirla. Esto incluirá los endpoints de comprobación de salud y predicción requeridos por Vertex AI.

Primero, añade las importaciones y configura el registro (logging) para Vertex AI. Debido a que Vertex AI trata stderr como salida de error, tiene sentido redirigir los registros a stdout.

import sys

from loguru import logger

# Configure logger
logger.remove()
logger.add(
    sys.stdout,
    colorize=True,
    format="<green>{time:HH:mm:ss}</green> | <level>{message}</level>",
    level=10,
)
logger.add("log.log", rotation="1 MB", level="DEBUG", compression="zip")

Para un cumplimiento completo de Vertex AI, define los endpoints requeridos en variables de entorno y establece el límite de tamaño para las solicitudes. Se recomienda usar endpoints privados de Vertex AI para despliegues en producción. De este modo, tendrás un límite de carga útil de solicitud más alto (10 MB en lugar de 1,5 MB para endpoints públicos), junto con una seguridad sólida y control de acceso.

# Vertex AI environment variables
AIP_HTTP_PORT = int(os.getenv("AIP_HTTP_PORT", "8080"))
AIP_HEALTH_ROUTE = os.getenv("AIP_HEALTH_ROUTE", "/health")
AIP_PREDICT_ROUTE = os.getenv("AIP_PREDICT_ROUTE", "/predict")

# Request size limit (10 MB for private endpoints, 1.5 MB for public)
MAX_REQUEST_SIZE = 10 * 1024 * 1024  # 10 MB in bytes

Añade dos modelos Pydantic para validar tus solicitudes y respuestas:

# Pydantic models for request/response
class PredictionRequest(BaseModel):
    instances: list
    parameters: Optional[Dict[str, Any]] = None

class PredictionResponse(BaseModel):
    predictions: list

Añade el endpoint de comprobación de salud para verificar la preparación de tu modelo. Esto es importante para Vertex AI, ya que sin una comprobación de salud dedicada, su orquestador hará ping a sockets aleatorios y no podrá determinar si el modelo está listo para la inferencia. Tu comprobación debe devolver 200 OK para el éxito y 503 Service Unavailable para el fallo:

# Health check endpoint
@app.get(AIP_HEALTH_ROUTE, status_code=status.HTTP_200_OK)
def health_check():
    """Health check endpoint for Vertex AI."""
    if not is_model_ready():
        raise HTTPException(status_code=503, detail="Model not ready")
    return {"status": "healthy"}

Ahora ya tienes todo para implementar el endpoint de predicción que manejará las solicitudes de inferencia. Aceptará un archivo de imagen, ejecutará la inferencia y devolverá los resultados. Ten en cuenta que la imagen debe estar codificada en base64, lo que aumenta adicionalmente el tamaño de la carga útil hasta en un 33%.

@app.post(AIP_PREDICT_ROUTE, response_model=PredictionResponse)
async def predict(request: PredictionRequest):
    """Prediction endpoint for Vertex AI."""
    try:
        predictions = []

        for instance in request.instances:
            if isinstance(instance, dict):
                if "image" in instance:
                    image_data = base64.b64decode(instance["image"])
                    input_image = get_image_from_bytes(image_data)
                else:
                    raise HTTPException(status_code=400, detail="Instance must contain 'image' field")
            else:
                raise HTTPException(status_code=400, detail="Invalid instance format")

            # Extract YOLO26 parameters if provided
            parameters = request.parameters or {}
            confidence_threshold = parameters.get("confidence", 0.5)
            return_annotated_image = parameters.get("return_annotated_image", False)

            # Run inference with YOLO26n model
            result = run_inference(input_image, confidence_threshold=confidence_threshold)
            detections_list = result["detections"]

            # Format predictions for Vertex AI
            detections = []
            for detection in detections_list:
                formatted_detection = {
                    "class": detection["name"],
                    "confidence": detection["confidence"],
                    "bbox": {
                        "xmin": detection["xmin"],
                        "ymin": detection["ymin"],
                        "xmax": detection["xmax"],
                        "ymax": detection["ymax"],
                    },
                }
                detections.append(formatted_detection)

            # Build prediction response
            prediction = {"detections": detections, "detection_count": len(detections)}

            # Add annotated image if requested and detections exist
            if (
                return_annotated_image
                and result["results"]
                and result["results"][0].boxes is not None
                and len(result["results"][0].boxes) > 0
            ):
                import base64

                annotated_image = get_annotated_image(result["results"])
                img_bytes = get_bytes_from_image(annotated_image)
                prediction["annotated_image"] = base64.b64encode(img_bytes).decode("utf-8")

            predictions.append(prediction)

        logger.info(
            f"Processed {len(request.instances)} instances, found {sum(len(p['detections']) for p in predictions)} total detections"
        )

        return PredictionResponse(predictions=predictions)

    except HTTPException:
        # Re-raise HTTPException as-is (don't catch and convert to 500)
        raise
    except Exception as e:
        logger.error(f"Prediction error: {e}")
        raise HTTPException(status_code=500, detail=f"Prediction failed: {e}")

Finalmente, añade el punto de entrada de la aplicación para ejecutar el servidor FastAPI.

if __name__ == "__main__":
    import uvicorn

    logger.info(f"Starting server on port {AIP_HTTP_PORT}")
    logger.info(f"Health check route: {AIP_HEALTH_ROUTE}")
    logger.info(f"Predict route: {AIP_PREDICT_ROUTE}")
    uvicorn.run(app, host="0.0.0.0", port=AIP_HTTP_PORT)

Ahora tienes una aplicación FastAPI completa que puede servir solicitudes de inferencia de YOLO26. Puedes probarla localmente instalando las dependencias y ejecutando el servidor, por ejemplo, con uv.

# Install dependencies
uv pip install -e .

# Run the FastAPI server directly
uv run src/main.py

Para probar el servidor, puedes consultar tanto los endpoints /health como /predict usando cURL. Coloca una imagen de prueba en la carpeta tests. Luego, en tu terminal, ejecuta los siguientes comandos:

# Test health endpoint
curl http://localhost:8080/health

# Test predict endpoint with base64 encoded image
curl -X POST -H "Content-Type: application/json" -d "{\"instances\": [{\"image\": \"$(base64 -i tests/test_image.jpg)\"}]}" http://localhost:8080/predict

Deberías recibir una respuesta JSON con los objetos detectados. En tu primera solicitud, espera un breve retraso, ya que Ultralytics necesita extraer y cargar el modelo YOLO26.

Extender la imagen de Docker de Ultralytics con tu aplicación

Ultralytics proporciona varias imágenes de Docker que puedes usar como base para la imagen de tu aplicación. Docker instalará Ultralytics y los controladores de GPU necesarios.

Para usar todas las capacidades de los modelos YOLO de Ultralytics, deberías seleccionar la imagen optimizada para CUDA para inferencia con GPU. Sin embargo, si la inferencia en CPU es suficiente para tu tarea, puedes ahorrar recursos de cómputo seleccionando también la imagen solo para CPU:

• Dockerfile: Imagen optimizada para CUDA para entrenamiento e inferencia en YOLO26 con una o varias GPU.
• Dockerfile-cpu: Imagen solo para CPU para inferencia con YOLO26.

Crear una imagen de Docker para tu aplicación

Crea un Dockerfile en la raíz de tu proyecto con el siguiente contenido:

# Extends official Ultralytics Docker image for YOLO26
FROM ultralytics/ultralytics:latest

ENV PYTHONUNBUFFERED=1 \
    PYTHONDONTWRITEBYTECODE=1

# Install FastAPI and dependencies
RUN uv pip install fastapi[all] uvicorn[standard] loguru

WORKDIR /app
COPY src/ ./src/
COPY pyproject.toml ./

# Install the application package
RUN uv pip install -e .

RUN mkdir -p /app/logs
ENV PYTHONPATH=/app/src

# Port for Vertex AI
EXPOSE 8080

# Start the inference server
ENTRYPOINT ["python", "src/main.py"]

En el ejemplo, se utiliza la imagen oficial de Docker de Ultralytics ultralytics:latest como base. Ya contiene el modelo YOLO26 y todas las dependencias necesarias. El punto de entrada del servidor es el mismo que usamos para probar la aplicación FastAPI localmente.

Construir y probar la imagen de Docker

Ahora puedes construir la imagen de Docker con el siguiente comando:

docker build --platform linux/amd64 -t IMAGE_NAME:IMAGE_VERSION .

Reemplaza IMAGE_NAME e IMAGE_VERSION con los valores que desees, por ejemplo, yolo26-fastapi:0.1. Ten en cuenta que debes construir la imagen para la arquitectura linux/amd64 si vas a desplegarla en Vertex AI. El parámetro --platform debe establecerse explícitamente si estás construyendo la imagen en un Mac con Apple Silicon o cualquier otra arquitectura no x86.

Una vez completada la construcción de la imagen, puedes probar la imagen de Docker localmente:

docker run --platform linux/amd64 -p 8080:8080 IMAGE_NAME:IMAGE_VERSION

Tu contenedor de Docker está ejecutando ahora un servidor FastAPI en el puerto 8080, listo para aceptar solicitudes de inferencia. Puedes probar tanto el endpoint /health como el /predict con los mismos comandos cURL que antes:

# Test health endpoint
curl http://localhost:8080/health

# Test predict endpoint with base64 encoded image
curl -X POST -H "Content-Type: application/json" -d "{\"instances\": [{\"image\": \"$(base64 -i tests/test_image.jpg)\"}]}" http://localhost:8080/predict

Subir la imagen de Docker a GCP Artifact Registry

Para importar tu modelo en contenedor en Vertex AI, necesitas subir la imagen de Docker a Google Cloud Artifact Registry. Si aún no tienes un repositorio en Artifact Registry, primero tendrás que crear uno.

Crear un repositorio en Google Cloud Artifact Registry

Abre la página de Artifact Registry en la consola de Google Cloud. Si es la primera vez que usas Artifact Registry, es posible que se te solicite habilitar primero la API de Artifact Registry.

1. Selecciona Crear repositorio.
2. Introduce el nombre de tu repositorio. Selecciona la región deseada y usa la configuración predeterminada para otras opciones, a menos que necesites cambiarlas específicamente.

1. Una vez creado el repositorio, guarda tu PROJECT_ID, Ubicación (Región) y Nombre del repositorio en tu gestor de secretos o archivo .env. Los necesitarás más adelante para etiquetar y subir tu imagen de Docker a Artifact Registry.

Autenticar Docker en Artifact Registry

Autentica tu cliente Docker en el repositorio de Artifact Registry que acabas de crear. Ejecuta el siguiente comando en tu terminal:

gcloud auth configure-docker YOUR_REGION-docker.pkg.dev

Etiquetar y subir tu imagen a Artifact Registry

Etiqueta y sube la imagen de Docker a Google Artifact Registry.

Etiqueta tu imagen con la URL del repositorio de Artifact Registry. Reemplaza los marcadores de posición con los valores que guardaste anteriormente.

docker tag IMAGE_NAME:IMAGE_VERSION YOUR_REGION-docker.pkg.dev/YOUR_PROJECT_ID/YOUR_REPOSITORY_NAME/IMAGE_NAME:IMAGE_VERSION

Sube la imagen etiquetada al repositorio de Artifact Registry.

docker push YOUR_REGION-docker.pkg.dev/YOUR_PROJECT_ID/YOUR_REPOSITORY_NAME/IMAGE_NAME:IMAGE_VERSION

Espera a que el proceso se complete. Ahora deberías ver la imagen en tu repositorio de Artifact Registry.

Para instrucciones más específicas sobre cómo trabajar con imágenes en Artifact Registry, consulta la documentación de Artifact Registry: Subir y descargar imágenes.

Importar tu modelo en Vertex AI

Usando la imagen de Docker que acabas de subir, ahora puedes importar el modelo en Vertex AI.

1. En el menú de navegación de Google Cloud, ve a Vertex AI > Registro de modelos. Alternativamente, busca "Vertex AI" en la barra de búsqueda en la parte superior de la consola de Google Cloud.

Crear un endpoint de Vertex AI y desplegar tu modelo

Para desplegar un modelo, necesitas crear un endpoint en Vertex AI.

1. En tu menú de navegación de Vertex AI, ve a Endpoints. Selecciona la región que usaste al importar tu modelo. Haz clic en Crear.

1. Una vez seleccionado el tipo de máquina, puedes hacer clic en Continuar. En este punto, puedes elegir habilitar la monitorización de modelos en Vertex AI, un servicio adicional que realizará un seguimiento del rendimiento de tu modelo y proporcionará información sobre su comportamiento. Esto es opcional e implica costes adicionales, así que selecciona según tus necesidades. Haz clic en Crear.

Vertex AI tardará varios minutos (hasta 30 minutos en algunas regiones) en desplegar el modelo. Recibirás una notificación por correo electrónico una vez que el despliegue se haya completado.

Probar tu modelo desplegado

Una vez completado el despliegue, Vertex AI te proporcionará una interfaz de API de ejemplo para probar tu modelo.

Para probar la inferencia remota, puedes usar el comando cURL proporcionado o crear otra biblioteca de cliente de Python que enviará solicitudes al modelo desplegado. Recuerda que debes codificar tu imagen en base64 antes de enviarla al endpoint /predict.

Has desplegado con éxito un modelo YOLO26 preentrenado con Ultralytics en Google Cloud Vertex AI.

Preguntas frecuentes

¿Puedo usar modelos YOLO de Ultralytics en Vertex AI sin Docker?

Sí; sin embargo, primero tendrás que exportar el modelo a un formato compatible con Vertex AI, como TensorFlow, Scikit-learn o XGBoost. Google Cloud proporciona una guía sobre cómo ejecutar modelos .pt en Vertex con una visión general completa del proceso de conversión: Ejecutar modelos de PyTorch en Vertex AI.

Ten en cuenta que la configuración resultante dependerá solo de la capa de servicio estándar de Vertex AI y no admitirá las funciones avanzadas del framework Ultralytics. Dado que Vertex AI admite totalmente los modelos en contenedor y puede escalarlos automáticamente según tu configuración de despliegue, esto te permite aprovechar todas las capacidades de los modelos YOLO de Ultralytics sin necesidad de convertirlos a un formato diferente.

¿Por qué FastAPI es una buena opción para servir inferencias con YOLO26?

FastAPI ofrece un alto rendimiento para cargas de trabajo de inferencia. Su soporte asíncrono permite gestionar múltiples solicitudes concurrentes sin bloquear el hilo principal, lo cual es importante al servir modelos de visión por computadora.

La validación automática de solicitudes/respuestas con FastAPI reduce los errores en tiempo de ejecución en servicios de inferencia en producción. Esto es especialmente valioso para APIs de detección de objetos donde la coherencia del formato de entrada es fundamental.

FastAPI añade una sobrecarga computacional mínima a tu canal de inferencia, dejando más recursos disponibles para la ejecución del modelo y las tareas de procesamiento de imágenes.

FastAPI también soporta SSE (Server-Sent Events), lo cual resulta útil para escenarios de inferencia en tiempo real o streaming.

¿Por qué tengo que seleccionar una región tantas veces?

Esta es en realidad una función de versatilidad de Google Cloud Platform, donde necesitas seleccionar una región para cada servicio que utilices. Para la tarea de desplegar un modelo contenerizado en Vertex AI, la selección de región más importante es la del Model Registry. Esta determinará la disponibilidad de tipos de máquinas y cuotas para el despliegue de tu modelo.

Además, si vas a ampliar la configuración y almacenar datos de predicción o resultados en Cloud Storage o BigQuery, necesitarás utilizar la misma región que para Model Registry para minimizar la latencia y garantizar un alto rendimiento en el acceso a los datos.