LFM2.5-230M-Base-CMoE-e8s2a2

本模型是 LiquidAI/LFM2.5-230M-Base 的 CMoE (Carved Mixture-of-Experts,arXiv:2502.04416) 转换版本,采用论文标准的 Carving by Sharing (无冗余切分) 策略。

⚠️ 重要说明:本模型是 fine-tune 起点,不是即开即用的推理模型。init 时模型输出严重偏离 dense 原模型,需要少量 fine-tune 才能恢复生成能力。详见下方 init 行为说明。

配置:e8s2a2

符号	含义	值
e8	总 expert 数	8
s2	shared expert 数 (通过 expert_bias 始终路由)	2
a2	每 token 激活的 routed expert 数	2

每个 token 共激活 4 个 expert (2 shared + 2 routed)。配合 moe_intermediate_size = 320 = 2560/8:

• 总参数量: 229,791,488 (vs dense 229,693,184,膨胀率仅 1.0004×,多出的 98K 是 router 权重和 expert_bias)
• 每 token 激活 intermediate: 4 × 320 = 1280 (dense 的 50%)
• expert 容量: 8 个 expert,每个 320 维,总容量 8×320 = 2560 (= dense),无冗余拷贝

这是 CMoE 论文的标准做法 — 在不增加总参数量的前提下,把 dense FFN 的 1/8 子空间分给 8 个 expert,后续 fine-tune 让 router 学会根据 input 选对子空间组合,expert 各自专精。

加载方式 (LFM 官方模板,无需 trust_remote_code)

from transformers import AutoModelForCausalLM, AutoTokenizer, TextStreamer
import torch

model_id = "dokoomae/LFM2.5-230M-Base-CMoE-e8s2a2"
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    device_map="auto",
    dtype=torch.bfloat16,
    # attn_implementation="flash_attention_2"  # 在支持的 GPU 上取消注释
)
tokenizer = AutoTokenizer.from_pretrained(model_id)
streamer = TextStreamer(tokenizer, skip_prompt=True, skip_special_tokens=True)

prompt = "What is C. elegans?"
input_ids = tokenizer.apply_chat_template(
    [{"role": "user", "content": prompt}],
    add_generation_prompt=True,
    return_tensors="pt",
    tokenize=True,
)["input_ids"].to(model.device)

# 注意: 直接 generate 在 init 时输出质量很差 (乱码或早停),
# 必须先做 short fine-tune (SFT, 1-3 epoch) 让 router 和 expert 适配后再推理
output = model.generate(
    input_ids,
    do_sample=True,
    temperature=0.1,
    top_k=50,
    repetition_penalty=1.05,
    max_new_tokens=512,
    streamer=streamer,
)

init 行为说明

为什么 init 不能直接推理

CMoE 论文 (arXiv:2502.04416) 的设计意图:

1. Carving = 有意义的初始化:expert 权重来自 dense FFN 的真实子空间,不是随机初始化
2. 不要求零样本等价 dense:init 时输出可以偏离 dense,只要 "有意义" 即可
3. 预期 fine-tune 恢复:carve 后必须做 short fine-tune,让 router 学会路由 + 让 expert 专精

具体到 e8s2a2 Sharing:

• 8 个 expert 各自负责 dense FFN 的 1/8 intermediate 子空间 (320 维)
• 每 token 只激活 4 个 expert,覆盖 50% 的 intermediate 维度
• 未激活的 expert 输出 = 0 (因 SwiGLU 的 silu(0) × w3(0) = 0)
• FFN 输出 magnitude 约为 dense 的 50%,残差流被 attention 主导,输出分布偏离 dense

init 时与 dense 的对比 (CPU,bfloat16)

对 prompt "What is C. elegans?":

指标	Dense	e8s2a2 (本模型)	e4s2a2 (参考)
argmax next token	C	<|cot_start|> (init 偏离)	C (init 严格等价)
logits 平均绝对差异	—	2.18	0.031
生成质量	流畅	乱码 / 早停	流畅
是否需要 fine-tune	否	是	否

与 e4s2a2 Sharing 的对比

本模型 (e8s2a2 Sharing) 与姊妹模型 dokoomae/LFM2.5-230M-Base-CMoE-e4s2a2 的关键区别:

维度	e4s2a2 (姊妹模型)	e8s2a2 (本模型)
expert 总数	4	8
每 expert intermediate	640	320
激活 expert/token	4	4
激活 intermediate/token	2560 (= dense)	1280 (= dense 的 50%)
总参数量	229.7M (= dense)	229.8M (= dense)
init 是否等价 dense	严格等价	偏离 (需 fine-tune)
是否需要 fine-tune	否	是
fine-tune 潜力	4 个 expert 容量	8 个 expert 容量 (2×)
适用场景	即开即用	打算 fine-tune 时使用

核心权衡:e8s2a2 牺牲了 init 的可用性,换取 2× 的 expert 容量 (8 vs 4)。如果打算做 fine-tune,e8s2a2 潜力更大;如果直接用,e4s2a2 更合适。

转换细节

架构

