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

Ce guide te montre 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'usage de détection d'objets pour YOLO26, mais les mêmes principes s'appliqueront pour l'utilisation d'autres modes YOLO.

Avant de commencer, tu devras créer un projet Google Cloud Platform (GCP). Tu obtiens 300 $ de crédits GCP à utiliser gratuitement en tant que nouvel utilisateur, et ce montant est suffisant pour tester une configuration opérationnelle que tu pourras étendre plus tard pour tout autre cas d'usage YOLO26, y compris 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 en utilisant FastAPI.
2. Créer un dépôt Artifact Registry GCP pour stocker ton image Docker.
3. Construire et envoyer l'image Docker avec le modèle vers Artifact Registry.
4. Importer ton modèle dans Vertex AI.
5. Créer un point de terminaison 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 gcloud CLI.
3. Il est fortement 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.

Créer un backend d'inférence avec FastAPI

Tout d'abord, tu dois créer une application FastAPI qui servira 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 conformité Vertex AI

Vertex AI attend de ton conteneur qu'il implémente deux points de terminaison spécifiques :

1. Point de terminaison Santé (/health) : doit retourner le statut HTTP 200 OK lorsque le service est prêt.

2. Point de terminaison Prédiction (/predict) : accepte des requêtes de prédiction structurées avec des images encodées en base64 et des paramètres optionnels. Des limites de taille de charge utile s'appliquent selon le type de point de terminaison.

   Les charges utiles de requête pour le point de terminaison /predict doivent suivre cette structure JSON :

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

Structure du dossier de projet

L'essentiel de notre construction se déroulera à l'intérieur du conteneur Docker, et Ultralytics chargera également un modèle YOLO26 pré-entraîné, tu peux donc garder la structure du dossier local 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 avec 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 sera utilisé pour exécuter le serveur FastAPI.
• pillow sera utilisé pour le traitement d'image, mais tu n'es pas limité aux images PIL seulement — Ultralytics prend en charge beaucoup d'autres formats.

Créer la logique d'inférence avec Ultralytics YOLO26

Maintenant que tu as configuré la structure du projet et les dépendances, tu peux implémenter la logique d'inférence YOLO26 principale. Crée un fichier src/app.py qui gérera le chargement du modèle, le traitement de l'image et la prédiction, en utilisant 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

Cela chargera le modèle une fois au démarrage du conteneur, et le modèle sera partagé entre toutes les requêtes. Si ton modèle doit gérer une charge d'inférence lourde, il est recommandé de sélectionner un type de machine avec plus de mémoire lors de l'importation du modèle dans Vertex AI à une étape ultérieure.

Ensuite, crée deux fonctions utilitaires pour le traitement des images d'entrée et de sortie avec pillow. YOLO26 prend en charge nativement 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 les boîtes englobantes, les noms de classes et les scores de confiance des prédictions du modèle. La fonction retournera un dictionnaire avec 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."""
    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}

Optionnellement, tu peux ajouter une fonction pour annoter l'image avec des boîtes englobantes et des étiquettes en utilisant la méthode de traçage 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 as la logique d'inférence YOLO26 principale, tu peux créer une application FastAPI pour la servir. Cela inclura les points de terminaison de vérification de santé et de prédiction requis par Vertex AI.

Tout d'abord, ajoute les importations et configure la journalisation pour Vertex AI. Parce que Vertex AI traite stderr comme une sortie d'erreur, il est judicieux de diriger 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 une conformité totale avec Vertex AI, définis les points de terminaison requis dans les variables d'environnement et définis la limite de taille pour les requêtes. Il est recommandé d'utiliser des points de terminaison Vertex AI privés pour les déploiements en production. De cette façon, tu auras une limite de charge utile de requête plus élevée (10 Mo au lieu de 1,5 Mo pour les points de terminaison publics), ainsi qu'une sécurité et un contrôle d'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 réponses :

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

class PredictionResponse(BaseModel):
    predictions: list

Ajoute le point de terminaison de vérification de santé pour vérifier la disponibilité de ton modèle. Ceci est important pour Vertex AI, car sans une vérification de santé dédiée, son orchestrateur pingera 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 pour le succès et 503 Service Unavailable pour l'é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 as maintenant tout ce qu'il faut pour implémenter le point de terminaison de prédiction qui gérera 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 de la charge utile 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 as maintenant une application FastAPI complète qui peut servir 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 à la fois les points de terminaison /health et /predict en utilisant 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 avec les objets détectés. Lors de ta première requête, attends-toi à un court délai, car Ultralytics doit extraire et charger le modèle YOLO26.

Étendre l'image Docker Ultralytics avec ton application

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

Pour utiliser toutes les capacités des modèles Ultralytics YOLO, tu devrais sélectionner l'image optimisée CUDA pour l'inférence GPU. Cependant, si l'inférence CPU suffit pour ta tâche, tu peux économiser des ressources informatiques en sélectionnant également l'image CPU uniquement :

• Dockerfile : Image optimisée CUDA pour l'entraînement et l'inférence YOLO26 sur un ou plusieurs GPU.
• Dockerfile-cpu : Image CPU uniquement pour l'inférence YOLO26.

