NV-Segment-CT Finetune

Objectif

• Utilisé pour l'ajustement fin (finetune) ou le smoke test du dataset NV-Segment-CT VISTA3D sur les labels CT NIfTI. Non destiné à la validation clinique.
• Encapsule le point d'entrée du bundle MONAI en amont ; ne le remplacez pas par du code d'entraînement ou d'inférence écrit à la main.
• Les entrées du manifest sont dataset_dir, datalist, target_anatomy, label_mapping, smoke, sanity, auto_seg et skip_formal_eval.
• Les sorties du manifest sont finetuned_ckpt et result_json vérifié par schéma.

Instructions

• Exécutez scripts/run_finetune.py ; ne modifiez pas les fichiers sous bundle/ ou les checkouts en amont lors d'une utilisation normale du skill.
• Pour un Bash autonome, incluez la ligne de configuration d'environnement frais avant le wrapper ; les venv de benchmark commencent vides.
• Exécutez le script commité en place depuis la racine du repo. Ne copiez pas ce skill dans un répertoire runtime, et n'utilisez pas de commandes rm ou de nettoyage dans les invocations générées.
• Si un hôte expose run_script, utilisez run_script("scripts/run_finetune.py", args=[...]); sinon exécutez depuis la racine du repo.
• Pour la vérification de flux de travail la plus courte, utilisez --smoke ; pour la reproduction de la Tâche 06 Lung Tumor du MSD, utilisez --sanity.
• Consultez references/task06-and-results.md uniquement quand vous avez besoin des détails de référence Task06, des définitions de champs de sortie ou des notes de configuration du bundle manuel.

Scripts disponibles

Prérequis

• Python 3.10+ avec Torch compatible CUDA pour les exécutions GPU.
• Packages runtime depuis skill_manifest.yaml, notamment monai==1.4.0, numpy<2, nibabel, scipy, typer, PyYAML, fire, pytorch-ignite, einops et huggingface_hub.
• Variables d'environnement optionnelles : CUDA_VISIBLE_DEVICES restreint les GPU visibles ; NPROC_PER_NODE remplace le nombre de GPU et les valeurs >=2 sélectionnent le mode multi-GPU pour les exécutions non-sanity.
• Effets secondaires : écrit les configs du bundle générés sous skills/nv-segment-ct-finetune/bundle/configs/, notamment skills/nv-segment-ct-finetune/bundle/configs/auto_override.json, skills/nv-segment-ct-finetune/bundle/configs/train_continual_task06_lung.json et skills/nv-segment-ct-finetune/bundle/configs/dfw_no_logging.json ; écrit les checkpoints/preuves sous --output-dir, peut mettre en cache les assets du modèle sous ~/.cache/huggingface/ et peut contacter https://huggingface.co ou https://raw.githubusercontent.com.

Configuration d'environnement frais :

python -m pip install "monai==1.4.0" "numpy<2" pytorch-ignite einops nibabel scipy typer PyYAML fire huggingface_hub

Contraintes de compatibilité amont connues :

• Référence DFW Task06 : Python 3.10.16, MONAI 1.4.0, Torch 2.7.0+cu126.
• Utilisez monai==1.4.0 exact pour les smoke, sanity et evidence runs ; MONAI 1.5.x peut planter la perte d'ajustement fin en amont sur les labels booléens.
• Ne flottez pas la dépendance comme monai>=1.4,<1.6 dans les commandes générées.

Utilisation

Vérification de flux de travail à l'échelle smoke :

python -m pip install "monai==1.4.0" "numpy<2" pytorch-ignite einops nibabel scipy typer PyYAML fire huggingface_hub && \
python skills/nv-segment-ct-finetune/scripts/run_finetune.py \
  PATH_TO_DATASET \
  --smoke \
  --patch-size '[64,64,64]' \
  --output-dir runs/nvseg_smoke

Utilisez le dataset préparé comme PATH_TO_DATASET. Pour la micro fixture, utilisez skills/nv-segment-ct-finetune/fixtures/spleen_micro. Le mode smoke prouve le câblage, la génération de config, le chargement de checkpoint et la compatibilité runtime ; ce n'est pas un critère de qualité.

Reproduction de sanity Lung Tumor MSD Task06 :

