Mergoo

mergoo 是一个用于轻松合并多个大语言模型专家，并高效训练合并后模型的库。借助 mergoo，您可以高效地整合不同通用或领域专用的大语言模型专家的知识。

🚀 特性

• 支持多种合并方法：专家混合模型、适配器混合模型 和 逐层合并
• 每一层均可灵活合并
• 支持的基础模型：Llama（包括 LLaMa3）、Mistral、Phi3 和 BERT
• 支持的训练器：🤗 Trainer、SFTrainer、PEFT
• 支持的设备：CPU、MPS、GPU
• 训练选项：仅微调 MoE 层的路由网络，或对合并后的模型进行全量微调

如果您喜欢这个项目，请考虑给它点个 ⭐️

安装

通过 pip 安装：

pip install mergoo

从 GitHub 安装最新的不稳定版本：

pip install git+https://github.com/Leeroo-AI/mergoo

从源代码安装：

git clone https://github.com/Leeroo-AI/mergoo
cd mergoo
pip install -e .

快速入门

配置设置

指定合并配置：

• model_type：基础模型类型。可选值：mistral、llama 或 bert。
• num_experts_per_token：每个 token 对应的专家数量。
• experts：待合并专家的配置，包括 expert_name 和 Hugging Face 🤗 的 model_id。
• router_layers：应用专家混合模型的层。

全量微调的专家

以下是在合并 全量 微调的大语言模型专家时的示例配置。

config = {
    "model_type": "mistral",
    "num_experts_per_tok": 2,
    "experts": [
        {"expert_name": "base_expert", "model_id": "mistralai/Mistral-7B-v0.1"},
        {"expert_name": "expert_1", "model_id": "meta-math/MetaMath-Mistral-7B"},
        {"expert_name": "expert_2", "model_id": "ajibawa-2023/Code-Mistral-7B"}
    ],
    "router_layers": ["gate_proj", "up_proj", "down_proj"]
}

在上述示例中，我们合并了基于 Mistral 的数学和代码专家。更多详细信息请参阅 此笔记本！

LoRA 上的专家混合模型 (MoE on LoRA)

以下是在合并 LoRA 微调的大语言模型专家时的示例配置。mergoo 在 LoRA 的基础上构建了一个路由层，从而形成 适配器混合模型。

config = {
    "model_type": "mistral",
    "num_experts_per_tok": 2,
    "base_model": "mistralai/Mistral-7B-v0.1",
    "experts": [
        {"expert_name": "adapter_1", "model_id": "predibase/customer_support"},
        {"expert_name": "adapter_2", "model_id": "predibase/customer_support_accounts"},
        {"expert_name": "adapter_3", "model_id": "predibase/customer_support_orders"},
        {"expert_name": "adapter_4", "model_id": "predibase/customer_support_payments"}
    ],
}

这里的 expert_name 以 adapter 开头，而不是 expert。更多详细信息请参阅 此笔记本！

合并专家

按照配置设置，mergoo 将创建合并后的模型如下：

import torch
from mergoo.compose_experts import ComposeExperts

# 创建检查点
model_id = "data/mistral_lora_moe"
expertmerger = ComposeExperts(config, torch_dtype=torch.float16)
expertmerger.compose()
expertmerger.save_checkpoint(model_id)

加载 / 微调合并后的专家

现在，您可以使用 Hugging Face Trainer 轻松训练合并后的模型：

from transformers import Trainer
from mergoo.models.modeling_mistral import MistralForCausalLM

model = MistralForCausalLM.from_pretrained("data/mistral_lora_moe") 
# 注意：'gate' / 路由层尚未训练，因此加载权重时会出现警告

trainer = Trainer( ... )
trainer.train()

📚 了解更多：

完成快速入门指南后，您可以探索以下教程，进一步熟悉 mergoo。

笔记本	详情
全量微调专家的 MoE	构建由全量微调专家组成的统一专家混合模型。灵感来自 BTX Research（Meta AI）。
LoRA 微调专家的 MoE	构建适配器混合专家模型。灵感来自 xlora | LoRA 混合 | MoLE | PHATGOOSE | MoELoRA
Hugging Face 博客	深入探讨 mergoo 库中合并方法背后的研究细节
基于 LLaMa3 的专家	通过整合基于 LLaMa3 的领域专家，构建您自己的 MoE 风格大语言模型专家
基于 Phi3 的专家	通过合并基于 Phi3 的微调模型，创建 MoE 风格的大语言模型架构

Mergoo 路线图与贡献

