企业官网建设流程全解析

• 人工智能
• 大模型
• 模型量化
• 模型优化
• 本地部署

更正标题笔误：# Agents-A1-OptiQ-4bit-REAP-19B文件结构全解：safetensors、kv_config与optiq_metadata完全清单

Agents-A1-OptiQ-4bit-REAP-19B是运行在 Apple Silicon（MLX）上的 19B 级 MoE 多模态模型：它把父模型的 35.1B 参数剪枝到 18.8B，磁盘占用从 21.5 GB 降到12.3 GB，运行仅需约 14.5 GB 内存。本文带你逐个读懂仓库里的 11 个文件——从safetensors权重分片、model.safetensors.index.json索引，到kv_config.json、optiq_metadata.json两大量化元数据，一次看清这套模型包的完整结构。

📦 一眼看懂：这套模型文件是干什么的

先记住这张"身份卡"，后面每个文件都能对号入座：

💡 关键机制一句话：剪掉的只是"没被路由选中的专家"，每个 token 激活的专家数仍是 8 个——所以模型变小了，速度却不变慢。

🗂️ 文件完全清单：11 个文件各管一摊

🧱 safetensors 权重分片：12.3 GB 如何切成 3 块

三个model-000XX-of-00003.safetensors分片按张量切分存放语言模型权重，分布并不均匀：

• 第 1 分片：553 个张量（含embed_tokens、前部网络层）
• 第 2 分片：712 个张量（最重的中间层段）
• 第 3 分片：492 个张量（含lm_head等尾部权重）

三个分片合计1757 个张量，总字节数12,355,664,128（约 12.3 GB），这个数字就写在 model.safetensors.index.json 的metadata.total_size里。

另外注意：*.safetensors和tokenizer.json都在 .gitattributes 中被声明为Git LFS文件。如果你在本地 mirror 里看到它们只有 100 多字节，那是 LFS 指针文件——用git lfs pull或git lfs install后重新 clone 即可拉到真实权重。

optiq_vision.safetensors：视觉塔为何单独存放

optiq/optiq_vision.safetensors 是一个侧车（sidecar）文件，存放视觉编码器（vision tower）的全部333 个张量，以bfloat16 原精度保留、不参与 4bit 量化。索引表中它们同样登记在册，例如：

• vision_tower.blocks.0.attn.qkv.weight→optiq/optiq_vision.safetensors
• vision_tower.blocks.27.attn.proj.bias→optiq/optiq_vision.safetensors

这种"语言侧量化、视觉侧保精度"的拆分，正是 OptiQ 多模态模型的典型做法，配置入口在 config.json 的optiq_vision字段（sidecar: optiq/optiq_vision.safetensors）。

🗺️ model.safetensors.index.json：张量分布速查表

这个 206 KB 的 JSON 是整个权重包的"目录页"，两大块内容：

{ "metadata": { "total_size": 12355664128 }, "weight_map": { "language_model.model.embed_tokens.weight": "model-00001-of-00003.safetensors", "...共 2090 个张量条目..." } }

张量名本身也透露了量化细节：每个量化矩阵都拆成三份——

比如language_model.model.layers.0.linear_attn.in_proj_a.weight / .scales / .biases三个张量同属第 0 层的线性注意力输入投影。

⚙️ config.json：架构与混合精度配置

config.json（约 116 KB，大部分篇幅是逐层量化位宽）顶层关键字段：

• architectures：Qwen3_5MoeForConditionalGeneration——带视觉/视频 token 的 MoE 生成模型（image_token_id: 248056、video_token_id: 248057）
• text_config：40 层（num_hidden_layers: 40）、隐藏维度 2048、词表 248320；剪枝后num_experts: 128，num_experts_per_tok: 8
• 注意力混合：layer_types中 30 层是linear_attention，每 4 层插一层full_attention（即第 3、7、11…39 层）
• quantization：默认bits: 4, group_size: 64, mode: affine，再用 500 多条逐层覆写把敏感层提到 8bit

📌 剪枝痕迹就藏在num_experts：父模型每层 256 个专家，这里只剩 128——-19B这个名字由此而来。

🔢 kv_config.json：KV Cache 量化清单（仅 10 行配置）

kv_config.json 很小，却直接决定长上下文的内存开销。它只列出全注意力层（线性注意力层不需要 KV Cache）的缓存量化位宽：

规律一目了然：8 个层用 4bit KV，仅第 11、15 层用 8bit 保精度，全部group_size: 64。推理框架读到这个文件，就会对相应层的 K/V 缓存按位宽压缩，显著降低长对话的显存压力。

🧾 optiq_metadata.json：量化与剪枝的"完整档案"

optiq_metadata.json（约 122 KB）是理解这个模型为什么是现在这个样子的核心档案，分四块：

1️⃣ 混合精度总览

即：绝大多数张量压到 4bit，397 个对精度敏感的张量（如各层注意力投影、共享专家、lm_head）保留 8bit，最终平均4.513 bpw。

2️⃣ per_layer：510 条逐张量位宽表

per_layer按层号.模块名给出每个张量的bits与group_size，与 config.json 的quantization一一对应，例如：

"language_model.model.layers.39.mlp.shared_expert_gate": { "bits": 8, "group_size": 64 }

3️⃣ expert_pruning：REAP 剪枝全程记录

• 方法：reap（路由器权重 × 专家输出范数的条件均值排序，保留排名靠前的专家）
• 规模：每层256 → 128（uniform_retention: true），top_k: 8路由不变
• 体积：专家权重从19.6 GB 砍到 9.8 GB（expert_bytes_before/after）
• 校准：optiq 六领域混合 8 个样本，seed: 42，专家覆盖率下限 0.9766
• retained_experts：逐层列出被保留的 128 个专家编号，可复现验证

参考同架构的验证结论：50% 保留率下 KL 散度仅0.077（明显退化的剪枝模型 >1.0），生成质量在人工评审中难以区分。详见 README.md。

4️⃣ 与 config.json 的对应关系

optiq_metadata.json是制作过程档案（谁做的、怎么选的），config.json的quantization是运行时配置（加载时真正读取的位宽）。两者数值一致，修改模型行为时以config.json为准。

🗣️ 推理三件套：tokenizer、模板与加载方式

在装有mlx-lm的环境里，两条命令即可跑起来：

pip install mlx-optiq optiq serve --model mlx-community/Agents-A1-OptiQ-4bit-REAP-19B

或直接用mlx_lm加载（权重、分词器、kv_config.json都会按上文结构自动解析）。

✅ 文件结构检查清单（下载后核对）

1. model.safetensors.index.json的total_size=12355664128字节 ✅
2. 3 个 safetensors 分片共1757张量 + 侧车333张量 =2090✅
3. config.json 中num_experts为128（而非 256）✅
4. kv_config.json 恰好10条全注意力层记录 ✅
5. optiq_metadata.json 的achieved_bpw ≈ 4.513✅

全部对上，说明权重包完整无损，可以安心部署到 Apple Silicon 上体验这个"更小不更慢"的 19B 专家剪枝模型了。

• 人工智能
• 大模型
• 模型量化
• 模型优化
• 本地部署