企业官网建设流程全解析

• 媒体生成
• 计算机视觉
• 深度学习
• 人工智能
• 大模型

导读

本文以 .dev_scripts/README.md 为骨架，系统讲解 OpenMMLab MMagic 仓库中面向开发者的一整套自动化脚本工具：包括单元测试覆盖检查、全模型 checkpoint 下载与基准测试、基于 Slurm 集群的 Debug/FP32/FP16 三种训练流程、训练任务监控、选择性重跑/跳过任务、确定性训练、文档链接校验、FLOPs 计算与 model-index 自动更新。读者学完后，可以独立使用这套工具链完成 MMagic 全仓库模型的回归验证、大规模集群训练调度与文档质量保障。文中所有命令与参数均以当前仓库 .dev_scripts 目录下的真实脚本实现为准，并给出对应源码位置供深入研读。

一、工具链总览

MMagic 的.dev_scripts目录维护了一套面向仓库维护者（而非终端用户）的开发辅助脚本。下表汇总了各脚本与本文各章节的对应关系：

其中train_benchmark.py、test_benchmark.py均以仓库根目录的 model-index.yml 为输入数据源（通过modelindex库加载），因此本文介绍的所有"全模型"操作都以该索引文件中的Models条目为基准。

二、检查单元测试覆盖率（update_ut.py）

2.1 基本用法

文档给出的命令为：

cd mmagic/ python .dev_scripts/update_ut.py

注意：原文档此处写作.dev_script/update_ut.py，实际仓库目录名为.dev_scripts，执行时请使用python .dev_scripts/update_ut.py。

运行后，脚本会输出三类问题清单：

• Additional UT：tests/下存在、但mmagic/中找不到对应源码文件的测试（冗余测试）；
• Missing UT：mmagic/下有源码、但tests/下缺少对应测试文件（缺失测试）——脚本会自动创建一个空白的占位测试文件；
• Blank UT：对应测试文件已存在，但内容行数不超过 3 行（空白测试），需要开发者根据源码实现补充。

2.2 源码实现原理

从 update_ut.py 源码（第 31–79 行）可以看到其映射逻辑：

