open-mmlab/mmagic · 上手攻略

  • 仓库：open-mmlab/mmagic
  • 链接：https://github.com/open-mmlab/mmagic
  • 分类：academic-writing · image-generation · image-restoration · video-editing
  • 作者：spark
  • 更新：2026-08-18

1. 这是什么

MMagic（Multimodal Advanced, Generative, and Intelligent Creation）是 OpenMMLab 体系下的 AIGC 工具箱，是 MMEditing 与 MMGeneration 合并后的统一继承者。它提供从底层 PyTorch 训练到高层 MMagicInferencer 的全套接口，覆盖图像 / 视频的生成、编辑、修复、超分、上色、3D-aware 生成等任务。

⚠️ README 自报最新 release 为 v1.2.0（2023-12-18），截至 2026-08-18 公开搜索未发现更新 release。仓库仍处于"可用但节奏放缓"的状态；新模型（如 Flux / SD3）不在 MMagic 模型库内——若你要的是前沿 diffusion，不是它。

适合：要快速跑通 Stable Diffusion / ControlNet / DreamBooth / NAFNet / SwinIR / Restormer / DragGAN / EG3D / PowerPaint 等经典模型的研究者、AIGC 内容创作者、CV 工程师。

不适合：要 SOTA 闭源 / 前沿 diffusion、需要企业级 SLO 与最新模型权重管理。

2. 解决什么问题

把"几十种 CV / AIGC 任务的 PyTorch 实现"统一到一套接口下，让研究者不用为每个模型写独立的 dataloader / training loop / evaluator / visualizer。具体来说：

  • 统一接口：Diffusion / GAN / Image Restoration / Super-Resolution / Colorization / 3D-aware 生成 都用同一套 MMagicInferencer API
  • 统一训练框架：基于 MMEngine + MMCV，分布式训练 / 混合精度 / 评估循环（MultiValLoop / MultiTestLoop）/ 可视化（TensorBoard + Wandb）/ 33+ 算法 PyTorch 2.0 加速是同一套配置
  • 统一评估：同时支持生成型（FID）和重建型（SSIM）指标，并支持多数据集并行评估
  • 模型库（model zoo）：内置数十个预训练权重，开箱即用

3. 快速安装

3.1 前置

  • Linux / Windows / macOS
  • Python ≥ 3.7（README "best practice" 推荐 3.9+）
  • PyTorch ≥ 1.8（best practice 2.0+）
  • MMCV ≥ 2.0.0
  • CUDA 11（推荐 Ampere 及以上 GPU；老 GPU 兼容 CUDA 10.2，但 11 是默认）

3.2 标准安装（best practice，来自 docs）

# Step 0：装 PyTorch（按 https://pytorch.org/get-started/locally/ 选 GPU / CPU 版本）
# GPU 例：
conda install pytorch torchvision cudatoolkit=11.3 -c pytorch
# CPU 例：
conda install pytorch=1.10 torchvision cpuonly -c pytorch

# Step 1：装 MIM（OpenMMLab 包管理器）
pip install -U openmim

# Step 2：用 MIM 装 MMCV、MMEngine、MMagic
mim install 'mmcv>=2.0.0'
mim install 'mmengine'
mim install 'mmagic'

# 验证
python -c "import mmagic; print(mmagic.__version__)"
# 期望输出形如 1.2.0

3.3 Docker 安装（来自官方文档）

# 构建镜像（Dockerfile 默认 PyTorch 1.8 + CUDA 11.1；改 Dockerfile 切版本）
docker build -t mmagic docker/

# 运行（--shm-size=8g 是 PyTorch DataLoader 多进程常用值）
docker run --gpus all --shm-size=8g -it -v {DATA_DIR}:/mmagic/data mmagic

3.4 从源码安装（拿到 main 分支最新代码）

git clone https://github.com/open-mmlab/mmagic.git
cd mmagic
pip3 install -e . -v          # 可编辑模式；改代码无须重装
# 或
pip3 install -e .[all]        # 多装 pre-commit hooks + unittest 依赖

3.5 装 MMCV 不用 MIM

如果不能或不想用 MIM，可手动指定 find-url：

pip install 'mmcv>=2.0.0' -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.10/index.html

⚠️ cu113 / torch1.10 是文档示例；其他组合见 MMCV installation。

3.6 硬件 + CUDA 版本建议（README 明确）

  • Ampere（RTX 30 / A100）→ CUDA 11 必须
  • 旧卡 → CUDA 11 向后兼容；若追求轻量 / 兼容性可选 CUDA 10.2
  • 严格按 PyTorch 自带 cudatoolkit 装即可，不需额外装完整 CUDA Toolkit；除非你要从源码编译 MMCV / CUDA 算子

4. 核心用法

4.1 五行 text-to-image（README 范例）

from mmagic.apis import MMagicInferencer

