inclusionAI/IDM · 上手攻略

  • 仓库：inclusionAI/IDM
  • 链接：https://github.com/inclusionAI/IDM
  • 分类：engineering（生成模型 / 少步文本生图 / 蒸馏方法）
  • 作者：spark
  • 更新：2026-11-03

论文：Intrinsic Distribution Matching，arXiv:2610.39633（cs.CV，2026-10-29 v1 提交，33,466 KB）。项目页 https://inclusionai.github.io/IDM/ （已 302 跳转至 https://www.inclusion-ai.org/IDM/）。 作者单位：Inclusion AI / 西湖大学 / 清华大学 / 浙江大学 / 上海创新研究院 / MBZUAI；一作 Deyuan Liu、Yansen Han、Kaiwen Zheng，通讯 Jintao Zhang、Jianguo Li、Tao Lin。 许可：代码 Apache-2.0；base model 与未来 IDM checkpoint 权重许可另计。 本攻略撰写于 2026-11-03，依据仓库 main 分支当时的 README（blob sha ed131392ab2d15cd56c7e10781a7adea31e556fd）与 requirements.txt（blob sha 38ed3a267b56537d23777c64cbafb10953f452b3）。仓库仍处活跃开发期，接口可能继续变动。

一、这是什么

IDM（Intrinsic Distribution Matching，内蕴分布匹配）是 Inclusion AI 提出的一种少步/一步文本生图蒸馏方法，配套官方开源代码。

它要解决的问题很具体：一步、几步的文生图模型没有"反复修正"的机会，一旦首步走偏细节就没了——尤其长文本渲染（海报、菜单、封面上的成段中英文）崩坏得最明显。

传统 DMD（Distribution Matching Distillation）用 score 差（参考分布 score 减生成分布 score）来监督快模型，但经典做法需要：① 一个预训练教师提供参考 score；② 训练一个独立的 fake-score 网络去追踪不断变化的生成分布。

IDM 的两个动作：

  1. Internal DMD：沿用 APEX 的做法，score 差直接从生成器内部的速度分支（internal velocity branches）得到，省掉独立的 fake-score 网络。
  2. 特征矩匹配：把反向 KL 场分解成"高斯矩分量 + 非高斯残差"，据此给出一个显式可约束的统计量——在生成器自己的 EMA 副本的最后一层激活上，约束特征均值与逐坐标标准差。关键点是：不需要任何外部特征编码器（不需要 DINOv2 之类），用生成器自身的表征当参考系。

推理阶段极轻：只需要学好的条件生成器 + 文本编码器 + VAE，不做特征提取、不做特征队列、不算矩、不跑 fake-score 分支。

⚠️ 重要现状：模型权重尚未发布。README 与项目页均标注 checkpoints "Coming soon"（Z-Image-Turbo 6B 与 Qwen-Image 20B 的全参 / LoRA r=32 / r=64 全部未放）。因此当前仓库只有推理代码，没有训练代码——目录里没有 train 脚本，训练侧（EMA 队列、矩损失实现）需自行实现。README 明确说明下载链接与 checkpoint 专属采样设置会随权重发布一并给出。

二、解决什么问题 / 核心结果

论文给出的数字（均为论文报告值，非本仓库实测），Z-Image-Turbo 6B、2 NFE、full-parameter：

方法 NFE OneIG GenEval DPG-Bench LongText-CN LongText-EN
Z-Image-Turbo 2 50.94 76.53 85.78 78.48 72.89
DMD2 2 50.70 76.12 85.40 85.30 80.99
TwinFlow 2 51.38 72.41 85.98 78.65 71.99
APEX 2 52.60 77.23 88.64 90.38 88.76
Z-Image-Turbo++ 2 52.50 75.70 85.86 91.62 89.88
IDM 2 53.06 77.81 86.82 94.25 90.20
Z-Image-Turbo（高 NFE 参考） 8 52.84 75.01 84.86 92.56 91.74

即：2 NFE 下 LongText-CN 94.25%、LongText-EN 90.20%，是所比较方法中该预算下最高。相对 Z-Image-Turbo++ 长文本 +2.63 / +0.32 个百分点，相对 APEX +3.87 / +1.44 个百分点。

