Distribuisci 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 di rilevamento 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). Riceverai $300 in crediti GCP da utilizzare gratuitamente come nuovo utente, e questo importo è sufficiente per testare una configurazione in esecuzione che potrai poi estendere per qualsiasi altro caso d'uso di YOLO26, inclusi 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 Google Cloud Artifact Registry per archiviare la tua immagine Docker.
3. Costruire e inviare l'immagine Docker con il modello a Artifact Registry.
4. Importare il tuo modello in Vertex AI.
5. Creare un endpoint Vertex AI e distribuire il modello.

Prerequisiti

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.

Crea un backend di inferenza con FastAPI

Per prima cosa, 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).

Fondamenti di conformità Vertex AI

Vertex AI prevede 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 di dimensione 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 della cartella del progetto

La maggior parte della build avverrà all'interno del container Docker e Ultralytics caricherà anche un modello YOLO26 preaddestrato, quindi puoi mantenere semplice la struttura della cartella 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

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à 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.

Crea la logica di inferenza con Ultralytics YOLO26

Ora che hai impostato 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, 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 sola volta all'avvio del container e il modello sarà condiviso tra tutte le richieste. Se il tuo modello gestirà un carico di inferenza pesante, è consigliabile selezionare un tipo di macchina con più memoria quando importi un modello in Vertex AI in una fase successiva.

Successivamente, crea due funzioni di utilità per l'elaborazione delle immagini in ingresso e in uscita con pillow. YOLO26 supporta le immagini PIL nativamente.

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

Crea un server di inferenza HTTP con FastAPI

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

Per prima cosa, aggiungi le importazioni e configura il logging per Vertex AI. Poiché Vertex AI tratta stderr come output di errore, ha senso convogliare i log su 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. È consigliabile utilizzare endpoint Vertex AI privati 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 sicurezza e controllo degli accessi robusti.

# 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 di integrità (health check) per verificare la prontezza del modello. Questo è importante per Vertex AI, poiché senza un controllo di integrità 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 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. Tieni presente 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 servire le richieste di inferenza di 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. 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 estrarre e caricare il modello YOLO26.

Estendi 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 GPU. Tuttavia, se l'inferenza su CPU è sufficiente per il tuo compito, puoi risparmiare risorse di calcolo selezionando anche l'immagine solo CPU:

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

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

Costruisci 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. Tieni presente 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 Apple Silicon o su 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 container 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

Carica l'immagine Docker in GCP Artifact Registry

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.

Crea un repository in Google Cloud Artifact Registry

Apri la pagina di Artifact Registry nella Google Cloud Console. Se stai utilizzando Artifact Registry per la prima volta, ti potrebbe essere richiesto di abilitare prima l'API Artifact Registry.

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

1. Una volta creato il repository, salva il tuo PROJECT_ID, la posizione (regione) e il nome del repository nel tuo vault dei segreti o nel file .env. Ti serviranno in seguito per taggare e inviare la tua immagine Docker a Artifact Registry.

Autentica Docker su Artifact Registry

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

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

Tagga 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 recuperare immagini.

Importa il tuo modello in Vertex AI

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

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

Crea 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 che hai utilizzato 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.

Testa 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 utilizzare 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.

FAQ

Posso 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.

Perché FastAPI è una buona scelta per servire l'inferenza di YOLO26?

FastAPI fornisce un throughput elevato per i carichi di lavoro di inferenza. Il supporto asincrono 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 utile per le API di rilevamento oggetti in cui la coerenza del formato di input è fondamentale.

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

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

Perché devo selezionare una regione così tante volte?

Questa è in realtà una funzionalità di versatilità di Google Cloud Platform, in cui 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.