NV-Reason-CXR

Objectif

• Utilisé pour les smoke tests de raisonnement sur radiographie thoracique NV-Reason-CXR en mode commande ou en direct. Pas pour le diagnostic ou les rapports cliniques.
• Utilisez le wrapper exactement comme documenté ; ne remplacez pas le point d'entrée en amont par une implémentation manuscrite.
• Manifest I/O : les entrées sont chest_xray_image_or_fixture ; les sorties sont result_json.

Instructions

• Lisez skill_manifest.yaml avant de modifier les arguments, les effets de bord ou les portes de validation.
• Exécutez scripts/run_nv_reason_cxr.py via la commande documentée ci-dessous ; conservez les sorties dans un répertoire d'exécution fourni par l'appelant.
• Si un agent hôte expose run_script, utilisez run_script("scripts/run_nv_reason_cxr.py", args=[...]) ; sinon, exécutez la commande Bash/Python indiquée ci-dessous.
• Vérifiez le JSON émis et les conseils du vérificateur associés avant de traiter l'exécution comme une preuve.

Scripts disponibles

Prérequis

• Configuration requise : GPU/CUDA si déclaré par le manifest ; packages Python listés dans runtime.side_effects.pip_packages.
• Effets de bord : écrit les sorties JSON dans le --out-dir de l'appelant, peut mettre en cache les ressources du modèle sous ~/.cache/huggingface/, et peut contacter https://huggingface.co ou https://github.com en dehors du mode --mock.
• Exécutez les commandes depuis la racine du référentiel sauf indication contraire dans une section existante ci-dessous.

Limitations

• Ceci est un wrapper léger. Le prétraitement des images, l'inférence du modèle et le décodage sont déléguées à Hugging Face Transformers et au modèle NV-Reason-CXR-3B.
• La sortie n'est pas un diagnostic, un rapport clinique, une recommandation de traitement ou une décision de triage. C'est une preuve d'ingénierie et doit être examinée par un professionnel qualifié avant toute utilisation médicale.
• Le modèle peut halluciner des observations, manquer des anomalies subtiles, mal lire les appareils de support ou produire un texte surconfiant.
• La fixture validée utilise un PNG synthétique généré et une réponse mock déterministe afin que l'IC puisse vérifier le comportement du wrapper sans télécharger les poids du modèle. Le mode mock n'est pas un substitut à l'inférence du modèle.
• Non destiné au déploiement clinique, à l'interprétation clinique, au diagnostic autonome, aux décisions de traitement.

Dépannage

Exécute le NV-Reason-CXR-3B de NVIDIA-Medtech pour l'interprétation d'images de radiographie thoracique via le chemin d'inférence Hugging Face Transformers documenté. Le wrapper ne réimplémente pas le modèle, le prétraitement des images ou le décodage.

Surface exécutable exacte

Pour les smoke tests en mode commande et les fixtures JSON, utilisez exactement ce chemin de wrapper depuis la racine du repo :

python skills/nv-reason-cxr/scripts/run_nv_reason_cxr.py PATH_TO_CXR_OR_FIXTURE --mock --out-dir OUT_DIR

Pour l'inférence d'images en direct, omettez --mock uniquement si l'utilisateur demande l'inférence du modèle en direct. N'inventez pas les commandes Medical AI Skills run, eval_engine/run.py, infer.py ou python -m nv_reason_cxr pour les exécutions utilisateur ordinaires.

Préconditions

Installez les dépendances d'inférence dans l'environnement qui exécutera la skill :

pip install torch==2.7.1 torchvision==0.22.1 transformers==4.56.1 Pillow

Les poids du modèle sont chargés depuis nvidia/NV-Reason-CXR-3B via Transformers. Ils peuvent être téléchargés au cache Hugging Face à la première utilisation. Définissez TRANSFORMERS_OFFLINE=1 ou passez --local-files-only seulement après que les poids sont déjà en cache.

CUDA est attendu pour l'inférence pratique. L'exécution sur CPU peut fonctionner pour les petits tests mais est lente et doit être explicitement demandée.

Vérifiez l'environnement local avant de télécharger les poids ou d'exécuter l'inférence :

python skills/nv-reason-cxr/scripts/run_nv_reason_cxr.py --check-setup

Le rapport de configuration vérifie les dépendances importables, la visibilité de CUDA, l'état du cache Hugging Face, et la prochaine étape recommandée.

