Bereitstellung eines vortrainierten YOLO-Modells mit Ultralytics auf Vertex AI für Inferenz#

In diesem Leitfaden erfährst du, wie du ein vortrainiertes YOLO26-Modell mit Ultralytics in einen Container packst, dafür einen FastAPI-Inferenzserver erstellst und das Modell mit dem Inferenzserver in Google Cloud Vertex AI bereitstellst. Die Beispielimplementierung behandelt den Anwendungsfall der Objekterkennung für YOLO26, aber dieselben Prinzipien gelten auch für die Verwendung anderer YOLO-Modi.

Bevor wir beginnen, musst du ein Google Cloud Platform (GCP)-Projekt erstellen. Als neuer Nutzer erhältst du ein kostenloses GCP-Guthaben von 300 $, und dieser Betrag reicht aus, um eine laufende Umgebung zu testen, die du später für jeden anderen YOLO26-Anwendungsfall erweitern kannst, einschließlich Training sowie Batch- und Streaming-Inferenz.

Was du lernen wirst#

1. Erstelle mit FastAPI ein Inferenz-Backend für das Ultralytics YOLO26-Modell.
2. Erstelle ein GCP Artifact Registry-Repository zum Speichern deines Docker-Images.
3. Erstelle das Docker-Image mit dem Modell und übertrage es in die Artifact Registry.
4. Importiere dein Modell in Vertex AI.
5. Erstelle einen Vertex AI-Endpunkt und stelle das Modell bereit.

Voraussetzungen#

1. Installiere Docker auf deinem Rechner.
2. Installiere das Google Cloud SDK und authentifiziere dich für die Verwendung der gcloud CLI.
3. Es wird dringend empfohlen, den Docker-Schnellstartleitfaden für Ultralytics durchzuarbeiten, da du im Rahmen dieses Leitfadens eines der offiziellen Ultralytics-Docker-Images erweitern musst.

1. Erstelle ein Inferenz-Backend mit FastAPI#

Zuerst musst du eine FastAPI-Anwendung erstellen, die Inferenzanfragen für das YOLO26-Modell verarbeitet. Diese Anwendung übernimmt das Laden des Modells, die Bildvorverarbeitung und die Inferenzlogik (Vorhersage).

Grundlagen der Compliance für Vertex AI#

Vertex AI erwartet, dass dein Container zwei bestimmte Endpunkte implementiert:

1. Health-Endpunkt (/health): Muss den HTTP-Status 200 OK zurückgeben, sobald der Dienst bereit ist.

2. Predict-Endpunkt (/predict): Akzeptiert strukturierte Vorhersageanfragen mit base64-kodierten Bildern und optionalen Parametern. Je nach Endpunkttyp gelten Grenzwerte für die Payload-Größe.

   Anfrage-Payloads für den Endpunkt /predict sollten dieser JSON-Struktur folgen:

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

Projektordnerstruktur#

Der größte Teil unseres Builds findet innerhalb des Docker-Containers statt, und Ultralytics lädt außerdem ein vortrainiertes YOLO26-Modell. Daher kannst du die lokale Ordnerstruktur einfach halten:

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

Erstelle pyproject.toml mit den Abhängigkeiten#

Um dein Projekt bequem zu verwalten, erstelle eine Datei pyproject.toml mit den folgenden Abhängigkeiten:

[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 wird zum Ausführen des FastAPI-Servers verwendet.
• pillow wird für die Bildverarbeitung verwendet, aber du bist nicht auf PIL-Bilder beschränkt — Ultralytics unterstützt viele weitere Formate.

Erstelle die Inferenzlogik mit Ultralytics YOLO26#

Nachdem du die Projektstruktur und die Abhängigkeiten eingerichtet hast, kannst du die zentrale YOLO26-Inferenzlogik implementieren. Erstelle eine Datei src/app.py, die das Laden des Modells, die Bildverarbeitung und die Vorhersage mithilfe der Ultralytics Python API übernimmt.

# 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

Dadurch wird das Modell einmal beim Start des Containers geladen und anschließend für alle Anfragen gemeinsam verwendet. Wenn dein Modell eine hohe Inferenzlast bewältigen muss, wird empfohlen, beim späteren Import des Modells in Vertex AI einen Maschinentyp mit mehr Arbeitsspeicher auszuwählen.

Erstelle als Nächstes zwei Hilfsfunktionen für die Verarbeitung von Eingabe- und Ausgabebildern mit pillow. YOLO26 unterstützt PIL-Bilder nativ.

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

Implementiere schließlich die Funktion run_inference, die die Objekterkennung übernimmt. In diesem Beispiel extrahieren wir Begrenzungsrahmen, Klassennamen und Konfidenzwerte aus den Modellvorhersagen. Die Funktion gibt ein Dictionary mit Erkennungen und Rohresultaten zur weiteren Verarbeitung oder Annotation zurück.

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}