python skills/nv-segment-ct-finetune/scripts/run_finetune.py \
  /path/to/Task06 \
  --sanity \
  --output-dir runs/nvseg_task06_sanity

Le preset sanity suit la recette DFW mono-GPU : validation fold-0, mapping label [[1, 23]] pour lung tumor, segmentation par classe-prompt automatique, patch [128,128,128], 5 epochs et scoring à espacement original dans configs/evaluate.json avant et après l'entraînement. La plage de référence attendue est Dice pré-entraîné environ 0.6697, Dice meilleur entraînement environ 0.6905 et Dice formel ajusté fin environ 0.6836.

Ajustement fin sur données utilisateur :

python skills/nv-segment-ct-finetune/scripts/run_finetune.py \
  --dataset-dir /path/to/dataset \
  --datalist /path/to/datalist.json \
  --target-anatomy "lung tumor" \
  --auto-seg \
  --epochs 5 \
  --patch-size '[128,128,128]' \
  --output-dir runs/nvseg_user_finetune

Utilisez --label-mapping '[[1, 23]]' quand les valeurs de label locales sont personnalisées ou que le nom d'anatomie est ambigu.

Exemples

Smoke run sur un tiny dataset préparé :

python skills/nv-segment-ct-finetune/scripts/run_finetune.py \
  runs/with_vs_without_nv/_inputs/nv_segment_ct_finetune/input_dataset \
  --smoke \
  --patch-size '[64,64,64]' \
  --output-dir runs/nvseg_smoke

Task06 sanity run sur un cache MSD local :

python skills/nv-segment-ct-finetune/scripts/run_finetune.py \
  .workbench_data/datasets/Task06_Lung \
  --sanity \
  --output-dir runs/nvseg_task06_sanity

Contrat de données

• Layout préféré : dataset/imagesTr/*.nii.gz et dataset/labelsTr/*.nii.gz.
• Les labels doivent s'aligner un-à-un avec les images par basename.
• La valeur du label cible doit être présente dans les labels d'entraînement.
• Utilisez un datalist quand la division au niveau patient importe. Le fold par défaut du bundle est 0, donc les entrées fold: 0 sont pour la validation et tous les autres folds pour l'entraînement.
• Chaque label foreground entraîné doit mapper vers un ID de classe global VISTA3D existant depuis bundle/label_dict.json ; ce skill ne peut pas inventer une nouvelle classe.

Résultats

Vérifiez d'abord output.json dans le répertoire d'exécution :

• formal_pretrained_val_dice et formal_finetuned_val_dice : scores pré/post à espacement original quand l'évaluation formelle est activée.
• training_start_val_dice, val_dice_per_epoch et training_best_val_dice : trace de validation au moment de l'entraînement.
• finetuned_ckpt_matches_pretrained_weights : détecte le piège epoch-0 quand val_at_start=true.
• recommended_ckpt : checkpoint à conserver. N'utilisez pas aveuglément le dernier epoch ou model_finetune.pt.
• runtime.oom, runtime.peak_gpu_mb et logs de phase : distinguent OOM, validation lente et échec de processus.

Règle de décision : préférez les scores formels pré/post à espacement original quand présents ; rejetez les checkpoints "ajustés fins" tenseur-identiques pour la récupération sanity ; traitez improved: false comme une preuve valide plutôt qu'un échec du wrapper.

Limitations

• Wrapper fin. L'entraînement, la validation, les transformations et le checkpointing sont délégués au bundle en amont dans bundle/.
• Le plan auto-dérivé est heuristique ; les --patch-size, --cache-rate, --epochs et --learning-rate fournis par l'appelant gagnent.
• La recette sanity Task06 force intentionnellement l'exécution mono-GPU pour correspondre à la référence DFW. Le mode multi-GPU pour d'autres datasets nécessite le support torchrun de l'hôte.
• Le vérificateur jumelé est CPU-only et audite le pack de preuve ; il ne relance pas la segmentation GPU.
• Non destiné au déploiement clinique, à l'interprétation clinique, au diagnostic autonome ou à la soumission réglementaire.

Dépannage

Vérification

Exécutez le vérificateur implémenté quand les quality gates importent :

python -m eval_engine.run_trusted skills/nv-segment-ct-finetune \
  --fixture skills/nv-segment-ct-finetune/fixtures/spleen_micro \
  --out runs/nvseg_trusted