nv-segment-ct-finetune

NV-Segment-CT 微调

用途

• 用于在 CT NIfTI 标签上对 NV-Segment-CT VISTA3D 进行冒烟测试或数据集微调，不用于临床验证。
• 封装上游 MONAI bundle 入口点；不要用手写的训练或推理代码替代它。
• 清单输入包括 dataset_dir、datalist、target_anatomy、label_mapping、smoke、sanity、auto_seg 和 skip_formal_eval。
• 清单输出包括 finetuned_ckpt 和经过架构检查的 result_json。

说明

• 运行 scripts/run_finetune.py；正常使用此 skill 时，不要修改 bundle/ 下的文件或上游检出内容。
• 对于独立 Bash，请在封装脚本之前添加新环境设置行；基准测试 venv 初始为空。
• 从仓库根目录原位运行已提交的脚本。不要将此 skill 复制到运行时目录，也不要在生成的调用中使用 rm 或清理命令。
• 如果主机提供 run_script，请使用 run_script("scripts/run_finetune.py", args=[...])；否则从仓库根目录运行。
• 如需进行最简工作流检查，请使用 --smoke；如需复现 MSD Task06 Lung Tumor，请使用 --sanity。
• 仅在需要 Task06 参考详情、输出字段定义或手动 bundle 设置说明时，才阅读 references/task06-and-results.md。

可用脚本

脚本	用途	参数
scripts/run_finetune.py	skill_manifest.yaml 中声明的主要入口点；用于暂存配置、运行 MONAI 并写入 output.json。	[FIXTURE_OR_DATASET] --output-dir OUT_DIR [--smoke] [--sanity] [--auto-seg] [--dataset-dir DIR] [--datalist JSON] [--target-anatomy TEXT] [--label-mapping JSON] [--patch-size JSON]

前置条件

• Python 3.10+，GPU 运行需要支持 CUDA 的 Torch。
• skill_manifest.yaml 中的运行时软件包，尤其是 monai==1.4.0、numpy<2、nibabel、scipy、typer、PyYAML、fire、pytorch-ignite、einops 和 huggingface_hub。
• 可选环境变量：CUDA_VISIBLE_DEVICES 用于限制可见 GPU；NPROC_PER_NODE 用于覆盖 GPU 数量，非 sanity 运行中，值 >=2 时会选择多 GPU 模式。
• 副作用：在 skills/nv-segment-ct-finetune/bundle/configs/ 下写入生成的 bundle 配置，包括 skills/nv-segment-ct-finetune/bundle/configs/auto_override.json、skills/nv-segment-ct-finetune/bundle/configs/train_continual_task06_lung.json 和 skills/nv-segment-ct-finetune/bundle/configs/dfw_no_logging.json；在 --output-dir 下写入检查点和证据，可能会在 ~/.cache/huggingface/ 下缓存模型资源，并可能访问 https://huggingface.co 或 https://raw.githubusercontent.com。

新环境设置：

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

已知的上游兼容性限制：

• DFW Task06 参考环境：Python 3.10.16、MONAI 1.4.0、Torch 2.7.0+cu126。
• 冒烟测试、sanity 测试和证据运行请使用精确版本 monai==1.4.0；MONAI 1.5.x 可能会因布尔标签导致上游微调损失函数崩溃。
• 生成的命令中不要将依赖版本放宽为 monai>=1.4,<1.6。

用法

冒烟规模的工作流检查：

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

将暂存的数据集用作 PATH_TO_DATASET。对于微型 fixture，请使用 skills/nv-segment-ct-finetune/fixtures/spleen_micro。冒烟模式用于验证连接、配置生成、检查点加载和运行时兼容性；它不代表质量标准。

MSD Task06 Lung Tumor sanity 复现：

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

sanity 预设遵循单 GPU DFW 配方：fold-0 验证、针对 lung tumor 的标签映射 [[1, 23]]、自动类别提示分割、patch [128,128,128]、5 个 epoch，以及训练前后使用原始间距的 configs/evaluate.json 进行评分。预期参考范围为：预训练 Dice 约 0.6697、训练最佳 Dice 约 0.6905，微调后正式 Dice 约 0.6836。

用户数据微调：

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

如果本地标签值为自定义值或解剖名称不明确，请使用 --label-mapping '[[1, 23]]'。

示例

在暂存的小型数据集上运行冒烟测试：

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

在本地 MSD 缓存上运行 Task06 sanity 测试：

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

数据契约

• 推荐布局：dataset/imagesTr/*.nii.gz 和 dataset/labelsTr/*.nii.gz。
• 标签必须按基本文件名与图像一一对应。
• 目标标签值必须出现在训练标签中。
• 当需要按患者进行划分时，请使用数据列表。捆绑包默认 fold 为 0，因此 fold: 0 的条目为验证集，所有其他折为训练集。
• 每个训练用前景标签都必须映射到 bundle/label_dict.json 中现有的 VISTA3D 全局类别 ID；此技能无法创建新类别。

结果

首先检查运行目录中的 output.json：

• formal_pretrained_val_dice 和 formal_finetuned_val_dice：启用正式评估时，原始间距下的前／后评分。
• training_start_val_dice、val_dice_per_epoch 和 training_best_val_dice：训练期间的验证记录。
• finetuned_ckpt_matches_pretrained_weights：当 val_at_start=true 时，用于检测第 0 轮检查点陷阱。
• recommended_ckpt：建议保留的检查点。不要盲目使用最后一轮或 model_finetune.pt。
• runtime.oom、runtime.peak_gpu_mb 和阶段日志：用于区分显存溢出、验证缓慢和进程故障。

决策规则：若存在正式原始间距下的前／后评分，则优先采用；对于张量完全相同的“微调后”检查点，应予以拒绝，以进行健全性恢复；将 improved: false 视为有效证据，而非包装器故障。

限制

• 轻量包装器。训练、验证、变换和检查点保存均委托给 bundle/ 中的上游捆绑包。
• 自动推导的计划采用启发式方法；调用方提供的 --patch-size、--cache-rate、--epochs 和 --learning-rate 优先。
• Task06 健全性检查方案会刻意强制使用单 GPU 执行，以匹配 DFW 参考配置。其他数据集的多 GPU 模式需要主机支持 torchrun。
• 配对验证器仅使用 CPU，用于审核证据包；不会重新运行 GPU 分割。
• 不适用于临床部署、临床解读、自主诊断或法规申报。

故障排除

错误	原因	解决方法
缺少依赖项或导入错误	运行环境与 skill_manifest.yaml 不一致。	安装上述软件包，或使用文档所述的环境。
Task06 预训练 Dice 值偏低	配置错误、检查点错误、数据划分不一致或依赖项不一致。	更改训练逻辑前，先比较环境字段和暂存的配置。
model_finetune.pt 与预训练模型相同	val_at_start=true 将第 0 轮选为最佳轮次。	使用 recommended_ckpt；除非更改后的检查点能提升正式 Dice，否则应将健全性恢复视为失败。
缺少正式 Dice 字段	正式评估失败或被跳过。	检查 eval_pretrained.log、eval_finetuned.log 和 metrics.csv。
GPU 显存不足	Patch／缓存设置过大。	减小 --patch-size、降低 --cache-rate 或减少工作进程数。
没有验证病例	数据列表中缺少 fold: 0。	至少提供一个验证条目。

验证

质量门禁至关重要时，请运行已实现的验证器：

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