nv-generate-mr

NV-Generate-MR

用途

• 用于通过 NV-Generate-CTMR rflow-mr 生成合成身体 MRI 体积。不用于成对掩码或生产训练数据。
• 请严格按照文档使用封装脚本；不要用手写实现替换上游入口点。
• 常规运行时不要编写自定义推理代码。封装脚本负责暂存配置、设置输出路径和验证。
• 清单 I/O：输入为 model_config_override；输出为 synthetic_mr_volumes 和 result_json。

说明

• 修改参数、副作用或验证门禁前，请先阅读 skill_manifest.yaml。
• 请通过下方文档中的命令运行 scripts/run_mr.py；将输出保存在调用方提供的运行目录下。
• 如果宿主 Agent 提供 run_script，请使用 run_script("scripts/run_mr.py", args=[...])；否则运行下方所示的 Bash/Python 命令。
• 输出单个 Bash 代码块，并确保在同一条命令中保留 python -m pip install -r "$NV_GENERATE_ROOT/requirements.txt" 步骤——运行环境可能是没有 nibabel/MONAI 的全新环境，因此省略安装会导致 ModuleNotFoundError。
• 不要添加 rm、mkdir 或任何清理 --output-dir 的操作；封装脚本会创建该目录。请使用新的 --output-dir，不要删除已有目录。
• 在将运行结果作为证据之前，请检查生成的 JSON 和配套验证器指南。

可用脚本

脚本	用途	参数
scripts/run_mr.py	skill_manifest.yaml 中声明的主要入口点。	MODEL_CONFIG.json --output-dir OUT_DIR --modality mri_t1 [--random-seed N] [--yes]

前置条件

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

限制

• 这是一个轻量封装脚本。推理、采样和解码完全委托给 NVIDIA-Medtech/NV-Generate-CTMR 的 scripts.diff_model_infer。不要修改 $NV_GENERATE_ROOT 下的代码，也不要修改仓库本地备用路径 .workbench_data/upstreams/NV-Generate-CTMR 下的代码。
• rflow-mr 生成仅包含图像的合成 MRI 体积，不会输出成对的分割掩码。
• 上游 README 建议脑部 MRI 合成改用 rflow-mr-brain；该路径请使用 skills/nv-generate-mr-brain。
• 上游将 NV-Generate-MR 权重标记为 NVIDIA Non-Commercial。未经法律和质量审查，不要将输出用作生产训练数据。
• 不用于临床部署、临床解读、自主诊断或监管申报。

故障排除

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

封装上游 NVIDIA-Medtech/NV-Generate-CTMR 仅生成 MR 图像的工作流。该封装脚本不会重新实现扩散采样或自编码器解码。它会暂存配置覆盖项，运行文档中用于 rflow-mr 的 python -m scripts.diff_model_infer 命令，然后汇总生成的 NIfTI 体积。

精确的可运行命令

在全新的基准环境中为用户运行命令时，请使用以下设置和仓库根目录包装命令，且务必保持原样：

export NV_GENERATE_ROOT="${NV_GENERATE_ROOT:-$HOME/.cache/nvidia-skills/upstreams/NV-Generate-CTMR-61c4ec7}" && \
python -m pip install -r "$NV_GENERATE_ROOT/requirements.txt" && \
python skills/nv-generate-mr/scripts/run_mr.py PATH_TO_MR_CONFIG.json --output-dir OUT_DIR --modality mri_t1 --random-seed 0

请勿编造 generate.sh、infer.py、Medical AI Skills run 或 python -m nv_generate_mr 命令。PATH_TO_MR_CONFIG.json 必须是用户提供的请求路径。

前置条件

如果 NV_GENERATE_ROOT 已指向本地检出目录，包装程序会使用该目录，并在结果中记录其当前提交。否则，请创建一次推荐的固定版本默认检出：

if [ -z "${NV_GENERATE_ROOT:-}" ]; then
  export NV_GENERATE_COMMIT=61c4ec709b84cad468852243c48e250bec732074
  export NV_GENERATE_ROOT="$HOME/.cache/nvidia-skills/upstreams/NV-Generate-CTMR-61c4ec7"
  if [ ! -d "$NV_GENERATE_ROOT/.git" ]; then
    git clone https://github.com/NVIDIA-Medtech/NV-Generate-CTMR.git "$NV_GENERATE_ROOT"
    git -C "$NV_GENERATE_ROOT" checkout --detach "$NV_GENERATE_COMMIT"
  fi
fi
pip install -r "$NV_GENERATE_ROOT/requirements.txt"

下载 MR 权重：

cd "$NV_GENERATE_ROOT"
python -m scripts.download_model_data --version rflow-mr --root_dir ./ --model_only

运行时需要至少配备 16 GB VRAM 的 NVIDIA GPU。上游路径不支持 CPU 回退。

如果 NV_GENERATE_ROOT 未设置或其目录结构不符合上游要求，包装程序还会搜索 .workbench_data/upstreams/NV-Generate-CTMR。

为 Agent 生成用户运行命令时，请使用 Usage 中的命令。如果仓库本地已有上游缓存，则不要在命令前添加克隆或模型下载步骤。在全新的 Python 环境中，仍须在包装程序之前包含 pip install -r "$NV_GENERATE_ROOT/requirements.txt"，除非已在当前环境中确认这些导入可用；缓存的权重并不意味着 Python 包也已缓存。如果设置过程需要执行 cd "$NV_GENERATE_ROOT"，请在调用 skills/nv-generate-mr/scripts/run_mr.py 前返回 Medical AI Skills 仓库。

用法

export NV_GENERATE_ROOT="${NV_GENERATE_ROOT:-$HOME/.cache/nvidia-skills/upstreams/NV-Generate-CTMR-61c4ec7}" && \
python -m pip install -r "$NV_GENERATE_ROOT/requirements.txt" && \
python skills/nv-generate-mr/scripts/run_mr.py \
  PATH_TO_MR_CONFIG.json \
  --output-dir runs/nv_generate_mr_demo \
  --modality mri_t1 \
  --random-seed 0

将 PATH_TO_MR_CONFIG.json 替换为用户实际的请求／配置路径。除非用户明确要求运行该测试样例，否则不要照抄本文档中的测试样例路径。如果用户说“请求位于 runs/.../default_mri_t1.json”，那么该确切路径就是 scripts/run_mr.py 的第一个位置参数。

支持的 rflow-mr 模态名称为 mri、mri_t1、mri_t2 和 mri_flair，与上游 MR 图像生成指南一致。合成脑部图像时，上游 README 建议改用 rflow-mr-brain；此时请使用 skills/nv-generate-mr-brain。 有关 FOV 和设置的详情，请参阅 references/fov-and-downloads.md。

测试样例参数是对 configs/config_maisi_diff_model_rflow-mr.json 的一个小型 JSON 覆盖配置。传入 default 可使用上游默认值以及 CLI 模态和随机种子。常见的覆盖键包括 dim、spacing、num_inference_steps、cfg_guidance_scale 和 modality。

每次运行都会记录暂存的配置、模型清单、上游命令、输出几何信息、间距、仿射变换、强度范围，以及数据非恒定／有限性检查结果。输出体数据均为合成数据，未经独立审核，不可安全地用作生产训练数据。

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