RTVI BYOM Porting

Objectif

Intégrer un VLM dans le service VSS RT-VLM sans coder en dur un checkpoint ou une plateforme GPU. Préférer la configuration, puis un adaptateur RTVI ou un plugin vLLM, et patcher vLLM uniquement si les points d'extension supportés ne peuvent pas exprimer le modèle.

Utiliser vss-deploy-dense-captioning pour un déploiement ordinaire ou un modèle déjà supporté. Utiliser cette compétence quand l'architecture du modèle, le processeur, le mappage des poids, les dépendances runtime ou l'adaptation des requêtes nécessitent un travail sur le repository.

Contrat du Modèle

Avant de modifier le code, documenter :

• la source et la révision immutables du modèle, la licence et les conditions d'accès ;
• l'architecture, le processeur, le tokenizer, la quantification et la longueur du contexte ;
• les hypothèses de token de vision et d'échantillonnage de frames ;
• les besoins en architecture CUDA, mémoire, vLLM/runtime et kernels personnalisés.

Pour une source Hugging Face privée, utiliser HF_TOKEN uniquement lors du téléchargement/remplissage du cache authentifiés. Ne jamais l'afficher, l'intégrer dans MODEL_PATH ou le bâtir dans une image. Prouver que le modèle en cache démarre après suppression de la credential temporaire. Si du code de modèle distant est requis, le relire d'abord et associer VLM_TRUST_REMOTE_CODE=true à une entrée d'allowlist exacte. Pour le profil VSS, définir RTVI_VLM_MODEL_PATH_ALLOWLIST ; à l'intérieur du conteneur service cela devient RTVI_MODEL_PATH_ALLOWLIST. De même, l'entrée de profil RTVI_VLM_ALLOW_UNSAFE_MODEL_CONFIG devient RTVI_ALLOW_UNSAFE_MODEL_CONFIG ; ne pas l'activer sans relire les hooks config bloqués.

Décision d'Intégration

Arrêter au premier chemin qui fonctionne :

1. Configuration uniquement : utiliser VLM_MODEL_TO_USE=vllm-compatible et MODEL_PATH=<ngc: ou chemin monté>. Une source git: est acceptable seulement pour l'exploration car le téléchargeur develop ne verrouille pas les révisions Hugging Face ; utiliser un snapshot monté avec révision verrouillée pour une preuve reproductible.
2. Adaptateur RTVI : normaliser config, processeur, comportement de requête ou réponse à l'intérieur de services/rtvi/rt-vlm/ tout en préservant le comportement de modèle existant.
3. Plugin ou shim : enregistrer l'architecture et les mappages de poids déterministes sans éditer les internes vLLM vendus.
4. Patch conditionnel à la version : patcher vLLM seulement après avoir documenté pourquoi les trois premiers chemins ne peuvent pas fonctionner. Le garder optionnel et ajouter un test de régression ciblé.

Utiliser VLM_MODEL_TO_USE=custom avec MODEL_IMPLEMENTATION_PATH seulement pour une implémentation de modèle RTVI personnalisée. Dans le profil VSS Compose ceux-ci sont exposés comme RTVI_VLM_MODEL_TO_USE, RTVI_VLM_MODEL_PATH et RTVI_VLM_MODEL_IMPLEMENTATION_PATH.

Pour les changements de source, adaptateur, plugin ou backend personnalisé, construire l'image RT-VLM depuis services/rtvi/rt-vlm/, la tester avec Compose standalone via RTVI_IMAGE, puis sélectionner le même repository et tag dans le profil VSS via VSS_RT_VLM_IMAGE et VSS_RT_VLM_TAG. Enregistrer le digest d'image testé. Un seul MODEL_IMPLEMENTATION_PATH hôte est insuffisant : l'implémentation doit exister à ce chemin à l'intérieur de l'image sélectionnée ou d'un bind mount Compose explicite.

Lire references/vllm-porting.md avant de modifier le chargement du modèle, l'enregistrement, le mappage de poids, les kernels, le comportement du cache ou vLLM.

Barrages Obligatoires

• Ne pas activer le mode eager par défaut. S'il est inévitable, capturer le bloqueur exact, l'impact de performance et la condition de suppression.
• Ne pas lier la logique de modèle générique à H100, B200, RTX, Orin, x86 ou Jetson. Utiliser la détection de capacité ou les limites de configuration existantes.
• Garder les secrets hors des commandes, logs, images, rapports et fichiers commités.
• Ne pas accepter un chargement réussi comme preuve d'un port réussi. La sortie doit être lisible et justifiée pour chaque modalité revendiquée.

Validation

Exécuter les plus petites vérifications pertinentes dans cet ordre :

1. Vérifications statiques et tests ciblés pour Python, shell et configuration modifiés.
2. Démarrer RT-VLM par le chemin canonique VSS Compose/profil et vérifier /v1/health/ready et /v1/models. D'abord utiliser Compose standalone quand un snapshot de modèle hôte avec révision verrouillée doit être monté ; le profil VSS n'expose pas MODEL_ROOT_DIR en develop.
3. Smoke-test des entrées texte, image et vidéo pour chaque modalité revendiquée. Définir le type de média explicite lors du test d'images plutôt que de compter sur le routage vidéo.
4. Lire references/quality-gates.md, conserver les réponses brutes caviardées, et rejeter le charabia, les répétitions ou les affirmations injustifiées.
5. Exécuter les vérifications de précision pertinentes pour caption, détection d'événement ou résumé.
6. Enregistrer la latence, le débit, la mémoire/utilisation GPU, l'état eager et l'état du kernel personnalisé.

Utiliser skills/deployment/rtvi-byom-porting/scripts/byom_port_report.py pour transformer les faits JSON observés en un rapport Markdown compact. La preuve est obligatoire pour un résultat PASS ; l'assistant ne la fabrique pas. Exécuter python3 skills/deployment/rtvi-byom-porting/scripts/tests/test_byom_port_report.py après avoir changé l'assistant.

Contrat d'Achèvement

Rapporter la révision exacte du modèle et du backend, le chemin d'intégration, l'état du mode eager, le gating de plateforme, la preuve smoke/accuracy/performance, les blocages restants et l'étape de validation bornée suivante.