一个简单、统一的多模态模型训练引擎。精简、灵活，专为大规模实验而构建。

快速入门 • 示例 • 模型支持 • 优化技术 • 代码库架构 • 文档

公告

• [2025-10] 🎉🎉 效率报告：我们提供了针对多种模型架构和训练配置的全面模型浮点运算利用率（MFU）指标。详细基准测试请参阅MFU参考。
• [2025-10] 🚀🚀 LMMs-Engine v0.1 正式发布！这是一个轻量级、高效的框架，专为大规模训练统一多模态模型而设计。

🚀 快速入门

安装

# 克隆仓库
git clone https://github.com/LMMs-Lab/lmms-engine.git
cd lmms-engine

# 安装可编辑包
uv pip install -e ".[all]"
# 或者作为普通包安装
uv pip install -e .
# 安装稳定版本
uv pip install lmms-engine

# 使用 uv sync 安装依赖
# 对于 Linux 系统（推荐——自动检测平台）：
bash uv_sync_linux.sh

# 对于其他系统或遇到问题时：
uv sync
# 如果 uv sync 失败，可以尝试：
uv pip install -r requirements.txt

# 可选：性能优化
uv pip install flash-attn --no-build-isolation
uv pip install liger-kernel

Docker

我们提供了包含 PyTorch、CUDA 及所有必要依赖的预构建环境的Docker 镜像。

docker run --gpus all -it --rm \
  -v $(pwd):/workspace \
  -w /workspace \  
  fatbao55/lmms-engine:v1.0 \
  bash

启动训练

推荐：torchrun（原生 PyTorch）

torchrun --nproc_per_node=8 --nnodes=1 --node_rank=0 \
  --master_addr=127.0.0.1 --master_port=12355 \
  -m lmms_engine.launch.cli config_yaml=examples/qwen3_vl/example_config.yaml

替代方案：Accelerate

accelerate launch --use_fsdp \
  -m lmms_engine.launch.cli config_yaml=examples/qwen3_vl/example_config.yaml

单 GPU

python -m lmms_engine.launch.cli config_yaml=examples/qwen3_vl/example_config.yaml

🔥 精选示例

优化术语说明：

• FSDP2：完全分片数据并行 v2，用于分布式训练
• USP：尤利西斯序列并行，适用于长上下文
• Muon：基于 Newton-Schulz 正交化的高级优化器
• Liger：Triton 融合核函数（交叉熵、RMSNorm、RoPE、SwiGLU），可减少 30% 的内存占用
• Packing：首次适应式装箱算法，使 MFU 提升至 35-40%，而未使用时仅为 20-25%（例如在 Qwen2.5-VL 微调中）
• NSA：原生稀疏注意力机制，高效处理长上下文
• EP：专家并行技术，用于混合专家模型，在不同 GPU 上划分专家

💡 提示：每个 run.sh 文件都包含详细的设置步骤、先决条件和配置选项。

🤖 模型支持

涵盖视觉-语言、扩散及语言模型的 20 多种架构。

多模态模型

• Qwen2.5-VL：SOTA 级别性能的视觉-语言模型
• Qwen3-VL：SOTA 级别性能的视觉-语言模型
• Qwen3-VL MoE：视觉-语言混合专家模型，支持专家并行和序列并行
• Qwen2.5-Omni：统一视觉 + 音频 + 文本模态
• Qwen3-Omni MoE：多模态混合专家模型，支持视觉 + 音频 + 文本以及专家并行
• LLaVA-OneVision：完全开源的视觉-语言模型
• Bagel：用于视觉理解和生成的统一多模态模型
• Aero：轻量级音频-语言模型

扩散与生成模型

• dLLM (Qwen3) - 带掩码预测的扩散语言模型
• WanVideo (1.3B/14B) - 文本/图像到视频生成（T2V/I2V/V2V）
• SiT (XL/2) - 用于类别条件图像生成的可扩展插值Transformer
• RAE-SigLip - 带对抗判别器的表示自编码器

语言模型

• Qwen2/2.5/3系列 - 完全支持Liger内核，具备融合操作
• 线性注意力模型 - 针对Muon优化的循环架构；请先安装FLA。
• 自定义架构 - 可通过@register_model()装饰器进行扩展

⚡️ 优化措施

从分布式训练到内核融合，实现生产级效率。

核心分布式训练

• FSDP2 - 基于PyTorch 2.0+ DTensor的参数、梯度和优化器状态划分。相比原始FSDP，其组合性更强，可灵活配置并行策略。

• Ulysses序列并行 - 将序列维度拆分到多个GPU上，以处理超长上下文。这对像Qwen3-VL这样拥有1万+视觉token的视觉-语言模型至关重要。

• 多维并行 - 组合TP x PP × DP网格，实现集群规模的训练。

内存与计算优化

• Flash Attention + 无填充 - 使用use_rmpad的分块注意力机制，完全消除填充计算。