速度（单卡 A100，BF16，batch=1 计延迟，batch=10 计吞吐）：

  • IDM (Z-Image-Turbo 6B)：1 NFE 0.25 s，2 NFE 0.30 s；吞吐 5.41 / 5.18 img/s。
  • IDM (Qwen-Image 20B)：1 NFE 0.35 s，2 NFE 0.44 s；吞吐 3.44 / 3.28 img/s。
  • FID（越低越好）：Z-Image 6B 全参 1 NFE 7.13 / 2 NFE 6.71；Qwen-Image 20B 全参 1 NFE 6.77 / 2 NFE 6.34；LoRA r=64 的 2 NFE 分别为 6.79 / 6.41。
  • Qwen-Image 20B 全参 2 NFE 另有 DPG-Bench 87.16%、WISE 0.56。
  • Rank-64 LoRA 更新 0.4B 参数，GenEval 基本保住全参水平（0.90 vs 0.91）。

受控消融（同一数据与训练配置，全参 IDM(Z-Image) 2 NFE，百分比）：

配置 OneIG GenEval DPG-Bench LongText-CN LongText-EN
无 DMD 无矩损失 52.25 76.24 85.68 92.70 88.88
无 DMD 损失 52.58 76.90 86.15 93.33 89.62
Internal DMD，无矩损失 52.87 77.46 86.54 93.87 89.79
DMD + 矩损失（DINOv2 特征） 53.00 77.75 86.71 94.13 90.09
IDM：DMD + 矩损失（EMA 特征） 53.06 77.81 86.82 94.25 90.20

相对 internal DMD 对照组，矩损失带来 +0.19 / +0.35 / +0.28 / +0.38 / +0.41 个百分点，五项汇总指标全部改善；EMA 特征与 DINOv2 表现接近，说明"生成器自身表征"这条路线成立。

诚实标注（重要）：README 与项目页均明确指出，以上对比中各外部方法训练数据与配置各不相同（APEX 甚至用更小的数据集合训练），因此"IDM 最优"只在同一训练设置下的受控消融里严格成立；跨方法比较仅作参考。DPG-Bench 上 APEX（88.64）高于 IDM（86.82），8-NFE 参考的 LongText-EN（91.74）也高于 IDM 的 90.20。

三、快速安装

要求：Python ≥ 3.10，CUDA 机器（显存需容下所选模型，20B backbone 明显比 6B 吃显存多）。默认精度 BF16。

git clone https://github.com/inclusionAI/IDM.git
cd IDM

python -m venv .venv
source .venv/bin/activate

# 若环境里还没有匹配的 PyTorch，先按 CUDA 版本装
# pip install torch --index-url https://download.pytorch.org/whl/cu124   # 版本号按自己的 CUDA 改
python -m pip install -r requirements.txt

requirements.txt 实测内容（已核对 blob）：

torch>=2.6,<3
diffusers==0.37.1
transformers>=4.57,<5
accelerate>=1.10,<2
peft>=0.17,<0.19
safetensors>=0.6
Pillow>=10

注意两点：

  • Diffusers 被 pin 在 ==0.37.1——README 说明辅助时间嵌入（auxiliary-time）wrapper 依赖其模型接口，版本错了会起不来。别随手升级。
  • 不需要 FlashAttention、FSDP 和任何训练服务；README 明确说这一点（对应"只发推理代码"的现状）。

开发自检：

python -m pip install -r requirements-dev.txt
python -m pytest -q     # tests/ 用小模型做 CPU 检查，不下载模型
ruff check .

四、核心用法

仓库结构（已核对目录清单）：inference.py（命令行生图）、unified_sampler.py（一步/两步一阶采样）、diffusers_patch/（推理适配器与 aux-time wrapper）、examples/prompts.txt、assets/（论文图）、tests/、paper/、docs/。

4.1 全参 checkpoint（权重尚未发布，以下为权重发布后的用法）

Z-Image backbone，2 NFE：