1. 递归扫描mmagic/**/*.py全部源码文件（第 37 行）；
2. 通过--exclude参数跳过无需测试的文件，默认排除项包括__init__.py、registry.py、version.py、__pycache__、stylegan3_ops/*、conv2d_gradfix.py、grid_sample_gradfix.py、misc.py、upfirdn2d.py、all_gather_layer.py、typing.py等（第 13–20 行）；
3. 按规则把源码路径映射为测试路径：mmagic→tests，并在目录名前加test_前缀、文件名前加test_前缀（第 45–55 行），例如mmagic/models/editors/sagan/sagan.py对应tests/test_models/test_editors/test_sagan/test_sagan.py；
4. 最后对比tests/test_*/**/*.py中已有的测试文件，得出三类清单（第 65–79 行）。

该脚本可通过--src、--dst、--exclude自定义扫描范围与排除规则，例如只检查mmagic/apis目录：python .dev_scripts/update_ut.py --src mmagic/apis --dst tests/test_apis。实际测试布局可对照 tests/test_models/test_editors 与 tests/test_apis 验证。

三、测试全部模型（download_models.py + test_benchmark.py）

文档给出的两步流程为：

python .dev_scripts/download_models.py python .dev_scripts/test_benchmark.py

结合源码，实际调用比文档更细，下面分别展开。

3.1 批量下载预训练权重

download_models.py 从 model-index.yml 解析每个模型的weights字段，剔除https://download.openmmlab.com/mmediting/前缀后按TASK/METHOD/MODEL.pth的目录结构保存到work_dirs/download下（默认DOWNLOAD_DIR，第 16–17 行）。

常用参数（对应源码第 51–68 行的parse_args）：

源码中值得注意的两点（第 21–48、128–153 行）：

• 除模型权重外，脚本还会自动下载仓库依赖的辅助权重，如人脸关键点2DFAN4、s3fd与vgg19，统一放到<checkpoint_root>/hub/checkpoints/，供需要感知网络的模型（如人脸相关生成模型）使用；
• 下载优先使用wget -q --show-progress -p <root> <url>，对旧版 wget 自动降级为wget -P <root> <url>。

3.2 提交全模型基准测试

test_benchmark.py 的位置参数与文档不同：partition和checkpoint_root都是必填位置参数（源码第 26–28 行），因此实际用法形如：

python .dev_scripts/test_benchmark.py <partition> <checkpoint_root> \ [--job-name <前缀>] [--work-dir <结果目录>] \ [--use-ceph-config] [--run] [--local] [--models <正则>...]

• partition：Slurm 集群分区名；checkpoint_root：第 3.1 步下载权重的根目录，可传s3://开头的路径（源码会通过mmengine.fileio.FileClient检测 Ceph 对象存储上的文件是否存在，第 119–131 行）；
• 默认只打印每个模型将要生成的job.sh脚本预览与 shell 命令，只有加上--run才会真正sbatch提交（第 255–273 行）；
• 每个测试任务固定申请 2 块 GPU、每节点 2 个任务、每任务 16 个 CPU 核（源码第 160–164 行），调用 tools/test.py 并把--out=<work_dir>/<model>/result.pkl传给测试脚本，用于后续汇总；
• --P0与--model-list互斥（源码第 72–80 行），用于只测试 P0 优先级清单或指定模型清单；
• --use-ceph-config会把配置路径中的configs替换为configs_ceph（第 95–96 行），配合第 4 节生成的 Ceph 配置使用。

3.3 测试结果汇总

test_benchmark.py支持--summary模式：读取各模型work_dir/<model>/result.pkl，与model-index.yml中记录的期望指标对比，按 metric_mapping.py 定义的映射（PSNR/SSIM/FID/NIQE 等各类指标及其容差tolerance与方向rule）输出富文本表格；--save可把表格另存为test_benchmark_summary.md，--by-task则按任务类型（如修复、抠图、生成）分别汇总。颜色规则见源码第 297–303 行：达标为绿色、超标为红色（方向由rule决定），未在容差内即视为回归。

四、训练全部模型（create_ceph_configs.py + train_benchmark.py）

"训练全部模型"是这套工具链的核心，分为配置生成与任务提交两个阶段。由于 MMagic 内部数据集存放于 Ceph（openmmlab:s3://openmmlab/datasets/...），训练前必须先通过create_ceph_configs.py把configs/下的本地数据路径批量改写为 Ceph 路径。

4.1 Debug 快速训练（第 3.1 节）

# create configs python .dev_scripts/create_ceph_configs.py \ --target-dir configs_ceph_debug \ --gpus-per-job 2 \ --iters 100 \ --save-dir-prefix work_dirs/benchmark_debug \ --work-dir-prefix work_dirs/benchmark_debug

参数含义（原文档已给出，结合源码补充默认值）：

若只想更新某一个配置，用--test-file：

python .dev_scripts/create_ceph_configs.py \ --test-file configs/aot_gan/aot-gan_smpgan_4xb4_places-512x512.py

--test-file模式下脚本会把该配置复制到configs_ceph/对应位置并单独处理（源码第 326–331 行），适合先验证单个配置再全量生成。

源码要点（create_ceph_configs.py）：

• 全量模式下先用shutil.copytree('configs', args.target_dir)复制整棵配置树，再递归处理每个.py，_base_下的基础配置会被跳过（第 139–141、298–315 行）；
• update_intervals（第 11–29 行）：当指定--iters时，把train_cfg改写为IterBasedTrainLoop且val_interval = iters // 5，LoggerHook间隔为iters // 10，CheckpointHook间隔为iters // 15；
• convert_data_config（第 32–135 行）：把data_root/data_roots（PGGAN 用字典形式）中的data、./data前缀替换为openmmlab:s3://openmmlab/datasets/classification/或.../editing/（ImageNet、CIFAR10 归入 classification，其余归入 editing），并同步改写LoadImageFromFile、LoadMask、RandomLoadResizeBg、CompositeFg等 pipeline 中的文件访问后端为petrel；
• 可视化后端（第 187–243 行）：可按需追加PaviVisBackend（以目录名作为project、配置名作为exp_name）、WandbVisBackend与TensorboardVisBackend；
• logger 与 checkpoint 的out_dir被改写为save_dir（第 245–255 行），即训练日志与权重默认落到 Ceph 存储桶。

4.2 提交训练任务

python .dev_scripts/train_benchmark.py mm_lol \ --config-dir configs_ceph_debug \ --run \ --gpus-per-job 2 \ --job-name debug \ --work-dir work_dirs/benchmark_debug \ --resume \ --quotatype=auto

其中位置参数partition（此处为mm_lol）是 Slurm 分区名。各选项含义如下（源码第 87–149 行）：

源码要点（train_benchmark.py）：

• 以 model-index.yml 为数据源，'cvt'开头的转换型配置会被跳过（第 315–317 行），无results记录的模型也跳过（第 310–312 行）；
• 每个模型的 GPU 数优先取 metafile 中Metadata['GPUs']，缺失时从配置文件名正则\d+xb\d+推断，推断失败默认 1 卡，再与--gpus-per-job取较小值（第 195–210 行）；
• 为每个模型生成独立job.sh（含#SBATCH --gres=gpu、--ntasks、--cpus-per-task、MASTER_PORT等），调用 tools/train.py 并追加--launcher=slurm、--resume、--amp、--cfg-options randomness.deterministic=True等参数（第 236–267 行）；
• 提交后会把JOBID @ JOBNAME列表写入形如train-YYYYMMDD-HHMMSS.log的历史文件（第 343–351 行），这是第 5 节监控、第 6–8 节重跑/跳过/失败重跑的数据基础。

4.3 FP32 全量训练（第 3.2 节）

# create configs for fp32 python .dev_scripts/create_ceph_configs.py \ --target-dir configs_ceph_fp32 \ --gpus-per-job 4 \ --save-dir-prefix work_dirs/benchmark_fp32 \ --work-dir-prefix work_dirs/benchmark_fp32 python .dev_scripts/train_benchmark.py mm_lol \ --config-dir configs_ceph_fp32 \ --run \ --resume \ --gpus-per-job 4 \ --job-name fp32 \ --work-dir work_dirs/benchmark_fp32 \ --quotatype=auto

该流程即"常规精度"（与configs/原始设置一致）的全量复现，4 卡/任务，--resume保证断点续训。

4.4 FP16（AMP）训练（第 3.3 节）

python .dev_scripts/create_ceph_configs.py \ --target-dir configs_ceph_amp \ --gpus-per-job 4 \ --save-dir-prefix work_dirs/benchmark_amp \ --work-dir-prefix work_dirs/benchmark_amp python .dev_scripts/train_benchmark.py mm_lol \ --config-dir configs_ceph_amp \ --run \ --resume \ --gpus-per-job 4 \ --amp \ --job-name amp \ --work-dir work_dirs/benchmark_amp \ --quotatype=auto

与 FP32 的唯一区别是提交时追加--amp（源码第 261–262 行），该参数会传入 tools/train.py 开启自动混合精度。仓库中部分原生配置本身就带有 fp16 设置（如 configs/styleganv2/stylegan2_c2-PL-R1_8xb4-apex-fp16-no-scaler-800kiters_ffhq-256x256.py），可通过--models筛选单独验证。

五、监控训练任务（job_watcher.py）

提交任务后会产生xxx.log（形如train-20220923-140317.log）记录所有任务的 job id 与 job name。监控命令为：

python .dev_scripts/job_watcher.py --work-dir work_dirs/benchmark_fp32/ --log 20220923-140317.log

注意：按当前仓库 job_watcher.py 的实现（第 149–170 行），实际参数名为--list（读取该 log 文件）而非--log，用法为：

python .dev_scripts/job_watcher.py --list 20220923-140317.log --work-dir work_dirs/benchmark_fp32/

脚本会为每个任务调用swatch examine <job_id>查询状态（running/success/queue/failed 等），读取对应job.<id>.out输出文件的最新 7 行（第 55–73 行），最终生成：

• 同名 CSV 文件（如20220923-140317.csv），报告每个 job 的 Name、ID、Status 与最近日志；
• 同时把纯文本状态表写入status.log。

此外，job_watcher.py 还内置了一个交互式 TUI（基于simple_term_menu，第 135–146 行）：不传--list时默认从~/.task_watcher/latest恢复上次任务列表，支持--type（默认failed，可选 running/success/queue/failed/all）过滤、--resume指定缓存文件，可在终端中逐任务查看尾部日志或整体状态。状态查询与过滤逻辑（get_info_from_id/filter_jobs）位于 .dev_scripts/utils/job_util.py，任务行格式统一为JOBID @ JOBNAME。

六、只训练部分模型（--rerun + --rerun-list）

当只需重跑个别模型时，用--rerun配合--rerun-list指定模型清单：

python .dev_scripts/train_benchmark.py mm_lol \ --config-dir configs_ceph_fp32 \ --run \ --resume \ --gpus-per-job 4 \ --job-name fp32 \ --work-dir work_dirs/benchmark_fp32 \ --quotatype=auto \ --rerun \ --rerun-list 20220923-140317.log

--rerun-list接受一个包含模型名的文件（log 文件即可）。源码中--rerun读取该文件得到 job 列表，--rerun-list得到的模型名集合将作为白名单过滤，只有名单内的模型才会生成任务（train_benchmark.py 第 213–217 行）。更轻量的替代方案是直接用--models传正则（如--models sagan pix2pix），二者可以配合使用。

七、跳过部分模型（--skip + --skip-list）

与重跑相反，若希望"全量训练但跳过某些模型"，使用--skip：

python .dev_scripts/train_benchmark.py mm_lol \ --config-dir configs_ceph_fp32 \ --run \ --resume \ --gpus-per-job 4 \ --job-name fp32 \ --work-dir work_dirs/benchmark_fp32 \ --quotatype=auto \ --skip \ --skip-list 20220923-140317.log

--skip读取--skip-list指定的文件作为黑名单，名单内的模型不生成任务（源码第 151–156、213 行）。两个模式实现上的区别在于：--skip在parse_args阶段直接读取文件填充args.skip_list，而--rerun会先解析 job 列表再交给--rerun-list使用。

八、重跑失败或被取消的任务（--rerun-fail / --rerun-cancel）

基于上次提交的历史 log，可以只重跑失败或被取消的任务：

python .dev_scripts/train_benchmark.py mm_lol \ --job-name RERUN \ --rerun train-20221009-211904.log \ --rerun-fail \ --run

• --rerun-fail：只重跑状态为 FAILED 的任务；
• --rerun-cancel：只重跑状态为 CANCELLED 的任务；
• 二者可同时使用，即同时重跑失败与被取消的任务。

实现上，parse_args会解析 log 中每个 job 的 id，通过swatch examine查询状态，并用 utils/job_util.py 的filter_jobs按['FAILED']/['CANCELLED']过滤（train_benchmark.py第 157–173 行），过滤结果以富文本表格打印。

还可以用--models进一步把重跑范围限定为失败/取消任务中的子集：

python .dev_scripts/train_benchmark.py mm_lol \ --job-name RERUN \ --rerun train-20221009-211904.log \ --rerun-fail \ --models sagan \ # only rerun 'sagan' models in all failed tasks --run

九、确定性训练（--deterministic）

深度学习中 cuDNN 的随机算法会导致训练结果不可复现。开启确定性训练需满足：

• torch.backends.cudnn.deterministic = True
• torch.backends.cudnn.benchmark = False

在基准训练命令中追加--deterministic即可消除随机性影响：

python .dev_scripts/train_benchmark.py mm_lol --job-name xzn --models pix2pix --cpus-per-job 16 --run --deterministic

从源码看，--deterministic会做两件事（第 250–251、264–265 行）：

1. 在生成的job.sh中导出CUBLAS_WORKSPACE_CONFIG=:4096:8，保证 cuBLAS 工作空间配置固定；
2. 给 tools/train.py 追加--cfg-options randomness.deterministic=True，即通过 MMEngine 的randomness配置项关闭 cudnn benchmark 并固定随机种子。

十、自动检查文档链接（doc_link_checker.py）

文档链接是文档质量的重要组成。用以下命令批量校验：

python .dev_scripts/doc_link_checker.py --target docs/zh_cn python .dev_scripts/doc_link_checker.py --target README_zh-CN.md python .dev_scripts/doc_link_checker.py --target docs/en python .dev_scripts/doc_link_checker.py --target README.md

--target既可以是文件也可以是目录，--ignore可忽略指定目录。其检查逻辑（doc_link_checker.py 第 28–91 行）：

• 用正则\[.*?\]\(.*?\)提取 Markdown 链接，跳过代码块（``` 围栏内不检查）与图片链接；
• http(s)://开头的链接中，只有download.openmmlab.com域名会发 HEAD 请求验证（状态码须为 200），其余外部链接不检查；
• 锚点（#开头）与<>跳过；xxx.md#anchor截取#前部分校验；
• 相对链接按文档所在目录解析，若目标文件不存在则记录为错误并抛出异常。

注意：文档明确提示，该脚本不要接入 CI——CI 环境中大量并发 HTTP 请求会触发 503，导致 CI 误报失败。

十一、计算 FLOPs

原文档给出的命令为：

python .dev_scripts/benchmark_valid_flop.py --flops --flops-str

说明：当前仓库的.dev_scripts目录下并不存在benchmark_valid_flop.py文件，该命令属于文档中的历史残留。实际计算模型 FLOPs 与参数量应使用仓库维护的分析工具 tools/analysis_tools/get_flops.py，例如：

python tools/analysis_tools/get_flops.py <配置文件路径> [--shape 输入尺寸]

此外 .dev_scripts/inference_benchmark.sh 提供了推理侧的性能基准脚本，可配合 tools/analysis_tools/print_config.py 先查看解析后的完整配置再计算 FLOPs。

十二、更新 model index（update_model_index.py）

MMagic 的 model-index.yml 是 MIM（Model Index Manager）依赖的索引文件，同时驱动着上文download_models.py、test_benchmark.py、train_benchmark.py三个脚本的模型枚举。手动维护极易出错，因此仓库提供了自动生成脚本：

python .dev_scripts/update_model_index.py

其工作流程（update_model_index.py）：

1. 解析 README 生成 metafile（第 101–240 行）：扫描configs/**/README.md，从标题行解析模型名与年份，从Task行解析任务类型，从 Markdown 表格解析Model（配置路径）、Dataset、Download（权重链接）与各指标列（如 PSNR/SSIM 支持xx/xx形式拆分为 dict），生成对应目录下的metafile.yml；
2. 汇总生成 model-index（第 243–264 行）：收集所有metafile.yml的相对路径写入根目录model-index.yml的Import字段；
3. 差异检测：通过utils.dump_yaml_and_check_difference对比新旧内容，若文件有变化则退出码为 1（源码第 267–291 行），因此该脚本被设计为可接入 pre-commit 钩子，提交前自动同步元数据。