Créer une image Docker pour ton application

Crée un 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 l'exemple, l'image Docker officielle 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 que nous avons utilisé pour tester l'application FastAPI localement.

Construire et tester l'image Docker

Maintenant, tu peux 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 tes valeurs souhaitées, par exemple, yolo26-fastapi:0.1. Note que tu dois construire l'image pour l'architecture linux/amd64 si tu déploies sur Vertex AI. Le paramètre --platform doit être explicitement défini si tu construis l'image sur un Mac avec 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 des requêtes d'inférence. Tu peux tester les points de terminaison /health et /predict avec les mêmes commandes cURL qu'auparavant :

# 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

Téléverser l'image Docker vers GCP Artifact Registry

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

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, tu pourrais être invité à activer l'API Artifact Registry en premier.

1. Sélectionne Créer un dépôt.
2. Entre le nom de ton dépôt. Sélectionne la région souhaitée et utilise les paramètres par défaut pour les autres options, sauf si tu as besoin de les modifier spécifiquement.

1. Une fois le dépôt créé, enregistre ton PROJECT_ID, ton emplacement (région) et le nom du dépôt dans ton coffre de secrets ou ton fichier .env. Tu en auras besoin plus tard pour taguer 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

Taguer et envoyer ton image vers Artifact Registry

Tague et envoie l'image Docker vers Google Artifact Registry.

Tague ton image avec l'URL du dépôt Artifact Registry. Remplace les espaces réservés par les valeurs que tu as enregistrées plus tôt.

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

Envoie l'image tagué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 que le processus se termine. Tu devrais maintenant voir l'image dans ton dépôt Artifact Registry.

Pour des instructions plus spécifiques sur la façon de travailler avec les images dans Artifact Registry, consulte la documentation d'Artifact Registry : Envoyer et extraire des images.

Importer ton modèle dans Vertex AI

En utilisant 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, va dans Vertex AI > Registre de modèles. Alternativement, cherche "Vertex AI" dans la barre de recherche en haut de la console Google Cloud.

Créer un point de terminaison Vertex AI et déployer ton modèle

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

1. Dans ton menu de navigation Vertex AI, va dans Points de terminaison. Sélectionne la région que tu as utilisée lors de l'importation de ton modèle. Clique sur Créer.

1. Une fois le type de machine sélectionné, tu peux cliquer sur Continuer. À 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. C'est optionnel et engendre des coûts supplémentaires, choisis donc en fonction de tes besoins. Clique sur Créer.

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 que le déploiement sera terminé.

Tester ton modèle déployé

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

Pour tester l'inférence à distance, 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 au point de terminaison /predict.

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

FAQ

Puis-je utiliser les modèles Ultralytics YOLO sur Vertex AI sans Docker ?

Oui ; cependant, tu devras d'abord exporter le modèle vers un format compatible avec Vertex AI, tel que TensorFlow, Scikit-learn ou XGBoost. Google Cloud fournit un guide sur l'exécution de modèles .pt sur Vertex avec un aperçu complet du processus de conversion : Exécuter des modèles PyTorch sur Vertex AI.

Veuillez noter que la configuration résultante s'appuiera uniquement sur la couche de service standard de Vertex AI et ne prendra pas en charge les fonctionnalités avancées du framework Ultralytics. Étant donné que Vertex AI prend entièrement en charge les modèles conteneurisés et peut les dimensionner automatiquement selon ta configuration de déploiement, cela te permet de tirer parti de toutes les capacités des modèles Ultralytics YOLO sans avoir besoin de les convertir dans un format différent.

Pourquoi FastAPI est-il un bon choix pour servir l'inférence YOLO26 ?

FastAPI offre un débit élevé pour les charges de travail d'inférence. Le support asynchrone permet de gérer plusieurs requêtes simultanées sans bloquer le thread principal, ce qui est important lors du service de modèles de vision par ordinateur.

La validation automatique des requêtes/réponses avec FastAPI réduit les erreurs d'exécution dans les services d'inférence en production. C'est particulièrement précieux pour les API de détection d'objets où la cohérence du format d'entrée est critique.

FastAPI ajoute une surcharge computationnelle minimale à ton pipeline d'inférence, laissant plus de ressources disponibles pour l'exécution du modèle et les tâches de traitement d'image.

FastAPI prend également en charge SSE (Server-Sent Events), ce qui est utile pour les scénarios d'inférence en streaming.

Pourquoi dois-je sélectionner une région si souvent ?

Il s'agit en fait d'une fonctionnalité de polyvalence de Google Cloud Platform, où tu dois sélectionner une région pour chaque service que tu utilises. Pour la tâche de déploiement d'un modèle conteneurisé sur Vertex AI, ta sélection de région la plus importante est celle pour le Model Registry. Elle déterminera la disponibilité des types de machines et des quotas pour ton déploiement de modèle.

De plus, si tu étends la configuration et stockes les données de prédiction ou les résultats dans Cloud Storage ou BigQuery, tu devras utiliser la même région que pour le Model Registry afin de minimiser la latence et garantir un débit élevé pour l'accès aux données.