Déploie un modèle YOLO préentraîné avec Ultralytics sur Vertex AI pour l’inférence#

Ce guide t’expliquera comment conteneuriser un modèle YOLO26 préentraîné avec Ultralytics, créer un serveur d’inférence FastAPI pour celui-ci et déployer le modèle avec le serveur d’inférence sur Google Cloud Vertex AI. L’implémentation d’exemple couvrira le cas d’utilisation de la détection d’objets avec YOLO26, mais les mêmes principes s’appliqueront à l’utilisation des autres modes YOLO.

Avant de commencer, tu devras créer un projet Google Cloud Platform (GCP). En tant que nouvel utilisateur, tu bénéficies de 300 $ de crédits GCP gratuits, ce qui suffit pour tester une configuration fonctionnelle que tu pourras ensuite étendre à tout autre cas d’utilisation de YOLO26, notamment l’entraînement ou l’inférence par lots et en streaming.

Ce que tu vas apprendre#

1. Créer un backend d’inférence pour le modèle Ultralytics YOLO26 avec FastAPI.
2. Créer un dépôt GCP Artifact Registry pour stocker ton image Docker.
3. Construire et envoyer l’image Docker contenant le modèle vers Artifact Registry.
4. Importer ton modèle dans Vertex AI.
5. Créer un endpoint Vertex AI et déployer le modèle.

Prérequis#

1. Installe Docker sur ta machine.
2. Installe le Google Cloud SDK et authentifie-toi pour utiliser la CLI gcloud.
3. Il est vivement recommandé de consulter le Guide de démarrage rapide Docker pour Ultralytics, car tu devras étendre l’une des images Docker officielles d’Ultralytics en suivant ce guide.

1. Créer un backend d’inférence avec FastAPI#

Commence par créer une application FastAPI qui traitera les requêtes d’inférence du modèle YOLO26. Cette application gérera le chargement du modèle, le prétraitement des images et la logique d’inférence (prédiction).

Principes fondamentaux de la conformité de Vertex AI#

Vertex AI attend de ton conteneur qu’il implémente deux endpoints spécifiques :

1. Endpoint Health (/health) : doit renvoyer le statut HTTP 200 OK lorsque le service est prêt.

2. Endpoint Predict (/predict) : accepte des requêtes de prédiction structurées contenant des images encodées en base64 et des paramètres facultatifs. Des limites de taille de payload s’appliquent selon le type d’endpoint.

   Les payloads de requête destinés à l’endpoint /predict doivent respecter la structure JSON suivante :

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

Structure du dossier du projet#

L’essentiel de la compilation se fera à l’intérieur du conteneur Docker, et Ultralytics chargera également un modèle YOLO26 préentraîné. Tu peux donc conserver une structure de dossier locale simple :

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

Créer pyproject.toml avec les dépendances#

Pour gérer facilement ton projet, crée un fichier pyproject.toml contenant les dépendances suivantes :

[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 servira à exécuter le serveur FastAPI.
• pillow servira au traitement des images, mais tu n’es pas limité aux seules images PIL : Ultralytics prend en charge de nombreux autres formats.

Créer la logique d’inférence avec Ultralytics YOLO26#

Maintenant que la structure du projet et les dépendances sont configurées, tu peux implémenter la logique centrale d’inférence de YOLO26. Crée un fichier src/app.py qui gérera le chargement du modèle, le traitement des images et la prédiction à l’aide de l’API Python d’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

Le modèle sera chargé une seule fois au démarrage du conteneur, puis partagé entre toutes les requêtes. Si ton modèle doit traiter une charge d’inférence importante, il est recommandé de sélectionner un type de machine disposant de davantage de mémoire lors de l’importation du modèle dans Vertex AI à une étape ultérieure.

Crée ensuite deux fonctions utilitaires pour le traitement des images d’entrée et de sortie avec pillow. YOLO26 prend nativement en charge les images 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()

Enfin, implémente la fonction run_inference qui gérera la détection d’objets. Dans cet exemple, nous extrairons des prédictions du modèle les BBox, les noms de classes et les scores de confiance. La fonction renverra un dictionnaire contenant les détections et les résultats bruts pour un traitement ou une annotation ultérieurs.

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}

