nv-segment-ct-finetune

NV-Segment-CT 微调

用途

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

使用说明

• 仅运行调用方请求的预设、数据集、输出目录和计算预算。设置依赖项和远程跟踪需要获得调用方批准。报告结果后即停止；后续训练、发布或部署均需单独请求。
• 运行 scripts/run_finetune.py；正常使用本技能时，不要修改 bundle/ 下的文件或上游检出内容。
• 对于独立的 Bash 调用，请在包装脚本之前加入全新的环境设置行；基准测试虚拟环境初始为空。
• 从仓库根目录原地运行已提交的脚本。不要将此技能复制到运行时目录，也不要在生成的调用中使用 rm 或清理命令。
• 如果宿主提供 run_script，请使用 run_script("scripts/run_finetune.py", args=[...])；否则从仓库根目录运行。
• 如需进行最简工作流检查，请使用 --smoke；如需复现 MSD Task06 Lung Tumor，请使用 --sanity。
• 根据下方标准，在标准工作流和 --softmax 工作流之间进行选择。不要将 --softmax 与 --auto-seg 或 --sanity 组合使用。
• 设置 --mlflow-experiment-name，即可在任一工作流的训练阶段启用 MLflow。--mlflow-tracking-uri 和 --mlflow-run-name 需要实验名称。正式的训练前／训练后评估不会获得 MLflow 凭据。
• 仅在需要 Task06 参考详情、输出字段定义或手动设置 bundle 的说明时，才阅读 references/task06-and-results.md。

工作流选择

仅当满足以下所有条件时，才使用 --softmax：

• 完整的类别集合在训练前已知，且不会因推理请求而变化。
• 标签互斥：每个体素要么是背景，要么恰好属于一个前景类别。
• 每个前景数据集标签都映射到现有的 VISTA3D 类别 ID，且需要传统的固定通道输出。

如果需要保留点提示、推理时动态选择类别、标签可能重叠，或必须复现 Task06 --sanity，请使用标准工作流。

对于 --label-mapping '[[1,3],[2,13]]'，通道 0 是背景，通道 1 表示由 VISTA3D 类别 3 初始化的数据集标签 1，通道 2 表示由 VISTA3D 类别 13 初始化的数据集标签 2。使用生成的 model_softmax.pt 和上游 configs/inference_softmax.json 时，请保留这些条目及其顺序。nv-segment-ct 和 nv-segment-ctmr 推理技能目前尚未提供该固定通道推理路径。

可用脚本

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

前置条件

• 运行 GPU 任务需要 Python 3.10+ 和支持 CUDA 的 Torch。
• 需要安装 skill_manifest.yaml 中的运行时软件包，尤其是 monai==1.4.0、numpy<2、nibabel、scipy、typer、PyYAML、fire、pytorch-ignite、einops 和 huggingface_hub。启用 MLflow 跟踪时，请安装 mlflow>=2.10,<4。
• 可选环境变量：CUDA_VISIBLE_DEVICES 用于限制可见 GPU；NPROC_PER_NODE 用于覆盖 GPU 数量，非 sanity 运行中，值 >=2 会启用多 GPU 模式；NVSEG_FINETUNE_AUTO_VENV=0 用于禁用缓存的 MONAI 1.4 兼容环境。远程跟踪可能会使用 DATABRICKS_CONFIG_PROFILE、DATABRICKS_HOST、DATABRICKS_TOKEN、MLFLOW_TRACKING_CLIENT_CERT_PATH、MLFLOW_TRACKING_INSECURE_TLS、MLFLOW_TRACKING_PASSWORD、MLFLOW_TRACKING_SERVER_CERT_PATH、MLFLOW_TRACKING_TOKEN 或 MLFLOW_TRACKING_USERNAME；这些变量仅在明确启用 MLflow 时转发，不会转发无关凭据。
• --softmax 还需要已固定版本的 NVIDIA-Medtech 源代码检出目录。将 NV_SEGMENT_CT_ROOT 设置为其 NV-Segment-CT 目录，或将 NV_SEGMENT_CTMR_ROOT 设置为同级的 NV-Segment-CTMR 目录。包装器会就地读取官方 softmax 配置和实现，只在 --output-dir 下写入生成的覆盖配置。
• 运行输出：生成的套件配置位于 skills/nv-segment-ct-finetune/bundle/configs/ 下，包括 auto_override.json、train_continual_task06_lung.json 和 dfw_no_logging.json；检查点和证据位于 --output-dir 下；启用本地跟踪时，跟踪数据位于 <output-dir>/mlruns 下。
• 依赖缓存位置：用于 MONAI 兼容软件包的 ~/.cache/nvidia-skills/venvs/nv-segment-ct-finetune-monai14/，以及用于模型资源的 ~/.cache/huggingface/。这些是可重复使用的运行时文件，不是 Agent 指令，也不代表授权再次运行。若未批准设置兼容环境，请设置 NVSEG_FINETUNE_AUTO_VENV=0；然后使用调用方提供的兼容环境。
• 网络访问：模型和配置下载使用 https://huggingface.co 和 https://raw.githubusercontent.com；明确启用远程跟踪时，仅会联系调用方批准的 MLflow 或 Databricks 目标。标签字典下载仅接受固定源主机上的 HTTPS，并会拒绝重定向。

