Despliega un modelo YOLO preentrenado con Ultralytics en Vertex AI para realizar inferencias#

Esta guía te mostrará cómo contenerizar un modelo YOLO26 preentrenado con Ultralytics, crear un servidor de inferencias FastAPI para él y desplegar el modelo con el servidor de inferencias 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 aplicarán al uso de otros modos de YOLO.

Antes de empezar, tendrás que crear un proyecto de Google Cloud Platform (GCP). Como usuario nuevo, recibirás 300 $ en créditos de GCP para usar gratis, 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, incluido el entrenamiento o la inferencia por lotes y en streaming.

Qué aprenderás#

1. Crea un backend de inferencias para el modelo Ultralytics YOLO26 usando FastAPI.
2. Crea un repositorio de GCP Artifact Registry para almacenar tu imagen de Docker.
3. Compila y sube la imagen de Docker con el modelo a Artifact Registry.
4. Importa tu modelo en Vertex AI.
5. Crea un endpoint de Vertex AI y despliega el modelo.

Requisitos previos#

1. Instala Docker en tu equipo.
2. Instala el Google Cloud SDK y autentícate para usar la CLI de gcloud.
3. Te recomendamos encarecidamente que consultes la Guía de inicio rápido de Docker para Ultralytics, porque tendrás que ampliar una de las imágenes oficiales de Docker de Ultralytics siguiendo esta guía.

1. Crea un backend de inferencias con FastAPI#

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

Fundamentos del cumplimiento de Vertex AI#

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