Tu peux éventuellement ajouter une fonction pour annoter l’image avec des BBox et des labels à l’aide de la méthode de tracé intégrée d’Ultralytics. Cela sera utile si tu souhaites renvoyer des images annotées dans la réponse de prédiction.

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)

Créer un serveur d’inférence HTTP avec FastAPI#

Maintenant que tu disposes de la logique centrale d’inférence de YOLO26, tu peux créer une application FastAPI pour l’exécuter. Elle comprendra les endpoints de vérification de l’état de santé et de prédiction requis par Vertex AI.

Commence par ajouter les imports et configurer la journalisation pour Vertex AI. Comme Vertex AI traite stderr comme une sortie d’erreur, il est logique de rediriger les journaux vers 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")

Pour assurer une conformité complète avec Vertex AI, définis les endpoints requis dans les variables d’environnement et fixe la limite de taille des requêtes. Il est recommandé d’utiliser des endpoints Vertex AI privés pour les déploiements en production. Tu bénéficieras ainsi d’une limite de payload plus élevée (10 Mo au lieu de 1,5 Mo pour les endpoints publics), ainsi que d’une sécurité et d’un contrôle des accès robustes.

# 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

Ajoute deux modèles Pydantic pour valider tes requêtes et tes réponses :

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

class PredictionResponse(BaseModel):
    predictions: list

Ajoute l’endpoint de vérification de l’état de santé pour vérifier que ton modèle est prêt. Cette étape est importante pour Vertex AI, car sans vérification de santé dédiée, son orchestrateur interrogera des sockets aléatoires et ne pourra pas déterminer si le modèle est prêt pour l’inférence. Ta vérification doit renvoyer 200 OK en cas de succès et 503 Service Unavailable en cas d’échec :

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

Tu disposes maintenant de tout ce qu’il faut pour implémenter l’endpoint de prédiction qui traitera les requêtes d’inférence. Il acceptera un fichier image, exécutera l’inférence et renverra les résultats. Note que l’image doit être encodée en base64, ce qui augmente également la taille du payload de jusqu’à 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}")

Enfin, ajoute le point d’entrée de l’application pour exécuter le serveur 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)

Tu disposes maintenant d’une application FastAPI complète capable de traiter les requêtes d’inférence YOLO26. Tu peux la tester localement en installant les dépendances et en exécutant le serveur, par exemple avec uv.

# Install dependencies
uv pip install -e .

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

Pour tester le serveur, tu peux interroger les endpoints /health et /predict avec cURL. Place une image de test dans le dossier tests. Ensuite, dans ton Terminal, exécute les commandes suivantes :

# 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

Tu devrais recevoir une réponse JSON contenant les objets détectés. Lors de ta première requête, prévois un court délai, car Ultralytics doit récupérer et charger le modèle YOLO26.

2. Étendre l’image Docker d’Ultralytics avec ton application#

Ultralytics fournit plusieurs images Docker que tu peux utiliser comme base pour l’image de ton application. Docker installera Ultralytics et les pilotes GPU nécessaires.

Pour exploiter toutes les capacités des modèles Ultralytics YOLO, sélectionne l’image optimisée pour CUDA afin d’effectuer l’inférence sur GPU. Toutefois, si l’inférence sur CPU suffit pour ta tâche, tu peux également économiser des ressources de calcul en sélectionnant l’image réservée au CPU :

• Dockerfile : image optimisée pour CUDA destinée à l’entraînement et à l’inférence YOLO26 avec un ou plusieurs GPU.
• Dockerfile-cpu : image réservée au CPU pour l’inférence YOLO26.

Créer une image Docker pour ton application#

Crée un fichier Dockerfile à la racine de ton projet avec le contenu suivant :

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

Dans cet exemple, l’image Docker officielle d’Ultralytics ultralytics:latest est utilisée comme base. Elle contient déjà le modèle YOLO26 et toutes les dépendances nécessaires. Le point d’entrée du serveur est le même que celui utilisé pour tester l’application FastAPI localement.

Construire et tester l’image Docker#

Tu peux maintenant construire l’image Docker avec la commande suivante :

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

