🌌 简介

MMaDA 是一个全新的 多模态扩散基础模型 家族，旨在文本推理、多模态理解以及文生图等多样化任务中实现卓越性能。MMaDA 的三大创新点如下：

1. MMaDA 采用 统一的扩散架构，具备共享的概率公式和模态无关的设计，从而无需针对不同模态单独构建组件。
2. MMaDA 引入了一种 混合长链式思维（CoT）微调 策略，能够跨模态整合并形成统一的 CoT 格式。
3. MMaDA 采用了基于策略梯度的统一强化学习算法——我们称之为 UniGRPO，专为扩散基础模型量身定制。通过多样化的奖励建模方式，UniGRPO 能够将推理与生成两类任务的后训练过程统一起来，确保性能持续提升。

📰 最新动态

• [2025-11-13] 我们发布了 MMaDA-Parallel，这是一类用于思考感知型图像编辑与生成的新多模态dLLM。
• [2025-09-09] 我们开源了面向dLLM的综合强化学习框架 dLLM-RL，同时发布了SOTA指令微调及长CoT模型 TraDo-8B-Instruct、TraDo-4B-Instruct 和 TraDo-8B-Thinking。
• [2025-06-02] 我们开源了 MMaDA-8B-MixCoT。
• [2025-05-24] 我们新增了对MPS推理的支持，并已在M4设备上进行了测试。
• [2025-05-22] 我们发布了MMaDA用于文本生成、多模态生成和图像生成的推理与训练代码。
• [2025-05-22] 我们开源了 MMaDA-8B-Base。
• [2025-05-22] 我们发布了关于首个统一多模态扩散模型MMaDA的研究论文（https://arxiv.org/abs/2505.15809）及其演示页面（https://huggingface.co/spaces/Gen-Verse/MMaDA）。

🧬 MMaDA系列概览

MMaDA包含一系列反映不同训练阶段的检查点：

1. MMaDA-8B-Base：完成预训练与指令微调后，具备基础的文本生成、图像生成、图像描述以及 思考能力。
2. MMaDA-8B-MixCoT：经过混合长链式思维（CoT）微调后，能够进行 复杂 的文本、多模态及图像生成推理。
3. MMaDA-8B-Max（即将发布）：在UniGRPO强化学习完成后，将在复杂推理和惊艳的视觉生成方面表现卓越，未来将正式推出。
4. MMaDA-Parallel-A 和 MMaDA-Parallel-M：这是一类 并行思考感知型 多模态扩散模型，可在整个去噪过程中实现文本与图像之间的连续双向交互。

⚙️ 快速入门

首先，请搭建环境：

pip install -r requirements.txt

然后启动本地Gradio演示：

python app.py

或者您也可以通过我们的Hugging Face演示在线体验。

🚀 推理

对于批量推理，我们在此提供相应的推理脚本。

1. 文本生成

在文本生成方面，我们沿用了LLaDA的配置与生成脚本。简单运行如下：

python generate.py

2. 多模态生成

对于多模态生成及文生图任务，首先请登录您的wandb账号：

wandb login

随后即可运行多模态生成的推理演示，并在wandb上查看结果：

python3 inference_mmu.py \
  config=configs/mmada_demo.yaml \
  mmu_image_root=./mmu_validation \
  mmu_prompts_file=./mmu_validation/prompts_with_vqa.json \

3. 文本到图像生成

对于多模态生成和文本到图像生成，首先登录您的 wandb 账户：

wandb login

文本到图像生成的推理演示，您可以在 wandb 上查看结果：

python3 inference_t2i.py config=configs/mmada_demo.yaml batch_size=1 validation_prompts_file=validation_prompts/text2image_prompts.txt guidance_scale=3.5 generation_timesteps=15
mode='t2i'

🔧 训练

请在 configs/xx.yaml 中更新您的训练数据路径。

阶段 0：准备您的 accelerate 配置

请先准备好您的 accelerate 配置。您可以简单运行：

accelerate config

或者使用我们提供的 accelerate_configs 中的配置文件：

├── accelerate_configs/ 
|   ├── 1_gpu.yaml
|   └── 8_node_8_gpus_deepspeed_zero2.yaml (用于 8 台机器、每台 8 张 GPU)

阶段 1.1：在 ImageNet 数据集上预训练

首先我们使用 LLaDA-8B-Instruct 初始化模型，并在 ImageNet 数据集上进行训练，以获得基础的视觉能力。

accelerate launch --config_file path/to/your/accelerate_config --main_process_port=8888 training/train_mmada.py config=configs/mmada_pretraining_stage1_llada_instruct.yaml

阶段 1.2：在图文数据集上预训练

接下来，我们将阶段 1.1 中的 ImageNet 数据集替换为图文数据集。请将 mmada_pretraining_stage2_llada_instruct.yaml 文件中的预训练模型路径替换为您在阶段 1.1 中得到的检查点。

accelerate launch --config_file path/to/your/accelerate_config --main_process_port=8888 training/train_mmada_stage2.py config=configs/mmada_pretraining_stage2_llada_instruct.yaml

阶段 1.3：在文本指令遵循任务上预训练

在这个阶段，我们开始进行文本指令遵循任务的训练，并加入相应的验证步骤。请将 mmada_pretraining_stage3_llada_instruct.yaml 文件中的预训练模型路径替换为您在阶段 1.2 中得到的检查点。

