⚡

NV生成MR脑部微调Skill nv-generate-mr-brain-finetune

该技能用于微调NVIDIA NV-Generate-CTMR的MR脑部v1扩散UNet模型，支持T1、T2、FLAIR、SWI、MRA等模态的NIfTI数据。它负责配置暂存、数据嵌入生成、模型训练与推理，输出检查点及合成影像，适用于医学影像生成、多模态MRI合成、医学AI模型微调等场景。

医学影像生成 0 次安装 0 次浏览 更新于 9/6/2026
名称 nv-generate-mr-brain-finetune
描述 用于从NIfTI数据列表对NV-Generate-CTMR MR-Brain v1进行T1、T2、FLAIR、SWI或MRA数据的微调。不用于临床或生产数据审批。
开源协议 Apache-2.0 allowed-tools: Bash, Read, Write, WebFetch, Env permissions: [env, file_read, file_write, network, shell] metadata:
作者 NVIDIA MedTech Team tags: - MedTech - MRI - 脑部 - 微调

NV-Generate-MR-Brain-Finetune（NV生成MR脑部微调）

目的

  • 用于从用户提供的T1、T2、FLAIR、SWI或MRA NIfTI训练体积中微调NV-Generate-CTMR rflow-mr-brain v1扩散UNet。
  • 不用于临床解读、监管用途，或批准用于生产训练的合成数据。
  • 该包装器在本地暂存配置胶水，并将执行委托给现有的上游脚本：scripts.diff_model_create_training_data、scripts.diff_model_train，以及可选的scripts.diff_model_infer。它不执行笔记本。
  • 清单输入/输出：输入为datalist和data_base_dir；输出为finetuned_checkpoint、可选的inference_outputs和result_json。
  • 底层训练合约是上游配置/环境JSON（与train_diff_unet_tutorial.ipynb中单元格[10]驱动的相同）。该包装器为您暂存这些JSON文件，并将最常调优的字段暴露为CLI标志；以下章节记录这些字段、默认值以及如何监控/调优运行。

使用说明

  • 在更改参数、副作用或验证门之前，请阅读skill_manifest.yaml。
  • 从Medical AI Skills仓库根目录运行scripts/run_mr_brain_finetune.py。
  • 如果主机代理暴露run_script，请使用run_script("scripts/run_mr_brain_finetune.py", args=[...])；否则运行下面的Bash/Python命令。
  • 对于命令形状检查，不要安装软件包、克隆仓库、下载权重或启动GPU训练。仅使用提供的datalist、显式的--data-base-dir、显式的--output-dir和请求的模态发出包装器命令。
  • 当用户明确要求训练启动命令时，不要静默替换为--preflight；仅在预检请求中包含--preflight。
  • 在检查新datalist时首先使用--preflight；仅当用户明确想要启动GPU微调时移除--preflight。
  • 对于暂存的预检输入包目录，当这些文件存在时，使用BUNDLE/preflight_datalist.json作为datalist，使用BUNDLE/preflight_dataset作为--data-base-dir。

示例

从输入包验证并暂存预检微调检查（推荐的第一步——无需GPU，无需训练）。这是唯一的标准命令；将INPUT_BUNDLE和OUT_DIR替换为您的路径：

export NV_GENERATE_ROOT="${NV_GENERATE_ROOT:-$HOME/.cache/nvidia-skills/upstreams/NV-Generate-CTMR-da438fe}" && \
python skills/nv-generate-mr-brain-finetune/scripts/run_mr_brain_finetune.py \
  INPUT_BUNDLE/preflight_datalist.json \
  --data-base-dir INPUT_BUNDLE/preflight_dataset \
  --output-dir OUT_DIR \
  --modality mri_t1 \
  --preflight

对于真实的GPU微调和其他变化，请参阅下面的使用。

所请求的训练启动命令形状检查（无设置或执行）：

python skills/nv-generate-mr-brain-finetune/scripts/run_mr_brain_finetune.py \
  PATH_TO_DATALIST.json \
  --data-base-dir PATH_TO_DATA_ROOT \
  --output-dir runs/nv_generate_mr_brain_finetune \
  --epochs 2 \
  --modality mri_t1

可用脚本

脚本 用途 参数
scripts/run_mr_brain_finetune.py skill_manifest.yaml声明的主要入口点。 DATALIST.json --data-base-dir DATA_DIR --output-dir OUT_DIR [--epochs N] [--modality mri_t1] [--num-gpus N] [--no-amp] [--model-config FILE] [--download-model-data] [--run-inference] [--preflight]

