config.json参数逐个讲透:Spark-X2.6-4B-Base配置参考手册
config.json参数逐个讲透:Spark-X2.6-4B-Base配置参考手册
📌 Spark-X2.6-4B-Base 是 SparkLLM 团队推出的约 40 亿参数(实际 41.1 亿)端侧通用语言模型。这份 config.json 就是定义它"架构 DNA"的核心配置文件——本文带你逐个参数讲透,读懂混合注意力、100 万长上下文背后的配置逻辑。
1. config.json 是什么?30秒认识这份文件
| 文件 | 作用 | 一句话理解 |
|---|---|---|
| config.json | 模型架构配置 | 模型的"出生证明",决定结构怎么搭 |
| configuration_spark.py | 配置类实现 | 把 JSON 参数读进 Spark2_5Config 类 |
| modeling_spark.py | 模型结构代码 | 真正"搭积木"的神经网络实现 |
| generation_config.json | 生成默认参数 | 温度、top_p 等采样行为 |
| tokenizer_config.json | 分词器配置 | 对话模板 chat_template 所在地 |
| model.safetensors.index.json | 权重索引 | 记录 41.1 亿参数分布在哪些权重文件 |
💡 简单说:加载模型时,框架先读 config.json 知道"模型长什么样",再去读权重文件填充数值。
2. 身份识别类参数:框架如何认出它是 Spark
"architectures": ["Spark2_5ForCausalLM"],
"model_type": "spark2_5",
"auto_map": {
"AutoConfig": "configuration_spark.Spark2_5Config",
"AutoModel": "modeling_spark.Spark2_5Model",
"AutoModelForCausalLM": "modeling_spark.Spark2_5ForCausalLM"
},
"transformers_version": "4.57.1"
- architectures:告诉 transformers 库该用哪个类加载模型(因果语言模型,即"自回归预测下一个词")。
- model_type:模型家族标识
spark2_5,与 configuration_spark.py 中Spark2_5Config类的model_type一一对应。 - auto_map:Spark 是自定义架构,这里声明"请从本目录的
configuration_spark.py/modeling_spark.py加载自定义类"。这是很多开源模型能"开箱即用"的关键配置。 - transformers_version:记录导出时的框架版本(4.57.1),建议用相同或更新版本加载。
3. 规模类参数:4B 模型的身体骨架
| 参数 | 值 | 含义 |
|---|---|---|
hidden_size |
2560 | 隐藏层维度,每个 token 在模型内部的"表示宽度" |
num_hidden_layers |
36 | 模型深度,即 Transformer 堆叠 36 层 |
num_attention_heads |
16 | 每层注意力的 Q 头数量 |
num_key_value_heads |
4 | KV 头数量,16:4 的 GQA 分组注意力 |
head_dim |
256 | 每个注意力头的维度(2560÷16=160,这里刻意放大到 256) |
intermediate_size |
10240 | FFN/MLP 中间层维度,恰好是 hidden_size 的 4 倍 |
vocab_size |
131072 | 词表大小 13 万,多语言覆盖的基础 |
max_position_embeddings |
1048576 | 最大位置编码 100 万,支撑超长上下文 |
🔍 GQA 是个亮点:KV 头只有 Q 头的 1/4,推理时 KV Cache 显存占用大幅下降——这正是端侧部署省钱省显存的核心技巧。源码中的约束校验见 configuration_spark.py:num_attention_heads 必须能被 num_key_value_heads 整除。
权重索引文件显示,该模型共 4,112,079,360 个参数、bf16 下约 8.22GB(见 model.safetensors.index.json 的 metadata 字段),分 5 个 safetensors 文件存放。
4. 混合注意力参数:Spark 架构的"杀手锏"
这是 config.json 中最有特色的一组参数,直接决定模型如何兼顾长上下文与推理速度:
4.1 layer_types:滑动 + 全量注意力交替
"layer_types": [
"sliding_attention", "sliding_attention", "sliding_attention", "full_attention",
...
]
- 36 层中,每 3 层滑动注意力 + 1 层全量注意力(第 4、8、12……36 层为
full_attention)。 - sliding_attention:只看最近
sliding_window个 token,计算量小、速度快。 - full_attention:看到全部历史 token,负责"全局记忆"。
这种"3滑1全"的混合设计,让 100 万 token 的长文本也能高效处理——绝大多数层只算局部,少数层做全局。
4.2 sliding_window:滑动窗口宽度
"sliding_window": 512
滑动注意力层的"视野"为最近 512 个 token。窗口越小,注意力矩阵越稀疏,推理越快。
4.3 rope_parameters:两套 RoPE 位置编码
"rope_parameters": {
"full_attention": { "partial_rotary_factor": 0.25, "rope_theta": 5000000 },
"sliding_attention": { "partial_rotary_factor": 1.0, "rope_theta": 10000 }
}
| 层级 | rope_theta | partial_rotary_factor | 为什么这样配 |
|---|---|---|---|
| full_attention | 5,000,000 | 0.25 | 超大 base 值 + 部分旋转,专为 100 万级超长位置设计 |
| sliding_attention | 10,000 | 1.0 | 只需看 512 窗口,经典参数即可 |
rope_theta 越大,位置编码在远端位置越不容易"混淆";partial_rotary_factor 表示只有前 25% 的维度参与旋转。读取逻辑见 configuration_spark.py 的 get_rope_theta 与 get_partial_rotary_factor 方法。
5. 门控注意力与激活函数:细部设计
| 参数 | 值 | 含义 |
|---|---|---|
headwise_attn_output_gate |
true | 启用逐注意力头输出门控,每个头有独立"开关" |
gate_attn_act_mode |
sigmoid | 门控激活函数用 sigmoid(输出 0~1,像音量旋钮) |
hidden_act |
gelu | FFN 中间层激活函数用 GELU |
attention_bias / mlp_bias |
false | 线性层不带偏置,省参数省计算 |
attention_dropout |
0.0 | 推理时关闭注意力丢弃(训练期正则化手段) |
⚙️ 头级门控让模型能对不同注意力头动态加权"采纳多少",是近年提升小模型稳定性的流行技巧。
6. 精度、归一化与初始化
| 参数 | 值 | 含义 |
|---|---|---|
dtype |
bfloat16 | 权重以 bf16 存储,显存减半且数值稳定 |
rms_norm_eps |
1e-06 | RMSNorm 归一化的防除零小常数 |
initializer_range |
0.01976 | 权重初始化标准差(约 1/√2560) |
use_cache |
true | 推理默认启用 KV Cache,逐 token 生成不重复计算 |
7. 特殊 token 与词嵌入
"bos_token_id": 0, "eos_token_id": 1, "pad_token_id": 2,
"tie_word_embeddings": true
- bos / eos / pad:起始、结束、填充 token 的编号,与 special_tokens_map.json 中的
<|start▁of▁sentence|>、<|end▁of▁sentence|>、<|▁pad▁|>一一对应。 - tie_word_embeddings: true:输入嵌入表与输出嵌入表共享同一份权重,对 4B 级小模型是显著的参数省法。
8. 搭配 generation_config.json:生成行为速查
generation_config.json 定义了默认采样行为,新手最常问的参数都在里面:
| 参数 | 值 | 建议 |
|---|---|---|
temperature |
1.0 | 创作类任务可调 0.7 左右降低随机性 |
top_p |
0.95 | 核采样,通用默认 |
top_k |
-1 | 关闭 top-k 限制 |
max_tokens |
1048576 | 与 max_position_embeddings 对齐 |
另外,tokenizer_config.json 中的 chat_template 支持 thinking_effort(low / high)三档思考预算,配合 enable_thinking 开关可在推理质量与延迟之间自由权衡。
9. 常见疑问 FAQ
Q1:为什么 model_type 是 spark2_5 而不是 2.6?
X2.6 沿用 X2.5 的完全相同架构,能力提升来自后训练(见 README.md),因此 model_type 保持 spark2_5。
Q2:能改 hidden_size 等参数吗? 不建议。这些参数与 5 个权重文件严格绑定,改动会导致权重形状不匹配而加载失败。
Q3:想微调该用哪个配置?
架构参数无需改动,微调时保持 tie_word_embeddings: true 和 GQA 设置不变即可,官方推荐使用 Llama-Factory(见 README.md)。
10. 总结:一张表看懂 Spark-X2.6-4B-Base
| 维度 | 配置值 | 关键词 |
|---|---|---|
| 总参数 | 4.11B(bf16 约 8.2GB) | 端侧友好 |
| 结构 | 36 层 × 2560 维 | 标准 Transformer 深度 |
| 注意力 | 16Q/4KV 头 + 头级门控 | GQA + Gate |
| 上下文 | 100 万 token | 3滑1全混合注意力 |
| 词表 | 131,072 | 多语言 |
| 许可证 | Apache 2.0(见 LICENSE) | 可商用 |
读完这份 config.json,你已掌握了 Spark-X2.6-4B-Base 的全部架构密码——下次再看到其他模型的配置文件,也能一眼看懂它的"身体构造"了。🚀