1. Initialisation de l'environnement : Éviter les erreurs de démarrage

L'une des frustrations majeures lors de l'utilisation d'une image Docker ou d'un environnement pré-configuré pour YOLOv9 est de rencontrer un message ModuleNotFoundError dès la première commande. Cela provient souvent d'une mauvaice activation de l'environnement virtuel.

Activation correcte de Conda

Par défaut, de nombreux conteneurs démarrent sur l'environnement base. Pour utiliser les dépendances spécifiques à YOLOv9, vous devez basculer explicitement vers l'environnement dédié :

# Vérifier les environnements disponibles
conda env list

# Activer l'environnement cible
conda activate yolov9_env

Si la commande conda activate renvoie une erreur de type CommandNotFoundError, initialisez votre shell :

conda init bash && source ~/.bashrc

Compatibilité CUDA et PyTorch

YOLOv9 nécessite une synchronisation stricte entre le pilote NVIDIA du système hôte et les bibliothèques internes du conteneur. Si torch.cuda.is_available() renvoie False, vérifiez que votre driver hôte supporte la version de CUDA installée (souvent CUDA 11.x ou 12.x pour YOLOv9). Ne tentez pas de réinstaller PyTorch avec un simple pip install torch, car cela pourrait écraser la version optimisée pour CUDA.

2. Problèmes de chemins et d'exécution des scripts

Une erreur fréquente comme File not found: data.yaml survient lorsque le script est lancé depuis le mauvais répertoire de travail. Les scripts YOLOv9 utilisent des chemins relatifs basés sur la racine du projet.

# Mauvaise pratique : exécuter depuis la racine utilisateur
python /workspace/yolov9/detect_dual.py --weights model.pt

# Bonne pratique : se déplacer dans le dossier du code
cd /workspace/yolov9
python detect_dual.py --source ./data/images/demo.jpg --weights ./yolov9-s.pt

3. Optimisation de l'inférence (Inference Tuning)

Si vos résultats de détection sont vides ou si le script plante, vérifiez les paramètres suivants :

Sélection du processeur graphique (GPU)

L'argument --device doit correspondre à l'index réel de votre GPU. Sur certains systèmes cloud, l'index commence à 1 au lieu de 0.

# Vérifier l'index du GPU via nvidia-smi
nvidia-smi

# Spécifier le bon index (exemple avec l'index 1)
python detect_dual.py --device 1 --source ./data/images/test.jpg

Gestion du mode GUI (OpenCV)

Dans un environnement serveur sans écran (headless), l'appel à cv2.imshow() provoquera un crash. Pour éviter cela lors de l'exécution dans un conteneur, désactivez l'affichage visuel et forcez l'enregistrement des résultats :

python detect_dual.py --source ./data/images/ --weights yolov9-s.pt --nosave --view-img # À éviter en headless
python detect_dual.py --source ./data/images/ --weights yolov9-s.pt --name output_results # Recommandé

4. Préparation des données et entraînement

L'entraînement échoue souvent à cause d'une structure de données non conforme ou d'une saturation de la mémoire (OOM).

Configuration du fichier data.yaml

Utilisez toujours des chemins absolus dans votre fichier de configuration YAML pour éviter toute ambiguïté, surtout au sein d'un conteneur Docker.

# Exemple de structure data.yaml correcte
train: /datasets/project/images/train
val: /datasets/project/images/val
nc: 2
names: ['objet_A', 'objet_B']

Script de validation des labels

Avant de lancer l'entraînement, assurez-vous que vos fichiers .txt sont au format YOLO (coordonnées normalisées entre 0 et 1). Voici un script rapide pour vérifier l'intégrité de vos annotations :

import os
from pathlib import Path

def validate_yolo_annotations(img_folder, label_folder):
    images = list(Path(img_folder).glob("*.jpg"))
    for img in images:
        lbl = Path(label_folder) / f"{img.stem}.txt"
        if not lbl.exists():
            print(f"Annotation manquante pour : {img.name}")
            continue
        
        with open(lbl, 'r') as f:
            for idx, line in enumerate(f):
                data = line.strip().split()
                if len(data) != 5:
                    print(f"Erreur format ligne {idx+1} dans {lbl.name}")
                else:
                    # Vérification de la normalisation [0, 1]
                    coords = [float(x) for x in data[1:]]
                    if not all(0 <= c <= 1 for c in coords):
                        print(f"Coordonnées hors limites dans {lbl.name} : {coords}")

validate_yolo_annotations("/root/data/images/train", "/root/data/labels/train")

Gestion de la mémoire GPU (OOM)

Le paramètre --batch définit la taille du lot. Si vous recevez une erreur Out of Memory, réduisez cette valeur ou diminuez le nombre de processus de chargement de données avec --workers.

5. Techniques avancées pour la précision et le déploiement

Multi-Scale Testing (MST)

Pour améliorer la détection des petits objets lors de l'évaluation, activez le test multi-échelle. Cela augmente le temps de calcul mais booste le mAP (Mean Average Precision).

python test_dual.py --data data.yaml --weights yolov9-s.pt --img 640 --multi-scale --task val

Exportation ONNX et BatchNorm

Lors de l'exportation du modèle pour une utilisation en production (TensorRT, ONNX Runtime), il est crucial de geler les couches de normalisation de lot (BatchNorm) pour garantir la stabilité de l'inférence. Dans le fichier models/common.py, assurez-vous que la classe de convolution force le mode évaluation :

# Modification suggérée dans common.py pour l'export
class Conv(nn.Module):
    def __init__(self, c1, c2, k=1, s=1, p=None, g=1, act=True):
        super().__init__()
        self.conv = nn.Conv2d(c1, c2, k, s, autopad(k, p), groups=g, bias=False)
        self.bn = nn.BatchNorm2d(c2)
        self.bn.eval() # Forcer le mode eval pour l'exportation
        self.act = nn.SiLU() if act is True else (act if isinstance(act, nn.Module) else nn.Identity())

Inférence sur flux RTSP

Pour traiter des flux vidéo en direct sans accumulation de latence ou fuite mémoire, utilisez impérativement le drapeau --stream :

python detect_dual.py --source 'rtsp://user:pass@ip:port/stream' --weights yolov9-s.pt --stream