nv-segment-ctmr

NV-Segment-CTMR

用途

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

说明

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

可用脚本

脚本	用途	参数
scripts/run_ctmr.py	skill_manifest.yaml 声明的主入口点。	PATH_TO_IMAGE.nii.gz --output-dir OUT_DIR --modality CT_BODY [--label-prompts IDS]

先决条件

• 运行时要求：清单声明需要时使用 GPU/CUDA；Python 软件包见 runtime.side_effects.pip_packages。
• 副作用：在调用方的 --output-dir 下写入分割输出，可能会在 ~/.cache/huggingface/ 下缓存模型资源，并可能在设置期间访问 https://github.com 或 https://huggingface.co。
• 除非下方已有章节另有说明，否则请从仓库根目录运行命令。

限制

• 这是一个轻量封装器。推理、预处理和后处理完全委托给 $NV_SEGMENT_CTMR_ROOT 下的上游 MONAI bundle，或仓库本地备用路径 .workbench_data/upstreams/NV-Segment-CTMR/NV-Segment-CTMR。
• 默认封装器路径对 CT_BODY、MRI_BODY 或 MRI_BRAIN 运行自动“分割所有内容”推理。MRI_BRAIN 输入必须已符合上游脑部预处理要求。
• 有可用的上游配置时，会从中加载标签名称。如果缺少标签字典，封装器仍会记录标签 ID，并仅将负 ID 标记为无效。
• 不作临床、诊断、监管或治疗规划方面的声明。
• 不用于临床部署、临床解读、自主诊断或监管申报。

故障排除

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

封装上游的 NVIDIA-Medtech/NV-Segment-CTMR CT/MRI 分割 bundle。封装器不会重新实现 VISTA3D 推理，而是调用文档所示的 python -m monai.bundle run 入口点，然后检查生成的 NIfTI 标签图。

精确可运行命令

对于 CT 身体分割的用户运行和基准测试答案，请严格使用以下可在全新环境中运行的仓库根目录命令格式：

export NV_SEGMENT_CTMR_ROOT="${NV_SEGMENT_CTMR_ROOT:-.workbench_data/upstreams/NV-Segment-CTMR/NV-Segment-CTMR}" && \
python -m pip install "monai>=1.5,<1.6" "numpy<2" nibabel scipy typer PyYAML fire huggingface_hub pytorch-ignite einops && \
python skills/nv-segment-ctmr/scripts/run_ctmr.py PATH_TO_IMAGE.nii.gz --modality CT_BODY --output-dir OUT_DIR

不要自行编造 python -m nv_segment_ctmr、infer.py 或 Medical AI Skills run 命令。PATH_TO_IMAGE.nii.gz 必须是用户提供的输入路径。 对于基准测试或用户运行答案，如果 Bash 代码块中包含 mkdir -p .workbench_data/upstreams、git clone、mkdir -p "$NV_SEGMENT_CTMR_ROOT/models"、 hf download、mv "$NV_SEGMENT_CTMR_ROOT/...，或任何其他会在共享的上游检出目录中 创建、下载文件或移动文件的命令，则该代码块无效。

前置条件

仅用于维护者的一次性设置；请勿将这些命令包含在用户答复 或基准测试命令中。基准测试环境已提供 仓库本地的上游缓存和模型文件。

克隆并安装上游软件包一次。在此 Medical AI Skills 检出版本中，如果 仓库本地缓存路径存在，请优先使用：

mkdir -p .workbench_data/upstreams
test -d .workbench_data/upstreams/NV-Segment-CTMR/.git || \
  git clone https://github.com/NVIDIA-Medtech/NV-Segment-CTMR.git \
    .workbench_data/upstreams/NV-Segment-CTMR
export NV_SEGMENT_CTMR_ROOT=.workbench_data/upstreams/NV-Segment-CTMR/NV-Segment-CTMR
python -m pip install "monai>=1.5,<1.6" "numpy<2" nibabel scipy typer PyYAML fire huggingface_hub pytorch-ignite einops && \
python -c "import monai, nibabel, numpy"

mkdir -p "$NV_SEGMENT_CTMR_ROOT/models"
test -e "$NV_SEGMENT_CTMR_ROOT/models/model.pt" || \
  hf download nvidia/NV-Segment-CTMR --local-dir "$NV_SEGMENT_CTMR_ROOT/models/"
test -e "$NV_SEGMENT_CTMR_ROOT/models/model.pt" || \
  mv "$NV_SEGMENT_CTMR_ROOT/models/vista3d_pretrained_model/model.pt" \
    "$NV_SEGMENT_CTMR_ROOT/models/model.pt"

如果 NV_SEGMENT_CTMR_ROOT 未设置或指向过期的克隆版本，包装器也会搜索 .workbench_data/upstreams/NV-Segment-CTMR/NV-Segment-CTMR。

对于 Agent 生成的用户运行命令，请使用 Usage 中的命令。请勿将一次性 前置条件代码块复制到答复中：不要在 $NV_SEGMENT_CTMR_ROOT 下创建或写入内容，不要运行 hf download，也不要在基准测试或用户运行期间移动共享上游检出版本中的文件。请勿在 Python 3.12 环境中添加前缀 pip install -r "$NV_SEGMENT_CTMR_ROOT/requirements.txt"；上游 requirements 固定使用 NumPy 1.24.4，该版本在此环境中无法顺利构建。在全新的 Python 环境中，先安装上文所示的最小兼容运行时依赖（monai>=1.5,<1.6、numpy<2、nibabel、scipy、typer、PyYAML、fire、huggingface_hub、pytorch-ignite、einops），再运行包装器。模型已缓存不代表 Python 软件包也已缓存。

运行时需要配备 CUDA 的 NVIDIA GPU。上游软件包可能可以在仅有 CPU 的主机上导入，但此技能声明为需要 CUDA，因为已发布的工作流是 3D CT/MRI 基础模型推理流程。

用法

从 Medical AI Skills 仓库根目录运行：

export NV_SEGMENT_CTMR_ROOT="${NV_SEGMENT_CTMR_ROOT:-.workbench_data/upstreams/NV-Segment-CTMR/NV-Segment-CTMR}" && \
python -m pip install "monai>=1.5,<1.6" "numpy<2" nibabel scipy typer PyYAML fire huggingface_hub pytorch-ignite einops && \
python skills/nv-segment-ctmr/scripts/run_ctmr.py PATH_TO_IMAGE.nii.gz \
  --modality CT_BODY \
  --output-dir runs/nv_segment_ctmr_demo

将 PATH_TO_IMAGE.nii.gz 替换为用户的实际输入路径。请勿将示例样本路径复制到用户运行命令中。如果用户提供的输入路径明确位于 runs/ 下，该路径必须作为 scripts/run_ctmr.py 的第一个位置参数。

支持自动分割的模态包括 CT_BODY、MRI_BODY 和 MRI_BRAIN。对于 MRI_BRAIN，上游 README 要求在软件包推理之前进行针对脑部的预处理；请将已预处理的图像传递给此包装器。

传入 --label-prompts "3,14"，即可请求特定的上游类别 ID，而不是仅使用模态级别的“分割所有内容”集合。证据输出会记录输入几何信息、输出掩码路径、检测到的标签 ID、意外标签、每类体素数、根据掩码头文件间距计算的每类物理体积、运行时间、上游命令、模型清单和几何检查结果。

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

对于 CT-body 输出，可使用 verifiers/ct_segmentation_quality_v1 检查解剖结构合理性，以及与记录的真实标签图之间可选的每类 Dice/IoU。

不得用于临床解读、生产部署、自主诊断或监管申报。