nv-segment-ct-finetune

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

NV-Segment-CT Finetune

NV-Segment-CT 微调

Purpose

用途

Used for smoke or dataset finetuning of NV-Segment-CT VISTA3D on CT NIfTI labels. Not for clinical validation.
Wraps the upstream MONAI bundle entrypoint; do not replace it with handwritten training or inference code.

Manifest inputs are

dataset_dir

datalist

target_anatomy

label_mapping

smoke

sanity

auto_seg

, and

skip_formal_eval

Manifest outputs are
```
finetuned_ckpt
```
and schema-checked
```
result_json
```
.

用于在CT NIfTI标签上对NV-Segment-CT VISTA3D进行冒烟测试或数据集微调。不用于临床验证。
封装上游MONAI bundle入口点；请勿用手写训练或推理代码替代它。

清单输入项包括

dataset_dir

、

datalist

、

target_anatomy

、

label_mapping

、

smoke

、

sanity

、

auto_seg

和

skip_formal_eval

。

清单输出项包括
```
finetuned_ckpt
```
和经过 schema 校验的
```
result_json
```
。

Instructions

操作说明

Run
```
scripts/run_finetune.py
```
; do not patch files under
```
bundle/
```
or upstream checkouts during normal skill use.
For standalone Bash, include the fresh-environment setup line before the wrapper; benchmark venvs start empty.
Run the committed script in place from the repo root. Do not copy this skill to a runtime directory, and do not use
```
rm
```
or cleanup commands in generated invocations.

If a host exposes

run_script

, use

run_script("scripts/run_finetune.py", args=[...])

; otherwise run from the repo root.

For the shortest workflow check, use
```
--smoke
```
; for MSD Task06 Lung Tumor reproduction, use
```
--sanity
```
.
Read
```
references/task06-and-results.md
```
only when you need Task06 reference details, output-field definitions, or manual bundle setup notes.

运行
```
scripts/run_finetune.py
```
；正常使用该技能期间，请勿修改
```
bundle/
```
下的文件或上游检出内容。
对于独立Bash环境，在执行包装器前需包含新鲜环境设置命令；基准虚拟环境初始为空。
从仓库根目录原地运行已提交的脚本。请勿将此技能复制到运行时目录，且在生成的调用命令中请勿使用
```
rm
```
或清理命令。
如果主机提供
```
run_script
```
函数，请使用
```
run_script("scripts/run_finetune.py", args=[...])
```
；否则从仓库根目录运行。
如需最短流程检查，请使用
```
--smoke
```
参数；如需复现MSD Task06肺部肿瘤任务，请使用
```
--sanity
```
参数。
仅当需要Task06参考细节、输出字段定义或手动bundle设置说明时，才阅读
```
references/task06-and-results.md
```
。

Available Scripts

可用脚本

Script Purpose Arguments

Script	Purpose	Arguments
`scripts/run_finetune.py`	Primary entrypoint declared by `skill_manifest.yaml` ; stages configs, runs MONAI, and writes `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]`

scripts/run_finetune.py

Primary entrypoint declared by

skill_manifest.yaml

; stages configs, runs MONAI, and writes

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]

脚本用途参数

脚本	用途	参数
`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]`

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]

Prerequisites

前置条件

Python 3.10+ with CUDA-capable Torch for GPU runs.

Runtime packages from

skill_manifest.yaml

, especially

monai==1.4.0

numpy<2

nibabel

scipy

typer

PyYAML

fire

pytorch-ignite

einops

, and

huggingface_hub

Optional environment variables:
```
CUDA_VISIBLE_DEVICES
```
restricts visible GPUs;
```
NPROC_PER_NODE
```
overrides GPU count and values
```
>=2
```
select multi-GPU mode for non-sanity runs.

Side effects: writes generated bundle configs under

skills/nv-segment-ct-finetune/bundle/configs/

, including

skills/nv-segment-ct-finetune/bundle/configs/auto_override.json

skills/nv-segment-ct-finetune/bundle/configs/train_continual_task06_lung.json

, and

skills/nv-segment-ct-finetune/bundle/configs/dfw_no_logging.json

; writes checkpoints/evidence under

--output-dir

, may cache model assets under