文档同时给出了 metafile 的字段规范（Collection与Model两类，含Name、Config、Results、Weights、Metadata等字段及各自的必填/可选属性），开发者新增模型时按此规范补充configs/<算法>/README.md后运行该脚本即可自动维护索引。

十三、结语：一条完整的模型回归工作流

把上述工具串联起来，就得到 MMagic 维护者每日的例行工作流：

1. 改代码→ 运行python .dev_scripts/update_ut.py补齐缺失/空白 UT；
2. 准备数据→python .dev_scripts/create_ceph_configs.py --target-dir configs_ceph_debug --iters 100生成 Debug 配置；
3. 小规模验证→train_benchmark.py <partition> --config-dir configs_ceph_debug --run --resume快速跑通全管线；
4. 全量训练→ 按 FP32 / FP16 分别生成configs_ceph_fp32/configs_ceph_amp并提交，辅以--deterministic、--quotatype=auto；
5. 监控→job_watcher.py --list <历史log>生成 CSV，异常任务用--rerun --rerun-fail定向重跑；
6. 测试回归→download_models.py拉权重 →test_benchmark.py <partition> <checkpoint_root> --run→--summary --save汇总；
7. 发布前→doc_link_checker.py --target docs/...校验链接，update_model_index.py同步 metafile 与 model-index，最后用tools/analysis_tools/get_flops.py补充 FLOPs 数据。

这套脚本体系与 tools/train.py、tools/test.py、model-index.yml 及 configs 各算法配置紧密耦合，理解其参数与源码实现，是参与 MMagic 大规模模型训练与发布流程的必备技能。

• 媒体生成
• 计算机视觉
• 深度学习
• 人工智能
• 大模型