sd_inferencer = MMagicInferencer(model_name='stable_diffusion')
text_prompts = 'A panda is having dinner at KFC'
result_out_dir = 'output/sd_res.png'
sd_inferencer.infer(text=text_prompts, result_out_dir=result_out_dir)

模型首次使用会触发权重下载（按 model zoo 中对应 config 的链接）。

4.2 模型动物园覆盖（README 列举）

按任务分：

  • Conditional GANs：SNGAN/Projection GAN (ICLR'2018)、SAGAN (ICML'2019)、BIGGAN/BIGGAN-DEEP (ICLR'2018)
  • Unconditional GANs：DCGAN、LSGAN、PGGAN、SinGAN、StyleGANV1/V2/V3、DragGAN (2023)、WGAN-GP、GGAN
  • Image Restoration：SwinIR (ICCVW'2021)、NAFNet (ECCV'2022)、Restormer (CVPR'2022)
  • Image Super-Resolution：SRCNN、SRResNet&SRGAN、EDSR、ESRGAN、Real-ESRGAN 系列
  • Text2Image / Diffusion：ControlNet、DreamBooth (含 LoRA)、Stable Diffusion、Disco Diffusion、GLIDE、Guided Diffusion
  • 3D-aware Generation：EG3D
  • Image Colorization：InstColorization
  • Inpainting / Matting / 视频生成：PowerPaint、AnimateDiff、SDXL、ViCo、FastComposer（社区贡献）

完整列表见 Model Zoo。

4.3 训练 + 评估

MMagic 把训练 / 测试脚本对接到 MMEngine 的 Runner，所以典型流程是：

# 单 GPU
python tools/train.py configs/stable_diffusion/your_config.py

# 多 GPU 分布式（torchrun 是 PyTorch ≥ 1.10 官方推荐）
torchrun --nproc_per_node=4 tools/train.py configs/stable_diffusion/your_config.py --launcher pytorch

# 测试 + 评估（FID / SSIM / LPIPS 等）
python tools/test.py configs/stable_diffusion/your_config.py \
  checkpoints/your_model.pth --eval fid

⚠️ 上面 tools/train.py / tools/test.py 是 MMagic / OpenMMLab 的惯例路径（与 MMDetection 等同系列一致），具体 config 名以仓库内 configs/ 目录为准。

4.4 高级特性

  • DiffuserWrapper：让你直接用 Hugging Face diffusers 的基本模型和采样策略（README 明确写 "calling basic models and sampling strategies through DiffuserWrapper"）
  • DreamBooth LoRA：在 SD 基础上做轻量微调
  • ControlNet + SAM：动画 / 区域可控生成（社区贡献 README）
  • GAN 操控：GAN interpolation / projection / manipulation 全套接口
  • 可视化：本地文件 / TensorBoard / Wandb 三选一
  • 多数据集并行评估：通过 MultiValLoop + MultiTestLoop

4.5 复现 ≤ 10 行最小可跑命令（README "Getting Started" 节直接复制）

# 最小 text-to-image 复现脚本（README 范例）
from mmagic.apis import MMagicInferencer
inferencer = MMagicInferencer(model_name='stable_diffusion')
inferencer.infer(text='A panda is having dinner at KFC', result_out_dir='output/sd_res.png')

加上环境：

mim install 'mmcv>=2.0.0'
mim install 'mmengine'
mim install 'mmagic'
python your_script_above.py

⚠️ 首次跑会下载 SD 1.x / 2.x 权重；磁盘 / 网络 / 时间预算请按 SD 权重（几个 GB）预估。

5. 典型适用场景

  • 学术论文复现：要复现一篇 2018-2023 年的 CV 论文（GAN / Restoration / Diffusion），MMagic 几乎都有对应 config 与权重
  • AIGC 二次开发：基于 SD / ControlNet / DreamBooth 做 LoRA 微调、做动画（AnimateDiff）、做可控生成（SAM + ControlNet）
  • 图像修复流水线：把 NAFNet / Restormer / SwinIR 串成修复 pipeline（去噪 → 去模糊 → 超分）
  • 3D-aware 头像生成：用 EG3D 训练人脸或角色
  • GAN 操控研究：StyleGAN 系列 + DragGAN 的拖拽编辑
  • 3.x 老项目迁移：从 MMEditing 0.x 迁到 MMagic 1.x，参考 migration docs

6. 坑与注意

  1. 最新 release 是 2023-12：v1.2.0 之后再无 PyPI release。Flux / SD3 / Wan2.1 / CogVideoX / HunyuanVideo 等 2024-2026 的前沿模型不在 MMagic。新 diffusion 项目直接用 diffusers / HuggingFace pipeline 更划算。
  2. MMCV / CUDA / PyTorch 三方版本强耦合：装 MMCV 必须严格匹配 PyTorch + CUDA 版本。报错 90% 是这三者对不上。用 MIM 自动解决；手 pip 必须带 -f 找 URL。
  3. 不要在已有 PyTorch 的环境混装不同 CUDA runtime：先 pip uninstall torch torchvision 再装，避免链接到错误 CUDA。
  4. 数据集路径硬编码：所有 config 里的 data_root / ann_file 默认是绝对路径；跑训练前必须改 config 或用 --cfg-options data.train.dataset.data_root=... 覆盖。
  5. OOM（显存不够） 是常态：MMagic 默认 batch=全图大小，老 GPU（< 12GB）跑 SD 必 OOM。解法：勾 train_cfg / val_cfg / test_cfg 里的 data_preprocessor.cpu_offload 或用 gradient_checkpointing=True（视模型而定）。
  6. --shm-size=8g：Docker 跑 PyTorch DataLoader 多进程时共享内存不够会卡死；官方 README 写的就是 8g。
  7. PowerPaint 等项目代码在 projects/ 子目录：不是默认 install 的一部分，需要单独 cd projects/powerpaint && pip install -e .，README "What's New" 节明示。
  8. 指标解读：FID 越小越好、SSIM 越大越好；但同一模型在不同分辨率 / crop / 数据集 split 下的 FID 不可直接对比——MMagic 评估默认设了 resize=True / crop=False，跨论文对比要复现论文原始评估脚本。
  9. 视频生成 / 3D-aware 模型对显存要求：SDXL / AnimateDiff / EG3D 单卡 24GB 是底线。
  10. License：仓库根 LICENSE 显示 Apache 2.0（badge 同），但部分 model weights 走各自原始 License（如 StyleGAN 是 Nvidia Research License）；商业化前要逐模型核查权重许可。

7. 与同类对比

维度 MMagic HuggingFace diffusers torchvision / timm OpenMMLab MMPretrain
定位 AIGC 工具箱（编辑/生成/修复） Diffusion / Flow Matching 模型库 通用 CV backbone + 经典任务 预训练 backbone + 通用 CV
模型数量 数十个（GAN + Diffusion + Restoration） 数百个（仅 diffusion / flow） 数百个（backbone / 分类） 数百个（backbone / 检测 / 分割）
训练框架 MMEngine（统一） accelerate / 自带 Trainer 自写 loop 或 Catalyst MMEngine（统一）
评估 内建 FID / SSIM / LPIPS 自接 torchmetrics 自接 内建 + 多数据集
文档 / 中文支持 中英双语 README 英文为主 英文 中英双语
适合 CV / AIGC 研究 + 复现 前沿 diffusion / 通用 backbone / 分类 预训练 + 下游
不适合 最新 SOTA diffusion 完整训练流水线 AIGC 任务 AIGC

简版取舍：复现经典 CV/AIGC 论文 + 一套训练评估框架 → MMagic；最新 diffusion 模型实验 → diffusers；backbone / 分类 / 检测 / 分割 → MMPretrain / MMDetection。

8. 一句话推荐

如果你的研究 / 业务落在 2024 年之前的 CV + AIGC 范畴，要一套"训练 / 评估 / 推理 / 可视化"统一的工具箱，MMagic 仍然是 OpenMMLab 体系下最成熟的选择；如果追 2025-2026 前沿 diffusion / video，直接走 diffusers + 自训脚本。

来源与不确定处

  • 来源（已 fetch 验证）：
  • https://raw.githubusercontent.com/open-mmlab/mmagic/main/README.md 完整 raw
  • https://mmagic.readthedocs.io/en/latest/get_started/install.html 完整安装文档
  • https://github.com/open-mmlab/mmagic 仓库主页
  • 不确定处：
  • v1.2.0 之后是否真的没有新 release：PyPI 页面被反爬挡住，未独立 verify。tavily 搜索未发现 2025-2026 release；按 README 主体文字推断 v1.2.0 / 2023-12-18 仍为最新 release。引用前请回 PyPI / GitHub Releases 实测。
  • tools/train.py / tools/test.py 是否为当前默认脚本名：基于 OpenMMLab 系列惯例推断，未在本攻略独立 ls。具体以仓库根目录 tools/ 实测为准。
  • OOM 解法 / cpu_offload / gradient_checkpointing 字段：通用 PyTorch 经验，未在 MMagic README 中逐字段列出——具体 config 内字段名需看 configs/stable_diffusion/.../your_config.py 内注释。
  • PowerPaint 子项目安装：基于 README "What's New" 节推断要在 projects/ 子目录装，但未独立 verify 当前子目录结构。
  • License 模型权重细节：仓库 LICENSE = Apache 2.0（badge 与官方 OpenMMLab 风格一致），但模型权重各自原始 License 未在 README 表格化——商业化前必须逐模型查权重 LICENSE。
  • 多 GPU 分布式启动方式：torchrun 是 PyTorch 官方推荐，但 MMagic 内可能仍保留旧版 python -m torch.distributed.launch 脚本支持——以 tools/dist_train.sh 实测为准。