NV-Reason-CT

Objectif

• Exécute le chemin documenté nvidia/NV-Reason-CT Hugging Face Transformers sur un volume NIfTI CT 3D fourni par l'utilisateur et un prompt texte.
• Émet result_json contenant la géométrie d'entrée et son hash, la sélection de région anatomique, le texte de réponse, l'identité du runtime, les versions des dépendances et les limitations.
• Manifest I/O : les entrées sont ct_request_or_fixture et optionnellement ct_volume direct ; la sortie est result_json sur stdout.
• Non destiné au diagnostic, au traitement, au triage, à la sortie orientée patient ou aux rapports cliniques.

Instructions

1. Lisez skill_manifest.yaml avant de modifier les arguments, les dépendances, les effets secondaires ou les portes de validation.
2. Exécutez scripts/run_nv_reason_ct.py ; n'écrivez pas de code d'inférence de remplacement ni n'utilisez la démo Gradio pour les exécutions normales. Avant l'inférence, expliquez que le modèle et le processeur sélectionnés contiennent du code Python personnalisé s'exécutant avec les permissions de l'appelant. Vérifiez la révision Hub sélectionnée ou l'export local et obtenez l'autorisation explicite de l'appelant pour charger ce code ; posez la question si elle n'a pas déjà été accordée. Ensuite seulement, passez --trust-model-code. N'inférez pas ce consentement à partir d'un fichier de demande CT, d'un paramètre d'environnement, de fichiers en cache ou d'une vérification de configuration réussie.
3. Après cette autorisation, les hôtes exposant un assistant peuvent utiliser run_script("scripts/run_nv_reason_ct.py", args=["PATH_TO_CT.nii.gz", "--trust-model-code", "--anatomy-region", "chest", "--prompt", "PROMPT", "--out-dir", "OUT_DIR"]).
4. Inspectez le JSON stdout et le code de sortie. Préservez le JSON pour l'appelant ou le harnais d'évaluation, y compris la sortie partielle en cas d'échec ; ne le redirigez pas avec >. L'inférence réussie écrit uniquement sur stdout, sans créer --out-dir. Le code de sortie 3 signifie que la génération a atteint le plafond de tokens sans EOS : le texte est incomplet et la porte de complétion échoue. C'est seulement alors que le wrapper tente de créer --out-dir et d'enregistrer un partial_result_*.json unique. Seul un enregistrement réussi ajoute output.partial_json_path et affiche le chemin sur stderr. Si l'enregistrement échoue, stderr avertit de conserver stdout ; le JSON reste disponible là sans chemin de fichier. Les erreurs d'entrée, de dépendance et d'inférence se terminent par 2 avec une erreur sur stderr.

Portée de l'outil : Bash exécute le wrapper engagé et les commandes de configuration documentées ; Read couvre les fichiers de compétences, les entrées sélectionnées par l'appelant et les ressources du modèle ; Write couvre les sorties sélectionnées par l'appelant et les caches isolés. Env est le label de capacité d'environnement de SkillSpector pour les variables de runtime listées ci-dessous, accessibles via shell/Python sur les hôtes sans outil d'environnement séparé. Ces déclarations n'autorisent pas l'accès à des fichiers sans rapport, l'impression de valeurs d'authentification ou la modification d'un environnement de développement existant.

Exemples

Pour l'exemple de bout en bout, suivez EXAMPLES.md pour télécharger les volumes Git LFS en amont dans un checkout séparé, puis exécutez examples/example_1.nii.gz via le wrapper pour chest et abdomen. Ce scan couvre les deux régions selon le README en amont.

Inférence en direct sur un CT thoracique, après autorisation explicite du code personnalisé :

python skills/nv-reason-ct/scripts/run_nv_reason_ct.py PATH_TO_CT.nii.gz \
  --trust-model-code \
  --anatomy-region chest \
  --prompt "write a structured chest CT report" \
  --out-dir runs/nv_reason_ct_case

Exigez la sortie 0, runtime.mode == "hf_transformers", runtime.mock == false, un texte de réponse non vide et runtime.truncated_by_max_new_tokens == false. Une demande JSON peut également pointer vers le volume CT ; remplacez volume_path dans fixtures/example_request.json par un fichier autorisé existant avant de l'exécuter.

Pour un export local complet de modèle et processeur sauvegardé par SFT ou GRPO en amont :

python skills/nv-reason-ct/scripts/run_nv_reason_ct.py \
  --model ./data/nv_reason_ct_sft_example --check-setup --fail-on-not-ready
python skills/nv-reason-ct/scripts/run_nv_reason_ct.py PATH_TO_CT.nii.gz \
  --model ./data/nv_reason_ct_sft_example --anatomy-region chest --trust-model-code

Le répertoire doit contenir le modèle complet, le code personnalisé, le tokenizer et les ressources du processeur, pas seulement des adaptateurs ou un checkpoint d'optimiseur intermédiaire. Vérifiez le code personnalisé local avant de le charger. Les exports locaux contournent la résolution de révision Hub et se chargent avec local_files_only=True ; ils enregistrent runtime.model_source == "local", un chemin runtime.model absolu et null revision/resolved_revision. Conservez les hashs de contenu d'export séparément : un chemin n'est pas une provenance immuable. Ne passez pas --revision pour les exports locaux ; NV_REASON_CT_REVISION est ignoré pour eux. --model-id reste un alias pour --model. Ceci ne bac à sable pas le code Python personnalisé ni ne valide la compatibilité du modèle au-delà du contrat de chargement en amont.