python inference.py \
 --backbone z-image \
 --model /path/to/IDM-Z-Image \
 --prompt 'A cafe menu with the heading "MORNING COFFEE" and three lines: "Americano $4", "Latte $5", "Mocha $6".' \
 --steps 2 --height 1024 --width 1024 --seed 42 \
 --output-dir outputs/z-image

Qwen-Image backbone，1 NFE：

python inference.py \
 --backbone qwen-image \
 --model /path/to/IDM-Qwen-Image \
 --prompt '一张咖啡馆海报，标题"今日咖啡"，三行菜单"美式咖啡 18元""拿铁咖啡 22元""摩卡咖啡 25元"。' \
 --steps 1 --height 1024 --width 1024 --seed 42 \
 --output-dir outputs/qwen-image

4.2 只换 transformer（基座沿用原 pipeline）

python inference.py \
 --backbone z-image \
 --model /path/to/Z-Image-Turbo \
 --transformer /path/to/IDM-transformer \
 --prompt 'A book cover titled "The Art of Calm".' \
 --steps 2

--transformer 指向的目录必须含 config.json 与 safetensors 权重。--aux-time-embed 有 auto（默认，按 checkpoint 的 _class_name 自动判断）/ on / off 三档；老导出物需手动 on/off 对齐架构。README 强调：transformer 参数缺失或意外会直接报错，而不是静默留随机权重。

4.3 LoRA 权重

python inference.py \
 --backbone qwen-image \
 --model /path/to/Qwen-Image \
 --lora /path/to/IDM-LoRA \
 --lora-weight-name pytorch_lora_weights.safetensors \
 --prompt 'A poster with the title "Explore Japan".' \
 --steps 2 --output-dir outputs/lora

LoRA 必须是 Diffusers pipeline 格式且与基座匹配；默认文件名 pytorch_lora_weights.safetensors，可用 --lora-weight-name 改。加载时即合并，--lora-scale 默认 1.0。README 明确：原始 optimizer state、FSDP 分片、未转换的 PEFT 训练 checkpoint 不是推理输入。

4.4 常用参数速查（均已核对 inference.py 的 argparse）

参数 说明
--model 必填，Diffusers pipeline 目录或 HF repo ID
--backbone 必填，z-image 或 qwen-image
--prompt / --prompt-file 二选一必填；文件为 UTF-8，每行一个 prompt（空行忽略）
--steps 只能是 1 或 2，默认 2；对应恰好 1/2 次条件 transformer 前向，不用 CFG
--timesteps 自定义噪声水平，每个 NFE 一个，严格递减且落在 (0, 1]
--stochastic-ratio 步间加噪刷新比例，0~1，默认 0
--height / --width 默认 1024，必须是 16 的正整数倍
--seed 默认 42，范围 [0, 2^63)
--num-images 每 prompt 生成张数，逐张递增 seed
--device cuda / cuda:N / cpu
--dtype bfloat16（默认）/ float16 / float32
--output-dir 默认 outputs
--local-files-only 禁止下载，只用本地文件或已有 HF 缓存

批量生成：

python inference.py \
 --backbone z-image --model /path/to/IDM-Z-Image \
 --prompt-file examples/prompts.txt --num-images 2 \
 --steps 2 --output-dir outputs/batch

输出产物：每张图一个 PNG + 一个 JSON（记录 prompt、seed、backbone、model/transformer/lora 路径、lora_scale、aux_time_embed、nfe、timesteps、stochastic_ratio、height/width/dtype）。已存在的输出不会被覆盖——同名会直接抛 FileExistsError，换 --output-dir 或 --seed。

4.5 采样器内部逻辑（unified_sampler.py 已核对）

  • 约定 t=1 为噪声、t=0 为数据；默认一阶 Euler，噪声水平 [1]（steps=1）或 [1, 0.5]（steps=2），末端落到干净端点 0。
  • 每个 step 对条件速度网络求值一次，不跑负向 prompt 分支、不跑 fake-score 分支。
  • stochastic_ratio > 0 时在步间混合预测噪声与新采样噪声（sqrt(1-ratio) / sqrt(ratio)），且最后一步（next_t == 0）不加噪。
  • --timesteps 传入时长度必须等于 --steps，且严格递减，否则 argparse 直接报错。

