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 非商业用途。未经法律和质量审核，请勿将输出用作生产训练数据。
• 不适用于临床部署、临床解读、自主诊断或监管申报。

故障排除

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

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

可精确运行的命令

在全新的基准测试环境中运行用户命令时，请使用以下设置，并原样使用仓库根目录下的包装命令：

export NV_GENERATE_ROOT="${NV_GENERATE_ROOT:-.workbench_data/upstreams/NV-Generate-CTMR}" && \
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 必须是用户提供的请求路径。

前置条件

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

mkdir -p .workbench_data/upstreams
test -d .workbench_data/upstreams/NV-Generate-CTMR/.git || \
  git clone https://github.com/NVIDIA-Medtech/NV-Generate-CTMR.git \
    .workbench_data/upstreams/NV-Generate-CTMR
export NV_GENERATE_ROOT=.workbench_data/upstreams/NV-Generate-CTMR
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 生成的用户运行命令，请使用“用法”中的命令。如果仓库本地上游缓存已存在，不要在前面添加克隆或模型下载步骤。在全新的 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:-.workbench_data/upstreams/NV-Generate-CTMR}" && \
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。

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

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