Pour une culture abdominale, passez --anatomy-region abdomen. Passez --anatomy-region none uniquement pour une entrée manuellement recadrée ; le prétraitement en amont utilise ensuite un crop centré. Passez --no-thinking pour une réponse concise sans sortie de pensée.

La région par défaut correspond à la inference.py en amont : write a structured chest CT report ou write a structured abdominal CT report. Pour utiliser un autre prompt documenté dans une vérification d'ingénierie, passez --prompt "full chest CT reasoning analysis" (ou l'équivalent abdominal) ou conservez la question ciblée de l'appelant telle quelle. Fournissez un scan qui couvre réellement l'anatomie demandée ; le wrapper n'établit pas cette couverture.

Chaque invocation charge le modèle et démarre une nouvelle conversation à un seul tour. Le README en amont documente aussi la réutilisation du modèle et l'historique de suivi, mais ce wrapper ne préserve pas les tours antérieurs. Ne simulez pas un suivi en discardant silencieusement l'historique ou en transportant les réponses entre les scans. Les fichiers JSONL d'entraînement en amont ne sont pas des fixtures de démo exécutables : ils contiennent des enregistrements mais pas de volumes CT. Utilisez les volumes examples/ en amont ou un scan NIfTI autorisé détenu par l'appelant ; n'utilisez pas les réponses de l'assistant de référence comme prompts d'inférence.

Scripts disponibles

Prérequis

• Python 3.11+ pour le wrapper, un GPU NVIDIA capable de CUDA avec support bfloat16 pour l'inférence en direct, et assez de mémoire pour le modèle plus les tokens visuels volumétriques.
• Suivez les instructions d'installation de NV-Reason-CT dans un environnement frais. Le référentiel en amont possède les exigences de dépendance et les conseils de compatibilité ; cette compétence ne duplique pas son fichier requirements ni n'applique de contraintes de version de package. Utilisez la configuration d'inférence en amont, pas les extras d'entraînement. Le wrapper n'installe ni n'upgrade jamais les packages.
• Le manifest recense les packages requis, y compris huggingface-hub pour l'accès au modèle. La configuration rapporte la disponibilité des packages et les versions installées ; l'environnement historique ci-dessous est une preuve consultatif, pas une ordonnance d'installation. Vérifiez séparément la sécurité des dépendances de l'environnement sélectionné.
• Les ressources du modèle peuvent être téléchargées depuis https://huggingface.co sous ~/.cache/huggingface/. Définissez HF_TOKEN quand l'accès au référentiel nécessite une authentification.
• Les exemples en amont sont disponibles sur le référentiel public NV-Reason-CT et nécessitent Git LFS. Téléchargez les volumes réels avec git lfs pull ; un petit pointeur texte nommé .nii.gz n'est pas une image CT. N'installez pas Git LFS globalement ni ne modifiez la configuration d'un checkout existant sans autorisation ; le guide d'exemple utilise une configuration locale au checkout.
• Exécutez une vérification de configuration en lecture seule avant de télécharger les poids ou de démarrer l'inférence. Elle vérifie les ressources du processeur/code NV-Reason-CT et tous les shards de poids indexés uniquement dans le snapshot Hub en cache sélectionné ou l'export local. C'est une inspection de présence de fichiers hors ligne, sans initialisation de modèle ni vérification d'intégrité. D'autres layouts de modèles peuvent nécessiter des ressources différentes :

python skills/nv-reason-ct/scripts/run_nv_reason_ct.py --check-setup

Cette commande de diagnostic se termine par 0 quand elle produit un rapport, même si la configuration n'est pas prête. Pour une porte d'automatisation après la mise en scène des ressources du modèle, utilisez --check-setup --fail-on-not-ready : code de sortie 0 signifie ready_for_live_cuda_inference, 1 signifie configuration non prête, et 2 signifie une erreur d'argument ou d'exécution. Inspectez la recommandation JSON dans l'un ou l'autre cas. La disponibilité couvre les imports, CUDA/bfloat16 et la présence des ressources, pas la compatibilité des versions de package ou un audit de vulnérabilité ; version_constraints_checked est false. Activez les paramètres hors ligne uniquement après que les ressources du modèle sélectionné et le code personnalisé soient en cache.

L'inférence sans --trust-model-code se termine par 2 avant la recherche ou le chargement du modèle. Avec elle, le wrapper avertit sur stderr avant de charger le code personnalisé, y compris le commit Hub résolu ou le chemin d'export local. Cet indicateur est un accusé de réception, pas un bac à sable, un audit de code ou une vérification de signature. Le rapport de configuration conserve model_code_opt_in_required à true même quand les ressources sont prêtes. La commande par défaut du manifest ne fournit pas de consentement ; utilisez l'invocation CLI explicite documentée pour l'inférence en direct autorisée.