五、典型适用场景

  1. 海报/菜单/封面类密集中文长文本生成：这是 IDM 明确主打的方向（LongText-CN 94.25%）。电商主图、促销海报、带价目表的咖啡菜单，都属于"文字必须对"的场景。
  2. 高并发在线出图：2 NFE、batch=10 时单卡 A100 跑 5.18 img/s（Z-Image 6B）/ 3.28 img/s（Qwen-Image 20B），延迟 0.30 s / 0.44 s，适合做同步出图 API 而非离线批处理。
  3. 显存受限的 LoRA 微调 + 部署：rank-64 LoRA 只更新 0.4B 参数，GenEval 保住全参水平（0.90 vs 0.91），适合团队先微调自己领域文本风格，再合并部署。
  4. 一步生成的实时/交互场景：--steps 1 就是 1 次网络前向，0.25 s 出图，可做草稿级预览。
  5. 研究向：想复现"少步生图 + 分布矩约束"这条路线的人，可以从 diffusers_patch/ 和 unified_sampler.py 读推理侧实现；训练侧需自己搭 EMA 特征队列与矩损失。

不适用：想立刻下载权重跑效果（还没发）；想在消费级显卡上跑 Qwen-Image 20B；需要 CFG / 多步精修 / 高分辨率出图（--steps 只支持 1 或 2）。

六、坑与注意

  1. 权重没发：这是最大的坑。README 与项目页的 Checkpoints 表格全是 "Coming soon"（Z-Image-Turbo 6B、Qwen-Image 20B 的 Full / LoRA r=32 / r=64 全部如此）。README 还特别说明下载链接与 checkpoint 专属采样设置会随权重发布一并给出——也就是说现在即使硬凑出一个权重，采样参数也不一定是最终值。
  2. 仓库没有训练代码：目录里只有 inference.py、unified_sampler.py、diffusers_patch/ 等推理件，没有 train 脚本、没有 EMA 特征队列实现、没有矩损失。想复现论文训练得自行实现（论文 Eq. 13/14 与项目页的 A/B/C 三点说明是唯一指引）。README 也明说"checkpoint-specific sampling settings and end-to-end quality validation are pending the weight release"。
  3. 基座权重 ≠ IDM 权重：README 特别警告——"Base-model or APEX weights are not IDM checkpoints; they do not reproduce the IDM results above." 拿 Z-Image-Turbo 原权重跑不会得到论文数字，别误判成代码坏了。
  4. diffusers==0.37.1 是硬 pin：diffusers_patch/ 的 aux-time wrapper 依赖该版本接口，升到 0.38+ 很可能报参数不匹配的错。
  5. --steps 只接受 1 或 2：choices=(1, 2) 写死在 argparse 里，传 4 会直接报错退出，不是降级处理。
  6. 尺寸必须 16 的倍数：height % 16 or width % 16 会触发 parser.error；默认值 1024 是合规的，改成 1000 或 1023 会失败。
  7. 输出不覆盖：同名文件存在直接 FileExistsError 抛出，批量重跑时容易"跑到一半炸掉"，建议每次换 --output-dir 或改 --seed。
  8. --timesteps 的三条约束：长度 == --steps、每个值落在 (0, 1]、严格递减；违反任一条都是 argparse 报错。--stochastic-ratio 必须在 [0, 1]。
  9. seed 上界与自增溢出检查：seed + len(prompts) * num_images 不得越过 2^63，否则报错。批量大 prompt 文件时注意。
  10. 多卡写法：--device cuda:1 指定另一张卡；--device cpu 只适合"小兼容性检查"（README 原文），且需配 --dtype float32——CUDA 不可用时程序明确提示走这条路。
  11. aux-time-embed 版本不匹配：新导出用 auto 即可，老导出要手动 --aux-time-embed on/off 对齐架构；参数不匹配会报错而非静默随机初始化（这一点设计得不错）。
  12. 速度与质量数字的边界：README 自述"All values below are reported in the paper. They are not measurements from running this repository."；且 LoRA 权重是合并后才计时的。外部方法（APEX/DMD2/TwinFlow）训练数据与配置不同，跨方法对比不构成严格公平比较，APEX 的 DPG-Bench 反而更高。
  13. 许可证分离：代码 Apache-2.0，但 base model 与未来 IDM checkpoint 的许可另行适用，商用前要单独确认权重许可。

