nv-generate-ct-rflow

NV-Generate-CT（rflow-ct）

用途

• 使用 NV-Generate-CTMR rflow-ct 生成合成 CT 体数据和掩码。未经审核，不可将其用作生产环境的训练数据。
• 请严格按照文档使用包装器；不要用手写实现替换上游入口点。
• 正常运行时不要编写自定义推理代码。包装器负责配置暂存、输出路径、标签映射证据和验证。
• 清单 I/O：输入为 config_infer_override；输出为 synthetic_ct_volumes 和 result_json。

说明

• 更改参数、副作用或验证关卡前，请先阅读 skill_manifest.yaml。
• 按照下方记录的命令运行 scripts/run_rflow_ct.py；将输出保存在调用方提供的运行目录下。
• 如果宿主 Agent 提供 run_script，请使用 run_script("scripts/run_rflow_ct.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/_anatomy.py	主入口点使用的内部辅助工具。	仅导入；不要直接调用。
scripts/_summary_card.py	主入口点使用的内部辅助工具。	仅导入；不要直接调用。
scripts/list_anatomies.py	用于目录或解剖结构查询的辅助命令。	[--region REGION] [--filter TEXT] [--controllable]
scripts/run_rflow_ct.py	由 skill_manifest.yaml 声明的主入口点。	CONFIG_INFER.json --output-dir OUT_DIR [--random-seed N] [--version rflow-ct] [--yes]
scripts/run_ct_mask.py	用于独立原始 MAISI 掩码生成的高级诊断辅助工具。	REQUEST.json --output-dir OUT_DIR [--random-seed N] [--preflight-only] [--yes]
scripts/run_ct_from_mask.py	根据 MAISI 标签掩码生成 CT 图像的高级辅助工具。	REQUEST.json --output-dir OUT_DIR [--random-seed N] [--yes]
scripts/run_ct_image.py	不带配对标签生成仅含 CT 图像的高级辅助工具。	MODEL_CONFIG.json --output-dir OUT_DIR [--version rflow-ct] [--random-seed N] [--yes]

前置条件

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

限制

• 这是一个轻量包装器。推理、采样和解码完全委托给 NVIDIA-Medtech/NV-Generate-CTMR 的 scripts.inference。不要修改 $NV_GENERATE_ROOT 下的代码。
• rflow-ct 需要 CUDA；对于默认的 256³ output_size，至少需要约 16 GB 显存。更大的 output_size（例如 512×512×768）需要 A100/H100。
• 输出体数据是合成数据。未经独立质量审核，不得将其用作生产环境医疗技术模型的训练数据。
• 不得用于临床部署、临床解读、自主诊断或监管申报。

故障排查

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

封装上游的 NVIDIA-Medtech/NV-Generate-CTMR 整流流合成流水线。此包装器不会重新实现扩散、采样或自编码器解码，而是严格按照项目 README 中的说明调用上游的 scripts.inference 入口点，并检查生成的图像/掩膜对。

前置条件

1. 克隆上游仓库，并将 NV_GENERATE_ROOT 指向该仓库（仅需设置一次）：

   test -d "$HOME/nv-generate-ctmr/.git" || \
     git clone https://github.com/NVIDIA-Medtech/NV-Generate-CTMR.git $HOME/nv-generate-ctmr
   export NV_GENERATE_ROOT=$HOME/nv-generate-ctmr
   pip install -r "$NV_GENERATE_ROOT/requirements.txt"
   

2. 将 rflow-ct 权重和掩膜候选数据集下载到克隆仓库中（仅需下载一次，约 5.5 GB）：

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

   掩膜候选数据集（datasets/all_masks_flexible_size_and_spacing_4000） 用于对扩散采样器进行条件控制；如果通过 --model_only 忽略这些数据集， 推理脚本会在启动时因缺少文件而失败。 解剖尺寸条件文件也是完整 CT 下载的一部分，生成可控掩膜时需要该文件。

3. 配备显存至少为 16 GB 的 NVIDIA GPU 和 CUDA。不支持 CPU 回退。

对于 Agent 生成的用户运行命令，优先使用 Usage 中的简短包装器命令。如果 NV_GENERATE_ROOT 或仓库本地的上游缓存已存在，则不要添加克隆或模型下载步骤。在全新的 Python 环境中，除非当前环境已确认可以导入所需模块，否则仍需在包装器命令前包含 pip install -r "$NV_GENERATE_ROOT/requirements.txt"；权重已缓存并不意味着 Python 软件包也已缓存。请从 medical-AI-skills 仓库根目录运行包装器。如果设置过程需要执行 cd "$NV_GENERATE_ROOT"，则在调用 skills/nv-generate-ct-rflow/scripts/run_rflow_ct.py 前，先返回 Medical AI Skills 仓库。

用法

export NV_GENERATE_ROOT="${NV_GENERATE_ROOT:-$HOME/nv-generate-ctmr}" && \
python -m pip install -r "$NV_GENERATE_ROOT/requirements.txt" && \
python skills/nv-generate-ct-rflow/scripts/run_rflow_ct.py \
  PATH_TO_CONFIG_INFER.json \
  --output-dir runs/nv_generate_ct_rflow_demo \
  --random-seed 0 \
  --version rflow-ct

将 PATH_TO_CONFIG_INFER.json 替换为用户实际请求/配置文件的路径。除非用户 明确要求运行该测试样例，否则不要复制本文档中的测试样例路径。如果用户说“病例请求位于 runs/.../chest_lung_tumor_controllable.json”，则该确切路径就是传给 scripts/run_rflow_ct.py 的第一个位置参数。

测试样例参数是一个 config_infer.json 覆盖文件：它可以替换 num_output_samples、body_region、anatomy_list、controllable_anatomy_size、 output_size 和 spacing。传入 default 可原样使用上游配置。包装器会先将覆盖文件放入上游目录，再运行。

测试样例目录

fixtures/ 附带了针对常见成对合成用例精心整理的配置：胸部肺叶、带可控肺部肿瘤的胸部、腹部实质器官、 带可控肝脏肿瘤的腹部、头部 + 颈椎、骨盆。 完整表格请参阅 fixtures/README.md。

辅助命令

# Browse the 132-class label_dict grouped by body region.
python skills/nv-generate-ct-rflow/scripts/list_anatomies.py --region chest
python skills/nv-generate-ct-rflow/scripts/list_anatomies.py --controllable
python skills/nv-generate-ct-rflow/scripts/list_anatomies.py --filter tumor

# Validate a fixture and preview cost without launching inference.
NV_GENERATE_ROOT=$HOME/nv-generate-ctmr \
  python skills/nv-generate-ct-rflow/scripts/run_rflow_ct.py \
    skills/nv-generate-ct-rflow/fixtures/abdomen_liver_spleen.json \
    --output-dir runs/preview --preflight-only

高级辅助工具保留在此技能中，用于调试和较少见的 CT 生成模式。仅在用户明确要求使用该模式时才使用：

# Raw MAISI mask diagnostic, useful for checking lung tumor -> label 23.
python skills/nv-generate-ct-rflow/scripts/run_ct_mask.py \
  skills/nv-generate-ct-rflow/fixtures/ct_mask_lung_tumor.json \
  --output-dir runs/ct_mask_debug --preflight-only

# CT image from an existing MAISI label mask with body label 200.
python skills/nv-generate-ct-rflow/scripts/run_ct_from_mask.py \
  skills/nv-generate-ct-rflow/fixtures/ct_from_mask_request_example.json \
  --output-dir runs/ct_from_mask_demo

# CT image-only generation without paired labels.
python skills/nv-generate-ct-rflow/scripts/run_ct_image.py \
  skills/nv-generate-ct-rflow/fixtures/ct_image_only_default.json \
  --output-dir runs/ct_image_only_demo --version rflow-ct

包装器每次调用时都会运行预检（无论是否指定 --preflight-only）：检查配置架构边界、根据上游 label_dict 匹配解剖结构名称、 body_region 是否在受支持的集合中、controllable_anatomy_size 约束、 上游 CT 输出大小／间距契约、考虑身体区域的 x/y FOV 最小值、数据集是否存在于 $NV_GENERATE_ROOT/datasets/ 下、CUDA 是否可用，以及预计峰值 VRAM／ 耗时。预计耗时超过 5 min 或峰值 VRAM 超过 30 GB 的运行必须使用 --yes 才能继续。

每次调用都会运行 python -m scripts.inference -t configs/config_network_rflow.json -i configs/config_infer.json -e configs/environment_rflow-ct.json --random-seed <s> --version rflow-ct。输出证据会记录上游 git 提交、模型检查点哈希值、渲染后的配置、 每个样本的图像／掩膜几何信息、掩膜标签集、图像 HU 范围摘要，以及每类体素体积。

当 controllable_anatomy_size 非空时，上游会忽略较宽泛的 anatomy_list，并将保存的配对标签图中的标签筛选为可控解剖结构名称。 保存的配对标签值是局部的 1..N 序号，而非原始 MAISI 标签 ID。读取 result_json 中的 output.output_label_mapping，将保存的输出标签映射回源标签；例如， 输出标签 1 可以对应 MAISI 标签 23（lung tumor）。 对于经过筛选的肺肿瘤示例，建议使用约 0.5 或更大的可控尺寸；对于某些随机种子， 较小的请求（例如 0.2）可能会导致标签 23 对应的组件缺失或极小。

有关 FOV 和设置详情，请参阅 references/fov-and-downloads.md。有关 高级辅助工具的标签空间详情，请参阅 references/ct-mask-label-space.md 和 references/ct-from-mask-format.md。

可视化样本卡片

除了 NIfTI 图像对，包装器还会在输出目录中写入 summary.html：每个样本包含 带标签叠加的中间切片三联图（轴向／冠状／矢状），以及渲染后配置和 供验证器查看的汇总数据表。无需启动 3D Slicer 即可快速查看结果。 传入 --no-summary-card 可跳过此步骤。

解剖结构合理性（标签集检查、作为 CT 的体素 HU 范围、图像／掩膜几何信息匹配、 声明的输出标签均存在、肺叶 HU 下限）由 verifiers/ct_synthesis_quality_v1 检查。

不得用于临床解读、生产部署训练数据或任何非合成研究用途。