Link to this sectionDistribuisci un modello YOLO preaddestrato con Ultralytics su Vertex AI per l'inferenza#

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

Prima di iniziare, dovrai creare un progetto Google Cloud Platform (GCP). Ottieni $300 in crediti GCP da utilizzare gratuitamente come nuovo utente, e questo importo è sufficiente per testare una configurazione funzionante che potrai successivamente estendere per qualsiasi altro caso d'uso di YOLO26, inclusi l'addestramento o l'inferenza batch e in streaming.

Link to this sectionCosa imparerai#

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

Link to this sectionPrerequisiti#

1. Installa Docker sulla tua macchina.
2. Installa il Google Cloud SDK ed esegui l'autenticazione per utilizzare la gcloud CLI.
3. È vivamente consigliato consultare la Guida introduttiva a Docker per Ultralytics, poiché dovrai estendere una delle immagini Docker ufficiali di Ultralytics seguendo questa guida.

Link to this sectionCrea un backend di inferenza con FastAPI#

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

Link to this sectionFondamenti di conformità di Vertex AI#

Vertex AI prevede che il tuo contenitore 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 dovrebbero seguire questa struttura JSON:

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

Link to this sectionStruttura della cartella del progetto#

La maggior parte della nostra build avverrà all'interno del contenitore Docker e Ultralytics caricherà anche un modello YOLO26 preaddestrato, quindi puoi mantenere semplice la struttura delle cartelle locale:

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

Link to this sectionCrea 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à utilizzato per eseguire il server FastAPI.
• pillow verrà utilizzato per l'elaborazione delle immagini, ma non sei limitato solo alle immagini PIL — Ultralytics supporta molti altri formati.

Link to this sectionCrea la logica di inferenza con Ultralytics YOLO26#

Ora che hai impostato la struttura del progetto e le dipendenze, puoi implementare la logica principale di inferenza YOLO26. Crea un file src/app.py che gestirà il caricamento del modello, l'elaborazione delle immagini e la predizione, utilizzando 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 volta all'avvio del contenitore e il modello sarà condiviso tra tutte le richieste. Se il tuo modello dovrà gestire un carico di inferenza elevato, è consigliabile selezionare un tipo di macchina con più memoria durante l'importazione del modello in Vertex AI in un passaggio successivo.

