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。
• 可选环境变量：NV_SEGMENT_CTMR_ROOT 用于选择可信的上游检出目录；CUDA_VISIBLE_DEVICES 用于限制可见的 GPU；必要时，MONAI_DATA_DIRECTORY 和 PYTORCH_CUDA_ALLOC_CONF 可覆盖包装器默认的输出本地缓存和分配器设置。
• 副作用：在调用方的 --output-dir 下写入分割输出；可能会在 ~/.cache/huggingface/ 下缓存模型资源，并可能在设置期间访问 https://github.com 或 https://huggingface.co。
• 除非下方已有章节另有说明，否则请从仓库根目录运行命令。

限制

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

故障排除

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

包装上游的 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:-$HOME/.cache/nvidia-skills/upstreams/NV-Segment-CTMR-cb921f5/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/...，或任何其他会在共享上游检出目录中创建、下载或移动文件的命令，则该代码块无效。

前置条件

仅限维护者进行一次性设置；不要在用户回答或基准测试命令中包含这些命令。基准测试环境已提供仓库本地上游缓存和模型文件。

如果 NV_SEGMENT_CTMR_ROOT 已指向本地捆绑包检出目录，包装脚本会使用该目录，并在结果中记录其当前提交。否则，请克隆一次推荐的固定默认版本：

if [ -z "${NV_SEGMENT_CTMR_ROOT:-}" ]; then
  export NV_SEGMENT_CTMR_COMMIT=cb921f5c58837c0f42a713855d68b32af88e1cdd
  export NV_SEGMENT_CTMR_CHECKOUT="$HOME/.cache/nvidia-skills/upstreams/NV-Segment-CTMR-cb921f5"
  if [ ! -d "$NV_SEGMENT_CTMR_CHECKOUT/.git" ]; then
    git clone https://github.com/NVIDIA-Medtech/NV-Segment-CTMR.git "$NV_SEGMENT_CTMR_CHECKOUT"
    git -C "$NV_SEGMENT_CTMR_CHECKOUT" checkout --detach "$NV_SEGMENT_CTMR_COMMIT"
  fi
  export NV_SEGMENT_CTMR_ROOT="$NV_SEGMENT_CTMR_CHECKOUT/NV-Segment-CTMR"
fi
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 \
    --revision 4fb8b4a6b2532be9f1c449a3726fe5440ab4213a \
    --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 中的命令。不要将一次性 Preconditions 代码块复制到回答中：不要在 $NV_SEGMENT_CTMR_ROOT 下创建或写入文件，不要运行 hf download，也不要在基准测试或用户运行期间移动共享上游检出目录中的文件。在 Python 3.12 环境中，不要在前面加上 pip install -r "$NV_SEGMENT_CTMR_ROOT/requirements.txt"；上游依赖项固定为 NumPy 1.24.4，该版本在此环境中无法顺利构建。在全新的 Python 环境中，请先安装上方所示的最小兼容运行时依赖（monai>=1.5,<1.6、numpy<2、nibabel、scipy、typer、PyYAML、fire、huggingface_hub、pytorch-ignite、einops），再运行包装脚本。缓存模型不代表 Python 包也已缓存。

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

用法

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

export NV_SEGMENT_CTMR_ROOT="${NV_SEGMENT_CTMR_ROOT:-$HOME/.cache/nvidia-skills/upstreams/NV-Segment-CTMR-cb921f5/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 身体输出，可使用 verifiers/ct_segmentation_quality_v1 检查解剖合理性，以及与已记录真实标注的可选逐类 Dice/IoU。

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