~/.cache/huggingface/

, and may contact

https://huggingface.co

https://raw.githubusercontent.com

Fresh environment setup:

bash

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

Known upstream compatibility constraints:

DFW Task06 reference: Python
```
3.10.16
```
, MONAI
```
1.4.0
```
, Torch
```
2.7.0+cu126
```
.
Use exact
```
monai==1.4.0
```
for smoke, sanity, and evidence runs; MONAI 1.5.x can crash the upstream finetune loss on boolean labels.
Do not float the dependency as
```
monai>=1.4,<1.6
```
in generated commands.

支持CUDA的Torch环境下的Python 3.10+，用于GPU运行。

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数量，当值
```
>=2
```
时，非sanity运行将启用多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

。

新鲜环境设置命令：

bash

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
```
。

Usage

使用示例

Smoke-scale workflow check:

bash

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

Use the staged dataset as

PATH_TO_DATASET

. For the micro fixture, use

skills/nv-segment-ct-finetune/fixtures/spleen_micro

. Smoke mode proves wiring, config generation, checkpoint loading, and runtime compatibility; it is not a quality bar.

MSD Task06 Lung Tumor sanity reproduction:

bash

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

The sanity preset follows the single-GPU DFW recipe: fold-0 validation, label mapping

[[1, 23]]

for

lung tumor

, automatic class-prompt segmentation, patch

[128,128,128]

, 5 epochs, and original-spacing

configs/evaluate.json

scoring before and after training. Expected reference range is pretrained Dice about

0.6697

, training-best Dice about

0.6905

, and fine-tuned formal Dice about

0.6836

User-data finetune:

bash

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

Use

--label-mapping '[[1, 23]]'

when local label values are custom or the anatomy name is ambiguous.

冒烟规模流程检查：

bash

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

。冒烟模式用于验证连接、配置生成、检查点加载和运行时兼容性；不代表质量标准。

MSD Task06肺部肿瘤sanity复现：

bash

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]]

、自动类别提示分割、

[128,128,128]

补丁、5个epoch，以及训练前后使用原始间距

configs/evaluate.json

评分。预期参考范围为预训练Dice约

0.6697

、训练最佳Dice约

0.6905

、微调后正式Dice约

0.6836

。

用户数据微调：

bash

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]]'

。

Examples

示例命令

Smoke run on a staged tiny dataset:

bash

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 on a local MSD cache:

bash

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

在已准备好的小型数据集上运行冒烟测试：

bash

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测试：

bash

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

Data Contract

数据约定

Preferred layout:

dataset/imagesTr/*.nii.gz

and

dataset/labelsTr/*.nii.gz

Labels must align one-to-one with images by basename.
The target label value must be present in the training labels.
Use a datalist when patient-level splitting matters. The bundle default
```
fold
```
is
```
0
```
, so
```
fold: 0
```
entries are validation and all other folds are training.
Every trained foreground label must map to an existing VISTA3D global class id from
```
bundle/label_dict.json
```
; this skill cannot invent a new class.

推荐布局：

dataset/imagesTr/*.nii.gz

和

dataset/labelsTr/*.nii.gz

。

标签必须与图像按文件名一一对应。
目标标签值必须存在于训练标签中。
当需要按患者级别拆分时，请使用数据列表。Bundle默认
```
fold
```
为
```
0
```
，因此
```
fold: 0
```
的条目为验证集，其他所有fold为训练集。
每个训练的前景标签必须映射到
```
bundle/label_dict.json
```
中已有的VISTA3D全局类别ID；此技能无法创建新类别。

Results

结果说明

Check

output.json

in the run directory first:

```
formal_pretrained_val_dice
```
and
```
formal_finetuned_val_dice
```
: original-spacing pre/post scores when formal eval is enabled.

training_start_val_dice

val_dice_per_epoch

, and

training_best_val_dice

: training-time validation trace.

finetuned_ckpt_matches_pretrained_weights

: detects the epoch-0 checkpoint trap when

val_at_start=true

```
recommended_ckpt
```
: checkpoint to keep. Do not blindly use the last epoch or
```
model_finetune.pt
```
.
```
runtime.oom
```
,
```
runtime.peak_gpu_mb
```
, and phase logs: distinguish OOM, slow validation, and process failure.

Decision rule: prefer formal original-spacing pre/post scores when present; reject tensor-identical "fine-tuned" checkpoints for sanity recovery; treat

improved: false

as valid evidence rather than a wrapper failure.

请首先查看运行目录中的

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检查点陷阱。

```
recommended_ckpt
```
：建议保留的检查点。请勿盲目使用最后一个epoch的检查点或
```
model_finetune.pt
```
。
```
runtime.oom
```
、
```
runtime.peak_gpu_mb
```
和阶段日志：用于区分内存不足(OOM)、验证缓慢和进程失败。

决策规则：优先使用已有的正式原始间距训练前后评分；如果sanity恢复时得到与预训练权重完全相同的“微调”检查点，则判定为失败；将

improved: false

视为有效证据，而非包装器故障。

Limitations

局限性

Thin wrapper. Training, validation, transforms, and checkpointing are delegated to the upstream bundle in
```
bundle/
```
.
The auto-derived plan is heuristic; caller-provided
```
--patch-size
```
,
```
--cache-rate
```
,
```
--epochs
```
, and
```
--learning-rate
```
win.
The Task06 sanity recipe intentionally forces single-GPU execution to match the DFW reference. Multi-GPU mode for other datasets requires host
```
torchrun
```
support.
The paired verifier is CPU-only and audits the evidence pack; it does not re-run GPU segmentation.
Not for clinical deployment, clinical interpretation, autonomous diagnosis, or regulatory submission.

轻量包装器。训练、验证、变换和检查点功能均委托给
```
bundle/
```
中的上游bundle。
自动生成的方案为启发式；调用者提供的
```
--patch-size
```
、
```
--cache-rate
```
、
```
--epochs
```
和
```
--learning-rate
```
优先级更高。
Task06 sanity方案强制使用单GPU执行，以匹配DFW参考结果。其他数据集的多GPU模式需要主机支持
```
torchrun
```
。
配对验证器仅支持CPU，用于审计证据包；不会重新运行GPU分割。
不适用于临床部署、临床解读、自主诊断或监管提交。

Troubleshooting

故障排除

Error	Cause	Fix
Missing dependency or import error	Runtime drift from `skill_manifest.yaml` .	Install the packages above or use the documented environment.
Low Task06 pretrained Dice	Wrong config, wrong checkpoint, data split drift, or dependency drift.	Compare environment fields and staged configs before changing training logic.
`model_finetune.pt` matches pretrained	`val_at_start=true` selected epoch 0 as best.	Use `recommended_ckpt` ; treat sanity recovery as failed unless a changed checkpoint improves formal Dice.
Missing formal Dice fields	Formal eval failed or was skipped.	Inspect `eval_pretrained.log` , `eval_finetuned.log` , and `metrics.csv` .
GPU out of memory	Patch/cache settings too large.	Reduce `--patch-size` , lower `--cache-rate` , or reduce workers.
No validation cases	Datalist lacks `fold: 0` .	Provide at least one validation entry.

错误	原因	修复方案
依赖缺失或导入错误	运行环境与 `skill_manifest.yaml` 存在偏差。	安装上述指定包或使用文档中说明的环境。
Task06预训练Dice值偏低	配置错误、检查点错误、数据拆分偏差或依赖版本偏差。	在修改训练逻辑前，先对比环境字段和已准备好的配置。
`model_finetune.pt` 与预训练权重一致	`val_at_start=true` 选择了epoch 0作为最佳检查点。	使用 `recommended_ckpt` ；除非修改后的检查点能提升正式Dice值，否则sanity恢复视为失败。
缺少正式Dice字段	正式评估失败或被跳过。	检查 `eval_pretrained.log` 、 `eval_finetuned.log` 和 `metrics.csv` 。
GPU内存不足	补丁/缓存设置过大。	减小 `--patch-size` 、降低 `--cache-rate` 或减少工作进程数。
无验证案例	数据列表中缺少 `fold: 0` 的条目。	至少提供一个验证条目。

Verification

验证

Run the implemented verifier when quality gates matter:

bash

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

当需要质量把关时，运行已实现的验证器：

bash

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