Optional kannst du eine Funktion hinzufügen, die das Bild mithilfe der integrierten Plotting-Methode von Ultralytics mit Begrenzungsrahmen und Beschriftungen annotiert. Das ist nützlich, wenn du annotierte Bilder in der Vorhersageantwort zurückgeben möchtest.

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)

Erstelle einen HTTP-Inferenzserver mit FastAPI#

Nachdem du die zentrale YOLO26-Inferenzlogik erstellt hast, kannst du eine FastAPI-Anwendung dafür erstellen. Sie umfasst die von Vertex AI benötigten Endpunkte für die Gesundheitsprüfung und Vorhersage.

Füge zunächst die Importe hinzu und konfiguriere die Protokollierung für Vertex AI. Da Vertex AI stderr als Fehlerausgabe behandelt, ist es sinnvoll, die Protokolle an stdout weiterzuleiten.

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

Für eine vollständige Vertex AI-Compliance definierst du die erforderlichen Endpunkte in Umgebungsvariablen und legst das Größenlimit für Anfragen fest. Für Bereitstellungen in der Produktion wird empfohlen, private Vertex AI-Endpunkte zu verwenden. Dadurch erhältst du ein höheres Anfrage-Payload-Limit (10 MB statt 1,5 MB bei öffentlichen Endpunkten) sowie robuste Sicherheits- und Zugriffskontrollen.

# 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

Füge zwei Pydantic-Modelle zur Validierung deiner Anfragen und Antworten hinzu:

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

class PredictionResponse(BaseModel):
    predictions: list

Füge den Endpunkt für die Gesundheitsprüfung hinzu, um die Bereitschaft deines Modells zu überprüfen. Das ist für Vertex AI wichtig, denn ohne eine dedizierte Gesundheitsprüfung würde der Orchestrator zufällige Sockets anpingen und könnte nicht feststellen, ob das Modell für die Inferenz bereit ist. Deine Prüfung muss bei Erfolg 200 OK und bei einem Fehler 503 Service Unavailable zurückgeben:

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

Nun hast du alles, um den Vorhersageendpunkt zu implementieren, der die Inferenzanfragen verarbeitet. Er akzeptiert eine Bilddatei, führt die Inferenz aus und gibt die Ergebnisse zurück. Beachte, dass das Bild base64-kodiert sein muss, wodurch sich die Größe der Payload zusätzlich um bis zu 33 % erhöht.

@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}")

Füge schließlich den Einstiegspunkt der Anwendung hinzu, um den FastAPI-Server auszuführen.

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)

Du hast nun eine vollständige FastAPI-Anwendung, die YOLO26-Inferenzanfragen verarbeiten kann. Du kannst sie lokal testen, indem du die Abhängigkeiten installierst und den Server ausführst, beispielsweise mit uv.

# Install dependencies
uv pip install -e .

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

Um den Server zu testen, kannst du mit cURL sowohl den Endpunkt /health als auch /predict abfragen. Lege ein Testbild im Ordner tests ab. Führe anschließend in deinem Terminal die folgenden Befehle aus:

# 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

Du solltest eine JSON-Antwort mit den erkannten Objekten erhalten. Rechne bei deiner ersten Anfrage mit einer kurzen Verzögerung, da Ultralytics das YOLO26-Modell abrufen und laden muss.

2. Erweitere das Ultralytics-Docker-Image mit deiner Anwendung#

Ultralytics stellt mehrere Docker-Images bereit, die du als Grundlage für dein Anwendungs-Image verwenden kannst. Docker installiert Ultralytics und die erforderlichen GPU-Treiber.

Um den vollständigen Funktionsumfang der Ultralytics YOLO-Modelle zu nutzen, solltest du für die GPU-Inferenz das für CUDA optimierte Image auswählen. Wenn für deine Aufgabe jedoch CPU-Inferenz ausreicht, kannst du Rechenressourcen sparen, indem du ebenfalls das reine CPU-Image auswählst:

• Dockerfile: Für CUDA optimiertes Image für das Training und die Inferenz von YOLO26 mit einer oder mehreren GPUs.
• Dockerfile-cpu: Reines CPU-Image für die YOLO26-Inferenz.

Erstelle ein Docker-Image für deine Anwendung#

Erstelle im Stammverzeichnis deines Projekts eine Dockerfile mit folgendem Inhalt:

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

Im Beispiel wird das offizielle Ultralytics-Docker-Image ultralytics:latest als Grundlage verwendet. Es enthält bereits das YOLO26-Modell und alle erforderlichen Abhängigkeiten. Der Einstiegspunkt des Servers ist derselbe wie beim lokalen Testen der FastAPI-Anwendung.

Erstelle und teste das Docker-Image#

Nun kannst du das Docker-Image mit dem folgenden Befehl erstellen:

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