先决条件

  • 显式的NV_GENERATE_ROOT可以指向调用者的本地检出，并且必须包含scripts/diff_model_create_training_data.py、scripts/diff_model_train.py和scripts/diff_model_infer.py。结果记录其当前提交。
  • 如果NV_GENERATE_ROOT未设置，包装器会在.workbench_data/upstreams/NV-Generate-CTMR中搜索。
  • CUDA_VISIBLE_DEVICES可选，可用于选择真实训练的GPU。
  • 运行时要求：真实训练需要NVIDIA CUDA GPU、来自上游requirements.txt的Python包，以及下载的MR脑部权重。
  • 副作用：在调用者提供的--output-dir下写入暂存的配置、嵌入、检查点、可选的推理图像和日志；可能在上游检出和~/.cache/huggingface/下写入模型缓存；可能联系https://huggingface.co获取模型资产以及https://github.com获取上游检出。
  • Datalist是MONAI风格的JSON对象，其training[].image路径相对于--data-base-dir。training[].modality可选，默认为mri_t1。

当未提供本地检出时，创建一次推荐的固定默认检出：

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

仅当NV_GENERATE_ROOT处于确切的清单提交且其跟踪文件干净时，包装器才执行上游代码。通过文档化的配置标志提供自定义训练和推理设置，而不是编辑检出。子进程仅接收运行时、CUDA、区域设置和证书变量的白名单；API密钥、令牌、密码和不相关的父环境值不会转发。公共v1资产不需要凭据；如果您的网络设置需要单独的下载工具，请预先下载它们。

在GPU运行之前，请下载清单声明的确切的自动编码器和MR脑部v1检查点修订版。传递--download-model-data执行相同的两个固定下载：

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"

1. 配置与环境JSON（适合您的数据）

这是围绕上游train_diff_unet_tutorial.ipynb流程的薄包装器。每次运行执行四个步骤，将繁重任务委托给模型作者的脚本：

  1. 暂存配置 — 复制三个配置JSON，仅重写运行特定的路径和n_epochs（笔记本单元格15）。
  2. python -m scripts.diff_model_create_training_data → 生成潜在*_emb.nii.gz嵌入（单元格17）。
  3. 写入嵌入sidecar文件 — 每个嵌入生成一个<emb>.nii.gz.json，包含spacing/modality（以及模型使用时的身体区域索引）。这是笔记本（单元格19）中而非上游scripts/中的粘合代码，diff_model_train需要它；该技能拥有此逻辑。
  4. python -m scripts.diff_model_train（单元格21），可选python -m scripts.diff_model_infer。

通过编辑配置JSON来调优，而不是添加标志。 所有训练/推理超参数（lr、batch_size、cache_rate、推理dim/spacing/num_inference_steps/cfg_guidance_scale等）都位于config_maisi_diff_model_rflow-mr-brain.json。编辑上游副本，或使用--model-config FILE（以及--env-config/--model-def用于另外两个）传递您自己的。包装器只重写以下字段。

环境JSON（environment_maisi_diff_model_rflow-mr-brain.json）— 包装器每次运行重写的字段：

字段 设置来源 说明
data_base_dir --data-base-dir 相对training[].image路径的根目录。
json_data_list 您的datalist 暂存副本，每个条目都填入modality。
embedding_base_dir, model_dir, output_dir --output-dir 潜在嵌入、检查点、推理图像。
modality_mapping_path 上游 将模态名称映射到整数代码。
model_filename --model-filename 输出检查点名称（默认diff_unet_3d_rflow-mr-brain_v1.pt）。
existing_ckpt_filepath 上游权重 / --existing-ckpt-filepath 起始检查点；通过--train-from-scratch清除。
trained_autoencoder_path 上游权重 / --trained-autoencoder-path 用于编码/解码潜在的VAE。

模型配置（config_maisi_diff_model_rflow-mr-brain.json）— 包装器仅触及的字段：

字段 设置来源 默认值 说明
diffusion_unet_train.n_epochs --epochs 2（上游配置自带1000） 方便覆盖（单元格15也这样做）；包装器默认较小以用于验证。
diffusion_unet_inference.modality --modality 来自modality_mapping.json 与可选的--run-inference的训练模态保持一致。

该文件中的其他所有内容（lr、batch_size、cache_rate、diffusion_unet_inference的其余部分）都保持原样——编辑JSON以更改。

固定的v1推理块默认值为dim=[256,256,128]、spacing=[0.94,0.94,1.36]、cfg_guidance_scale=2。包装器保留这些字段。较旧的v0示例可能显示256^3、1mm间距和guidance scale 10；使用暂存的v1 JSON作为执行真相来源。

运行时标志（非配置字段）：--num-gpus N（>1启动torch.distributed.run），--no-amp（禁用混合精度，传递给diff_model_train）。

--modality从configs/modality_mapping.json中选择整数代码。支持的脑部值包括mri（8）、mri_t1（9，默认）、mri_t2（10）、mri_flair（11）、mri_mra（16）、mri_swi（20），以及去除颅骨的值mri_t1_skull_stripped（29）、mri_t2_skull_stripped（30）、mri_flair_skull_stripped（31）、mri_swi_skull_stripped（32）和mri_mra_skull_stripped（33）。逐个样本的training[].modality覆盖--modality。模态也提供给步骤3的嵌入sidecar文件。上游报告的MRA训练覆盖率稀疏，因此不保证MRA输出质量。

