Compétence DeepStream Development

Lorsque cette compétence est active, LISEZ TOUJOURS les documents de référence pertinents avant de générer du code. NE PAS vous fier à la mémoire - les documents de référence contiennent des détails critiques sur les noms de propriétés exacts, l'utilisation correcte de l'API et les pièges courants.

Référence rapide SDK et architecture

Exigences de version DeepStream SDK 9.0

• GStreamer : 1.24.2
• Pilote NVIDIA : 590+
• CUDA : 13.1
• TensorRT : 10.14.1.48
• Plateformes : Ubuntu 24.04 (x86_64 et ARM64/Jetson)

Flux pipeline typique

Source → Stream Muxer → Inference → [Tracker] → OSD → Renderer

Les composants entre [crochets] sont optionnels -- ne les ajoutez que si l'utilisateur les demande explicitement.

Modèle de mémoire

DeepStream utilise le gestionnaire de mémoire vidéo NVIDIA (NVMM) pour les transferts de tampon GPU sans copie. Les chaînes de capacités utilisent memory:NVMM pour indiquer la mémoire GPU (ex. : video/x-raw(memory:NVMM), format=NV12).

Règles critiques

1. Ajouter uniquement les composants demandés : NE PAS ajouter d'éléments pipeline que l'utilisateur n'a pas demandés.

   • Tracker (nvtracker) : Ajouter seulement si l'utilisateur demande explicitement le suivi ou les ID d'objets entre les images
   • GIEs secondaires : Ajouter seulement si l'utilisateur demande la classification ou l'extraction d'attributs
   • Analytics (nvdsanalytics) : Ajouter seulement si l'utilisateur demande le franchissement de ligne, le comptage ROI, etc.
   • Message broker (nvmsgbroker/nvmsgconv) : Ajouter seulement si l'utilisateur demande la messagerie Kafka/cloud
   • En cas de doute, construisez le pipeline fonctionnel minimal et laissez l'utilisateur demander des ajouts