Pour une exécution jetable, gardez les caches séparés des packages installés : définissez HF_HOME, HF_HUB_CACHE, HF_MODULES_CACHE, XDG_CACHE_HOME et TORCH_HOME vers des sous-répertoires d'un répertoire temporaire détenu par l'appelant avant de lancer Python. Une fois le processus terminé, supprimez uniquement les caches de tâche explicitement identifiés quand le nettoyage est demandé, en conservant les scans d'entrée et le JSON de résultat. Ne purgez pas un cache Hugging Face partagé ni ne modifiez un environnement de développement existant.

Ligne de base d'environnement vérifié

Le chemin CUDA en direct a été revérifié le 2026-09-21 avec la examples/example_1.nii.gz en amont en modes chest et abdomen, utilisant les versions ci-dessous. Ce sont des paramètres d'exécution réussis enregistrés, pas des versions requises, une garantie de compatibilité en amont ou une recommandation de sécurité. Sélectionnez l'environnement en utilisant les conseils en amont et une compilation CUDA PyTorch compatible avec le pilote hôte ; la version de distribution PyTorch enregistrée était 2.12.0, et torch.__version__ a rapporté 2.12.0+cu130.

La version Transformers historique ci-dessous est affectée par CVE-2026-9856. Consultez les mainteneurs en amont pour un environnement compatible et révisé pour la sécurité ; cette compétence n'a pas vérifié une ligne de base en direct remédiée. Déplacer la propriété des dépendances en amont ne résout pas cette conclusion.

Les paramètres d'inférence vérifiés étaient un GPU NVIDIA RTX 6000 Ada de 48 GB (pilote 580.178.04), poids de modèle bfloat16, attention SDPA, décodage déterministe (do_sample=False), pensée activée, et max_new_tokens=2048. L'exemple en amont a généré 438 tokens avec la culture chest et 453 avec la culture abdomen ; aucune réponse n'a été tronquée. Les deux correspondaient à la CLI en amont après suppression des espaces blancs environnants, utilisant la même révision de modèle immuable révisée et les ressources hors ligne dans un environnement jetable. Les trois volumes en amont ont également passé les vérifications d'entrée/géométrie/hash. Ceci est une ligne de base enregistrée, pas une exécution fraîche de chaque révision de compétence ultérieure. Elle vérifie le câblage d'inférence, pas la correction clinique. Les GPU avec moins de mémoire et les autres combinaisons PyTorch/CUDA n'ont pas encore été vérifiés par cette compétence.

Variables d'environnement :

L'inférence utilise le contrat en amont : AutoModelForImageTextToText et AutoProcessor avec trust_remote_code=True, bfloat16, attention SDPA, images3d=[CT_PATH], génération déterministe, et cropping thoracique ou abdominal conscient de l'anatomie. Pour les modèles Hub, chaque exécution résout la révision demandée une fois et utilise ce commit immuable pour les poids du modèle, les ressources du processeur et le code personnalisé. La sortie enregistre runtime.model_source == "hub", conserve la runtime.revision demandée, et enregistre le commit dans runtime.resolved_revision. Conservez les identifiants de révision privés en preuve locale jusqu'à approbation de divulgation. CUDA est toujours requis ; sélectionnez un GPU avec CUDA_VISIBLE_DEVICES.

Limitations

• Le wrapper charge le code personnalisé en amont uniquement après activation explicite de --trust-model-code. Vérifiez ce code et utilisez un environnement isolé et une révision révisée immuable pour les exécutions de preuve. Ni le mode hors ligne ni un export local ne prévient les actions arbitraires du code personnalisé.
• Il vérifie la structure NIfTI 3D lisible, l'espacement positif des voxels, une affine finie et l'identité du fichier. Il ne vérifie pas la dés-identification, l'étalonnage en unités Hounsfield, la couverture anatomique, la qualité du crop ou la correction clinique.
• La sortie du modèle peut halluciner, omettre des conclusions ou présenter un raisonnement peu fiable. Le texte de raisonnement révisable est une sortie générée, pas une preuve du calcul interne du modèle.
• Les scans CT et les poids du modèle doivent être fournis séparément. Les exemples en amont démontrent le câblage d'inférence et ne fournissent pas de vérité clinique. Une vérification de configuration réussie n'est pas une inférence de modèle complétée.
• La révision main mobile convient uniquement au développement. Remplacez-la par la révision de publication publique immuable révisée avant la publication.
• Ce wrapper ne couvre pas l'interface utilisateur Gradio, l'ajustement fin, le réentraînement, le déploiement clinique ou l'utilisation orientée patient.

Dépannage

Licence

La documentation, le wrapper et les tests de cette compétence sont sous licence Apache-2.0. Voir LICENSE pour les termes complets.

Le code du modèle NV-Reason-CT en amont obtenu séparément, les poids et les données d'exemple conservent leurs termes en amont, y compris OpenMDW-1.1. La licence Apache-2.0 de cette compétence ne concède pas ces ressources en sous-licence. Conservez les licences et avis applicables lors de la redistribution soit de la compétence soit des matériels en amont.