作为一款处于快速发展的开源库，我们热烈欢迎各种形式的贡献，无论是引入新功能、优化基础设施，还是改进文档。

以下是 mergoo 的路线图：

• 支持 Transformer 块中的 MoE
• 与 Hugging Face 🤗 兼容
• 支持 Trainer 和 SFTrainer
• 在 BTX 中加载统一检查点
• 功能：可转换的 QKV 线性层
• 功能：可转换的 FF 线性层
• 功能：仅针对解码器层索引列表的路由器
• 分片式 Safetensor 保存
• 支持基于 LLaMa 和 Mistral 的专家模型
• 支持基于 Phi3 的专家模型
• 支持 LORA 专家混合（适配器混合）
• 路由器负载均衡损失
• 合并过程中为降低内存使用而实现张量的懒加载
• 支持其他按层合并的方法，包括 Mergekit
• 支持基于 Gemma 和 Mamba 的专家模型
• 支持 Flash Attention
• 支持深度混合 Transformer

欢迎您提出新功能建议和/或参与 mergoo 路线图的建设！

加入我们的社区吧！

🚀 我们非常期待您的反馈，请加入 Leeroo 社区：

• Twitter
• LinkedIn
• 官网
• Discord

如果您有未在此列出的问题，欢迎在 GitHub 上提交 Issue，或发送邮件至 [support@leeroo.com]！

Mergoo 快速上手指南

Mergoo 是一个用于轻松合并多个大语言模型（LLM）专家并高效训练合并后模型的 Python 库。它支持混合专家（MoE）、混合适配器（MoA）等多种合并策略，兼容 Llama、Mistral、Phi3 等主流基座模型。

环境准备

• 操作系统：Linux, macOS, Windows
• Python 版本：建议 Python 3.8+
• 硬件支持：CPU, MPS (Mac), GPU (CUDA)
• 前置依赖：
  • PyTorch
  • Hugging Face Transformers
  • Hugging Face PEFT (如需使用 LoRA 合并)
  • Hugging Face TRL (可选，用于 SFT 训练)

国内加速建议： 安装依赖时推荐使用清华或阿里镜像源，以提升下载速度：

pip install torch transformers peft trl -i https://pypi.tuna.tsinghua.edu.cn/simple

安装步骤

方式一：通过 PyPI 安装（推荐）

pip install mergoo

国内加速版：

pip install mergoo -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：安装 GitHub 最新开发版

pip install git+https://github.com/Leeroo-AI/mergoo

方式三：源码安装

git clone https://github.com/Leeroo-AI/mergoo
cd mergoo
pip install -e .

基本使用

以下示例展示如何配置并合并多个基于 Mistral 的专家模型（包含数学和代码能力的专家），生成一个混合专家模型。

1. 配置合并参数

定义需要合并的专家模型列表及路由层设置：

config = {
    "model_type": "mistral",
    "num_experts_per_tok": 2,
    "experts": [
        {"expert_name": "base_expert", "model_id": "mistralai/Mistral-7B-v0.1"},
        {"expert_name": "expert_1", "model_id": "meta-math/MetaMath-Mistral-7B"},
        {"expert_name": "expert_2", "model_id": "ajibawa-2023/Code-Mistral-7B"}
    ],
    "router_layers": ["gate_proj", "up_proj", "down_proj"]
}

2. 执行合并并保存

使用 ComposeExperts 类加载配置，执行合并并保存检查点：

import torch
from mergoo.compose_experts import ComposeExperts

# 设置保存路径
model_id = "data/mistral_moe_merged"

# 初始化合并器并执行
expertmerger = ComposeExperts(config, torch_dtype=torch.float16)
expertmerger.compose()
expertmerger.save_checkpoint(model_id)

3. 加载与微调

合并完成后，可直接使用 Hugging Face Trainer 加载模型进行后续微调：

from transformers import Trainer
from mergoo.models.modeling_mistral import MistralForCausalLM

# 加载合并后的模型
# 注意：初次加载时，未训练的路由层（gate/router）可能会产生权重加载警告，属正常现象
model = MistralForCausalLM.from_pretrained("data/mistral_moe_merged") 

# 配置并启动训练
trainer = Trainer(
    model=model,
    # ... 其他训练参数 (args, data_collator, train_dataset 等)
)
trainer.train()

提示：若需合并 LoRA 适配器（Mixture of Adapters），只需在配置中将 expert_name 前缀改为 adapter 并指定 base_model 即可，具体可参考官方 Notebook 教程。