Remplace IMAGE_NAME et IMAGE_VERSION par les valeurs de ton choix, par exemple yolo26-fastapi:0.1. Note que tu dois construire l’image pour l’architecture linux/amd64 si tu la déploies sur Vertex AI. Le paramètre --platform doit être défini explicitement si tu construis l’image sur un Mac Apple Silicon ou toute autre architecture non-x86.

Une fois la construction de l’image terminée, tu peux tester l’image Docker localement :

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

Ton conteneur Docker exécute maintenant un serveur FastAPI sur le port 8080, prêt à accepter les requêtes d’inférence. Tu peux tester les endpoints /health et /predict avec les mêmes commandes cURL que précédemment :

# 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. Envoyer l’image Docker vers GCP Artifact Registry#

Pour importer ton modèle conteneurisé dans Vertex AI, tu dois envoyer l’image Docker vers Google Cloud Artifact Registry. Si tu ne disposes pas encore d’un dépôt Artifact Registry, tu devras d’abord en créer un.

Créer un dépôt dans Google Cloud Artifact Registry#

Ouvre la page Artifact Registry dans la console Google Cloud. Si tu utilises Artifact Registry pour la première fois, il se peut que l’on te demande d’activer d’abord l’API Artifact Registry.

1. Sélectionne Create Repository.
2. Saisis le nom de ton dépôt. Sélectionne la région souhaitée et conserve les paramètres par défaut pour les autres options, sauf si tu dois les modifier spécifiquement.

1. Une fois le dépôt créé, enregistre ton PROJECT_ID, ta Location (Region) et ton Repository Name dans ton coffre de secrets ou ton fichier .env. Tu en auras besoin plus tard pour étiqueter et envoyer ton image Docker vers Artifact Registry.

Authentifier Docker auprès d’Artifact Registry#

Authentifie ton client Docker auprès du dépôt Artifact Registry que tu viens de créer. Exécute la commande suivante dans ton terminal :

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

Étiqueter et envoyer ton image vers Artifact Registry#

Étiquette et envoie l’image Docker vers Google Artifact Registry.

Étiquette ton image avec l’URL du dépôt Artifact Registry. Remplace les espaces réservés par les valeurs enregistrées précédemment.

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

Envoie l’image étiquetée vers le dépôt Artifact Registry.

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

Attends la fin du processus. Tu devrais maintenant voir l’image dans ton dépôt Artifact Registry.

Pour obtenir des instructions plus précises sur l’utilisation des images dans Artifact Registry, consulte la documentation Artifact Registry : envoyer et récupérer des images.

4. Importer ton modèle dans Vertex AI#

À l’aide de l’image Docker que tu viens d’envoyer, tu peux maintenant importer le modèle dans Vertex AI.

1. Dans le menu de navigation de Google Cloud, accède à Vertex AI > Model Registry. Tu peux également rechercher « Vertex AI » dans la barre de recherche située en haut de la console Google Cloud.

5. Créer un endpoint Vertex AI et déployer ton modèle#

Pour déployer un modèle, tu dois créer un endpoint dans Vertex AI.

1. Dans le menu de navigation de Vertex AI, accède à Endpoints. Sélectionne la région utilisée lors de l’importation de ton modèle. Clique sur Create.

1. Une fois le type de machine sélectionné, tu peux cliquer sur Continue. À ce stade, tu peux choisir d’activer la surveillance du modèle dans Vertex AI, un service supplémentaire qui suivra les performances de ton modèle et fournira des informations sur son comportement. Cette option est facultative et entraîne des coûts supplémentaires ; sélectionne-la donc selon tes besoins. Clique sur Create.

Vertex AI prendra plusieurs minutes (jusqu’à 30 minutes dans certaines régions) pour déployer le modèle. Tu recevras une notification par e-mail une fois le déploiement terminé.

6. Tester ton modèle déployé#

Une fois le déploiement terminé, Vertex AI te fournira un exemple d’interface API pour tester ton modèle.

Pour tester l’inférence distante, tu peux utiliser la commande cURL fournie ou créer une autre bibliothèque cliente Python qui enverra des requêtes au modèle déployé. N’oublie pas que tu dois encoder ton image en base64 avant de l’envoyer à l’endpoint /predict.

Tu as déployé avec succès un modèle YOLO26 préentraîné avec Ultralytics sur Google Cloud Vertex AI.

FAQ#