nv-segment-ct

NV-Segment-CT

用途

• 用于在 CT NIfTI 影像卷上运行 NV-Segment-CT VISTA3D，并记录标签图证据。不用于临床解读。
• 请严格按照文档使用封装器；不要用手写实现替换上游入口点。
• 清单 I/O：输入为 ct_volume；输出为 label_map 和 result_json。

说明

• 更改参数、副作用或验证门之前，请先阅读 skill_manifest.yaml。
• 使用下方文档中的命令运行 scripts/run_vista3d.py；将输出保存在调用方提供的运行目录中。
• 如果主机 Agent 提供 run_script，请使用 run_script("scripts/run_vista3d.py", args=[...])；否则运行下方所示的 Bash/Python 命令。
• 在将运行结果视为证据之前，请检查生成的 JSON 和配套的验证器说明。

可用脚本

脚本	用途	参数
scripts/run_vista3d.py	由 skill_manifest.yaml 声明的主要入口点。	PATH_TO_CT.nii.gz [--output-dir OUT_DIR] [--label-prompts IDS]

先决条件

• 运行时要求：清单中声明需要时使用 GPU/CUDA；Python 包见 runtime.side_effects.pip_packages。
• 副作用：将下载的包写入 skills/nv-segment-ct/bundle/，可能会在 ~/.cache/huggingface/ 下缓存模型资源；首次设置期间可能会访问 https://huggingface.co；可选的脾脏样例获取器会从 https://msd-for-monai.s3-us-west-2.amazonaws.com 下载 MSD09。
• 除非下方已有章节另有说明，否则请从仓库根目录运行命令。

限制

• 这是一个轻量封装器。推理、预处理和后处理完全委托给 bundle/ 中官方的 hugging_face_pipeline.HuggingFacePipelineHelper。请勿修改 bundle/ 下的代码。
• transformers 必须为 4.x 版本；HF 模型代码使用了 5.x 之前的惯用写法（例如 _tied_weights_keys）。
• 自动检测设备（有 cuda 时使用 cuda，否则使用 cpu）；--device 标志可覆盖此设置。
• 输出可能符合架构要求，但语义上为空（例如，标签提示词与输入解剖结构不匹配）。合理性检查门会断言每个请求的解剖结构至少包含一个前景体素。
• 不用于临床部署、临床解读、自主诊断或监管申报。

故障排除

错误	原因	解决方法
缺少依赖或导入错误	运行时包与 skill_manifest.yaml 不一致。	安装清单中声明的包，或使用文档中的设置命令。
输出为空或架构无效	输入路径错误、模态不受支持或上游失败。	使用已知样例重新运行，并检查封装器 JSON 和 stderr。
验证门失败	输出违反了声明的工程不变量。	保留失败的证据包，并根据验证门消息修复输入或封装器代码。

封装上游的 nvidia/NV-Segment-CT 辅助程序。此封装器不会 重新实现 VISTA3D 推理。

精确可运行入口

对于 CT 分割用户运行，请严格使用此仓库根目录下的封装器路径：

python skills/nv-segment-ct/scripts/run_vista3d.py PATH_TO_CT.nii.gz --label-prompts "1,3,5,14" --output-dir OUT_DIR

不要自行编造 infer.py、Medical AI Skills run、python -m nv_segment_ct 或仅使用解剖结构名称的标志。对于脾脏、肝脏、右肾和左肾，所需的 VISTA3D 标签 ID 确切为 1,3,5,14。

前置条件

此技能假设使用 Python 3.12 环境，且未预装任何运行时依赖——文档中的命令会安装所需的全部内容。 固定的依赖列表位于 requirements.txt。

有两项一次性下载（文档中的命令会执行第一项；初始化时需单独运行样例获取步骤）：

# Spleen example fixture from Decathlon MSD09 (~1.5 GB tar, ~11 MB
# fixture extracted into skills/nv-segment-ct/fixtures/spleen_03.nii.gz):
python skills/nv-segment-ct/fixtures/fetch_spleen_fixture.py

这两项下载（下方的包和样例）都被 git 忽略（Medical AI Skills 政策：不得将医疗数据或模型权重纳入 git）。获取脚本可幂等运行，并会将 tar 缓存到 .workbench_data/datasets/，因此重复运行时不会产生额外操作。

运行时需要支持 CUDA 的 NVIDIA GPU。也支持 CPU 回退，但速度较慢。

使用方法

在 Medical AI Skills 仓库根目录中运行以下单条命令，所有步骤将在全新的 Python 3.12 venv 中执行，使技能能够自行引导完成设置：

pip install -r skills/nv-segment-ct/requirements.txt && \
huggingface-cli download nvidia/NV-Segment-CT \
  --local-dir skills/nv-segment-ct/bundle/ && \
python skills/nv-segment-ct/scripts/run_vista3d.py PATH_TO_CT.nii.gz \
  --label-prompts "1,3,5,14" \
  --output-dir vista3d_outputs

用户指定解剖结构时，请在运行前将其转换为 VISTA3D 类 ID。对于常见的腹部 CT 请求：

解剖结构	VISTA3D 类 ID
肝脏	1
脾脏	3
右肾	5
左肾	14

对于“分割脾脏、肝脏、右肾和左肾”，正确的 --label-prompts 值必须是 "1,3,5,14"。不要使用其他标签字典中的肾脏 ID；封装程序会校验请求的标签集，如果生成的掩码包含请求集合以外的标签，就会将本次运行标记为无效。

pip install 步骤至关重要：不要假设当前环境中已安装 monai/torch 等依赖。huggingface-cli download 步骤也是约定的一部分——它会将约 832 MB 的模型包下载到 skills/nv-segment-ct/bundle/（首次运行后会缓存；后续调用不会执行任何操作）。

label-prompts 是 VISTA3D 类 ID。证据输出会记录输入几何信息、输出掩码路径、检测到的标签 ID、意外标签、各类体素数、根据输出掩码头文件中的间距计算得出的各类物理体积、运行时间、模型身份，以及固定的代码派生工件检查项，例如掩码形状、仿射变换匹配情况、标签集、前景计数和类别体积范围。

传入 --ground-truth PATH，即可在 input.ground_truth_path 下记录参考标签图路径。此技能不会计算 Dice；这是配对验证器的工作。

verifiers/ct_segmentation_quality_v1 会检查解剖结构合理性（各类体积范围、碎片化程度、双侧对称性、肝脏是否大于脾脏），并可选地针对记录的真实标注计算各类 Dice/IoU。

不得用于临床解读、生产部署或非 CT 模态。