• 大模型
• 基础模型
• 多模态
• 模型量化
• 本地部署

clef-8bit 是面向 Apple Silicon 的 Clef 决策模型（27B 参数）MLX 8-bit 量化移植版。它不是聊天模型，而是把"状态 + 问题 schema"在一次前向中直接输出每个合法选项的概率。本文以官方 PyTorch bf16 实现为基准，详解精度对拍（parity）的完整验证方法：文本场景 top answer 一致率 10/10，最大概率偏差仅 0.007。

先搞清楚：clef-8bit 是什么模型 🧩

Clef 来自 Cloudflare，属于决策模型（decision model）：输入一段状态（文本、JSON、图片或视频）加一组带类型的问题，模型直接给出每个候选选项的概率，一次性前向完成，不走逐 token 生成。

本仓库的核心文件分工如下：

⚠️ 注意：用 LM Studio、Ollama 或mlx_vlm.generate加载它只会跑主干、输出无意义文本，只有clef_mlx.py会同时执行决策头。

为什么必须做精度对拍

一次转换同时引入了两个独立误差源：

1. 量化误差：权重从 bf16 压到 8-bit（affine 量化、组大小 64）；
2. 框架实现误差：PyTorch → MLX 的算子与内核差异。

如果对拍不严谨，你无法判断"输出变了"到底是量化损失还是移植 bug。因此验证必须同时报告两个指标：

• Top answer 一致率：每题最高概率选项是否与参考实现相同（关心"答案对不对"）；
• Max abs Δprob：各选项概率与参考实现的最大绝对差（关心"置信度偏了多少"）。

实测结果一览 📊

README.md 中记录的 parity 数据（M5 Max，128 GB 内存，小样本抽查而非完整 benchmark）：

解读：

• 文本场景概率偏差 ≤0.007，top answer 全对，说明 8-bit 量化 + MLX 移植的累计误差非常小；
• 多模态场景偏差略大（0.032）也正常——视觉塔虽然保留 bf16，但多模态的数值路径更长；
• top answer 无一翻转，意味着在实际业务里"选错团队、判错紧急度"这类风险基本不存在。

如何复现这套对拍验证

第 1 步：准备环境

对拍不需要 PyTorch 参与 MLX 侧运行：

pip install "mlx-vlm>=0.7.4,<0.8" huggingface_hub

版本基线：mlx 0.32.3、mlx-lm 0.32.0、mlx-vlm 0.7.4，见 clef_mlx.py 中的TESTED_VERSIONS声明，版本不匹配时会主动告警。

第 2 步：获取模型

git clone https://gitcode.com/hf_mirrors/mlx-community/clef-8bit

第 3 步：跑通 MLX 侧推理

仓库自带命令行入口，无需写代码：

python clef_mlx.py predict \ --state "Checkout has been failing for every customer for the last hour." \ --questions '{"urgent": {"type": "noul", "instructions": "Is this urgent?"}}'

也可以以 Python 方式调用 load / predict 拿到每题的完整概率字典。

第 4 步：与 PyTorch 基准逐项比对

对拍流程的关键是控制变量：

1. 固定同一批测试记录（本文基准为 4 条文本记录 10 题 + 5 条多模态记录 9 题）和同一份问题 schema；
2. 分别喂给官方 PyTorch bf16 参考实现（joint_schema_model）与 MLX 8-bit 的 clef_mlx.py；
3. 逐题比对 top 选项与每个选项的概率，汇总一致率与最大 Δprob。

这套结果可信的前提在 README.md 的 Conversion 一节已交代：prompt/token 布局与参考实现逐 token 一致（含图片与视频），joint_head.safetensors 原样拷贝——因此两边输出差异只能来自主干量化和 MLX 内核计算，误差归因是干净的。

为什么 8-bit 还能保持一致性

• 量化粒度保守：affine 量化、group_size 64，主干 model-00001-of-00006.safetensors 等 6 个分片整体只引入微小逐元素扰动；
• 敏感部分不量化：vision tower 与决策头均保持 bf16；
• 输出方式抗扰动：概率由 JointSchemaHead 单次前向产生，隐状态的小幅偏差很少足以翻转 top 选项。

精度与体量的取舍怎么选

同系列四个变体（数据见 README.md）：

配套质量检查（Decision Index 抽样）：本模型 57.96 分，4-bit 版本 57.02 分，与 Cloudflare 公布的 61.21 分之差主要来自抽样噪声与评测管线差异，而非量化本身——这再次印证 8-bit 对答案质量的影响可忽略。

常见问题 FAQ

Q：对拍数据是完整 benchmark 吗？不是，是 spot-check（小样本抽查）。如需完整结论，建议按上节流程自跑更大样本集。

Q：输入超长怎么办？默认与参考实现一致，截断到 16,384 tokens 以内；传truncate=False会抛出clef_mlx.ContextTooLong错误（ContextTooLong）。

Q：4-bit 和 8-bit 我该选哪个？内存够（≥48 GB）优先 8-bit，精度更贴近 bf16 基准且延迟相近；16 GB 机器选 flash-4bit。

小结

clef-8bit 的对拍验证给出了量化移植的两个关键数字：top answer 10/10 全对、最大概率偏差 0.007（文本）/ 0.032（多模态）。验证方法的核心在于控制变量——token 布局与参考实现完全对齐、决策头零转换拷贝，使误差可以干净归因到量化本身。如果你的工作流依赖结构化决策输出，这套"双指标 + 固定样本集"的对拍范式同样可以迁移到自己的量化模型验证中。

• 大模型
• 基础模型
• 多模态
• 模型量化
• 本地部署