microsoft/Mage-Flow · Hugging Face

Source: https://huggingface.co/microsoft/Mage-Flow

Mage-Flow：一种高效的面向图像生成与编辑的原生分辨率基础模型

arXiv (https://github.com/microsoft/Mage/blob/main/assets/mage_flow_tech_report.pdf) 项目页面 (https://microsoft.github.io/Mage) GitHub (https://github.com/microsoft/Mage) Hugging Face (https://huggingface.co/microsoft/Mage-Flow-Base) Hugging Face (https://huggingface.co/microsoft/Mage-Flow) Hugging Face (https://huggingface.co/microsoft/Mage-Flow-Turbo) Hugging Face (https://huggingface.co/microsoft/Mage-Flow-Edit-Base) Hugging Face (https://huggingface.co/microsoft/Mage-Flow-Edit) Hugging Face (https://huggingface.co/microsoft/Mage-Flow-Edit-Turbo) 许可证：MIT (https://opensource.org/licenses/MIT)

图库

Mage-Flow 是一个紧凑的 40亿参数规模生成栈，用于高效的 文本到图像生成 和 基于指令的图像编辑。不同于扩展到数百亿参数，Mage-Flow 通过精心的 分词器–骨干网络–系统协同设计 达到可与最先进模型竞争的质量，同时保持快速、轻内存，并在实际计算预算下易于微调。

该栈由 两个共享、协同设计的组件 构建：

• Mage-VAE — 一个轻量级、高保真度的潜在分词器（单步扩散编码/解码，带锚点潜在 KL 正则化）。
• NR-MMDiT — 一个共享的 40 亿参数 原生分辨率多模态扩散 Transformer，在 Mage-VAE 潜在空间中通过 rectified flow matching 进行训练。

结合原生分辨率打包和融合核训练基础设施，这个共享栈支持 两种模型实例化：用于文本到图像生成的 Mage-Flow 和用于基于指令图像编辑的 Mage-Flow-Edit。每种都提供 基础版、RL 对齐版 和 4 步 Turbo 版。

https://huggingface.co/microsoft/Mage-Flow#%E2%9C%A8-highlights✨ 亮点

• 紧凑且有竞争力。 一个单一的 40 亿参数系列同时用于生成和编辑，匹配或超越更大的开源系统（Qwen-Image 20B、Z-Image 6B、FLUX.2 32B、FireRed-Image-Edit 20B）。
• 高效的分词器。 Mage-VAE 在重建保真度上与 FLUX.2-VAE 相当，同时每像素的编码/解码 MAC 数减少约 12 倍 / 约 22 倍，消除了 VAE 作为高分辨率瓶颈的问题。
• 原生分辨率。 单个检查点可从 512 到 2048 生成任意宽高比的图像，包括极端的 4:1（例如 512×2048、2048×512）。
• 系统级速度。 原生分辨率打包（FlashAttention 变长 + 每个样本 2D RoPE）+ 融合 CUDA 核将每步训练时间从约 1.93 秒减少至约 0.78 秒（训练速度提升约 2.5 倍）；CFG 的条件/无条件分支在 一次 打包的前向传播中完成。
• 完整系列。 生成和编辑均有 基础版、RL 对齐版 和 4 步 Turbo 版。
• 通用编辑。 Mage-Flow-Edit 支持在统一的图像和文本条件模型中实现语义内容编辑、外观变换、图像修复和结构感知输出。详见报告中的编辑图库。
• 交互式延迟。 在单个 A100 上，10242 分辨率下：Mage-Flow-Turbo 0.59 秒/图像，Mage-Flow-Edit-Turbo 1.02 秒/次编辑，峰值内存约 18–20 GB（在对比的系统中最低）。

一对多编辑多样性 — Mage-Flow-Edit 可以从单个参考图像生成多样化的输出。

https://huggingface.co/microsoft/Mage-Flow#%F0%9F%93%A5-model-zoo📥 模型库

每个检查点都是一个独立的 diffusers 风格的仓库（transformer/ 加上共享的 vae/、text_encoder/、scheduler/）。

https://huggingface.co/microsoft/Mage-Flow#%F0%9F%96%BC%EF%B8%8F-showcase🖼️ 展示

文本到图像 — 提示遵循、精细细节以及清晰的英文/中文文本渲染。（第一个面板已展开；点击标题可展开其他面板。）

展示 t2i 预告

通用场景 通用场景

肖像 肖像

美食与静物 美食

英文文本渲染 英文文本

中文文本渲染 中文文本

基于指令的编辑 — 外观、内容、场景/主体、以人为本与创意、底层视觉和修复编辑（源图 → 结果）。（第一个面板已展开；点击标题可展开其他面板。）

各种编辑 I 编辑展示1

各种编辑 II 编辑展示2

局部内容与物体编辑 内容编辑

场景、主体与相机变换 场景与主体

外观与艺术渲染 外观

以人为本与创意编辑 以人为本与创意

底层视觉与条件重建 底层视觉

双向退化与修复 修复

https://huggingface.co/microsoft/Mage-Flow#%F0%9F%93%8A-performance📊 性能表现

完整的基准测试表（文本到图像与图像编辑）— 点击展开****文本到图像 — 完整基准测试套件：GenEval、DPG-Bench、TIIF-Bench（短/长分割）、CVTG-2K、OneIG（EN/CN）、LongText（EN/CN）。数值越高越好；GenEval / CVTG-2K / OneIG / LongText 在 0–1 尺度上，DPG / TIIF 在 0–100 尺度上。类型列标注了闭源与开源；粗体/下划线 = 开源模型中最佳/次佳（闭源模型仅供参考，不参与排名）；– = 未报告；★ = 我们的模型。

图像编辑 — ImgEdit-Bench (0–5)、GEdit-Bench EN/CN (0–10)、TextEdit-Bench 合成/真实 (0–25)。数值越高越好；类型列标注了闭源与开源；粗体/下划线 = 开源模型中最佳/次佳；– = 未报告；★ = 我们的模型。

https://huggingface.co/microsoft/Mage-Flow#%F0%9F%8F%97%EF%B8%8F-architecture🏗️ 架构

Mage-VAE — 一个潜在分词器，构建为 对称的单步扩散编解码器：解码器是一个全卷积的单步像素扩散模型（无全局注意力块），编码器是其架构对偶（一个以像素为条件的单步潜在生成器）。标准的 Gaussian 先验 KL 被替换为 锚点潜在 KL，将后验正则化至 FLUX.2-VAE 潜在，从而产生一个适合生成的 128 通道、16× 下采样的潜在空间。

Mage-VAE 架构与训练 Mage-VAE — 锚点 VAE (FLUX.2-VAE)、对称单步编码器/解码器架构以及三阶段训练流程。

Mage-Flow — 一个 40 亿参数的多模态 DiT，使用 Qwen3-VL 编码提示，使用 Mage-VAE 编码图像，然后处理 打包 的可变长度图像+文本序列，使用每个样本的 2D 旋转嵌入和联合自注意力。原生分辨率打包 消除了桶量化和填充，使单个检查点能够泛化到任意输出尺寸，并将 CFG 的条件/无条件分支融合为单次前向传播。

Mage-Flow / 原生分辨率 MMDiT 架构 Mage-Flow — 通过原生分辨率 MMDiT（左）对可变长度图像+文本标记进行原生分辨率打包，以及双流 MMDiT 块（右）。

后训练 — 从 Base 开始，生成模型通过 Diffusion-NFT（提示遵循、美学、文本渲染、偏好）进行对齐以产生 RL 模型，并通过 解耦 DMD + 对抗性感知引导 蒸馏为 4 步 Turbo。编辑模型复用这一配方，在生成和编辑数据的混合上进行训练以保持生成先验。

https://huggingface.co/microsoft/Mage-Flow#%F0%9F%9A%80-quick-start🚀 快速开始

https://huggingface.co/microsoft/Mage-Flow#installation安装

先安装除 flash-attn 之外的所有内容，然后单独安装 flash-attn，关闭构建隔离 — 它会针对已安装的 torch 编译 CUDA 扩展，因此必须已存在 torch 和匹配的 CUDA 工具包。

cd Mage/mage_flow
uv venv && source .venv/bin/activate

# 1) 固定、经过测试的依赖集（torch 2.13, transformers 5.5, diffusers 0.38, pillow 12.3, ...）。
#    推荐用于可复现性。`uv pip install -e .` 也可以，但其宽松的版本范围可能会解析出比代码测试所用更新的 torch/transformers。
uv pip install -r requirements.txt
uv pip install -e . --no-deps           # mage-flow 包本身

# 2) flash-attn — 需要已安装构建工具，且 CUDA 工具包的主版本号必须与你的 torch 构建匹配（例如 torch cu12x ↔ nvcc 12.x）。cu13/nvcc-12 组合会失败。
uv pip install setuptools wheel ninja
uv pip install --no-build-isolation flash-attn==2.8.3

普通的 pip 也是等效的（先 pip install -r requirements.txt，pip install -e . --no-deps，然后执行两条 flash-attn 命令）。这会注册三个命令：mage-flow、mage-flow-edit、mage-flow-app。

**torch / CUDA：**默认的 PyPI torch wheel 面向最新的 CUDA（当前为 cu13x）。如果你的机器的 CUDA 工具包是 12.x，请先从匹配的索引安装 torch，例如 uv pip install torch==2.13.0 torchvision==0.28.0 --index-url https://download.pytorch.org/whl/cu126，否则 flash-attn 构建将因 CUDA 版本不匹配而失败。（torch 2.13.0 提供 cu126/cu129/cu130 wheel — 选择与你的 nvcc 匹配的那个。）

https://huggingface.co/microsoft/Mage-Flow#python-apiPython API

pipe.generate(prompts, **kw) 和 pipe.edit(prompts, ref_images, **kw) 返回一个与 prompts 对齐的 list[PIL.Image]。一个 prompts 列表 会在每个去噪步骤中批处理为一次打包前向传播（每个样本可以有自己的分辨率/种子）。

文本到图像：

from mage_flow import MageFlowPipeline

pipe = MageFlowPipeline.from_pretrained("microsoft/Mage-Flow", device="cuda")

# 1) 单张图像
img = pipe.generate(["一位年长非洲男性的特写肖像，深皱纹，戴着传统帽子，柔和自然光，超写实。"],
                    steps=20, cfg=5.0, heights=[1024], widths=[1024])[0]
img.save("t2i.png")

# 2) 批量：在一次打包前向传播中处理多个提示/分辨率/种子（每步）
imgs = pipe.generate(
    ["正午时分拍摄的乌尤尼盐沼镜面，静谧感弥漫在空气中。每片草叶上挂着露珠。国家地理社论风格，电影级景深，细腻的天然纹理。",
     "一位年长非洲男性的特写肖像，深皱纹，戴着传统帽子，柔和自然光，超写实。",
     "一碗四川麻婆豆腐盖在茉莉香米上的沉浸式特写，盛在手制陶瓷盘上，配以一小块柑橘。表面油脂捕捉到微小的镜面高光。使用哈苏H6D-100c拍摄，环境窗光，令人垂涎的图像。"],
    heights=[512, 1024, 1792], widths=[2048, 1024, 1024],   # 每个样本不同；4:1 也可以
    seeds=[1, 2, 3], steps=20, cfg=5.0,
)

图像编辑：

from mage_flow import MageFlowPipeline

pipe = MageFlowPipeline.from_pretrained("microsoft/Mage-Flow-Edit", device="cuda")

# 单张参考图（路径或 PIL 图像）
img = pipe.edit(["将背景替换为一片向日葵田野"], ["assets/dog.jpg"],
                steps=30, cfg=5.0, max_size=1024)[0]
img.save("single_edit.png")

# 多图像编辑 — ref_images[i] 是一个源图像列表
img = pipe.edit(["将图像2中的物体融合到图像1中"],
                [["scene.png", "object.png"]], steps=30, cfg=5.0)[0]
img.save("multi_edit.png")

# 显式输出尺寸（覆盖 max_size）；Turbo 编辑 = 4 步 / cfg 1
img = pipe.edit(["将背景替换为一片向日葵田野"], ["assets/dog.jpg"],
                heights=[1024], widths=[1024], steps=4, cfg=1.0)[0]
img.save("single_edit_1024x1024.png")

参数（generate/edit 共用）：

https://huggingface.co/microsoft/Mage-Flow#cliCLI

# 文本到图像（两个提示一次性批量处理）
mage-flow --prompt "一位年长非洲男性的特写肖像，深皱纹，戴着传统帽子，柔和自然光，超写实。" --prompt "一只 Orange Tabby 猫睡在编织藤篮里，阳光从窗户洒下，散景背景，彩色胶片风格。" --steps 20 --cfg 5.0 --height 1024 --width 1024 --seeds 1 2 -o output/

# 图像编辑
mage-flow-edit --prompt "将背景替换为一片向日葵田野" --ref assets/dog.jpg --steps 30 --cfg 5.0 -o edited.png

# Turbo 生成（4 步，cfg=1）
mage-flow --prompt "..." --steps 4 --cfg 1.0 --turbo -o turbo.png