---
title: LingXi-Image-MoE
canonical_url: "https://www.modelscope.cn/models/haohanxingcheng/LingXi-Image-MoE"
md_url: "https://www.modelscope.cn/models/haohanxingcheng/LingXi-Image-MoE.md"
repository: haohanxingcheng/LingXi-Image-MoE
last_updated: 2026-07-30
pipeline_tag: text-to-image-synthesis
tasks:
  - text-to-image-synthesis
base_model_relation: finetune
parameters: 1.9B
tensor_type:
  - F32
library_name:
  - safetensors
  - diffusers
  - pytorch
frameworks:
  - Pytorch
downloads: 13
stars: 0
---

# LingXi-Image-MoE

> LingXi-Image-MoE - haohanxingcheng 在 ModelScope 开源的模型。LingXi-Image-MoE: 从交替到全层 混合专家架构在文生图扩散模型中的对比研究

- **Repository**: haohanxingcheng/LingXi-Image-MoE
- **Tasks**: text-to-image-synthesis
- **Parameters**: 1.9B
- **Downloads**: 13
- **Stars**: 0
- **Last updated**: 2026-07-30

Source: https://www.modelscope.cn/models/haohanxingcheng/LingXi-Image-MoE

---

<div align="center">

# LingXi-Image-MoE: 从交替到全层<br>混合专家架构在文生图扩散模型中的对比研究

<a href="https://arxiv.org/abs/xxxx.xxxxx" target="_blank"><img src="https://img.shields.io/badge/论文-b5212f.svg?logo=arxiv" height="22px"></a>
<a href="https://huggingface.co/shyai/LingXi-Image-MoE" target="_blank"><img src="https://img.shields.io/badge/%F0%9F%A4%97%20模型-d96902.svg" height="22px"></a>
<a href="https://github.com/Lingxi-Qihang/LingXi-Image-MoE" target="_blank"><img src="https://img.shields.io/badge/代码-181717.svg?logo=github" height="22px"></a>
<a href="https://modelscope.cn/models/haohanxingcheng/LingXi-Image-MoE" target="_blank"><img src="https://img.shields.io/badge/魔搭-624aff.svg" height="22px"></a>

</div>

# 🔥 动态