2. Par défaut, utiliser nvurisrcbin pour les sources : Quand l'utilisateur dit « caméra », « flux », « vidéo » ou fournit un chemin fichier :

   • Toujours utiliser nvurisrcbin -- il gère RTSP, HTTP et les fichiers locaux (file://) de façon transparente
   • Utiliser filesrc + qtdemux + parser seulement si l'utilisateur demande explicitement un contrôle brut de la source fichier
   • Pour les sources RTSP/live, aussi définir live-source=1 sur nvstreammux et sync=0 sur le sink
   • Convertir les chemins locaux en URI : "file://" + os.path.abspath(path)

3. Itération métadonnées : Utiliser .frame_items et .object_items (retournent des itérateurs, PAS des listes)

   • JAMAIS utiliser len() sur ceux-ci - itérer pour compter
   • L'itérateur ne peut être consommé qu'une fois

4. Syntaxe Pad de requête : Utiliser le modèle "sink_%u", JAMAIS des noms de pad littéraux

   pipeline.link(("decoder", "mux"), ("", "sink_%u"))  # CORRECT
   # pipeline.link(("decoder", "mux"), ("", "sink_0"))  # WRONG - causera une erreur

5. Détection de plateforme pour les sinks :

   import platform
   sink_type = "nv3dsink" if platform.processor() == "aarch64" else "nveglglessink"

6. Clonage de tampon : Toujours cloner les tampons pour le traitement asynchrone

   tensor = buffer.extract(0).clone()  # CRITIQUE

7. Types de file d'attente :

   • queue.Queue → Utiliser avec threading.Thread
   • multiprocessing.Queue → Utiliser avec multiprocessing.Process
   • Utiliser le mauvais type provoque une perte de données silencieuse !

8. Format config nvinfer :

   • YAML : Utiliser section property: (PAS model:), key: value avec espace après le deux-points
   • INI : Utiliser section [property], key=value avec signe égal
   • La section DOIT s'appeler property

9. nvmsgbroker est un SINK : Ne peut pas avoir d'éléments aval - utiliser tee pour diviser le pipeline

10. TOUS les sinks ont besoin de async=0 pour les scissions Tee ou les sources dynamiques : CRITIQUE pour les transitions d'état

     # Lors de l'utilisation de scissions tee OU de sources dynamiques, TOUS les sinks DOIVENT avoir async=0
     pipeline.add("nveglglessink", "sink", {
         "sync": 0, "qos": 0,
         "async": 0  # CRITIQUE - prévient l'interblocage de transition d'état
     })

    Symptôme en cas d'omission : Le pipeline reste en état PAUSED, aucune vidéo ne s'affiche.

11. Attachement de probe intégré : measure_fps_probe ne peut être attaché qu'à des éléments de traitement (ex. : nvinfer, nvosdbin), PAS à des éléments sink. L'attachement à un sink lève RuntimeError: Probe failure.

12. Les modèles ONNX dynamiques nécessitent infer-dims : Quand le modèle ONNX a des formes d'entrée dynamiques (ex. : exporté avec dynamic=True dans YOLO Ultralytics, ou avec des axes dynamiques de batch/hauteur/largeur), vous DEVEZ ajouter infer-dims=C;H;W à la config nvinfer. Sans cela, TensorRT voit -1 pour les dimensions dynamiques et échoue avec setDimensions: Error Code 3. Valeurs courantes :

    • Modèles YOLO (entrée 640) : infer-dims=3;640;640
    • Modèles avec entrée 416 : infer-dims=3;416;416
    • Modèles avec entrée 1280 : infer-dims=3;1280;1280

13. Le format de sortie Ultralytics YOLO dépend de la génération du modèle -- les nouveaux modèles (v10+/v26+) génèrent des résultats post-NMS ; les anciens modèles (v8/v11) génèrent des tenseurs bruts pré-NMS. Le parser personnalisé et cluster-mode doivent correspondre à la sortie réelle :

    Génération modèle	Forme tenseur sortie	Champs	cluster-mode
    v8 / v11	[batch, 84, 8400]	[features(4+80), anchors] -- cx/cy/w/h brut + scores de classe, pas NMS	2 (NMS)
    v10 / v26+	[batch, 300, 6]	[max_det, (x1,y1,x2,y2,conf,cls)] -- déjà post-NMS, coordonnées pixel	4 (aucun)

    Comment identifier au runtime : enregistrer inferDims.d[0] et inferDims.d[1] à l'intérieur du parser personnalisé.

    • d={84, 8400} → pré-NMS (style v8/v11)
    • d={300, 6} → post-NMS (style v10/v26+)

    Symptôme de non-correspondance : Si cluster-mode: 2 est utilisé avec une sortie post-NMS [N, 6], les boîtes de délimitation apparaissent décalées de 45° ou 135° par rapport aux objets réels (le NMS de DeepStream retraite incorrectement les coordonnées déjà finales). Si vous voyez des boîtes inclinées ou tournées, vérifiez aussi la note OBB / rotation_angle dans references/nvinfer_config.md : pour les modèles non-OBB, initialisez la valeur NvDsInferObjectDetectionInfo avec obj{} et gardez rotation_angle = 0 ; un simple NvDsInferObjectDetectionInfo obj; laisse les champs non initialisés.

14. L'environnement virtuel doit inclure pyservicemaker : pyservicemaker est installé au niveau système mais N'EST PAS accessible depuis un environnement virtuel Python standard. Quand une tâche nécessite un venv (ex. : pour le téléchargement/conversion de modèle avec dépendances pip), toujours installer pyservicemaker et pyyaml dans le venv. La configuration venv dans le code généré et le README doivent toujours inclure :

     python3 -m venv venv
     source venv/bin/activate
     pip install /opt/nvidia/deepstream/deepstream/service-maker/python/pyservicemaker*.whl pyyaml
     pip install -r requirements.txt  # autres dépendances

    Symptôme en cas d'omission : ModuleNotFoundError: No module named 'pyservicemaker' lors de l'exécution de l'application dans le venv.

Chemins clés (DeepStream 9.0)

• Modèles : /opt/nvidia/deepstream/deepstream/samples/models/
• Détecteur primaire : /opt/nvidia/deepstream/deepstream/samples/models/Primary_Detector/resnet18_trafficcamnet_pruned.onnx
• Lib Tracker : /opt/nvidia/deepstream/deepstream/lib/libnvds_nvmultiobjecttracker.so
• Lib Kafka : /opt/nvidia/deepstream/deepstream/lib/libnvds_kafka_proto.so
• Exemples de configs : /opt/nvidia/deepstream/deepstream/samples/configs/deepstream-app/

Documents de référence

IMPORTANT : Toujours lire ces documents pour les détails complets. NE PAS générer du code de mémoire.

Référence rapide d'erreurs