⚡

CT医学影像分割技能Skill nv-segment-ct

用于在CT NIfTI体数据上运行NV-Segment-CT VISTA3D模型，进行腹部器官（如肝脏、脾脏、肾脏等）的自动分割，并输出标签图及包含体积、标签ID、运行时间等信息的证据JSON。关键词：CT分割、VISTA3D、NIfTI、器官分割、医学影像、NVIDIA、标签图。

医学影像分割 0 次安装 0 次浏览 更新于 9/6/2026
名称 nv-segment-ct
描述 用于在CT NIfTI体数据上运行NV-Segment-CT VISTA3D，并记录标签图证据。
开源协议 Apache-2.0 allowed-tools: Bash metadata:
作者 NVIDIA MedTech Team tags: - MedTech - CT - segmentation

NV-Segment-CT

目的

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

说明

  • 在更改参数、副作用或验证门之前，请阅读skill_manifest.yaml。
  • 通过下述文档化命令运行scripts/run_vista3d.py；将输出保留在调用方提供的运行目录下。
  • 如果宿主代理暴露了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]

先决条件

  • 运行时要求：支持venv的Python 3.10，以及Manifest声明时所需的GPU/CUDA。模型包来自固定版本的上游requirements文件；仅在本地添加包装器特定包。
  • 副作用：在~/.cache/nvidia-skills/venvs/nv-segment-ct-f9f5f51/下创建隔离环境， 将下载的bundle写入skills/nv-segment-ct/bundle/，可能在~/.cache/huggingface/下缓存模型资产， 并可能在首次设置期间联系https://huggingface.co和https://raw.githubusercontent.com；可选的脾脏fixture获取器会从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标志可覆盖。
  • 输出可能符合schema但在语义上为空（例如标签提示与输入解剖结构不匹配）。合理性门会断言每个请求的解剖结构至少有一个前景体素。
  • 不用于临床部署、临床解读、自主诊断、法规提交。

故障排除

错误 原因 修复
创建环境时提示ensurepip is not available 宿主Python安装缺少其操作系统的venv包。 安装匹配的Python 3.10 venv支持包，或使用virtualenv -p python3.10创建相同的隔离环境。
缺少依赖或导入错误 运行时包与skill_manifest.yaml不一致。 安装Manifest中声明的包，或使用文档中描述的设置命令。
输出为空或schema无效 输入路径错误、模态不支持或上游失败。 使用已知fixture重新运行，并检查包装器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 bundle本身不附带requirements.txt。

两个一次性下载（文档化命令执行第一个；fixture获取是引导时单独运行的步骤）：

# 来自Decathlon MSD09的脾脏示例fixture（约1.5 GB tar，提取到skills/nv-segment-ct/fixtures/spleen_03.nii.gz的约11 MB fixture）：
python skills/nv-segment-ct/fixtures/fetch_spleen_fixture.py

两个下载（下面的bundle和fixture）都被gitignore（Medical AI Skills策略：git中不存放医疗数据或模型权重）。获取脚本是幂等的，并将tar缓存在.workbench_data/datasets/下，因此重新运行是无操作。

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

用法

从技能仓库根目录运行完整引导。直接调用虚拟环境的二进制文件，以免修改调用方的活动环境：

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的模型bundle拉取到skills/nv-segment-ct/bundle/；后续调用会重用缓存。

label-prompts是VISTA3D类ID。证据输出记录输入几何、输出掩码路径、观察到的标签ID、意外标签、每类体素计数、根据输出掩码头间距计算的每类物理体积、运行时间、模型身份以及固定代码派生的伪影检查，如掩码形状、仿射匹配、标签集、前景计数和类体积边界。

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

解剖合理性（每类体积边界、碎片化、双侧对称性、肝脏大于脾脏）以及可选的每类Dice/IoU（与记录的ground truth比较）由verifiers/ct_segmentation_quality_v1检查。

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