Successivamente, crea due funzioni di utilità per l'elaborazione dell'immagine di input e output con pillow. YOLO26 supporta le immagini PIL in modo nativo.

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 oggetti. In questo esempio, estrarremo i riquadri delimitatori (bounding box), 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."""
    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}

Facoltativamente, puoi aggiungere una funzione per annotare l'immagine con riquadri delimitatori ed etichette utilizzando il metodo di tracciamento integrato di Ultralytics. Questo sarà utile se desideri 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)

Link to this sectionCrea un server di inferenza HTTP con FastAPI#

Ora che hai la logica di inferenza YOLO26 principale, puoi creare un'applicazione FastAPI per servirla. Ciò includerà l'endpoint di controllo integrità e di predizione richiesti da Vertex AI.

Innanzitutto, aggiungi le importazioni e configura la registrazione per Vertex AI. Poiché Vertex AI tratta stderr come output di errore, ha senso 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 una completa conformità a Vertex AI, definisci gli endpoint richiesti nelle variabili d'ambiente e imposta il limite di dimensione per le richieste. Si consiglia di utilizzare endpoint privati di Vertex AI per le distribuzioni in produzione. In questo modo avrai un limite di payload della richiesta più elevato (10 MB invece di 1,5 MB per gli endpoint pubblici), insieme a una maggiore sicurezza e 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 integrità per verificare la prontezza del tuo modello. Questo è importante per Vertex AI, poiché senza un controllo integrità dedicato, il suo orchestratore invierà ping a socket casuali e non sarà in grado di determinare se il modello è pronto per l'inferenza. Il tuo 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 il necessario per implementare l'endpoint di predizione che gestirà le richieste di inferenza. Accetterà un file immagine, eseguirà l'inferenza e restituirà i risultati. Nota che l'immagine deve essere codificata in base64, il che aumenta ulteriormente 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 hai 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 sia l'endpoint /health che /predict usando cURL. Metti 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 estrarre e caricare il modello YOLO26.

Link to this sectionEstendi l'immagine Docker di Ultralytics con la tua applicazione#

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

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

• Dockerfile: immagine ottimizzata per CUDA per l'addestramento e l'inferenza YOLO26 su singola/multi-GPU.
• Dockerfile-cpu: immagine solo CPU per l'inferenza YOLO26.

Link to this sectionCrea un'immagine Docker per la tua applicazione#

Crea un Dockerfile nella root del tuo 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, viene utilizzata come base l'immagine Docker ufficiale di Ultralytics ultralytics:latest. Contiene già il modello YOLO26 e tutte le dipendenze necessarie. L'entrypoint del server è lo stesso che abbiamo utilizzato per testare l'applicazione FastAPI localmente.

Link to this sectionCostruisci e testa l'immagine Docker#

Ora puoi costruire 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 tuoi valori desiderati, ad esempio yolo26-fastapi:0.1. Nota che devi costruire l'immagine per l'architettura linux/amd64 se stai distribuendo su Vertex AI. Il parametro --platform deve essere impostato esplicitamente se stai costruendo l'immagine su un Mac con Apple Silicon o qualsiasi altra architettura non x86.

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

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

Il tuo contenitore Docker sta ora eseguendo un server FastAPI sulla porta 8080, pronto ad accettare richieste di inferenza. Puoi testare sia l'endpoint /health che /predict con gli stessi comandi cURL di prima:

# 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

Link to this sectionCarica l'immagine Docker nel registro degli artefatti GCP#

Per importare il tuo 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.

Link to this sectionCrea un repository in Google Cloud Artifact Registry#

Apri la pagina Artifact Registry nella console Google Cloud. Se stai utilizzando Artifact Registry per la prima volta, potresti dover prima abilitare l'API Artifact Registry.

1. Seleziona Crea repository.
2. Inserisci il nome del tuo 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, posizione (regione) e nome del repository nel tuo vault dei segreti o nel file .env. Ti serviranno più avanti per taggare e inviare la tua immagine Docker ad Artifact Registry.

Link to this sectionAutentica Docker ad Artifact Registry#

Autentica il tuo client Docker al repository Artifact Registry appena creato. Esegui il seguente comando nel tuo terminale:

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

Link to this sectionTagga e invia la tua immagine ad Artifact Registry#

Tagga e invia l'immagine Docker a Google Artifact Registry.

Tagga la tua immagine 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 taggata 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.

Link to this sectionImporta il tuo modello in Vertex AI#

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

1. Nel menu di navigazione di Google Cloud, vai su Vertex AI > Registro modelli. In alternativa, cerca "Vertex AI" nella barra di ricerca in alto nella console Google Cloud.

Link to this sectionCrea un endpoint Vertex AI e distribuisci il tuo modello#

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

1. Nel menu di navigazione di Vertex AI, vai su Endpoint. Seleziona la regione utilizzata durante l'importazione del modello. Fai clic su Crea.

1. Una volta 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 terrà traccia delle prestazioni del tuo modello e fornirà informazioni sul suo comportamento. Questo è facoltativo e comporta costi aggiuntivi, quindi seleziona in base alle tue esigenze. Fai clic su Crea.

Vertex AI impiegherà alcuni minuti (fino a 30 minuti in alcune regioni) per distribuire il modello. Riceverai una notifica via email una volta completata la distribuzione.

Link to this sectionTesta il tuo modello distribuito#

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

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

Hai distribuito con successo un modello YOLO26 preaddestrato con Ultralytics su Google Cloud Vertex AI.

Link to this sectionFAQ#

Link to this sectionPosso utilizzare i modelli Ultralytics YOLO su Vertex AI senza Docker?#

Sì; tuttavia, dovrai prima esportare il modello in un formato compatibile con Vertex AI, come TensorFlow, Scikit-learn o XGBoost. Google Cloud fornisce una guida sull'esecuzione di modelli .pt su Vertex con una panoramica completa del processo di conversione: Eseguire modelli PyTorch su Vertex AI.

Tieni presente che la configurazione risultante si baserà solo sul livello di servizio standard di Vertex AI e non supporterà le funzionalità avanzate del framework Ultralytics. Poiché Vertex AI supporta pienamente i modelli containerizzati e può ridimensionarli automaticamente in base alla configurazione di distribuzione, ti consente di sfruttare tutte le funzionalità dei modelli Ultralytics YOLO senza doverli convertire in un formato diverso.

Link to this sectionPerché FastAPI è una buona scelta per servire l'inferenza di YOLO26?#

FastAPI fornisce un throughput elevato per i carichi di lavoro di inferenza. Il supporto async consente di gestire più richieste simultanee senza bloccare il thread principale, il che è importante quando si servono modelli di computer vision.

La convalida automatica di richiesta/risposta con FastAPI riduce gli errori di runtime nei servizi di inferenza in produzione. Questo è particolarmente prezioso per le API di object detection dove la coerenza del formato di input è fondamentale.

FastAPI aggiunge un sovraccarico computazionale minimo alla tua pipeline di inferenza, lasciando più risorse disponibili per l'esecuzione del modello e le attività di elaborazione delle immagini.

FastAPI supporta anche SSE (Server-Sent Events), che è utile per scenari di inferenza in streaming.

Link to this sectionPerché devo selezionare una regione così tante volte?#

Questa è in realtà una funzionalità di versatilità di Google Cloud Platform, dove devi selezionare una regione per ogni servizio che utilizzi. Per l'attività di distribuzione di un modello containerizzato su Vertex AI, la selezione della regione più importante è quella per il Model Registry. Determinerà la disponibilità di tipi di macchine e quote per la distribuzione del tuo modello.

Inoltre, se estenderai la configurazione e memorizzerai dati di previsione o risultati in Cloud Storage o BigQuery, dovrai utilizzare la stessa regione del Model Registry per ridurre al minimo la latenza e garantire un throughput elevato per l'accesso ai dati.