Ersetze IMAGE_NAME und IMAGE_VERSION durch deine gewünschten Werte, beispielsweise yolo26-fastapi:0.1. Beachte, dass du das Image für die Architektur linux/amd64 erstellen musst, wenn du es in Vertex AI bereitstellst. Der Parameter --platform muss explizit festgelegt werden, wenn du das Image auf einem Apple Silicon Mac oder einer anderen Nicht-x86-Architektur erstellst.

Sobald die Erstellung des Images abgeschlossen ist, kannst du das Docker-Image lokal testen:

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

Dein Docker-Container führt nun einen FastAPI-Server auf Port 8080 aus und ist bereit, Inferenzanfragen anzunehmen. Du kannst den Endpunkt /health und den Endpunkt /predict mit denselben cURL-Befehlen wie zuvor testen:

# 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. Lade das Docker-Image in die GCP Artifact Registry hoch#

Um dein containerisiertes Modell in Vertex AI zu importieren, musst du das Docker-Image in die Google Cloud Artifact Registry hochladen. Wenn du noch kein Artifact Registry-Repository hast, musst du zuerst eines erstellen.

Erstelle ein Repository in der Google Cloud Artifact Registry#

Öffne die Artifact Registry-Seite in der Google Cloud Console. Wenn du die Artifact Registry zum ersten Mal verwendest, wirst du möglicherweise zunächst aufgefordert, die Artifact Registry API zu aktivieren.

1. Wähle „Create Repository“ aus.
2. Gib den Namen deines Repositorys ein. Wähle die gewünschte Region aus und verwende für die übrigen Optionen die Standardeinstellungen, sofern du sie nicht ausdrücklich ändern musst.

1. Sobald das Repository erstellt wurde, speichere deine PROJECT_ID, den Standort (die Region) und den Repository-Namen in deinem Tresor für Geheimnisse oder in der Datei .env. Du benötigst diese Angaben später, um dein Docker-Image zu markieren und in die Artifact Registry zu übertragen.

Authentifiziere Docker bei der Artifact Registry#

Authentifiziere deinen Docker-Client beim soeben erstellten Artifact Registry-Repository. Führe den folgenden Befehl in deinem Terminal aus:

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

Markiere und übertrage dein Image in die Artifact Registry#

Markiere das Docker-Image und übertrage es in die Google Artifact Registry.

Markiere dein Image mit der URL des Artifact Registry-Repositorys. Ersetze die Platzhalter durch die zuvor gespeicherten Werte.

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

Übertrage das markierte Image in das Artifact Registry-Repository.

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

Warte, bis der Vorgang abgeschlossen ist. Nun solltest du das Image in deinem Artifact Registry-Repository sehen.

Detailliertere Anweisungen zum Arbeiten mit Images in der Artifact Registry findest du in der Artifact Registry-Dokumentation: Push and pull images.

4. Importiere dein Modell in Vertex AI#

Mit dem gerade übertragenen Docker-Image kannst du das Modell nun in Vertex AI importieren.

1. Gehe im Navigationsmenü der Google Cloud zu Vertex AI > Model Registry. Alternativ kannst du in der Suchleiste oben in der Google Cloud Console nach „Vertex AI“ suchen.

5. Erstelle einen Vertex AI-Endpunkt und stelle dein Modell bereit#

Um ein Modell bereitzustellen, musst du in Vertex AI einen Endpunkt erstellen.

1. Gehe im Navigationsmenü von Vertex AI zu „Endpoints“. Wähle die Region aus, die du beim Importieren deines Modells verwendet hast. Klicke auf „Create“.

1. Nachdem der Maschinentyp ausgewählt wurde, kannst du auf „Continue“ klicken. An diesem Punkt kannst du die Modellüberwachung in Vertex AI aktivieren – einen zusätzlichen Dienst, der die Leistung deines Modells verfolgt und Einblicke in sein Verhalten liefert. Diese Option ist freiwillig und verursacht zusätzliche Kosten. Wähle sie daher entsprechend deinen Anforderungen aus. Klicke auf „Create“.

Vertex AI benötigt mehrere Minuten (in einigen Regionen bis zu 30 Minuten), um das Modell bereitzustellen. Sobald die Bereitstellung abgeschlossen ist, erhältst du eine E-Mail-Benachrichtigung.

6. Teste dein bereitgestelltes Modell#

Sobald die Bereitstellung abgeschlossen ist, stellt Vertex AI dir eine beispielhafte API-Schnittstelle zum Testen deines Modells bereit.

Für die Remote-Inferenz kannst du den bereitgestellten cURL-Befehl verwenden oder eine weitere Python-Clientbibliothek erstellen, die Anfragen an das bereitgestellte Modell sendet. Denke daran, dein Bild vor dem Senden an den Endpunkt /predict in base64 zu kodieren.

Du hast erfolgreich ein vortrainiertes YOLO26-Modell mit Ultralytics in Google Cloud Vertex AI bereitgestellt.

FAQ#