Variables d'environnement opérationnelles :

Licence

Le code du référentiel en amont est Apache-2.0. Les poids du modèle sont publiés sous la licence NVIDIA OneWay Noncommercial License Agreement. Les utilisateurs sont responsables de la conformité aux conditions des poids du modèle avant l'inférence en direct.

Utilisation

À partir de la racine du repo Medical AI Skills :

python skills/nv-reason-cxr/scripts/run_nv_reason_cxr.py PATH_TO_CXR.png \
  --prompt "Find abnormalities and support devices." \
  --out-dir runs/nv_reason_cxr_case

Utilisez le script wrapper directement pour les commandes générées par l'agent. Ne le remplacez pas par eval_engine/run.py sauf si l'utilisateur demande explicitement d'exécuter le harnais d'évaluation. Ne redirigez pas stdout avec > dans les commandes générées : les appelants et le harnais d'évaluation lisent le JSON stdout du wrapper, y compris output.response_text, pour vérifier l'exécution. La surface exécutable directe est :

python skills/nv-reason-cxr/scripts/run_nv_reason_cxr.py PATH_TO_CXR_OR_FIXTURE \
  --mock \
  --out-dir runs/nv_reason_cxr_case

PATH_TO_CXR_OR_FIXTURE peut être une image PNG/JPEG ou une fixture JSON. Si l' utilisateur fournit une requête JSON comme runs/.../synthetic_cxr_input.json, passez ce chemin JSON exact en premier argument. Le script chargera les fixtures generated://synthetic_chest_xray, créera le PNG temporaire dans le répertoire de sortie, et émettra du JSON avec output.response_text. Utilisez --mock uniquement pour les smoke tests en mode commande ou les fixtures qui demandent le mode mock ; omettez --mock pour l'inférence du modèle en direct.

Pour l'entrée JPEG :

python skills/nv-reason-cxr/scripts/run_nv_reason_cxr.py PATH_TO_CXR.jpg \
  --prompt "Describe the chest X-ray findings." \
  --out-dir runs/nv_reason_cxr_case

Drapeaux :

• --model-id — id du modèle Hugging Face, par défaut nvidia/NV-Reason-CXR-3B.
• --device auto|cuda|cpu — par défaut auto, utilisant CUDA quand disponible.
• --allow-cpu — requis pour l'inférence CPU en direct ; les exécutions CPU peuvent être très lentes.
• --torch-dtype auto|float16|bfloat16|float32 — par défaut auto, utilisant bfloat16 sur CUDA et float32 sur CPU, correspondant au modèle BF16 publié.
• --max-new-tokens — plafond de génération, par défaut 2048.
• --local-files-only — utiliser uniquement les ressources Hugging Face en cache local.
• --mock — réponse de test sec déterministe pour l'IC et les vérifications de câblage.
• --prompt-preset findings|comprehensive|educational|structured — présets de prompt connus et validés optionnels à partir du comportement de la carte du modèle/démo.

Le chemin en direct local testé utilise :

• AutoModelForImageTextToText.from_pretrained(..., dtype=torch.bfloat16).eval().to("cuda")
• AutoProcessor.from_pretrained(..., use_fast=True)
• Entrée d'image PNG/JPEG plus un prompt texte
• max_new_tokens=2048 par défaut

Le script émet du JSON sur stdout et n'écrit aucun fichier de rapport clinique. Il enregistre les métadonnées de l'image d'entrée, le prompt, l'id du modèle, le mode runtime, le texte de réponse et les limitations connues. Si runtime.truncated_by_max_new_tokens est true, réexécutez avec une valeur --max-new-tokens plus élevée.

Smoke test avec fixture

La fixture validée utilise un PNG synthétique généré et le mode mock afin que le harnais d'évaluation puisse vérifier le wrapper sans télécharger les poids :

python eval_engine/run.py skills/nv-reason-cxr \
  --fixture skills/nv-reason-cxr/fixtures/synthetic_cxr_input.json \
  --out runs/nv_reason_cxr_smoke

Limites

Ceci est un outil de recherche et d'ingénierie uniquement. Il n'est pas validé pour le diagnostic clinique, les décisions de traitement, le triage, les rapports destinés aux patients ou l'utilisation réglementaire. Les sorties du modèle peuvent halluciner, manquer des observations subtiles ou surestimer l'incertitude. Un professionnel qualifié doit examiner toute utilisation dans un flux de travail médical.