1. Endpoint de estado (/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 la carga útil según el 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 la compilación se realizará dentro del contenedor de Docker, y Ultralytics también cargará un modelo YOLO26 preentrenado, por lo que puedes mantener sencilla la estructura de carpetas local:

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

Crea pyproject.toml con las dependencias#

Para gestionar cómodamente tu proyecto, 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 procesar imágenes, pero no estás limitado únicamente a imágenes PIL: Ultralytics admite muchos otros formatos.

Crea la lógica de inferencia con Ultralytics YOLO26#

Ahora que ya tienes configuradas la estructura del proyecto y las dependencias, puedes implementar la lógica principal de inferencia de YOLO26. Crea un archivo src/app.py que gestione la carga del modelo, el procesamiento de imágenes y la predicción mediante 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 al iniciar el contenedor, y el modelo se compartirá entre todas las solicitudes. Si el modelo va a gestionar una carga de inferencia elevada, te recomendamos 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 auxiliares para el procesamiento de las 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()

Por último, implementa la función run_inference que gestionará la detección de objetos. En este ejemplo, extraeremos las cajas delimitadoras, los nombres de las clases y las 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 procesamiento 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."""
    # 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 cajas delimitadoras y etiquetas usando el método de trazado integrado de Ultralytics. Esto resultará útil si quieres 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)

Crea un servidor HTTP de inferencias con FastAPI#

Ahora que ya tienes la lógica principal de inferencia de YOLO26, puedes crear una aplicación FastAPI para servirla. Esto incluirá los endpoints de comprobación de estado y predicción que requiere Vertex AI.

Primero, añade las importaciones y configura el registro para Vertex AI. Como 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 cumplir completamente los requisitos de Vertex AI, define los endpoints necesarios en variables de entorno y establece el límite de tamaño de las solicitudes. Te recomendamos usar endpoints privados de Vertex AI para los despliegues de producción. De este modo tendrás un límite de carga útil de solicitud mayor (10 MB en lugar de 1,5 MB para los endpoints públicos), junto con una seguridad y un control de acceso sólidos.

# 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 de 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 estado para verificar que tu modelo está listo. Esto es importante para Vertex AI, ya que, sin una comprobación de estado dedicada, su orquestador enviará solicitudes a sockets aleatorios y no podrá determinar si el modelo está listo para la inferencia. Tu comprobación debe devolver 200 OK si tiene éxito y 503 Service Unavailable si falla:

# 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"}

Ya tienes todo lo necesario para implementar el endpoint de predicción que gestionará 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 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}")

Por último, 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)

Ya 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 los endpoints /health y /predict mediante cURL. Coloca una imagen de prueba en la carpeta tests. Después, ejecuta los siguientes comandos en tu Terminal:

# 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 la primera solicitud, espera un breve retraso, ya que Ultralytics necesita descargar y cargar el modelo YOLO26.

2. Amplía 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 aprovechar todas las capacidades de los modelos YOLO de Ultralytics, debes seleccionar la imagen optimizada para CUDA para realizar inferencias en GPU. Sin embargo, si la inferencia en CPU es suficiente para tu tarea, también puedes ahorrar recursos de computación seleccionando la imagen exclusiva para CPU:

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

Crea una imagen de Docker para tu aplicación#

Crea un archivo 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 usa como base la imagen oficial de Docker de Ultralytics ultralytics:latest. Ya contiene el modelo YOLO26 y todas las dependencias necesarias. El punto de entrada del servidor es el mismo que usamos para probar localmente la aplicación FastAPI.

Compila y prueba la imagen de Docker#

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

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

Sustituye IMAGE_NAME y IMAGE_VERSION por los valores que quieras, por ejemplo, yolo26-fastapi:0.1. Ten en cuenta que debes compilar la imagen para la arquitectura linux/amd64 si vas a desplegarla en Vertex AI. El parámetro --platform debe establecerse explícitamente si compilas la imagen en un Mac con Apple Silicon o en cualquier otra arquitectura que no sea x86.

Cuando termine la compilación de la imagen, puedes probarla localmente:

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

Tu contenedor de Docker ya está ejecutando un servidor FastAPI en el puerto 8080, listo para aceptar solicitudes de inferencia. Puedes probar los endpoints /health y /predict con los mismos comandos cURL de 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

3. Sube la imagen de Docker a GCP Artifact Registry#

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

Crea un repositorio en Google Cloud Artifact Registry#

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

1. Selecciona Create Repository.
2. Introduce el nombre de tu repositorio. Selecciona la región que quieras y usa la configuración predeterminada para las demás opciones, salvo que necesites cambiarlas específicamente.

1. Cuando hayas creado el repositorio, guarda tu PROJECT_ID, la ubicación (región) y el nombre del repositorio en tu almacén de secretos o en el archivo .env. Los necesitarás más adelante para etiquetar y subir tu imagen de Docker a Artifact Registry.

Autentica Docker en Artifact Registry#

Autentica tu cliente de 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

Etiqueta y sube 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. Sustituye los marcadores de posición por 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 finalice el proceso. Ahora deberías ver la imagen en tu repositorio de Artifact Registry.

Para consultar 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.

4. Importa tu modelo en Vertex AI#

Ahora puedes importar el modelo en Vertex AI usando la imagen de Docker que acabas de subir.

1. En el menú de navegación de Google Cloud, ve a Vertex AI > Model Registry. Como alternativa, busca "Vertex AI" en la barra de búsqueda situada en la parte superior de Google Cloud Console.

5. Crea un endpoint de Vertex AI y despliega tu modelo#

Para desplegar un modelo, tienes que crear un endpoint en Vertex AI.

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

1. Una vez seleccionado el tipo de máquina, puedes hacer clic en Continue. En este momento, puedes elegir activar la supervisión de modelos en Vertex AI, un servicio adicional que hará un seguimiento del rendimiento de tu modelo y proporcionará información sobre su comportamiento. Es opcional y conlleva costes adicionales, así que selecciónalo según tus necesidades. Haz clic en Create.

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

6. Prueba tu modelo desplegado#

Cuando finalice el despliegue, Vertex AI te proporcionará una interfaz de API de ejemplo para probar el modelo.

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

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

Preguntas frecuentes#