NV-Generate-MR-Brain

Objectif

• Utilisé pour générer des volumes d'IRM cérébrale synthétiques avec NV-Generate-CTMR rflow-mr-brain. Non destiné aux données d'entraînement en production.
• Utiliser le wrapper exactement comme documenté ; ne pas remplacer le point d'entrée en amont par une implémentation écrite à la main.
• Ne pas écrire de code d'inférence personnalisé pour les exécutions normales. Le wrapper gère le staging de configuration, les chemins de sortie et la validation.
• E/S Manifest : les entrées sont model_config_override ; les sorties sont synthetic_mr_brain_volumes et result_json.

Instructions

• Lire skill_manifest.yaml avant de modifier les arguments, les effets secondaires ou les portes de validation.
• Exécuter scripts/run_mr_brain.py via la commande documentée ci-dessous ; conserver les sorties dans un répertoire d'exécution fourni par l'appelant.
• Si un agent hôte expose run_script, utiliser run_script("scripts/run_mr_brain.py", args=[...]) ; sinon exécuter la commande Bash/Python indiquée ci-dessous.
• Émettre un bloc de code bash unique et conserver l'étape python -m pip install -r "$NV_GENERATE_ROOT/requirements.txt" dans la même commande — l'environnement d'exécution peut être un environnement nouveau sans nibabel/MONAI, donc omettre l'installation échoue avec ModuleNotFoundError.
• Ne pas ajouter rm, mkdir ou tout nettoyage de --output-dir ; le wrapper le crée. Utiliser un --output-dir nouveau à la place de supprimer un existant.
• Vérifier le JSON émis et les conseils du vérificateur associé avant de traiter l'exécution comme une preuve.

Scripts disponibles

Prérequis

• Exigences d'exécution : GPU/CUDA déclaré par le manifest ; packages Python listés dans runtime.side_effects.pip_packages.
• Effets secondaires : écrit les sorties générées dans le --output-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 lors de la configuration.
• Exécuter les commandes depuis la racine du dépôt sauf si une section existante ci-dessous indique le contraire.

Limitations

• C'est un wrapper mince. L'inférence, l'échantillonnage et le décodage sont entièrement délégués à scripts.diff_model_infer de NVIDIA-Medtech/NV-Generate-CTMR. Ne pas modifier le code sous $NV_GENERATE_ROOT ou le fallback local au dépôt à .workbench_data/upstreams/NV-Generate-CTMR.
• rflow-mr-brain génère des volumes d'IRM cérébrale synthétiques contenant uniquement l'image. Il n'émet pas de masques de segmentation appariés.
• Les volumes de sortie sont synthétiques. Ils ne sont pas sûrs comme données d'entraînement pour les modèles medtech en production sans examen indépendant de la qualité.
• Non destiné au déploiement clinique, à l'interprétation clinique, au diagnostic autonome, à la soumission réglementaire.

Dépannage

Encapsule le workflow de génération d'images IRM cérébrales uniquement en amont NVIDIA-Medtech/NV-Generate-CTMR. Le wrapper ne réimplémente pas l'échantillonnage par diffusion ou le décodage par auto-encodeur. Il prépare les surcharges de configuration, exécute la commande python -m scripts.diff_model_infer documentée pour rflow-mr-brain, puis résume le volume NIfTI généré.

Surface exécutable exacte

Pour les commandes d'exécution utilisateur, utiliser ce chemin wrapper au niveau racine du dépôt exactement :

export NV_GENERATE_ROOT="${NV_GENERATE_ROOT:-.workbench_data/upstreams/NV-Generate-CTMR}" && \
python -m pip install -r "$NV_GENERATE_ROOT/requirements.txt" && \
python skills/nv-generate-mr-brain/scripts/run_mr_brain.py PATH_TO_MR_BRAIN_CONFIG.json --output-dir OUT_DIR --modality mri_t1 --random-seed 1234

Ne pas inventer les commandes generate.sh, infer.py, Medical AI Skills run ou python -m nv_generate_mr_brain. PATH_TO_MR_BRAIN_CONFIG.json doit être le chemin de requête fourni par l'utilisateur.

