KL散度0.343、top-1一致86%:flint-mixed-3-4bit量化质量评估方法论(eval_kl.py实战)

原创2026-10-23 18:04:181,678 阅读
文章标签:模型量化代码模型大模型本地部署人工智能模型评测

KL散度0.343、top-1一致86%:flint-mixed-3-4bit量化质量评估方法论(eval_kl.py实战)

flint-mixed-3-4bit 是把 40B 编码模型 Recursive Flint 压到 17.8 GB、可跑在 24 GB Apple Silicon Mac 上的 MLX 混合量化版本。本文以仓库自带的 eval_kl.py 为主线,讲解 LLM 量化质量评估方法论:KL 散度 0.343、top-1 一致率 86% 这两个数是怎么算出来的,以及你自己评估任意量化模型时可以直接照搬的五步方法。

一、项目背景:95% 的权重砍到 3-bit,体积省出 4.8 GB

Flint 是 Recursive 出品的 40B 参数 MoE 编码模型(256 个专家、每 token 激活 6 个)。官方 INT4 版本 体积 22.6 GB,而 rec 应用要求 48 GB 内存。flint-mixed-3-4bit 的思路是只压缩最占体量的部分:

模型组件 位宽 说明
路由专家(switch_mlp 的 gate/up/down_proj) 3-bit 约占总权重 95%,本次压缩目标
Attention、共享专家、输出层 4-bit 沿用官方训练好的 INT4 值
词嵌入(embed_tokens) 8-bit 高精度保留

这个"哪些层压到多少位"的最终配置记录在 config.json 的 mlx_export 字段中。构建脚本是 experts3_from_int4.py:先把 INT4 专家反量化回浮点,再用 --mse 参数逐组(每 64 个权重一组)搜索最优截断比例(1.0 → 0.7 共 7 档,见 RATIOS 定义),保留平方误差最小的那一档。

💡 为什么从 INT4 出发而不是原始 BF16?因为 INT4 是训练过的量化权重,起点本身就更好——这一点在下面的 PPL 对比中会得到验证。

二、三个指标:读懂量化模型的"体检报告"

eval_kl.py 只输出三类数字,但足够判断一次量化"伤没伤模型":

1. KL 散度(KL Divergence)——分布级距离

模型预测下一个 token 时输出的是一整个概率分布。KL 散度衡量"量化模型的分布"和"参考模型(INT4)的分布"偏离多少,越小越接近,0 表示完全一致。

工程上有个关键优化:KL 只在参考模型的 top-32 个 token 加一个"其余全部"桶上计算(K=32 定义、KL 公式实现),而不是遍历整个 15 万+ 的词表。头部 token 集中了绝大部分概率质量,这样算又快又稳。

2. top-1 一致率——最直白的相似度

两个模型在同一个上下文中,猜的第一个 token 相同的比例。86% 意味着 100 次预测里约 86 次"第一选择"和参考模型完全一致。这个指标非技术读者也能秒懂。

3. 困惑度(Perplexity)——语言流畅度

在固定语料上,模型对真实下一个 token 的预测越自信,PPL 越低。注意:PPL 更低不等于量化模型"更强"——分布移动后恰好更偏爱真实 token 也会让 PPL 变低,所以必须和 KL、top-1 一起看。

三、eval_kl.py 实战:两步命令复现完整评估

脚本用法写在 文件头部注释,只有两个子命令:

# 第 1 步:用参考模型(INT4)跑一遍语料,保存 top-32 对数概率
python eval_kl.py ref flint-int4 ref.npz "**/*.swift" "**/*.py" "**/*.ts"

# 第 2 步:用量化模型跑同一语料,自动算出 PPL、KL、top-1
python eval_kl.py cmp flint-mixed-3-4bit ref.npz "**/*.swift" "**/*.py" "**/*.ts"

要点拆解:

  • 语料:默认抓取当前目录下所有 .py 文件,拼接切分成 48 段 × 1024 token(NSEQ, SEQ 参数)。README 中实测用的是 48 个私有代码文件(Swift / Python / TypeScript),确保不在任何训练集里。
  • 一致性校验:cmp 模式会断言两次运行的 token 化结果完全相同(assert 语句),避免"语料不对齐导致指标失真"这种低级错误。
  • uint8 打包补丁:Recursive 的 INT4 导出把权重打包成 uint8,而 mlx-lm 期望 uint32。patch_uint8_packing() 用 view 把字节原样重解释为 uint32(位布局相同),这是加载官方 INT4 的必要一步。

cmp 跑完打印一行结果,例如:

cmp flint-mixed-3-4bit: ppl 4.4187 (ref 4.6186) | KL mean 0.3430 p99 ... | top-1 agree 86.20%

四、实测数据解读:0.343 / 86.2% 处于什么水平

README 中的对比表给出了四种构建的横向数据:

构建方案 体积 KL ↓ top-1 一致率 ↑
本构建(INT4 专家 → 3-bit) 17.8 GB 0.343 86.2%
INT4 专家 → 3-bit,普通 min/max 比例 ~17.8 GB 0.332 85.9%
BF16 → 6-bit ~30 GB 0.341 86.4%
BF16 → 3-bit 专家 + 6-bit 其余 17 GB 0.490 82.3%

📊 三个值得记住的结论:

  1. 自校验先行:INT4 对比自己跑一遍,KL = 0.0000、一致率 100%——评估流程本身必须先"零误差自证"。
  2. 起点决定天花板:从 BF16 直接量化(无论压到几 bit),KL 和一致率都明显更差;用训练过的 INT4 当起点,17.8 GB 的 3-bit 版几乎追平 30 GB 的 6-bit 版。
  3. PPL 要谨慎解读:本构建 PPL 4.42 甚至低于 INT4 的 4.62,但 README 明确提示这不代表"超越了 INT4",只是分布移动后恰好更偏爱真实 token。

配合 generation_config.json 中 Recursive 官方推荐的采样参数(temperature 1.0 / top_p 0.95 / top_k 20)跑 6 项编码任务,结果 6/6 全部通过,与 INT4 表现一致——指标接近 + 任务达标,双证据才算评估闭环。

五、方法论清单:评估你自己的量化模型

把本项目的做法抽象出来,就是五步清单:

  1. 选对参考模型——用最强的现成版本(本项目用训练过的 INT4),而非从 BF16 重新量化;
  2. 准备私有留出语料——48×1024 token 的领域内文本,确保不在训练集;
  3. 先跑自校验——参考模型对比自身必须得到 KL≈0、100% 一致;
  4. top-K + 剩余桶算 KL——兼顾精度与速度;
  5. 指标 + 任务双验证——KL / top-1 / PPL 之外,用真实任务(编码测试、Agent 调用)兜底。

六、仓库文件速览

文件 作用
README.md 快速上手、完整数据与方法细节
eval_kl.py 质量评估:KL、top-1、PPL
experts3_from_int4.py 构建:INT4 专家 → 3-bit(MSE 截断搜索)
config.json 模型结构与逐层量化位宽配置
generation_config.json 官方推荐采样参数
chat_template.jinja 对话模板(思考内容与回答分离)
model.safetensors.index.json 四个分片权重的索引
tokenizer.json / tokenizer_config.json / special_tokens_map.json 分词器及特殊 token 定义

⚠️ 局限说明:本构建未经 3-bit QAT 训练,评估样本较小(单一 64 GB M5 Max 机器、小任务集),且尚未在真实 24 GB Mac 上验证——作者也建议在 Community 区反馈实测内存占用与速度。

登录后查看全文
flint-mixed-3-4bit