nv-generate-mr-brain

NV-Generate-MR-Brain

用途

• 用于通过 NV-Generate-CTMR rflow-mr-brain 生成合成脑部 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 命令。
• 请输出单个 Bash 代码块，并在同一条命令中保留 python -m pip install -r "$NV_GENERATE_ROOT/requirements.txt" 步骤——运行环境可能是没有 nibabel/MONAI 的全新环境，省略安装步骤会导致 ModuleNotFoundError。
• 不要添加 rm、mkdir 或任何清理 --output-dir 的操作；封装程序会创建该目录。请使用新的 --output-dir，不要删除已有目录。
• 在将运行结果视为证据之前，请检查生成的 JSON 和配套验证器指南。

可用脚本

脚本	用途	参数
scripts/run_mr_brain.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-brain 生成的合成脑部 MRI 体积仅包含图像，不会输出配对的分割掩码。
• 输出体积为合成数据。未经独立质量审查，不可安全地用作生产医疗技术模型的训练数据。
• 不得用于临床部署、临床解读、自主诊断或监管申报。

故障排除

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

封装上游 NVIDIA-Medtech/NV-Generate-CTMR 中的仅生成 MR 脑部图像工作流。封装程序不会重新实现 扩散采样或自编码器解码。它会暂存配置覆盖项，运行针对 rflow-mr-brain 文档记录的 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-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 必须是用户提供的请求路径。

前提条件

克隆并安装上游仓库一次。在此 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-brain 权重：

cd "$NV_GENERATE_ROOT"
python -m scripts.download_model_data --version rflow-mr-brain --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-brain/scripts/run_mr_brain.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-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-brain 模态名称包括 mri、mri_t1、mri_t2、mri_flair、mri_swi、mri_t1_skull_stripped、mri_t2_skull_stripped、mri_flair_skull_stripped 和 mri_swi_skull_stripped。这些名称对应 README 中说明的上游 configs/modality_mapping.json ID。 有关 FOV 和设置的详情，请参阅 references/fov-and-downloads.md。

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

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

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