有关端到端参考（包括示例数据下载和检查点加载），请参阅上游教程train_diff_unet_tutorial.ipynb。

2. 用法（单行训练）

仅预检：

export NV_GENERATE_ROOT="${NV_GENERATE_ROOT:-$HOME/.cache/nvidia-skills/upstreams/NV-Generate-CTMR-da438fe}" && \
python skills/nv-generate-mr-brain-finetune/scripts/run_mr_brain_finetune.py \
  PATH_TO_DATALIST.json \
  --data-base-dir PATH_TO_DATA_ROOT \
  --output-dir runs/nv_generate_mr_brain_finetune_preflight \
  --preflight

预检包输入：

export NV_GENERATE_ROOT="${NV_GENERATE_ROOT:-$HOME/.cache/nvidia-skills/upstreams/NV-Generate-CTMR-da438fe}" && \
python skills/nv-generate-mr-brain-finetune/scripts/run_mr_brain_finetune.py \
  PATH_TO_INPUT_BUNDLE/preflight_datalist.json \
  --data-base-dir PATH_TO_INPUT_BUNDLE/preflight_dataset \
  --output-dir runs/nv_generate_mr_brain_finetune_preflight \
  --preflight

GPU微调：

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-finetune/scripts/run_mr_brain_finetune.py \
  PATH_TO_DATALIST.json \
  --data-base-dir PATH_TO_DATA_ROOT \
  --output-dir runs/nv_generate_mr_brain_finetune \
  --epochs 2 \
  --modality mri_t1 \
  --run-inference

将PATH_TO_DATALIST.json和PATH_TO_DATA_ROOT替换为用户的实际路径。不要使用fixture datalist进行真实训练；它只是一个用于预检的占位符。

3. 监控训练（TensorBoard）

scripts.diff_model_train在暂存的model_dir（OUT_DIR/artifacts/models）下写入TensorBoard事件文件。针对输出目录启动TensorBoard并观察损失曲线：

python -m pip install tensorboard && \
tensorboard --logdir runs/nv_generate_mr_brain_finetune/artifacts

运行摘要写入OUT_DIR/artifacts/workflow_summary.json（检查点路径、嵌入sidecar文件、推理输出）；包装器打印到stdout的JSON镜像相同路径，加上exit_code和stderr_tail用于快速故障排查。

4. 超参数调优和常见陷阱

  • 损失不下降/不稳定 — 在模型配置JSON中降低diffusion_unet_train.lr（默认1e-5），或保持AMP开启（默认）；--no-amp较慢但在旧GPU上数值更稳定。
  • 内存不足 — 在配置JSON中将diffusion_unet_train.batch_size保持为1，将cache_rate保持为0，并在扩展前确认自动编码器/UNet适合您的GPU。多GPU（--num-gpus N）通过torch.distributed.run分片批次。
  • 样本少/快速检查 — 保持--epochs小（包装器默认2用于验证，而非收敛；上游配置自带1000）。
  • 模态条件错误 — 将--modality或每个样本的training[].modality设置为configs/modality_mapping.json中存在的值；不匹配会生成清晰错误，而不是静默错误标记潜在特征。
  • 首次运行启动慢 — diff_model_create_training_data预计算潜在嵌入一次；重用相同的--output-dir以避免重新计算。

5. 评估微调模型

将暂存的检查点（OUT_DIR/artifacts/models/<model_filename>）用作生成时的扩散UNet，然后检查合成的体数据：

  • 在这里传递--run-inference进行快速内建合理性渲染，或
  • 将nv-generate-mr-brain推理技能指向微调检查点，以生成新的脑部MRI体数据以供定性审查。

此技能仅进行文件核算和命令来源把关——解剖学真实性和下游实用性必须由领域专家在生成的图像上判断。

限制

  • 需要包含现有扩散训练脚本的当前上游NV-Generate-CTMR检出。该技能本身在本地暂存所需配置和datalist粘合代码，不依赖笔记本或PR #33。
  • 完整训练可能成本高昂，并且在不同硬件、CUDA和软件包版本上不确定。
  • 该包装器把关文件核算和命令来源，而非解剖学真实性或下游模型实用性。
  • 不用于临床部署、临床解读、自主诊断、监管提交或生产训练数据批准。

故障排除

错误 原因 修复
diffusion training scripts were not found NV_GENERATE_ROOT未指向当前的NV-Generate-CTMR检出。 克隆或更新https://github.com/NVIDIA-Medtech/NV-Generate-CTMR并设置NV_GENERATE_ROOT。
missing datalist image training[].image路径不是相对于--data-base-dir或文件不存在。 修复datalist或传递正确的数据根目录。
CUDA或MONAI导入失败 运行时环境缺少上游依赖。 在所选环境中安装"$NV_GENERATE_ROOT/requirements.txt"。