accelerate launch --config_file path/to/your/accelerate_config --main_process_port=8888 training/train_mmada_stage3.py config=configs/mmada_pretraining_stage3_llada_instruct.yaml

阶段 2.1：混合 CoT 训练（纯文本）

在这个阶段，我们首先进行基于文本推理的 Mix-CoT 微调，同时提升图像质量。请将 mmada_pretraining_stage3_llada_instruct.yaml 文件中的预训练模型路径替换为您在阶段 1.3 中得到的检查点，并准备好您的 CoT 数据。

accelerate launch --config_file path/to/your/accelerate_config --main_process_port=8888 training/train_mmada_stage_cot_sft.py config=configs/mmada_pretraining_stage3_llada_instruct_512_cot.yaml

阶段 2.2：混合 CoT 训练（包含多模态推理）

在这个阶段，我们加入了多模态推理，并进一步提升图像质量。请将 mmada_pretraining_stage3_llada_instruct.yaml 文件中的预训练模型路径替换为您在阶段 2.1 中得到的检查点，并准备好您的 CoT 数据。

accelerate launch --config_file path/to/your/accelerate_config --main_process_port=8888 training/train_mmada_stage4.py config=configs/mmada_pretraining_stage4_llada_instruct.yaml

阶段 3 UniGRPO RL

注意： UniGRPO 算法已被进一步实现并集成到我们的 dLLM-RL 仓库中。如果您希望将多个奖励整合在一起，需要修改的关键文件是 ./reward/rl_reward_v.py，这应该是唯一的改动。

📊 评估

更多详情请参阅 evaluation/eval.md。

📖 引用

@article{yang2025mmada,
  title={MMaDA: 多模态大型扩散语言模型},
  author={Yang, Ling 和 Tian, Ye 和 Li, Bowen 和 Zhang, Xinchen 和 Shen, Ke 和 Tong, Yunhai 和 Wang, Mengdi},
  journal={arXiv 预印本 arXiv:2505.15809},
  year={2025}
}

🤝 致谢

本工作大量借鉴了 dLLM-RL、Show-o、LLaDA、maskgit、transformers、accelerate 和 webdataset 的工作。感谢所有作者的杰出贡献。

MMaDA 快速上手指南

MMaDA 是一个全新的多模态扩散基础模型系列，旨在通过统一的扩散架构，在文本推理、多模态理解和文生图任务中实现卓越性能。本指南将帮助您快速搭建环境并运行模型。

1. 环境准备

系统要求

• 操作系统: Linux (推荐) 或 macOS (已支持 MPS 加速，已在 M4 芯片测试)。
• Python: 3.8 或更高版本。
• GPU: 推荐使用 NVIDIA GPU (需安装 CUDA)，Mac Apple Silicon 芯片可使用 MPS 进行推理。
• 依赖管理: 建议使用 conda 或 venv 创建独立虚拟环境。

前置依赖

确保已安装 Git 和基本的编译工具。若使用国内网络环境，建议在安装 Python 依赖时配置清华或阿里镜像源以加速下载。

2. 安装步骤

克隆项目

git clone https://github.com/Gen-Verse/MMaDA.git
cd MMaDA

安装依赖

使用 pip 安装所需库。国内用户推荐添加镜像源参数：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

配置 Accelerate (训练必需)

如果您计划进行模型训练或微调，需先配置分布式训练环境：

accelerate config

注：也可直接使用项目中 accelerate_configs/ 目录下提供的预设配置文件（如单卡或多卡 DeepSpeed 配置）。

3. 基本使用

方式一：启动本地演示界面 (推荐新手)

最简单的方式是启动基于 Gradio 的本地 Web 界面，即可在浏览器中体验文本生成、多模态对话及文生图功能。

python app.py

启动后，终端会显示本地访问地址（通常为 http://127.0.0.1:7860），在浏览器打开即可使用。

在线体验: 如果不想本地部署，可直接访问 Hugging Face Demo。

方式二：命令行推理

1. 文本生成

执行简单的文本生成脚本（默认加载配置）：

python generate.py

2. 多模态生成与文生图

进行多模态理解或文生图任务前，需登录 Weights & Biases (wandb) 以记录结果（可选，但脚本默认调用）：

wandb login

多模态生成示例：

python3 inference_mmu.py \
  config=configs/mmada_demo.yaml \
  mmu_image_root=./mmu_validation \
  mmu_prompts_file=./mmu_validation/prompts_with_vqa.json

运行完成后，可在 wandb 面板查看生成的图像和结果。

文生图 (Text-to-Image) 示例：

python3 inference_t2i.py config=configs/mmada_demo.yaml batch_size=1 validation_prompts_file=validation_prompts/text2image_prompts.txt guidance_scale=3.5 generation_timesteps=15 mode='t2i'

模型选择

本项目提供多个预训练权重，可根据需求在 Hugging Face 下载并替换配置文件中的路径：

• MMaDA-8B-Base: 基础版，具备基本的文本/图像生成及思维链能力。
• MMaDA-8B-MixCoT: 混合长思维链微调版，擅长复杂推理和多模态任务。
• MMaDA-Parallel: 并行思维感知版，支持图文双向连续交互（适用于图像编辑等高级任务）。