ProMoE‑L (1.68B)开源地址：
- 💻 **GitHub**：[https://github.com/Lingxi-Qihang/LingXi-Image-MoE-1.68B-A0.56M](https://github.com/Lingxi-Qihang/LingXi-Image-MoE-1.68B-A0.56M)
- 🧠 **1.68B 模型权重**：[ModelScope LingXi-Image-MoE-1.68B-A0.56M](https://modelscope.cn/models/haohanxingcheng/LingXi-Image-MoE/tree/master/LingXi-Image-MoE-1.68B-A0.56M)
- 📦 **125万步 checkpoint**：[ModelScope ckpt_step_1250000.pth ](https://modelscope.cn/models/haohanxingcheng/LingXi-Image-MoE/tree/master/ckpt_step_1250000.pth)

- [2026-07-31] **ProMoE‑L (1.68B)** 联合训练完成，论文《能力涌现的时序规律：一个 1.68B 全层混合专家文生图模型训练的动力学分析》（Temporal Patterns of Capability Emergence: A Fine-Grained Analysis of Training Dynamics in a 1.68B Full-Layer MoE Text-to-Image Model）发布。
- [2026-07-14] 论文《从交替到全层：混合专家架构在文生图扩散模型中的对比研究》发布在 arXiv！
- [2026-07-14] 模型权重同步上线 [HuggingFace](https://huggingface.co/shyai/LingXi-Image-MoE) 和 [ModelScope](https://modelscope.cn/models/haohanxingcheng/LingXi-Image-MoE)
- [2026-07-14] 完整代码 [GitHub](https://github.com/Lingxi-Qihang/LingXi-Image-MoE) 开源，训练记录与路由日志在 [HuggingFace](https://huggingface.co/shyai/LingXi-Image-MoE) 和 [ModelScope](https://modelscope.cn/models/haohanxingcheng/LingXi-Image-MoE)仓库里面

---

## 关于本项目

本文基于 ProMoE（ICLR 2026）框架，将其从类别条件（ImageNet）适配到文本条件，实现了一套支持文本到图像生成与图像编辑的统一框架。全层 MoE 架构在 40 万步时即达到交替 MoE 80 万步以上的生成质量，收敛速度提升 2–2.5 倍。

---

## 👤 作者的话

我是独立研究者，一个人、一张显卡，自掏腰包探索视觉 MoE 的前沿。

我正在开发和运营一家叫“灵犀启航智能科技”的 AI 公司——产品、研发、运营目前都是我。公司预计下个月正式上线，届时将包含：

- 🎨 **灵犀 AIGC**（微信小程序）：AI 绘画、生成视频
- 🔒 **聆通 AI**（Android 应用）：离线 AI 助手，隐私优先的语音交互

官网也在同步搭建中。LingXi-Image-MoE-1.0 是我在视觉 MoE 方向的独立研究成果，也是灵犀启航未来图像生成能力的基座模型。

---

## 📌 项目路线图

- ✅ **LingXi-Image-MoE-1.0（ProMoE‑B，0.47B）**：全层 MoE 文生图模型，DPG‑Bench 63.86 分，超越 SD v1.5
- 🚧 **ProMoE‑L（1.68B）**：联合训练进行中，266 万混合数据，文生图 + 图像编辑统一框架
- 🧪 **统一编辑模型**：7:3 混合训练，在保持生成质量的同时实现强编辑能力
- 📈 **更大规模探索**：3B+ 参数 MoE，交叉注意力路由与指令级路由
- 📚 **诊断论文**：Loss Spike 系统修复、U 型分层专业化、渐进式唤醒（arXiv:2605.19378）

---

## 主要结果

### 全层 MoE vs 交替 MoE：100 万步生成质量对比

| 评估维度 | 交替 MoE（40万步） | 全层 MoE（40万步） |
|----------|-------------------|-------------------|
| 背景纯净度 | 灰蒙“雾气”明显，物体边缘发虚 | 背景干净，主体边缘锐利 |
| 多人交互 | 面部融化，肢体粘连 | 五官清晰，表情自然 |
| 文字渲染 | 笔画糊成噪点，不可读 | 字迹锐利，笔画分离 |
| 双格漫画 | 边界模糊，内容混杂 | 明确分格，左右主题独立 |
| 收敛速度 | 基线 | **2–2.5 倍加速** |

> **核心发现**：全层 MoE 在 40 万步时即达到交替 MoE 80 万步以上的生成质量，Dense 层是交替架构中多任务冲突和信息损耗的结构性根源。

### DPG-Bench 评测（285 万步 checkpoint）

| Model | Global | Entity | Attribute | Relation | Other | Overall↑ |
|-------|--------|--------|-----------|----------|-------|----------|
| SD v1.5 (0.86B) | 74.63 | 74.23 | 75.39 | 73.49 | 67.81 | 63.18 |
| **LingXi-Image-MoE (0.47B)** | **81.90** | **75.28** | **80.12** | **87.02** | **54.00** | **63.86** |
| PixArt-α | 74.97 | 79.32 | 78.60 | 82.57 | 76.96 | 71.11 |
| SDXL | 83.27 | 82.43 | 80.91 | 86.76 | 80.41 | 74.65 |

**关键子项得分：**
- **空间关系**: 87.83 — 超越 SDXL，逼近 SOTA
- **文字渲染**: 86.00 — 历史最佳（注入专有文字增强数据）
- **纹理质感**: 82.74 — 超越 SD v1.5 和 PixArt-α
- **实体完整性** (人脸/细节): 75.28 — 待提升（受限于 VAE 容量与训练稳定性）
- **计数能力**: 46.00 — 当前最大短板

---

## 核心特性

### ProMoE 两阶段路由
- **条件路由**：按功能角色将 token 分为有条件（CFG 中未被 dropout 的样本）和无条件（CFG 空文本样本）两组
- **原型路由**：通过可学习的原型向量与 token 的余弦相似度进行路由分配。每个 token 激活 Top-K 个路由专家
- **路由对比损失**：显式增强原型路由的类内聚力和类间多样性
- **无条件专家重定位**：保留 ProMoE 的两阶段路由结构，将无条件专家（Expert 12）重新定位为处理 CFG 空文本样本的专用专家

### MM-DiT 文本-图像融合
- 文本序列映射到模型隐藏空间后，与图像 token 沿序列维度拼接
- 自注意力同时处理文本和图像，无需交叉注意力模块
- 文本全局向量通过 AdaLN 调制注入模型

### 动态分辨率（连续旋转位置编码）
- **图像 token**：2D RoPE（Rotary Position Embedding），坐标归一化到 [0,1] 区间
- **文本 token**：1D RoPE 编码序列位置
- **优势**：单一权重支持任意分辨率（256/512/768/1024+），无需插值或微调
- 参考 FiT (NeurIPS 2024) 的连续位置编码思想

### 统一共生框架
- 文生图（T2I）：源潜变量为零黑图
- 图像编辑（Image Editing）：源潜变量为目标图像的原始编码
- 同一模型、同一训练过程，通过 source_latent 区分两种任务

---

## 环境配置

```bash
conda create -n promoe python=3.10 -y
conda activate promoe
pip install -r requirements.txt
```

## 数据预处理

使用 T5-base 编码文本、sd-vae-ft-mse 编码图像，预处理为缓存文件以加速训练。

以下以 `hf/ma-xu-fine-t2i` 数据集为例，展示完整的数据准备流程。

### 1. 下载数据

从 ModelScope 下载 tar 分片到本地：

```bash
bash preprocess/download.sh
```

会并发下载 `train-000000.tar` ~ `train-001310.tar`，默认保存到 `/data/coding/`。

### 2. 解压数据

```bash
python preprocess/extracted_data.py
```

解压后目录结构：
```
curated_extracted_data/
└── synthetic_original_prompt_square_resolution/
    ├── 000000000.jpg / 000000000.txt
    ├── 000000001.jpg / 000000001.txt
    └── ...
```
每张图片对应一个同名的 `.txt` 文件，其中包含文本描述。

### 3. 提取特征

使用 `preprocess_ma-xu-fine-t2i.py` 批量提取 VAE 潜变量和 T5 文本特征：

```bash
python preprocess/preprocess_ma-xu-fine-t2i.py \
  --image_root /path/to/curated_extracted_data \
  --output_dir /path/to/preprocessed_output \
  --t5_path /path/to/t5-base \
  --vae_path /path/to/sd-vae-ft-mse \
  --image_size 512 \
  --batch_size 8
```

脚本会自动扫描 `image_root` 下的所有图片，寻找同名的 `.txt` 文件配对，输出如下结构：

```
preprocessed_output/
├── latents/
│   ├── target_512/            # 512 分辨率潜变量
│   └── target/                # 256 分辨率潜变量
└── t5_text_features/
    ├── 000000000_seq.npy      # T5 序列特征 (512, 768)
    ├── 000000000_mask.npy     # 注意力掩码 (512,)
    └── ...
```

提取完成后，脚本会自动删除原始图片和文本文件以节省空间。

### 4. 配置训练

在 YAML 配置文件中设置预处理输出路径：

```yaml
latent_root: "/path/to/preprocessed_output/latents"
text_root: "/path/to/preprocessed_output/t5_text_features"
```

训练脚本 `train_GradientAccumulationSteps.py` 中的 `UnifiedSymbiosisDataset` 会自动从这两个目录加载数据。

## 数据集构成

实际训练使用约 **238 万** 图文对，计划数据集总规模约 340 万张（部分后续阶段暂未执行）：

| 子集 | 规模 | 说明 |
|------|------|------|
| Fine-T2I (enhanced + original) | 209 万 | 合成数据，覆盖长短文本 |
| Fine-T2I (curated) | 16.8 万 | 真实摄影，消除“AI 塑料味” |
| 人脸/文字增强数据 | 19.2 万 | 提升面部与文本渲染质量 |
| Pico-Banana-400K | 40 万 | 真实图像编辑（后续阶段） |

## 四阶段渐进式训练

```
bash train.sh                  # 阶段 2a → 4 (默认)
bash train.sh --full           # 阶段 1  → 4
bash train.sh --stage 3        # 阶段 3  → 4
bash train.sh --accum 4        # 4 步梯度累积 (默认 1)
```

默认不累积梯度。脚本自动编排全部阶段，阶段间自动衔接 checkpoint。

### 阶段配置

| 阶段 | 核心任务 | 数据集 | 分辨率 | 学习率 | 步数 | 状态 |
|------|---------|--------|--------|--------|------|------|
| 一 | 基础路由收敛与多任务对齐 | OpenGPT-4o-Image (8万) | 256 | 1×10⁻⁴ | 2200K | ✅ 完成 |
| 二a | T2I Scaling (低分辨率) | 混合数据 (约238万) | 256 | 2.5×10⁻⁵ | 200K (实际至285万) | ✅ 完成 |
| 二b | T2I Scaling (高分辨率) | 同上 | 512 | 5×10⁻⁵ | 100K | ⏳ 未执行 |
| 三 | 编辑能力专精 | Pico-Banana-400K (40万) | 512 | 5×10⁻⁵ | 100K | ⏳ 未执行 |
| 四 | 统一联合微调 | Mixed 7:3 (T2I + 编辑) | 512 | 5×10⁻⁵ | 50K | ⏳ 未执行 |

**注：** 阶段二的 209 万条数据从 Fine-T2I 数据集的 `synthetic_enhanced_prompt_square_resolution`（约 154 万）和 `synthetic_original_prompt_square_resolution`（约 130 万）两个子集中随机采样并合并而成，实际预处理后获得约 209 万对图文对。阶段二a 学习率已修正为实际使用的 2.5×10⁻⁵。

### 阶段配置文件

| 文件 | 用途 |
|------|------|
| `configs/stage2a.yaml` | 阶段二a：Fine-T2I, 256, lr=2.5e-5, 200K |
| `configs/stage2b.yaml` | 阶段二b：Fine-T2I, 512, lr=5e-5, 100K |
| `configs/stage3.yaml` | 阶段三：Pico-Banana-400K, 512, lr=5e-5, 100K |
| `configs/stage4.yaml` | 阶段四：Mixed, 512, lr=5e-5, 50K |

### 单阶段手动运行

```bash
python train_GradientAccumulationSteps.py \
  --config configs/stage2a.yaml
# 默认不累积梯度；如需累积: --grad_accum_steps 4
```

### 关键配置参数

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `image_size` | 256/512 | 训练分辨率 |
| `latent_root` | — | VAE 潜变量路径（含 target/ 子目录） |
| `text_root` | — | T5 文本特征路径 |
| `total_train_batch_size` | 1 | 总 batch size（需配合 grad_accum_steps） |
| `lr` | 1e-4 | 学习率 |
| `num_steps` | 阶段终点步数 | 总训练步数 |
| `resume_checkpoint_step` | — | 从指定步数的 checkpoint 恢复 |
| `grad_accum_steps` | 1 (CLI) | 梯度累积步数（默认不累积） |
| `routing_contrastive_lam` | 0 | 路由对比损失权重（设为 0 关闭） |
| `load_balance_loss_coef` | 0.01 | 负载均衡损失权重 |

### 注意
- 优化器状态因模型结构变更无法加载时会自动重置，不影响模型权重加载
- checkpoint 加载使用 `strict=False`，旧版 `pos_embed` / `text_pos_embed` 被安全忽略
- 阶段二b 需要将 latent 切换为 512 分辨率，脚本自动建立软链接
- 阶段三/四的数据（Pico-Banana-400K、混合数据）需先完成预处理，脚本检测到目录存在时自动执行，否则跳过

---

## 快速推理（inference.py）

独立的轻量推理脚本，仅需命令行参数，无需完整 YAML 配置：

```bash
# 单 prompt
python inference.py \
  --config configs/004_ProMoE_B.yaml \
  --ckpt path/to/checkpoint.pth \
  --prompt "A cat holds a poster" \
  --output outputs \
  --image_size 512 \
  --guide_scale 4.0 \
  --seed 42

# 批量读取 prompt 目录（每个 .txt 文件一个 prompt，输出同名 .png）
python inference.py \
  --config configs/004_ProMoE_B.yaml \
  --ckpt path/to/checkpoint.pth \
  --prompt_dir /path/to/prompt/dir \
  --output outputs
```

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--config` | 必填 | YAML 配置文件（仅读取模型架构参数） |
| `--ckpt` | 必填 | 模型 checkpoint 路径 |
| `--prompt` | — | 单条文本 prompt |
| `--prompt_dir` | — | 存放 .txt 文件的目录，每个文件读取 prompt |
| `--output` | outputs | 输出目录 |
| `--image_size` | 512 | 生成图像尺寸 |
| `--guide_scale` | 4.0 | CFG 引导强度 |
| `--sample_steps` | 50 | 采样步数 |
| `--seed` | 0 | 随机种子（批量时每个 prompt 自动递增） |

---

## 采样与评估

```bash
python sample.py --config configs/004_ProMoE_B.yaml
```

自定义参数：
```bash
python sample.py \
  --config configs/004_ProMoE_B.yaml \
  --step_list_for_sample 50000,100000 \
  --guide_scale_list 4.0,5.0,7.0 \
  --num_fid_samples 10000 \
  --sample_prompts "a cat sitting on a chair"
```

---

## 训练稳定性：Loss Spike 诊断与修复

在 280 万步后，训练反复出现 Loss 从 0.7 骤升至 3.6 的 Spike。经近一月排查，定位并修复了以下关键问题：

| 问题 | 症状 | 根本原因 | 修复方案 |
|------|------|---------|---------|
| 缺乏学习率衰减 | 后期震荡剧烈 | 固定 lr 使参数无法收敛 | 引入 CosineAnnealingLR |
| VAE 潜变量处理不当 | 引入数值噪声 | 误用方差采样 | 直接取均值，单次缩放 |
| 数据完整性不足 | 偶发梯度爆炸 | 损坏文件含 NaN/Inf | Dataset 层过滤 + Loss 异常跳过 |
| 优化器状态污染 | 恢复后仍易崩溃 | 动量被异常梯度污染 | 每次恢复重置优化器状态 |
| 显存碎片与误杀 | 偶发 OOM，正常样本被跳过 | Loss 阈值过低 | 提高阈值至 1.5，启用 expandable_segments |

这些经验已全部沉淀为可复现的工程基线，并迁移至下一代 ProMoE-L 模型。

---

## 已知局限

- **人脸细节**：受限于 4 通道 VAE 和 T5-base 容量，偶尔出现崩坏，需更大模型和专门数据
- **计数能力**：DPG-Bench count 仅 46 分，训练集中缺乏明确计数样本
- **编辑能力**：联合训练尚未完成，当前仅支持文生图（可通过零黑图源推理）
- **超长程稳定性**：0.47B 参数已接近 ProMoE-B 设计极限，建议升级到 ProMoE-L

---

## 模型架构

ProMoE-TC-B 配置（0.47B 参数）：
- 12 个路由专家 + 1 个无条件专家 + 1 个共享专家
- 12 层 Transformer，全部使用 MoE
- 隐藏层 768，12 个注意力头，head_dim=64
- Top-2 路由，余弦相似度路由权重
- AdaLN-Zero 条件归一化
- 序列拼接式文本注入

## 文件结构

```
├── configs/                     # YAML 配置文件
│   ├── 004_ProMoE_B.yaml       # 阶段一配置（参考）
│   ├── stage2a.yaml             # 阶段二a：T2I Scaling @ 256
│   ├── stage2b.yaml             # 阶段二b：T2I Scaling @ 512
│   ├── stage3.yaml              # 阶段三：Editing Specialization
│   └── stage4.yaml              # 阶段四：Unified Joint Fine-tuning
├── train.sh                     # 四阶段训练流水线脚本
├── models/
│   ├── modules.py               # 共享模块 (Attention, RoPE, MoE)
│   └── models_ProMoE_TC.py     # ProMoE 文本条件模型
├── preprocess/                  # 数据预处理脚本
│   ├── download.sh              # ma-xu-fine-t2i 数据集下载
│   ├── extracted_data.py        # tar 解压工具
│   ├── preprocess_ma-xu-fine-t2i.py  # ma-xu-fine-t2i 特征提取
│   ├── preprocess_all.py        # 批量预处理（VAE + T5）
│   ├── preprocess_vae.py        # VAE 潜变量编码
│   └── extract_t5_features.py   # T5 文本特征提取
├── train_GradientAccumulationSteps.py  # 训练脚本（梯度累积）
├── inference.py                 # 轻量推理脚本
├── sample.py                    # 采样与评估脚本
└── evaluation/                  # 评估脚本
```

---

## 引用

如果本项目对您的研究有帮助，请引用：

```bibtex
@misc{sha2025fullayer,
  title={从交替到全层: 混合专家架构在文生图扩散模型中的对比研究},
  author={Haiying Sha},
  year={2025},
  note={LingXi-Image-MoE-1.0},
  url={https://github.com/Lingxi-Qihang/LingXi-Image-MoE}
}
```

---

## 参考文献

[1] DiT: Scalable Diffusion Models with Transformers. ICCV 2023.  
[2] ProMoE: Routing Matters in MoE. ICLR 2026.  
[3] FiT: Flexible Vision Transformer for Diffusion Model. NeurIPS 2024.  
[4] PixArt-α: Fast Training of Diffusion Transformer for Photorealistic Text-to-Image Synthesis. ICLR 2024.