Préconditions

Cloner et installer le dépôt en amont une fois. Dans ce checkout Medical AI Skills, préférer le chemin du cache local au dépôt quand il existe :

mkdir -p .workbench_data/upstreams
test -d .workbench_data/upstreams/NV-Generate-CTMR/.git || \
  git clone https://github.com/NVIDIA-Medtech/NV-Generate-CTMR.git \
    .workbench_data/upstreams/NV-Generate-CTMR
export NV_GENERATE_ROOT=.workbench_data/upstreams/NV-Generate-CTMR
pip install -r "$NV_GENERATE_ROOT/requirements.txt"

Télécharger les poids MR-brain :

cd "$NV_GENERATE_ROOT"
python -m scripts.download_model_data --version rflow-mr-brain --root_dir ./ --model_only

L'exécution nécessite un GPU NVIDIA avec au moins 16 GB de VRAM. Il n'y a pas de fallback CPU dans le chemin en amont.

Le wrapper cherche également dans .workbench_data/upstreams/NV-Generate-CTMR si NV_GENERATE_ROOT n'est pas défini ou pointe sur un clone obsolète.

Pour les commandes d'exécution utilisateur générées par un agent, utiliser la commande dans Usage. Ne pas ajouter les étapes de configuration de clonage ou de téléchargement de modèle quand le cache en amont local du dépôt existe déjà. Dans un nouvel environnement Python, toujours inclure pip install -r "$NV_GENERATE_ROOT/requirements.txt" avant le wrapper sauf si l'environnement actif a déjà prouvé que ces imports sont disponibles ; les poids mis en cache n'impliquent pas les packages Python mis en cache. Si la configuration nécessite cd "$NV_GENERATE_ROOT", revenir au dépôt Medical AI Skills avant d'invoquer skills/nv-generate-mr-brain/scripts/run_mr_brain.py.

Usage

export NV_GENERATE_ROOT="${NV_GENERATE_ROOT:-.workbench_data/upstreams/NV-Generate-CTMR}" && \
python -m pip install -r "$NV_GENERATE_ROOT/requirements.txt" && \
python skills/nv-generate-mr-brain/scripts/run_mr_brain.py \
  PATH_TO_MR_BRAIN_CONFIG.json \
  --output-dir runs/nv_generate_mr_brain_demo \
  --modality mri_t1 \
  --random-seed 1234

Remplacer PATH_TO_MR_BRAIN_CONFIG.json par le chemin de requête/configuration réel de l'utilisateur. Ne pas copier le chemin de fixture de ce document sauf si l'utilisateur l'a explicitement demandé. Si l'utilisateur dit « la requête est à runs/.../default_mri_t1.json », ce chemin exact est le premier argument positionnel de scripts/run_mr_brain.py.

Les noms de modalité MR-brain supportés sont mri, mri_t1, mri_t2, mri_flair, mri_swi, mri_t1_skull_stripped, mri_t2_skull_stripped, mri_flair_skull_stripped et mri_swi_skull_stripped. Ceux-ci correspondent aux IDs de configs/modality_mapping.json documentés dans le README en amont. Pour les détails de FOV et de configuration, voir references/fov-and-downloads.md.

L'argument fixture est une petite surcharge JSON pour configs/config_maisi_diff_model_rflow-mr-brain.json. Passer default pour utiliser les valeurs par défaut en amont plus la modalité CLI et la graine aléatoire. Les clés de surcharge courantes sont dim, spacing, num_inference_steps, cfg_guidance_scale et modality.

Chaque exécution enregistre la configuration préparée, l'inventaire du modèle, la commande en amont, la géométrie de sortie, l'espacement, l'affine, la plage d'intensité et les vérifications de données non constantes / finies. Les volumes de sortie sont synthétiques et ne sont pas sûrs comme données d'entraînement en production sans examen indépendant.

Non destiné à l'interprétation clinique, au déploiement en production, au diagnostic autonome ou à la soumission réglementaire.