• 原生稀疏注意力（NSA） - 结合压缩注意力、TopK稀疏注意力和滑动窗口注意力的混合机制。

• Liger内核 - Triton融合内核（CrossEntropy、RMSNorm、RoPE、SwiGLU）通过避免中间结果的显式存储，显著降低内存占用。

• 猴子补丁系统 - 通过lmms_engine/configs/monkey_patch/在运行时注入内核，实现无需修改代码的模型特定优化。

• 序列打包 - 更快的首次适应装箱算法。

高级优化器

• Muon优化器 - 基于Triton内核的Newton-Schulz正交化，通过DTensor分布式执行。选择性地对二维参数应用，其收敛性能优于AdamW。

数据流水线

• 流式数据集 - 使用IterableDataset进行万亿token预训练，无需完整加载数据。

配置示例

dataset_config:
  packing: true
  packing_strategy: first_fit
  packing_length: 32000

trainer_args:
  use_rmpad: true  # 需要flash-attn
  use_liger_kernel: true

trainer_args:
  use_liger_kernel: true

trainer_args:
  use_muon: true # 启用muonwithadam优化器
  adam_beta1: 0.9 # muonwithadam优化器中的adam部分
  adam_beta2: 0.999 # muonwithadam优化器中的adam部分
  adam_epsilon: 1.0e-8 # muonwithadam优化器中的adam部分
  learning_rate: 0.001
  weight_decay: 0.01
  # ns_steps: 5  # Newton-Schulz迭代次数（默认）

  # 对于用户希望指定的模块

trainer_args:
  fsdp2: true
  fsdp_config:
    transformer_layer_cls_to_wrap: ["Qwen2VLDecoderLayer"]
    reshard_after_forward: false
    activation_checkpointing: true

trainer_args:
  sp_ulysses_degree: 2  # 序列并行度

model_config:
  load_from_pretrained_path: "lmms-lab/BAGEL-7B-MoT-ver.LE"

monkey_patch:
  - type: nsa
    model_type: bagel
    kwargs:
      block_size: 64
      compress_type: "weightedpool"  # weightedpool, linear, avgpool
      kernel_size: 32
      kernel_stride: 16
      topk: 16
      init_blocks: 1
      local_blocks: 2
      window_size: 512

📖 文档

分步工作流程

1. 处理数据集为OpenAI聊天格式（JSONL/JSON/Arrow/CSV）

   hf download kcz358/open-thoughts-debug --local-dir data/open_thoughts_debug --repo-type dataset
   

2. 准备数据集YAML（单个数据源可选）

   datasets:
     - path: data/open_thoughts_debug
       data_folder: ""
       data_type: arrow
   

3. 配置训练 - 参见examples/qwen3_vl/example_config.yaml或examples/中的任何模型特定配置。

综合指南

入门：

• 数据准备 - 如何准备和组织您的数据
• 数据集与打包指南 - 详细的数据集实现和打包策略
• 训练指南 - 全面的训练流程讲解

进阶主题：

• 设计原则 - 架构模式与哲学
• API参考 - 详细的API文档

🏗️ 代码库架构

组件注册表

工厂模式便于轻松扩展：

# 注册自定义数据集
from lmms_engine.datasets import register_dataset, BaseDataset

@register_dataset("my_custom_dataset")
class MyCustomDataset(BaseDataset):
    def __init__(self, config):
        super().__init__(config)
        # 自定义初始化

    def __getitem__(self, idx):
        # 自定义数据加载
        return item

# 注册自定义处理器
from lmms_engine.datasets.processor import register_processor

@register_processor("my_custom_processor")
class MyCustomProcessor:
    def __call__(self, raw_data):
        # 自定义处理逻辑
        return processed_data

训练流水线

构建者模式用于灵活组合：

from lmms_engine.train import TrainRunner

# 配置定义了整个流水线
runner = TrainRunner(config)
runner.build()  # 惰性初始化各个组件
runner.run()    # 执行训练

流水线阶段：

1. 模型初始化 - 从预训练模型或配置中加载
2. 数据集创建 - 包括处理器和数据整理器
3. Monkey Patching - 应用内核优化
4. 训练器设置 - FSDP2、DeepSpeed 或自定义训练器
5. 训练执行 - 包括检查点保存和日志记录

支持的训练器

🎯 使用场景

• 视觉-语言预训练 - Qwen-VL、LLaVA 在大规模多模态数据集上的应用
• 视频理解 - AERO 在 3D 视频数据上的应用
• 扩散模型 - DLLM、SiT、WanVideo 用于生成任务
• 表征学习 - RAE 用于视觉表征学习
• 语言模型预训练 - DGN、Qwen 结合 Muon 优化器
• 多模态微调 - 基于序列打包的高效 SFT

🤝 贡献

我们欢迎各位贡献！请参阅我们的设计原则以了解编码规范：

