Distribuisci un modello YOLO pretrained con Ultralytics su Vertex AI per l'inferenza#

Questa guida ti mostrerà come containerizzare un modello YOLO26 pretrained con Ultralytics, creare un server di inferenza FastAPI per il modello e distribuire il modello con il server di inferenza su Google Cloud Vertex AI. L'implementazione di esempio riguarderà il caso d'uso del rilevamento degli oggetti per YOLO26, ma gli stessi principi si applicheranno all'uso di altre modalità YOLO.

Prima di iniziare, dovrai creare un progetto Google Cloud Platform (GCP). Come nuovo utente, ricevi $300 di crediti GCP gratuiti e questo importo è sufficiente per testare una configurazione in esecuzione che potrai successivamente estendere a qualsiasi altro caso d'uso di YOLO26, incluso l'addestramento o l'inferenza batch e in streaming.

Cosa imparerai#

1. Creare un backend di inferenza per il modello Ultralytics YOLO26 usando FastAPI.
2. Creare un repository GCP Artifact Registry per archiviare la tua immagine Docker.
3. Creare e inviare l'immagine Docker con il modello ad Artifact Registry.
4. Importare il modello in Vertex AI.
5. Creare un endpoint Vertex AI e distribuire il modello.

Prerequisiti#

1. Installa Docker sul tuo computer.
2. Installa Google Cloud SDK e esegui l'autenticazione per usare la CLI gcloud.
3. Ti consigliamo vivamente di consultare la Guida rapida a Docker per Ultralytics, perché dovrai estendere una delle immagini Docker ufficiali di Ultralytics seguendo questa guida.

1. Crea un backend di inferenza con FastAPI#

Per prima cosa, devi creare un'applicazione FastAPI che gestisca le richieste di inferenza del modello YOLO26. Questa applicazione gestirà il caricamento del modello, il pre-processing delle immagini e la logica di inferenza (predizione).

Fondamenti di conformità di Vertex AI#

Vertex AI richiede che il tuo container implementi due endpoint specifici:

1. Endpoint Health (/health): deve restituire lo stato HTTP 200 OK quando il servizio è pronto.

2. Endpoint Predict (/predict): accetta richieste di predizione strutturate con immagini codificate in base64 e parametri opzionali. Si applicano limiti alle dimensioni del payload a seconda del tipo di endpoint.

   I payload delle richieste per l'endpoint /predict devono seguire questa struttura JSON:

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

Struttura delle cartelle del progetto#

La maggior parte della build verrà eseguita all'interno del container Docker e Ultralytics caricherà anche un modello YOLO26 pretrained, quindi puoi mantenere semplice la struttura delle cartelle locali:

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 le dipendenze#

Per gestire comodamente il tuo progetto, crea un file pyproject.toml con le seguenti dipendenze:

[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 verrà usato per eseguire il server FastAPI.
• pillow verrà usato per l'elaborazione delle immagini, ma non sei limitato alle sole immagini PIL: Ultralytics supporta molti altri formati.

Crea la logica di inferenza con Ultralytics YOLO26#

Ora che hai configurato la struttura del progetto e le dipendenze, puoi implementare la logica di inferenza principale di YOLO26. Crea un file src/app.py che gestirà il caricamento del modello, l'elaborazione delle immagini e la predizione, usando l'API Python di 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

Questo caricherà il modello una sola volta all'avvio del container e il modello sarà condiviso tra tutte le richieste. Se il modello dovrà gestire un carico di inferenza elevato, ti consigliamo di selezionare un tipo di macchina con più memoria quando importerai un modello in Vertex AI in un passaggio successivo.

Poi, crea due funzioni di utilità per l'elaborazione delle immagini di input e output con pillow. YOLO26 supporta nativamente le immagini PIL.

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()

Infine, implementa la funzione run_inference che gestirà il rilevamento degli oggetti. In questo esempio estrarremo i riquadri delimitatori, i nomi delle classi e i punteggi di confidenza dalle predizioni del modello. La funzione restituirà un dizionario con i rilevamenti e i risultati grezzi per ulteriori elaborazioni o annotazioni.

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}

