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 命令。
• 创建文档所述的 Python 3.10 虚拟环境，并直接调用其中的可执行文件；不要将模型依赖项安装到调用方当前启用的环境中。
• 将运行结果作为证据前，请检查生成的 JSON 和配套验证器说明。

可用脚本

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

前提条件

• 运行要求：Python 3.10，支持 venv；若清单有声明，还需 GPU/CUDA。模型软件包来自固定版本的上游 requirements 文件；本地只添加封装程序专用软件包。
• 副作用：在 ~/.cache/nvidia-skills/venvs/nv-segment-ct-f9f5f51/ 下创建隔离环境，在 skills/nv-segment-ct/bundle/ 下写入下载的 程序包，可能会在 ~/.cache/huggingface/ 下缓存模型资产，并可能在首次设置期间访问 https://huggingface.co 和 https://raw.githubusercontent.com；可选的脾脏 测试数据获取器会从 https://msd-for-monai.s3-us-west-2.amazonaws.com 下载 MSD09。
• 除非下方已有章节另有说明，否则请从仓库根目录运行命令。

限制

• 这是一个轻量封装程序。推理、预处理和后处理完全委托给 bundle/ 中的官方 hugging_face_pipeline.HuggingFacePipelineHelper。不要修改 bundle/ 下的代码。
• transformers==4.46.3 是经过测试、与上游 requirements 中的 Torch 2.0.1 兼容的封装层；较新的 Transformers 版本可能会禁用较旧的 Torch 后端。
• 固定版本的上游 requirements 包含 Torch 2.0.1。只能使用固定版本的 NVIDIA 模型资产；不要在此旧版复现环境中加载不可信的检查点。
• 自动检测设备（有 cuda 时使用 cuda，否则使用 cpu）；--device 标志可覆盖此设置。
• 输出可能符合架构，但语义上为空（例如，标签提示词与输入解剖结构不匹配）。健全性关卡要求每个请求的解剖结构至少有一个前景体素。
• 不用于临床部署、临床解读、自主诊断或法规申报。

故障排除

错误	原因	解决方法
创建环境时提示 ensurepip is not available	宿主机 Python 安装中缺少操作系统的 venv 软件包。	安装匹配的 Python 3.10 venv 支持软件包，或使用 virtualenv -p python3.10 创建相同的隔离环境。
缺少依赖项或导入错误	运行时软件包与 skill_manifest.yaml 不一致。	安装清单中声明的软件包，或使用文档所述的设置命令。
输出为空或架构无效	输入路径错误、模态不受支持或上游运行失败。	使用已知测试数据重新运行，并检查封装程序 JSON 和 stderr。
验证关卡失败	输出违反了声明的工程不变量。	保留失败的证据包，并根据关卡消息修复输入或封装程序代码。

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

可精确运行的接口

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

"$NV_SEGMENT_CT_VENV/bin/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。

前置条件

此技能假定使用支持 venv 的 Python 3.10 解释器。文档中的命令会创建专用环境，并从不可变的 NVIDIA-Medtech 提交 f9f5f51b589e5dc9c23c453cf5138398e4084056 安装模型依赖，依赖文件为 NV-Segment-CT/requirements.txt。Hugging Face 模型包本身不包含 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/，因此重复运行不会执行任何操作。

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

用法

从 skills 仓库根目录运行完整的初始化流程。直接调用虚拟环境中的可执行文件，以免修改调用方当前激活的环境：

export NV_SEGMENT_CT_VENV="${NV_SEGMENT_CT_VENV:-$HOME/.cache/nvidia-skills/venvs/nv-segment-ct-f9f5f51}"
export NV_SEGMENT_CT_REQUIREMENTS="${NV_SEGMENT_CT_REQUIREMENTS:-https://raw.githubusercontent.com/NVIDIA-Medtech/NV-Segment-CTMR/f9f5f51b589e5dc9c23c453cf5138398e4084056/NV-Segment-CT/requirements.txt}"

if [ ! -x "$NV_SEGMENT_CT_VENV/bin/python" ]; then
  python3.10 -m venv "$NV_SEGMENT_CT_VENV"
fi

"$NV_SEGMENT_CT_VENV/bin/python" -m pip install \
  -r "$NV_SEGMENT_CT_REQUIREMENTS" \
  "transformers==4.46.3" \
  "typer>=0.9"

"$NV_SEGMENT_CT_VENV/bin/hf" download nvidia/NV-Segment-CT \
  --revision afb51518689f71e6abb367ee6301b2cd0225c66a \
  --local-dir skills/nv-segment-ct/bundle/

"$NV_SEGMENT_CT_VENV/bin/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；包装脚本会验证请求的标签集合，如果输出的掩膜包含请求集合之外的标签，就会将本次运行标记为无效。

安装和下载步骤至关重要。固定版本的上游文件负责管理模型环境，而 Transformers 和 Typer 则为这个轻量包装脚本提供支持。hf download 会将约 832 MB 的模型包下载到 skills/nv-segment-ct/bundle/；后续调用会复用缓存。

label-prompts 是 VISTA3D 类别 ID。证据输出会记录输入几何信息、输出掩膜路径、检测到的标签 ID、意外标签、各类别的体素计数、根据输出掩膜头部中的间距计算出的各类别物理体积、运行时间、模型标识，以及固定的、由代码计算的产物检查项，例如掩膜形状、仿射矩阵匹配、标签集合、前景计数和类别体积范围。

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

解剖学合理性（各类别体积范围、碎片化、双侧对称性、肝脏大于脾脏）以及与已记录真实标注进行的可选逐类别 Dice/IoU 检查，均由 verifiers/ct_segmentation_quality_v1 完成。

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