全新环境设置：

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

启用 MLflow 跟踪时，还需安装：

python -m pip install "mlflow>=2.10,<4"

已知的上游兼容性限制：

• DFW Task06 参考环境：Python 3.10.16、MONAI 1.4.0、Torch 2.7.0+cu126。
• smoke、sanity 和证据运行请使用精确版本 monai==1.4.0；MONAI 1.5.x 可能会因布尔标签导致上游微调损失函数崩溃。
• 生成的命令中，不要将依赖版本范围放宽为 monai>=1.4,<1.6。
• 除非调用方覆盖，softmax 工作流会保留上游默认值：100 个 epoch 和 1e-4 的学习率。

--softmax 的一次性源代码设置：

export NV_SEGMENT_CTMR_COMMIT=cb921f5c58837c0f42a713855d68b32af88e1cdd
export NV_SEGMENT_CTMR_CHECKOUT="$HOME/.cache/nvidia-skills/upstreams/NV-Segment-CTMR-cb921f5"
if [ ! -d "$NV_SEGMENT_CTMR_CHECKOUT/.git" ]; then
  git clone https://github.com/NVIDIA-Medtech/NV-Segment-CTMR.git "$NV_SEGMENT_CTMR_CHECKOUT"
fi
git -C "$NV_SEGMENT_CTMR_CHECKOUT" checkout --detach "$NV_SEGMENT_CTMR_COMMIT"
export NV_SEGMENT_CT_ROOT="$NV_SEGMENT_CTMR_CHECKOUT/NV-Segment-CT"

用法

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

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

MSD Task06 Lung Tumor 合理性复现：

python skills/nv-segment-ct-finetune/scripts/run_finetune.py \
  /path/to/Task06 \
  --sanity \
  --output-dir runs/nvseg_task06_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]]'。

可选的本地 MLflow 跟踪：

python skills/nv-segment-ct-finetune/scripts/run_finetune.py \
  --dataset-dir /path/to/dataset \
  --datalist /path/to/datalist.json \
  --target-anatomy "lung tumor" \
  --epochs 5 \
  --mlflow-experiment-name nvseg-finetune \
  --mlflow-run-name trial-01 \
  --output-dir runs/nvseg_mlflow

此功能使用 MONAI 文档所述的 --tracking mlflow 路径和内置的 rank-zero 处理器。如果未提供 --mlflow-tracking-uri，数据将保存在 <output-dir>/mlruns。仅当需要远程跟踪时，才传入调用方批准的远程 URI，包括 databricks。MLflow 不会更改 patch 大小、变换、优化器值、DataLoader 设置或其他训练配置。

用于互斥标签的固定通道 softmax 微调：

export NV_SEGMENT_CT_ROOT="$HOME/.cache/nvidia-skills/upstreams/NV-Segment-CTMR-cb921f5/NV-Segment-CT"
python skills/nv-segment-ct-finetune/scripts/run_finetune.py \
  --dataset-dir /path/to/dataset \
  --datalist /path/to/datalist.json \
  --label-mapping '[[1,3],[2,13]]' \
  --softmax \
  --epochs 100 \
  --output-dir runs/nvseg_softmax

此功能委托给上游 configs/train_continual_softmax.json。它会生成 checkpoints/model_softmax.pt；源 model.pt 用于初始化网络， 但与 configs/inference_softmax.json 不兼容。因此，成功运行后，封装程序 会建议使用生成的 softmax 检查点。

示例