Facoltativamente, puoi aggiungere una funzione per annotare l'immagine con riquadri delimitatori ed etichette usando il metodo di plotting integrato di Ultralytics. Questo sarà utile se vuoi restituire immagini annotate nella risposta di predizione.

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 server di inferenza HTTP con FastAPI#

Ora che hai la logica di inferenza principale di YOLO26, puoi creare un'applicazione FastAPI per eseguirla. Questa includerà gli endpoint di controllo dello stato e di predizione richiesti da Vertex AI.

Per prima cosa, aggiungi gli import e configura il logging per Vertex AI. Poiché Vertex AI considera stderr come output di errore, è opportuno inviare i log 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")

Per garantire la piena conformità con Vertex AI, definisci gli endpoint richiesti nelle variabili d'ambiente e imposta il limite di dimensione per le richieste. Per le distribuzioni in produzione, ti consigliamo di usare endpoint Vertex AI privati. In questo modo avrai un limite del payload delle richieste più elevato (10 MB invece di 1,5 MB per gli endpoint pubblici), oltre a una solida sicurezza e a un efficace controllo degli accessi.

# 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

Aggiungi due modelli Pydantic per convalidare le tue richieste e risposte:

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

class PredictionResponse(BaseModel):
    predictions: list

Aggiungi l'endpoint di controllo dello stato per verificare che il modello sia pronto. Questo è importante per Vertex AI, perché senza un controllo dello stato dedicato il suo orchestratore eseguirà il ping di socket casuali e non sarà in grado di determinare se il modello è pronto per l'inferenza. Il controllo deve restituire 200 OK in caso di successo e 503 Service Unavailable in caso di errore:

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

Ora hai tutto ciò che serve per implementare l'endpoint di predizione che gestirà le richieste di inferenza. Accetterà un file immagine, eseguirà l'inferenza e restituirà i risultati. Tieni presente che l'immagine deve essere codificata in base64, aumentando inoltre la dimensione del payload fino al 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}")

Infine, aggiungi il punto di ingresso dell'applicazione per eseguire il server 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)

Ora disponi di un'applicazione FastAPI completa in grado di gestire le richieste di inferenza YOLO26. Puoi testarla localmente installando le dipendenze ed eseguendo il server, ad esempio con uv.

# Install dependencies
uv pip install -e .

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

Per testare il server, puoi interrogare entrambi gli endpoint /health e /predict usando cURL. Inserisci un'immagine di test nella cartella tests. Quindi, nel tuo Terminale, esegui i seguenti comandi:

# 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

Dovresti ricevere una risposta JSON con gli oggetti rilevati. Alla prima richiesta, aspettati un breve ritardo, poiché Ultralytics deve scaricare e caricare il modello YOLO26.

2. Estendi l'immagine Docker di Ultralytics con la tua applicazione#

Ultralytics fornisce diverse immagini Docker che puoi usare come base per l'immagine della tua applicazione. Docker installerà Ultralytics e i driver GPU necessari.

Per usare tutte le funzionalità dei modelli Ultralytics YOLO, dovresti selezionare l'immagine ottimizzata per CUDA per l'inferenza su GPU. Tuttavia, se per la tua attività è sufficiente l'inferenza su CPU, puoi risparmiare risorse di calcolo selezionando anche l'immagine esclusiva per CPU:

• Dockerfile: immagine ottimizzata per CUDA per l'addestramento e l'inferenza YOLO26 su una o più GPU.
• Dockerfile-cpu: immagine esclusiva per CPU per l'inferenza YOLO26.

Crea un'immagine Docker per la tua applicazione#

Crea un Dockerfile nella radice del progetto con il seguente contenuto:

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

Nell'esempio, l'immagine Docker ufficiale di Ultralytics ultralytics:latest viene usata come base. Contiene già il modello YOLO26 e tutte le dipendenze necessarie. Il punto di ingresso del server è lo stesso usato per testare localmente l'applicazione FastAPI.

Crea e testa l'immagine Docker#

Ora puoi creare l'immagine Docker con il seguente comando:

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