七、与同类对比

方法 监督来源 需要 fake-score 网络？ 需要外部特征编码器？ 推理侧额外开销 主要长文本成绩（2 NFE, Z-Image）
DMD（经典） 教师 score 差 是 否 有 —
DMD2 改进的 DMD 是（论文体系内） 否 有 LongText-CN 85.30 / EN 80.99
TwinFlow 双流一致性 — — 有 78.65 / 71.99
APEX internal velocity 分支 否 否 有 90.38 / 88.76
IDM internal DMD + EMA 特征矩约束 否 否 无（纯生成器 + 文本编码器 + VAE） 94.25 / 90.20

相对定位：

  • vs 经典 DMD / DMD2：IDM 省掉 fake-score 网络，长文本明显更好（94.25 vs 85.30 CN）。
  • vs TwinFlow：GenEval 上 IDM 77.81 远高于 TwinFlow 72.41。
  • vs APEX（最接近的对照，且 IDM 推理实现即改编自 APEX）：IDM 在长文本上更强（+3.87 / +1.44），但 DPG-Bench 落后（86.82 vs 88.64），且 APEX 属外部参照、训练设置不同。
  • vs 传统多步蒸馏（LCM / SDXL-Turbo / SD-Turbo 等）：IDM 路线不依赖 guidance 或对抗式微调，1~2 步即可；LCM 系多在 4~8 步。
  • vs 其他 2026 年少步生图工作（如 SDEdit-free 系一步/少步蒸馏）：IDM 的差异化在于"用生成器自身 EMA 表征做矩约束"，因此不背外部 encoder（如 DINOv2）的计算与许可负担；代价是额外训练复杂度上升。

八、一句话推荐

推荐——如果你关注"一步/两步出图 + 中文密集长文本不掉字"，这是目前公开方法里最有说服力的一条路线（2 NFE 下 LongText-CN 94.25%，单卡 A100 0.30 s/张）；但现在只适合读代码和搭推理管线，权重未发、训练代码未开，等权重与 checkpoint 采样设置落地后再动手更稳妥。

附：待核 / 不确定项

  • ⚠️ 权重发布状态："Coming soon" 为 2026-11-03 读取 README 与项目页所见；发布计划时间仓库未给出，待后续核。
  • ⚠️ 训练代码：仓库当前无训练脚本；训练侧实现细节（EMA 衰减系数、特征队列长度、矩损失的池化位置）需以论文正文 / 项目页 Eq. 13/14 为准，本次未逐条核 PDF 正文。
  • ⚠️ 论文数值：本文所有指标均 verbatim 抄自 README / 项目页 / arXiv abstract 与表格，非本仓库实测；论文未标注实验所用具体数据集名称（README 仅称 "the shared internal DMD control"、参考集等），训练数据构成需回查 PDF。
  • ⚠️ checkpoint 专属采样设置：README 声明随权重发布提供，本文给出的默认 timesteps [1] / [1, 0.5] 为代码默认（已与 unified_sampler.py 的 [1.0 - i/steps] 逻辑核对一致），不保证等于最终推荐设置。
  • ⚠️ pip install torch 的 CUDA 轮子版本：README 只说"按你的 CUDA 环境装合适的 PyTorch"，未给具体命令；文中示例 cu124 仅为占位，需自行匹配。
  • ⚠️ arXiv 编号 2610.39633 / 仓库名大小写：均为读取时的原文，但该 arXiv ID 与项目页内容存在若干"看起来非标准"之处（如 ID 段 39633 偏大、PDF 体积 33,466 KB），本次未做第三方交叉核对，建议以 arXiv 官方页面为准。