• 源模型: Lfm2ForCausalLM (dense,14 层混合 conv/attention,hidden=1024,FFN intermediate=2560)
• 目标模型: Lfm2MoeForCausalLM (transformers 原生类,无需 trust_remote_code=True)
• MoE 层: 第 2–13 层 (前 2 层保持 dense,遵循 LFM2-MoE 惯例)
• 每个 expert 的 intermediate size: 320 (= 2560 / 8 expert)

Carving 策略:Carving by Sharing (无冗余)

把 dense SwiGLU FFN (w1, w2, w3,intermediate dim=2560) 沿 intermediate 维度等分成 8 块 (每块 320),直接映射到 8 个 expert,没有任何复制或噪声:

expert id	来源	角色	expert_bias
0	chunk 0 (intermediate 0–320)	shared (始终路由)	100.0
1	chunk 1 (intermediate 320–640)	shared (始终路由)	100.0
2	chunk 2 (intermediate 640–960)	routed (bias 倾向被选)	50.0
3	chunk 3 (intermediate 960–1280)	routed (bias 倾向被选)	50.0
4	chunk 4 (intermediate 1280–1600)	routed	0.0
5	chunk 5 (intermediate 1600–1920)	routed	0.0
6	chunk 6 (intermediate 1920–2240)	routed	0.0
7	chunk 7 (intermediate 2240–2560)	routed	0.0

init 时的路由行为

1. Router 权重零初始化 → 所有 expert 的 sigmoid score 都是 0.5
2. expert_bias = [100, 100, 50, 50, 0, 0, 0, 0] 让 top-4 选择固定为 [0, 1, 2, 3] (即 dense FFN 的前 4 块)
3. norm_topk_prob=True 把 top-K sigmoid 权重归一化到和为 1 (每个 0.25)
4. routed_scaling_factor = 1.0 (论文默认,不补偿)
5. 4 个被选 expert 的输出 = 0.25 × (chunk_0 + chunk_1 + chunk_2 + chunk_3),只覆盖 dense FFN 前 50% 的 intermediate

Fine-tune 后的预期行为

• Router 学习:router 权重从零开始学,根据 input 选出对当前 token 最相关的 4 个 expert 子空间
• Expert 专精:每个 expert 在它负责的 320 维子空间内专精某些模式 (例如不同 token 类型、不同语义类别)
• 能力恢复:论文实验显示,short fine-tune (1-3 epoch) 后 MoE 模型能力恢复到接近 dense 水平
• 能力超越:更长的 fine-tune 后,MoE 模型能力可超过 dense (因 expert 容量是 dense 的 8×,有更多专精空间)

速度对比 (CPU,bfloat16,max_new_tokens=128)

指标	Dense	e4s2a2	e8s2a2 (本模型)
参数量	229,693,184	229,742,336	229,791,488
forward 平均 (ms)	62.7	77.8	67.4
generate 平均 (s)	7.57	9.29	— (init 不可用)
tokens/sec	16.92	13.77	— (init 不可用)

说明:e8s2a2 init 时生成乱码或早停,所以 generate 速度无意义。CPU 上 MoE 因 router + scatter/gather 开销略慢于 dense,在 CUDA GPU 上 (尤其是配合 grouped-GEMM kernel) MoE 在相同激活参数量下通常能达到与 dense 相当或更快的速度。

文件清单

文件	说明
config.json	Lfm2MoeConfig (model_type=lfm2_moe)
model.safetensors	Carved 权重 (229.8M 参数,bfloat16)
generation_config.json	生成默认配置 (从源模型拷贝)
tokenizer.json	Fast tokenizer (从源模型拷贝)
tokenizer_config.json	Tokenizer 配置 (从源模型拷贝)
chat_template.jinja	Chat template (从源模型拷贝)
LICENSE	LFM Open License v1.0 (继承自源模型)

使用建议

1. 直接推理: 不要直接用,init 输出不可读。请改用姊妹模型 dokoomae/LFM2.5-230M-Base-CMoE-e4s2a2
2. 作为 fine-tune 起点: 推荐用法。在 SFT 数据集上 fine-tune 1-3 epoch,router 和 expert 会快速适应,生成质量恢复到接近 dense 水平
3. Fine-tune 数据量: 论文显示 1-3B token 的 SFT 数据即可让 router 学到合理的路由策略
4. GPU 加速: 配合 attn_implementation="flash_attention_2" 和 grouped-GEMM kernel 可获得最大加速

许可证

LFM Open License v1.0 (继承自源模型 LiquidAI/LFM2.5-230M-Base)。

重要条款:

• 年营收低于 1000 万美元的实体可免费用于商业用途
• 年营收超过 1000 万美元的实体需另行与 Liquid AI 签订商业许可
• 合格的非营利组织 (501(c)(3) 或同等机构) 用于非商业/研究目的不受营收门槛限制

完整许可证文本见同仓库的 LICENSE 文件。

参考

• CMoE 论文: Carved Mixture of Experts (arXiv:2502.04416)
• 源模型: LiquidAI/LFM2.5-230M-Base
• 姊妹模型 (e4s2a2,init 严格等价 dense,即开即用): dokoomae/LFM2.5-230M-Base-CMoE-e4s2a2