Sostituisci IMAGE_NAME e IMAGE_VERSION con i valori desiderati, ad esempio yolo26-fastapi:0.1. Tieni presente che devi creare l'immagine per l'architettura linux/amd64 se la distribuisci su Vertex AI. Il parametro --platform deve essere impostato esplicitamente se stai creando l'immagine su un Mac con Apple Silicon o su qualsiasi altra architettura non x86.

Una volta completata la build dell'immagine, puoi testare localmente l'immagine Docker:

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

Il tuo container Docker sta ora eseguendo un server FastAPI sulla porta 8080, pronto ad accettare richieste di inferenza. Puoi testare entrambi gli endpoint /health e /predict con gli stessi comandi cURL usati in precedenza:

# 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. Carica l'immagine Docker in GCP Artifact Registry#

Per importare il modello containerizzato in Vertex AI, devi caricare l'immagine Docker in Google Cloud Artifact Registry. Se non hai ancora un repository Artifact Registry, dovrai prima crearne uno.

Crea un repository in Google Cloud Artifact Registry#

Apri la pagina Artifact Registry nella Google Cloud Console. Se usi Artifact Registry per la prima volta, potrebbe esserti richiesto di abilitare prima l'API Artifact Registry.

1. Seleziona Crea repository.
2. Inserisci il nome del repository. Seleziona la regione desiderata e usa le impostazioni predefinite per le altre opzioni, a meno che tu non debba modificarle specificamente.

1. Una volta creato il repository, salva PROJECT_ID, Location (Region) e Repository Name nel tuo archivio dei segreti o nel file .env. Ti serviranno in seguito per applicare il tag e inviare l'immagine Docker ad Artifact Registry.

Esegui l'autenticazione Docker per Artifact Registry#

Esegui l'autenticazione del client Docker al repository Artifact Registry appena creato. Esegui il seguente comando nel terminale:

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

Applica il tag e invia l'immagine ad Artifact Registry#

Applica il tag e invia l'immagine Docker a Google Artifact Registry.

Applica all'immagine il tag con l'URL del repository Artifact Registry. Sostituisci i segnaposto con i valori salvati in precedenza.

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

Invia l'immagine con tag al repository Artifact Registry.

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

Attendi il completamento del processo. Ora dovresti vedere l'immagine nel tuo repository Artifact Registry.

Per istruzioni più specifiche su come lavorare con le immagini in Artifact Registry, consulta la documentazione di Artifact Registry: inviare e scaricare immagini.

4. Importa il modello in Vertex AI#

Usando l'immagine Docker appena inviata, ora puoi importare il modello in Vertex AI.

1. Nel menu di navigazione di Google Cloud, vai a Vertex AI > Model Registry. In alternativa, cerca "Vertex AI" nella barra di ricerca nella parte superiore della Google Cloud Console.

5. Crea un endpoint Vertex AI e distribuisci il modello#

Per distribuire un modello, devi creare un endpoint in Vertex AI.

1. Nel menu di navigazione di Vertex AI, vai a Endpoints. Seleziona la regione usata quando hai importato il modello. Fai clic su Crea.

1. Dopo aver selezionato il tipo di macchina, puoi fare clic su Continua. A questo punto puoi scegliere di abilitare il monitoraggio del modello in Vertex AI, un servizio aggiuntivo che monitorerà le prestazioni del modello e fornirà informazioni sul suo comportamento. È opzionale e comporta costi aggiuntivi, quindi selezionalo in base alle tue esigenze. Fai clic su Crea.

Vertex AI impiegherà diversi minuti (fino a 30 minuti in alcune regioni) per distribuire il modello. Riceverai una notifica via email al termine della distribuzione.

6. Testa il modello distribuito#

Una volta completata la distribuzione, Vertex AI ti fornirà un'interfaccia API di esempio per testare il modello.

Per testare l'inferenza remota, puoi usare il comando cURL fornito oppure creare un'altra libreria client Python che invii richieste al modello distribuito. Ricorda che devi codificare l'immagine in base64 prima di inviarla all'endpoint /predict.

Hai distribuito correttamente un modello YOLO26 pretrained con Ultralytics su Google Cloud Vertex AI.

FAQ#