配置参数逐个讲:Laguna-S-2.1-OptiQ-2bit的config.json、generation_config.json与量化设置完全手册
配置参数逐个讲:Laguna-S-2.1-OptiQ-2bit的config.json、generation_config.json与量化设置完全手册
Laguna-S-2.1-OptiQ-2bit 是 Poolside 的 Laguna-S-2.1 大语言模型经 OptiQ 静态混合精度量化后的版本,面向 MLX / vLLM 推理框架。本文带你逐个读懂 config.json、generation_config.json 与 optiq_metadata.json 里的关键参数,帮你快速理解这个 2-bit 量化模型"长什么样"、"怎么跑"。
先认识这个模型:它是什么
在啃参数之前,先建立直觉。Laguna-S-2.1-OptiQ-2bit 有两个"身份标签":
| 标签 | 含义 |
|---|---|
| Laguna-S-2.1 | 底座模型,采用 MoE(混合专家)+ MLA(多潜头注意力)架构,约 117.56B 参数 |
| OptiQ-2bit | 使用 OptiQ 工具做了 2-bit 混合精度量化,把体积压到约 2.5 bit/参数 |
它的关键特性来自 README.md 的头部元数据:library_name: mlx、pipeline_tag: text-generation、base_model: poolside/Laguna-S-2.1,并声明了 openmdw-1.1 开源协议。权重被切分为 9 个分片(model-00001-of-00009.safetensors ~ model-00009-of-00009.safetensors),由 model.safetensors.index.json 索引映射。
💡 一句话概括:这是一个把 MoE 大模型压到 2-bit 左右、专为苹果 MLX 等框架本地推理优化的量化模型。
一、config.json 参数逐个讲
config.json 是模型的"身份证",告诉推理框架"我是什么结构、怎么初始化"。它约 4400+ 行,绝大部分篇幅是逐层的量化配置,我们把核心参数分成四类来看。
1. 模型架构类参数
这些字段定义了模型的"骨架",都集中在 config.json 开头。
| 参数 | 取值 | 通俗解释 |
|---|---|---|
model_type |
laguna |
模型家族名,框架据此加载对应实现 |
architectures |
LagunaForCausalLM |
顶层类名,见 modeling_laguna.py |
auto_map |
LagunaConfig / LagunaForCausalLM |
自动映射到本地自定义代码 |
hidden_size |
3072 |
每个 token 的隐层维度 |
num_hidden_layers |
48 |
Transformer 层数 |
vocab_size |
100352 |
词表大小 |
intermediate_size |
12288 |
稠密 MLP 的中间层宽度 |
head_dim |
128 |
每个注意力头的维度 |
torch_dtype |
bfloat16 |
训练/参考精度 |
tie_word_embeddings |
false |
输入/输出词嵌入不共享 |
其中 auto_map 指向的 configuration_laguna.py 和 modeling_laguna.py 正是这个自定义架构的实现源码,AutoConfig 会被解析成 LagunaConfig,AutoModelForCausalLM 解析成 LagunaForCausalLM——这是它能被 HuggingFace 生态"识别"的关键。
2. MoE 混合专家类参数(模型的核心)
Laguna 的主体是 混合专家(Mixture of Experts, MoE),每个 token 只激活部分专家,从而"参数大、计算省"。
| 参数 | 取值 | 通俗解释 |
|---|---|---|
num_experts |
256 |
每层路由专家总数 |
num_experts_per_tok |
10 |
每个 token 实际激活的专家数(Top-10 路由) |
moe_intermediate_size |
1024 |
单个路由专家的 MLP 宽度 |
shared_expert_intermediate_size |
1024 |
始终激活的"共享专家"宽度 |
moe_routed_scaling_factor |
2.5 |
路由输出缩放系数 |
norm_topk_prob |
true |
对 Top-K 路由概率归一化 |
decoder_sparse_step |
1 |
每层都走稀疏(MoE)分支 |
gating |
per-head |
门控按注意力头计算 |
mlp_layer_types |
第 0 层 dense,其余 sparse |
只有第 0 层是稠密 MLP,1~47 层全是 MoE |
📌 理解要点:mlp_layer_types 表明第 0 层用普通稠密 mlp,而第 1~47 层用 sparse(即带 switch_mlp + shared_expert 的专家路由)。这解释了后面量化配置里为什么层号 0 的键名是 mlp.*,而 1~47 层是 mlp.switch_mlp.* / mlp.shared_expert.*。
3. 注意力与上下文长度类参数
| 参数 | 取值 | 通俗解释 |
|---|---|---|
num_attention_heads |
48 |
全注意力层的头数 |
num_key_value_heads |
8 |
KV 头数(GQA 分组查询注意力,省显存) |
num_attention_heads_per_layer |
48 / 72 交替 |
每层实际头数,随层类型变化 |
layer_types |
full_attention / sliding_attention |
每层注意力类型 |
sliding_window |
512 |
滑窗注意力的窗口大小(token) |
max_position_embeddings |
1048576 |
最大上下文长度,即 1M token |
attention_dropout |
0.0 |
训练期注意力 dropout,推理无影响 |
rms_norm_eps |
1e-06 |
RMSNorm 数值稳定项 |
层类型规律:layer_types 以"1 个 full_attention + 3 个 sliding_attention"为周期重复 12 次,共 48 层。滑窗层只关注局部 512 个 token,大幅降低长文本计算量,这也是它敢标 1M 上下文的原因。
超长上下文怎么来的? 看 config.json 的 rope_parameters:
full_attention用 YaRN 位置编码,rope_theta500000、factor128,把原始8192的上下文放大 128 倍 → 约 1M;sliding_attention用defaultRoPE(rope_theta10000)。
🔑 YaRN 是一种 RoPE 外推方案,
factor: 128直接决定了上下文能从 8K 扩到 1M。这是"长文本能力"的技术来源。
4. 分词与 Token 类参数
| 参数 | 取值 | 说明 |
|---|---|---|
bos_token_id |
2 |
句首/结束 token |
eos_token_id |
[2, 24] |
两个结束 token |
pad_token_id |
9 |
填充 token |
这些和 tokenizer_config.json 里的 eos_token、pad_token 对应(如 〈|EOS|〉、〈|PAD|〉),实际词表在 tokenizer.json 中。对话行为则由 chat_template.jinja 这个模板驱动(支持 <system> / <user> / <assistant> 结构及 think 思考块)。
二、generation_config.json 参数逐个讲
generation_config.json 定义模型"怎么说话"——采样策略、结束条件、思考与工具调用行为。它只有 24 行,逐行看懂即可。
采样参数(决定输出"稳不稳")
| 参数 | 取值 | 通俗解释 |
|---|---|---|
do_sample |
true |
开启随机采样(而非贪心) |
temperature |
1.0 |
温度,1.0 表示不缩放概率分布 |
top_p |
1.0 |
核采样阈值,1.0 表示不按概率累计截断 |
top_k |
20 |
每步只从概率最高的 20 个 token 里选 |
min_p |
0.0 |
最小概率阈值,0 表示不启用 |
eos_token_id |
[2, 24] |
遇到这两个 token 停止生成 |
📌 组合效果:top_p=1.0 + top_k=20 表示实际生效的截断是"只留 Top-20 候选",再配合 temperature=1.0 从中随机选一个——既有多样性,又不会选到离谱的低概率词。
工具调用与思考模式(这个模型的"特色")
| 参数 | 取值 | 作用 |
|---|---|---|
tool_call_parser |
poolside_v1 |
解析模型输出的函数/工具调用格式 |
reasoning_parser |
poolside_v1 |
解析模型的推理(思考)内容 |
default_chat_template_kwargs |
enable_thinking: true |
默认开启思考模式 |
这是 Laguna 的重点能力:默认开启 enable_thinking,模型会先输出 think 推理块再给答案,并能用 poolside_v1 格式发起工具调用。这也和 chat_template.jinja 里 enable_thinking | default(true) 的设置一致。
推测解码 speculative_config(提速开关)
"speculative_config": {
"method": "dflash",
"source": "huggingface",
"model": "poolside/Laguna-S-2.1-DFlash",
"num_speculative_tokens": 15
}
| 字段 | 含义 |
|---|---|
method: dflash |
使用 DFlash 推测解码方案 |
model |
配套的草稿模型 Laguna-S-2.1-DFlash |
num_speculative_tokens: 15 |
每步最多推测 15 个 token |
推测解码用一个轻量草稿模型先"猜"一串 token,主模型再一次性校验,从而在几乎不降质的前提下提升生成速度。是否需要该草稿模型,取决于你的推理框架是否启用了 speculative_config。
三、量化设置深度解读(OptiQ 2-bit 的核心)
这是本模型最特别的部分,涉及两份文件:config.json 里的 quantization 字段 + 独立的 optiq_metadata.json。
static_mixed_precision:静态混合精度
config.json 的 quantization 字段定义了量化方案:
"quantization": {
"group_size": 64,
"bits": 4,
"mode": "affine",
"model.embed_tokens": { "bits": 4, "group_size": 64 },
...
}
| 字段 | 取值 | 通俗解释 |
|---|---|---|
mode |
affine |
仿射(缩放+偏移)量化方式 |
bits |
4 |
默认位宽 4-bit(全局兜底值) |
group_size |
64 |
每 64 个权重共享一组缩放/偏移参数 |
| 各张量子项 | {"bits": …} |
可单独覆盖某张量的位宽 |
🔑 关键:bits: 4 只是默认值,真正起作用的是下方按"层 → 张量"逐一指定的位宽——大部分张量保持 4-bit,只有特定 MoE 专家张量被降到了 2-bit,这就是名字里"2bit"的由来。
2-bit 与 4-bit 的分布规律
optiq_metadata.json 的摘要字段说明了全局策略:
| 字段 | 取值 | 含义 |
|---|---|---|
method |
static_mixed_precision |
静态混合精度量化 |
base_model |
poolside/Laguna-S-2.1 |
量化前的底座 |
reference |
structural_rules |
依据"结构规则"决定哪些张量降位 |
target_bpw |
2.5 |
目标平均位宽 2.5 bit |
achieved_bpw |
2.5023 |
实际达成 2.5023 bit/参数 |
n_high_bits |
417 |
4-bit 张量数量 |
n_low_bits |
109 |
2-bit 张量数量 |
全模型共 526 个张量被量化,其中 417 个 4-bit、109 个 2-bit。2-bit 的分布非常有针对性:
- 只落在 MoE 路由专家
mlp.switch_mlp的三个投影上(gate_proj/up_proj/down_proj); - 集中在第 5~41 层(第 5 层仅
up_proj为 2-bit,第 6~41 层三个投影全为 2-bit,共 37 层受影响); - 注意力投影(q/k/v/o/g)、共享专家
shared_expert、词嵌入与lm_head一律保持 4-bit。
💡 设计逻辑:路由专家数量多(256 个 × 47 层),对总体积极贡献最大,是"可以牺牲一点精度换空间"的地方;而注意力、共享专家、输出层对质量更敏感,所以保留在 4-bit。这种"该省的地方省、该保的地方保"的取舍,正是混合精度量化的价值所在。
量化前后的体积账
按 model.safetensors.index.json 的元数据,模型总参数约 117.56B。以 2.5 bit 平均位宽计,权重量化后体积约为原 bfloat16(16-bit)的 1/6.4 左右,这正是能在消费级设备(如 Apple Silicon 的 MLX)上加载运行的大 MoE 模型的关键。
四、完整文件清单速查
| 文件 | 作用 |
|---|---|
| README.md | 模型元数据、协议、框架标签 |
| config.json | 模型结构 + 逐张量量化配置(核心) |
| configuration_laguna.py | 自定义 Config 实现 |
| modeling_laguna.py | 自定义模型实现 |
| generation_config.json | 采样 / 思考 / 工具 / 推测解码配置 |
| optiq_metadata.json | OptiQ 量化元数据与逐层位宽 |
| tokenizer.json / tokenizer_config.json | 分词器词表与配置 |
| chat_template.jinja | 对话模板(含思考块) |
| model-0000X-of-00009.safetensors | 9 个权重分片 |
| model.safetensors.index.json | 权重张量 → 分片索引 |
小结:三句话记住这个模型
- 结构:MoE 混合专家(256 专家、Top-10 路由)+ MLA 注意力,48 层、约 117.56B 参数,支持 1M 上下文(YaRN 外推)。
- 行为:默认开启思考模式(
enable_thinking),top_k=20采样,支持poolside_v1工具调用,可用dflash推测解码提速。 - 量化:OptiQ 静态混合精度,注意力/共享专家/词表保持 4-bit,仅第 5~41 层的 MoE 路由专家降到 2-bit,平均位宽 2.50 bit,大幅压缩体积。
⚠️ 说明:
config.json与generation_config.json是模型的只读描述文件,用于推理框架初始化,一般无需手动修改;调整生成行为时优先改 generation_config.json 中的采样与思考参数。