本文带你逐字段读懂gemma-4-e2b-it-OptiQ-4bit-decision这个 Gemma-4 E2B 决策模型的全部配置文件：config.json 的 4-bit 混合精度量化策略、joint_head 联合头参数、optiq_metadata.json 的位宽元数据，以及 LoRA 适配器与 KV 缓存配置，是 Apple Silicon 上运行该模型的完整配置指南。

📦 模型是什么

这个模型把 gemma-4-e2b-it-OptiQ-4bit 底座改造成了类型化决策模型（Typed Decisions）：在骨干上加一层 LoRA，并新增一个 joint schema 头，一次前向同时回答 noul、choice、score 三类问题。

• 运行环境：Apple Silicon + MLX + OptiQ，optiq serve对外暴露/v1/systemone接口
• 磁盘体积：约 5.4 GB（4-bit 骨干 + 视觉 sidecar + LoRA 适配器 + 决策头）
• 训练方式：仅用基准测试自带的训练集（1,080 条记录，3 epochs，LoRA rank 16）
• 实测表现：400 个用例（2,000 次决策）上 Accuracy0.802、Brier0.039，p50 延迟 0.99 s（M3 Max）

更多评测明细见 README.md。

🧩 文件清单：先看仓库里有什么

⚙️ config.json 逐字段清单

这是整个仓库信息量最大的文件（2400+ 行），可按四块理解：

1️⃣ 顶层标识

2️⃣ 多模态特殊 token（config.json）

3️⃣ quantization：混合精度量化核心

config.json 中quantization定义了默认规则：

• 默认位宽：bits: 4，group_size: 64，mode: affine（仿射分组量化，每 64 个元素共享一组 scale/zero-point）
• 逐张量覆盖：文件随后用上千行 JSON 为每个投影矩阵单独指定 4-bit 或 8-bit，例如embed_tokens保持 8-bit、第 0 层全部投影 8-bit、第 1 层起 MLP 降为 4-bit。这一份覆盖清单与 optiq_metadata.json 的per_layer严格对应

4️⃣ 三塔结构参数

optiq_vision块（config.json）声明了 sidecar 的位置：sidecar: "optiq/optiq_vision.safetensors"，共 1411 个张量，来自 bf16 底座，用于在 4-bit 主干上保留视觉/音频的高精度。

🎯 joint_head：决策联合头怎么配置

joint_head_config.json 只有 6 个字段，却定义了模型最核心的"决策大脑"：

权重存放在 joint_head.safetensors。这个头让模型无需生成自然语言文本，而是一次前向直接输出三类问题的结构化答案，这也是它 p50 延迟只有 0.99 s 的关键。

配套的 decision_config.json 提供三组温度[1.071, 0.983, 1.026]，分别校准三类问题各自的概率温度，用于让输出置信度更接近真实概率（直接影响 Brier 与 KL 指标）。

📊 optiq_metadata.json 逐字段清单

这份文件记录 OptiQ 混合精度量化的完整"配方"，字段不多但全是干货：

规律很清晰：越靠近首尾的层（第 0 层与第 34 层）越敏感，全部保留 8-bit；中间层的q_proj、k_proj等注意力投影多为 8-bit，MLP 的gate/up/down_proj大量 4-bit。

🔌 其余配置文件速览

• adapter_config.json：fine_tune_type: lora、decision_model: true、num_layers: 35；LoRA 参数rank: 16、scale: 1.0、dropout: 0.0，注入键覆盖q/k/v/o_proj、MLP 三个投影及linear_attn投影
• kv_config.json：KV 缓存的逐层量化表（layer_idx0–14，bits4 或 8，group_size: 64），长上下文推理时进一步压缩缓存显存
• generation_config.json：默认temperature: 1.0、top_k: 64、top_p: 0.95、do_sample: true，eos_token_id为[1, 106, 50]三个候选
• tokenizer_config.json：处理器为Gemma4Processor，左填充（padding_side: left），内置response_schema定义了工具调用解析规则（call:(?P<name>\w+)...正则），支持 thinking、tool_calls 结构化输出
• chat_template.jinja：Google 官方 Gemma 4 对话模板，处理多轮闭合、工具调用循环与 thinking 内容顺序

🚀 快速上手

pip install -U mlx-optiq optiq serve --model mlx-community/gemma-4-e2b-it-OptiQ-4bit-decision

如果需要在其他目录本地克隆该仓库做实验：

git clone https://link.gitcode.com/i/a1c9c83a3495af5b03284f157e230c82

💡 小结

这个仓库的配置设计有三个值得学习的点：

1. 混合精度而非一刀切：默认 4-bit + 敏感张量提升 8-bit，实测 5.258 bpw 换来了接近全精度骨干的决策精度
2. sidecar 分离多模态塔：4-bit 语言主干与 bf16 视觉/音频塔分文件存放，用optiq_vision字段声明装配关系
3. 决策头替代文本生成：joint head 一次前向输出类型化决策，配合三路温度校准，把延迟压到 1 秒以内

读懂上面的清单后，你就可以自由校验任意一份 OptiQ 4-bit 决策模型的完整性——只要quantization、per_layer与kv_config三者位宽一致，模型就是健康的。