nv-generate-mr-brain

NV-Generate-MR-Brain

用途

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

说明

• 更改参数、副作用或验证门槛前，请先阅读 skill_manifest.yaml。
• 通过下方所述命令运行 scripts/run_mr_brain.py；将输出保存在调用方提供的运行目录下。
• 如果宿主 Agent 提供 run_script，请使用 run_script("scripts/run_mr_brain.py", args=[...])；否则运行下方所示的 Bash/Python 命令。
• 如果是审查命令格式，请勿安装软件包、克隆代码仓库、下载权重或启动 GPU 推理。仅输出包含所提供配置路径以及显式 --output-dir、--modality 和 --random-seed 值的准确封装命令。
• 如果要执行运行，请输出单个 bash 代码块，并在同一命令中保留 python -m pip install -r "$NV_GENERATE_ROOT/requirements.txt" 步骤——运行环境可能是全新环境，不包含 nibabel/MONAI，因此省略安装步骤会导致 ModuleNotFoundError。
• 如果选择 --modality mri_mra，请说明上游报告的 MRA 训练覆盖较少，且不保证输出质量。
• 不要添加 rm、mkdir 或对 --output-dir 的任何清理操作；封装脚本会创建该目录。请改用新的 --output-dir，而不是删除已有目录。
• 在将运行结果视为证据前，请检查生成的 JSON 和配套的验证器说明。

示例

仅审查命令格式（不进行设置或执行）：

python skills/nv-generate-mr-brain/scripts/run_mr_brain.py \
  PATH_TO_MR_BRAIN_CONFIG.json \
  --output-dir runs/nv_generate_mr_brain_demo \
  --modality mri_t1 \
  --random-seed 1234

如需执行运行，请使用 用法下方包含设置步骤的命令。

可用脚本

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

前提条件

• 运行时要求：清单中声明的 GPU/CUDA；以及 runtime.side_effects.pip_packages 中列出的 Python 软件包。
• 副作用：在调用方的 --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-brain 生成的合成脑部 MRI 体积数据仅包含图像，不会生成配对的分割掩膜。
• 输出体积数据为合成数据。未经独立质量审查，不适合用作生产医疗技术模型的训练数据。
• 不得用于临床部署、临床解读、自主诊断或监管申报。

故障排查

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

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

精确的可运行接口

用户运行命令时，请准确使用此仓库根目录下的包装器路径：

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

不要臆造 generate.sh、infer.py、Medical AI Skills run 或 python -m nv_generate_mr_brain 命令。PATH_TO_MR_BRAIN_CONFIG.json 必须是用户提供的请求路径。

前置条件

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

if [ -z "${NV_GENERATE_ROOT:-}" ]; then
  export NV_GENERATE_COMMIT=da438fec6484cdb6f421f8c7051d954ebefff730
  export NV_GENERATE_ROOT="$HOME/.cache/nvidia-skills/upstreams/NV-Generate-CTMR-da438fe"
  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"

只有当 NV_GENERATE_ROOT 位于清单指定的确切提交，且其跟踪文件干净时，包装器才会执行上游代码。将模型权重保留为 models/ 下未跟踪的文件，并使用包装器覆盖 JSON，而不要编辑上游配置。子进程只会接收运行时、CUDA、区域设置和证书变量的允许列表；不会转发 API 密钥、令牌、密码及其他无关的父进程环境变量。

从清单指定的确切修订版本下载复用的自编码器和 MR-Brain v1 检查点：

python -m huggingface_hub.commands.huggingface_cli download \
  nvidia/NV-Generate-CT models/autoencoder_v1.pt \
  --revision 75ac080fb1083c403793563477724c038e7d430c \
  --local-dir "$NV_GENERATE_ROOT"
python -m huggingface_hub.commands.huggingface_cli download \
  nvidia/NV-Generate-MR-Brain models/diff_unet_3d_rflow-mr-brain_v1.pt \
  --revision ef9759bf221265b2704569cdeeac20bbf03b62ee \
  --local-dir "$NV_GENERATE_ROOT"

包装器会在启动推理前，根据已发布的 Git LFS SHA-256 对象 ID 验证这两个下载文件。

运行时需要至少配备 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-brain/scripts/run_mr_brain.py 前返回 Medical AI Skills 仓库。

用法

export NV_GENERATE_ROOT="${NV_GENERATE_ROOT:-$HOME/.cache/nvidia-skills/upstreams/NV-Generate-CTMR-da438fe}" && \
python -m pip install -r "$NV_GENERATE_ROOT/requirements.txt" && \
python skills/nv-generate-mr-brain/scripts/run_mr_brain.py \
  PATH_TO_MR_BRAIN_CONFIG.json \
  --output-dir runs/nv_generate_mr_brain_demo \
  --modality mri_t1 \
  --random-seed 1234

将 PATH_TO_MR_BRAIN_CONFIG.json 替换为用户实际请求／配置文件的路径。除非用户明确要求运行该夹具，否则不要复制本文档中的夹具路径。如果用户说“请求位于 runs/.../default_mri_t1.json”，则该确切路径就是 scripts/run_mr_brain.py 的第一个位置参数。

支持的 MR 脑部模态名称包括 mri、mri_t1、mri_t2、mri_flair、mri_mra、mri_swi、mri_t1_skull_stripped、mri_t2_skull_stripped、mri_flair_skull_stripped、mri_mra_skull_stripped 和 mri_swi_skull_stripped。这些名称对应 README 中所述的上游 configs/modality_mapping.json ID。 有关 FOV 和设置的详情，请参阅 references/fov-and-downloads.md。

固定的 v1 配置提供轴向 T1w 默认值：dim=[256,256,128]、spacing=[0.94,0.94,1.36]、30 个推理步骤以及 cfg_guidance_scale=2。除非针对特定模型的验证证明有必要覆盖，否则请保留暂存的配置值；较早的示例可能描述 v0 的 256^3／1 mm 几何参数或 guidance scale 10。v1 支持 MRA，但上游训练数据报告中 MRA 扫描数量较少，因此无法保证输出质量。

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

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

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