在暂存的微型数据集上运行 Smoke：

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 合理性检查：

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 条目用于验证，其余所有 fold 用于训练。
• 每个训练前景标签都必须映射到 bundle/label_dict.json 中现有的 VISTA3D 全局类别 ID；此技能无法创建新类别。
• 在 --softmax 模式下，映射的第一列是保存的数据集标签，第二列是预训练的 VISTA 类别 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 时出现的 epoch-0 检查点陷阱；softmax 使用不同的检查点架构。
• recommended_ckpt：根据记录的工作流和指标生成的检查点建议。选择检查点前请检查这些记录；仅凭最后一个 epoch 或文件名不能证明有所改进。请将建议报告给调用方；部署不在此技能的范围内。
• invocation.mlflow_tracking：所选跟踪 URI、实验名称和可选运行名称；禁用跟踪时为 null。
• runtime.oom、runtime.peak_gpu_mb 和阶段日志：用于区分 OOM、验证缓慢和进程失败。

决策规则：存在正式原始间距的训练前／后分数时，优先参考这些分数；排除张量与预训练权重完全相同的“微调”检查点，以恢复合理性检查；将 improved: false 视为有效证据，而非封装程序故障。

局限性

• 轻量封装。训练、验证、变换和检查点保存均委托给上游 bundle/ 中的内容。
• 张量比较使用受限的 weights_only=True 检查点加载。遇到不支持的序列化对象时会产生比较错误；不会重试不受限的 pickle 加载。此比较并非对上游训练／检查点加载器进行安全审计。
• 仅作为复现记录：成功运行五个 epoch 的 Task06 使用了 Python 3.12.3、PyTorch 2.12.0+cu130（CUDA 13.0）、MONAI 1.4.0、NumPy 1.26.4、PyTorch-Ignite 0.5.4、NiBabel 5.4.2、SciPy 1.16.0、einops 0.8.2、Fire 0.7.1、Hugging Face Hub 0.36.2、Transformers 4.57.6、 Typer 0.25.1、PyYAML 6.0.3 和 MLflow 3.14.0，运行于一块 NVIDIA RTX 6000 Ada 48 GB GPU 上。这些版本用于记录实证环境；它们不是额外的包约束，也不代表其他版本无法运行。
• 自动推导的计划采用启发式方法；调用方提供的 --patch-size、--cache-rate、--epochs 和 --learning-rate 优先。
• --softmax 与 --sanity 不兼容：Task06 参考分数和原始间距的前／后评估属于标准 VISTA3D 持续学习工作流。Softmax 运行会记录训练验证轨迹，但在声称质量达标前，还需要进行单独的特定任务评估。
• Task06 sanity 配方会有意强制使用单 GPU 执行，以匹配 DFW 参考配置。其他数据集的多 GPU 模式需要主机支持 torchrun。
• 配对验证器仅使用 CPU，用于审核证据包；不会重新运行 GPU 分割。
• MLflow 支持为可选功能，并使用 MONAI 内置的跟踪处理器。跟踪错误属于上游 MONAI 运行的一部分，因此可能导致微调命令失败。
• 不用于临床部署、临床解读、自主诊断或监管申报。

故障排查

错误	原因	修复方法
缺少依赖项或导入错误	运行环境与 skill_manifest.yaml 不一致。	安装上述软件包，或使用文档记录的环境。
Task06 预训练 Dice 较低	配置错误、检查点错误、数据划分发生偏差，或依赖项发生偏差。	在更改训练逻辑之前，比较环境字段和暂存的配置。
model_finetune.pt 与预训练模型一致	val_at_start=true 将 epoch 0 选为最佳 epoch。	使用 recommended_ckpt；除非更改后的检查点能提升正式 Dice，否则应视 sanity 恢复失败。
缺少正式 Dice 字段	正式评估失败或被跳过。	检查 eval_pretrained.log、eval_finetuned.log 和 metrics.csv。
GPU 显存不足	Patch／缓存设置过大。	减小 --patch-size、降低 --cache-rate，或减少工作进程数。
没有验证用例	Datalist 缺少 fold: 0。	至少提供一个验证条目。
--softmax requires the pinned ... checkout	缺少 August softmax 配置／实现，或检出的提交不同。	检出 cb921f5c58837c0f42a713855d68b32af88e1cdd，并设置 NV_SEGMENT_CT_ROOT 或 NV_SEGMENT_CTMR_ROOT。
MLflow 跟踪失败	未安装 MLflow、凭据无效，或无法访问该实验。	检查 finetune.log，修复 MLflow 客户端配置后重新运行；省略 --mlflow-experiment-name 可禁用跟踪。

验证

当质量门槛很重要时，请运行已实现的验证器：

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