• 简单性：编写简洁明了的代码
• 可读性：优先考虑清晰度而非技巧性
• 可测试性：确保组件易于测试
• 最小改动：仅修改与当前任务相关的代码
• 代码越少，债务越小：尽量减少代码量

😊 致谢

感谢以下项目提供的优秀工作：

• axolotl
• LLaMA-Factory
• nanotron
• veScale
• veOmni

📝 引用

如果您在研究中使用 LMMs Engine，请引用以下内容：

@software{lmms_engine2025,
  title={LMMs Engine: 一个简单、统一的多模态框架，用于预训练和微调。},
  author={LMMs-Lab},
  year={2025},
  url={https://github.com/LMMs-Lab/lmms-engine}
}

📄 许可证

本项目采用 Apache 2.0 许可证授权，详情请参阅LICENSE文件。

🔗 链接

• GitHub: https://github.com/EvolvingLMMs-Lab/lmms-engine
• LMMs-Lab: https://lmms-lab.com
• 文档: docs/
• 问题追踪: https://github.com/EvolvingLMMs-Lab/lmms-engine/issues

🎉 使用 LMMs-Engine 的优秀项目

• LongVT: 通过原生工具调用激励“用长视频思考”

• OpenMMReasoner: 以开放且通用的方法推动多模态推理的边界

lmms-engine 快速上手指南

lmms-engine 是一个轻量、灵活且专为大规模训练设计的统一多模态模型训练引擎。支持包括 Qwen 系列、BAGEL、WanVideo 等在内的 20+ 种主流架构，内置 FSDP2、Ulysses 序列并行、Muon 优化器及 Liger Kernel 等生产级效率优化。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux (推荐，脚本自动检测平台) 或其他支持 PyTorch 的系统
• Python: 3.11 或更高版本
• PyTorch: 2.0 或更高版本 (需匹配对应的 CUDA 版本)
• 包管理器: 推荐使用 uv 以获得更快的依赖解析和安装速度
• 硬件: 建议使用 NVIDIA GPU 以启用 Flash Attention 等加速特性

安装步骤

1. 克隆仓库

git clone https://github.com/LMMs-Lab/lmms-engine.git
cd lmms-engine

2. 安装依赖

推荐使用 uv 进行环境管理。

方式 A：开发模式安装（推荐）

# 安装所有可选依赖
uv pip install -e ".[all]"

# 或者仅安装核心包
uv pip install -e .

方式 B：同步环境（适用于 Linux）

# Linux 系统推荐运行此脚本，自动处理平台相关依赖
bash uv_sync_linux.sh

# 其他系统或遇到错误时尝试
uv sync

# 如果 uv sync 失败，回退到传统方式
uv pip install -r requirements.txt

方式 C：直接安装稳定版

uv pip install lmms-engine

3. 性能优化组件（可选但强烈推荐）

为了获得最佳训练效率（如显存降低 30%+），建议安装以下加速库：

uv pip install flash-attn --no-build-isolation
uv pip install liger-kernel

4. Docker 方案（备选）

如果您希望使用预构建的环境（包含 PyTorch, CUDA 及所有依赖），可直接拉取 Docker 镜像：

docker run --gpus all -it --rm \
  -v $(pwd):/workspace \
  -w /workspace \  
  fatbao55/lmms-engine:v1.0 \
  bash

基本使用

lmms-engine 通过 YAML 配置文件驱动训练。以下是最简单的启动示例。

启动训练

单卡训练 (Single GPU) 最快速的测试方式：

python -m lmms_engine.launch.cli config_yaml=examples/qwen3_vl/example_config.yaml

多卡分布式训练 (推荐) 使用原生 torchrun 启动多卡训练（例如 8 卡）：

torchrun --nproc_per_node=8 --nnodes=1 --node_rank=0 \
  --master_addr=127.0.0.1 --master_port=12355 \
  -m lmms_engine.launch.cli config_yaml=examples/qwen3_vl/example_config.yaml

使用 Accelerate 启动 如果您习惯使用 Hugging Face Accelerate：

accelerate launch --use_fsdp \
  -m lmms_engine.launch.cli config_yaml=examples/qwen3_vl/example_config.yaml

配置说明

• 配置文件: 上述命令中的 examples/qwen3_vl/example_config.yaml 是示例配置。您可以复制该文件并根据需要修改模型路径、数据集路径、超参数等。
• 模型支持: 框架内置了多种模型的示例配置（如 examples/qwen2_5_llm/, examples/wanvideo/ 等），直接参考对应的 run.sh 或 YAML 文件即可快速复用。
• 开启优化: 在 YAML 配置文件中设置 trainer_args 即可轻松开启高级特性，例如：

  trainer_args:
    use_liger_kernel: true   # 启用 Liger Kernel 节省显存
    use_muon: true           # 启用 Muon 优化器加速收敛
    fsdp2: true              # 启用 FSDP2 分布式策略
  

更多详细配置项和特定模型的启动脚本，请参阅项目根目录下的 examples/ 文件夹。