LFM2.5-24B-A2B-Preview-mxfp4完整配置参考:config.json与generation_config.json逐项说明
LFM2.5-24B-A2B-Preview-mxfp4完整配置参考:config.json与generation_config.json逐项说明
📦 LFM2.5-24B-A2B-Preview-mxfp4 是 Liquid AI 出品的 LFM2.5-24B-A2B-Preview 混合专家(MoE)文本生成模型在 Apple MLX 平台上的 mxfp4 量化版本。本文作为完整配置参考,对 config.json 与 generation_config.json 中的每个字段逐项说明,帮助你快速读懂这份 MLX 模型配置、正确加载并调优生成参数。
🧭 模型速览:24B 总参数,只有约 2B 激活
在逐项讲解之前,先建立整体认知:
| 项目 | 说明 |
|---|---|
| 模型类型 | MoE(混合专家)因果语言模型,架构为 Lfm2MoeForCausalLM |
| 参数量 | 总参数约 24B,每 token 只激活约 2B(A2B 即 Active 2B) |
| 量化格式 | mxfp4:4-bit 权重量化,group size 32 |
| 权重体积 | 共约 12.74 GB,拆分为 3 个 safetensors 分片 |
| 上下文长度 | 131,072 tokens(128K 长上下文) |
| 多语言 | 支持英文、中文、阿拉伯文、法文、德文、日文、韩文、西班牙文、葡萄牙文、意大利文 |
| 许可 | LFM Open License v1.0,见 LICENSE 与 NOTICE |
仓库文件构成如下,均可在仓库根目录直接查看:
| 文件 | 作用 |
|---|---|
| config.json | 模型结构与默认生成配置(本文主角之一) |
| generation_config.json | 独立生成的默认参数(本文主角之二) |
| conversion_info.json | 量化转换记录:源模型、工具版本、验证结果 |
| model.safetensors.index.json | 权重分片索引,映射每个张量到具体分片 |
| model-00001-of-00003.safetensors 等 3 个分片 | mxfp4 量化权重 |
| tokenizer.json / tokenizer_config.json | 分词器(词表 128000) |
| chat_template.jinja | 对话模板,支持 system 提示与工具调用 |
🏗️ config.json 逐项说明:模型架构部分
1️⃣ 身份与类型标识
| 字段 | 值 | 说明 |
|---|---|---|
architectures |
["Lfm2MoeForCausalLM"] |
加载时使用的模型类名,表明这是 MoE 因果语言模型 |
model_type |
lfm2_moe |
模型族标识,加载器据此选择对应实现 |
transformers_version |
5.12.1 |
导出时使用的 Transformers 版本,仅供参考 |
2️⃣ MoE 专家路由核心参数
这是理解 LFM2.5 高效的关键——每层内部藏着一组"专家",路由器每个 token 只挑选其中几个来工作:
| 字段 | 值 | 说明 |
|---|---|---|
num_experts |
64 |
每个 MoE 层共 64 个专家 |
num_experts_per_tok |
4 |
每个 token 激活 top-4 个专家,是"2B 激活"的来源 |
moe_intermediate_size |
1536 |
单个专家的 FFN 中间维度 |
num_dense_layers |
2 |
第 0、1 层为稠密 FFN(无专家路由),其余 38 层均为 MoE 层 |
use_expert_bias |
true |
启用专家负载均衡偏置(expert bias),防止个别专家被"刷爆" |
norm_topk_prob |
true |
对选中的 top-k 专家权重做归一化,保证输出稳定 |
routed_scaling_factor |
1.0 |
专家输出前的路由缩放系数,1.0 表示不缩放 |
intermediate_size |
11776 |
稠密层(前 2 层)的 FFN 中间维度 |
3️⃣ 层结构与注意力机制
LFM2.5 采用 卷积层(conv)为主、注意力层(full_attention)为辅 的混合架构,这是它长上下文高效的重要设计:
| 字段 | 值 | 说明 |
|---|---|---|
num_hidden_layers |
40 |
共 40 层 |
layer_types |
40 项序列 | 每 4 层出现 1 个 full_attention(第 2、6、10…38 层,共 10 个),其余 30 层为 conv |
conv_L_cache |
3 |
卷积层的缓存长度,控制推理时的状态大小 |
conv_bias |
false |
卷积不使用偏置项 |
hidden_size |
2048 |
隐藏层维度 |
num_attention_heads |
32 |
查询头数 |
num_key_value_heads |
8 |
KV 头数,采用 GQA(分组查询注意力),显著节省 KV 缓存 |
max_position_embeddings |
131072 |
最大上下文 128K tokens |
rope_parameters |
rope_theta=1e7, rope_type=default |
默认 RoPE 位置编码,基频 1000 万,适配长上下文 |
initializer_range |
0.02 |
权重初始化标准差 |
norm_eps |
1e-05 |
归一化层 epsilon |
💡 小贴士:layer_types 中的 conv 层用局部卷积替代全局注意力,长文本时计算量远低于全注意力层,这也是 128K 上下文能在消费级硬件上跑起来的关键。
4️⃣ 词表与特殊 Token
| 字段 | 值 | 说明 |
|---|---|---|
vocab_size |
128000 |
词表大小 |
bos_token_id |
124894 |
句首(begin of sequence)token |
eos_token_id |
[124900] |
句末 token,生成到它即停止 |
pad_token_id |
124893 |
填充 token |
tie_word_embeddings |
true |
输入嵌入与输出层共享权重,节省约 2048×128000 个参数 |
dtype |
bfloat16 |
未被量化的浮点权重(如归一化层、嵌入)保留为 BF16 |
5️⃣ 量化配置解读(mxfp4 策略)
quantization 与 quantization_config(两者内容一致)描述了权重量化策略,这是理解 "-mxfp4" 后缀的核心:
"quantization_config": {
"group_size": 32,
"bits": 4,
"mode": "mxfp4",
"language_model.model.layers.2.feed_forward.gate": {
"group_size": 64,
"bits": 8
}
// …第 2 至 39 层的 feed_forward.gate 均如此
}
| 字段 | 值 | 说明 |
|---|---|---|
mode |
mxfp4 |
Microscaling FP4 格式:4-bit 权重 + 每 32 个权重一个缩放因子 |
bits |
4 |
主体权重 4-bit 量化(仅量化权重,激活仍用全精度) |
group_size |
32 |
每 32 个权重共享一个缩放因子,精度与压缩率平衡 |
| 逐层覆盖项 | 第 2–39 层 feed_forward.gate |
MoE 路由器投影单独使用 8-bit 仿射量化(group size 64),因为路由器对精度敏感,4-bit 会损害路由质量 |
完整量化记录(含转换工具、RTN 方法、硬件为 Apple M3 Ultra、严格重载校验等)见 conversion_info.json。
6️⃣ 其他字段
| 字段 | 值 | 说明 |
|---|---|---|
use_cache |
true |
默认启用 KV/卷积缓存加速解码 |
do_sample / temperature / top_k |
true / 0.1 / 50 |
顶层默认采样参数,与 generation_config 内嵌块及独立文件保持一致 |
generation_config |
内嵌对象 | 模型配置中内嵌的生成默认值,与 generation_config.json 相同 |
vision_config |
{} |
空对象占位,本模型为纯文本生成模型 |
⚙️ generation_config.json 逐项说明:生成参数默认值
这个文件在推理时独立加载,决定"开箱即用"时的生成行为:
| 字段 | 值 | 说明 |
|---|---|---|
_from_model_config |
true |
标记该配置从模型配置中同步而来 |
bos_token_id |
124894 |
起始 token |
eos_token_id |
[124900] |
停止 token |
pad_token_id |
124893 |
填充 token |
do_sample |
true |
启用采样(非纯贪心解码) |
temperature |
0.1 |
温度极低 → 输出高度确定、保守稳定,适合知识问答 |
top_k |
50 |
每步只在概率最高的 50 个 token 中采样,进一步抑制幻觉 |
repetition_penalty |
1.05 |
轻微惩罚重复词,减少啰嗦复读 |
use_cache |
true |
启用缓存加速自回归解码 |
output_attentions |
false |
不返回注意力矩阵(省内存) |
output_hidden_states |
false |
不返回隐状态 |
transformers_version |
5.12.1 |
版本标记 |
🎯 参数调优建议:默认配置偏向"准确优先"。写创意内容时可适当调高 temperature(如 0.7–0.9);注意该模型会先输出推理过程再给出最终答案,因此 max-tokens 建议预留充足(如 1024 以上)。
📄 如何使用这份配置
本模型需在 MLX-VLM 的 LFM2.5 支持版本上运行(导出时实测 MLX 0.32.3、Transformers 5.17.0,见 conversion_info.json):
pip install mlx-vlm
python -m mlx_vlm generate \
--model LFM2.5-24B-A2B-Preview-mxfp4 \
--prompt "What is the capital of France? Answer briefly." \
--max-tokens 512 \
--temperature 0.1
建议直接使用仓库自带的 chat_template.jinja 组织对话(支持 system 提示词与工具调用),并配合 tokenizer.json 完成分词。
❓ 常见问题
问:12.74 GB 权重,显存/内存要留多少? 答:权重约 12.74 GB,加上 KV 缓存、卷积缓存和临时分配,建议预留 16–24 GB 统一内存(如 M 系列芯片 16GB 起步、24GB 更从容),长上下文时缓存占用会明显增加。
问:为什么路由器权重要单独用 8-bit?
答:MoE 路由器决定"每个 token 交给哪些专家",是模型能力的调度中枢。4-bit 精度下路由误差会被放大,因此第 2–39 层 feed_forward.gate 单独保留 8-bit,这是 mxfp4 版本在压缩率与路由稳定性之间的折中设计。
问:两个配置文件字段不一致怎么办?
答:以 generation_config.json 为生成行为的独立默认值;config.json 内嵌的 generation_config 块与之一致(_from_model_config 标记同步来源),实际推理时命令行参数优先级最高。
✅ 小结
config.json描述了 40 层、64 专家 top-4 路由的 MoE 架构,混合卷积/注意力设计 + GQA 支撑 128K 长上下文- mxfp4 量化主体 4-bit(group 32),路由器 8-bit 保护是精度关键
generation_config.json默认temperature=0.1、top_k=50,稳定保守,按需可调- 全部原始依据:config.json、generation_config.json、conversion_info.json、README.md