markbaseengine/26B_MXFP4_TEST_REPORT.md

Gemma-4 26B 模型测试报告

测试日期

2026-06-19

模型信息

• 模型: MLX Gemma-4 26B (gemma-4-26b-a4b-mxfp4)
• 位置: ~/.cache/huggingface/hub/models--mlx-community--gemma-4-26b-a4b-mxfp4/
• 大小: 14.8GB (3 shards)
• 层数: 30层（不是42层）
• Hidden size: 2816
• Vocab size: 262144
• MoE experts: 128专家

转换过程

步骤 1: 权重重命名

• 移除 language_model.model. 前缀
• 1490 个权重成功重命名
• embed_tokens, vision_tower, layers.* 等全部重命名

步骤 2: Scales 格式转换

• uint8 → bfloat16（针对 scales）
• embed_tokens.scales 已正确转换

步骤 3: 合并 shards

• 3个 shards 合并为单个 model.safetensors (15GB)

步骤 4: 创建 config.json

• hidden_size=2816
• num_hidden_layers=30（修正，最初错误设置为42）
• vocab_size=262144

加载测试结果

成功部分

• ✓ embed_tokens 加载成功（支持可选 biases）
• ✓ 权重名称自动匹配（支持带/不带前缀）
• ✓ Layer 0-26 成功加载
• ✓ Attention weights (q/k/v/o_proj) 全部找到
• ✓ MLP weights (gate/up/down_proj) 全部找到

失败原因

Fatal error: Index out of range (Swift/ContiguousArrayBuffer.swift:692)

根本原因：MLX 26B 使用混合量化格式，与标准 4-bit 不兼容

MLX 量化格式分析

配置详情（来自原始 config.json）

{
  "quantization": {
    "group_size": 32,
    "bits": 4,
    "mode": "mxfp4",  // ← 关键：使用 MXFP4 格式
    
    // 所有 MLP 层使用特殊配置：
    "layers.*.mlp.gate_proj": { "group_size": 64, "bits": 8 },
    "layers.*.mlp.down_proj": { "group_size": 64, "bits": 8 },
    "layers.*.mlp.up_proj": { "group_size": 64, "bits": 8 },
    "layers.*.router.proj": { "group_size": 64, "bits": 8 }
  }
}

实际权重形状分析

Attention 层（MXFP4, group_size=32）

• q_proj.weight: [4096, 352] → actual_dim = 2816 ✓
• q_proj.scales: [4096, 88] → 2816/32 = 88 ✓

MLP 层（8-bit, group_size=64）- 这是问题所在！

• down_proj.weight: [2816, 528] → actual_dim = 4224 (不是2816!)
• down_proj.scales: [2816, 33] → 4224/64 = 66 (但实际是33?)
• down_proj.biases: [2816, 33]

问题: MLP 使用 8-bit quantization，每个 uint8 存储 1 个值（不是 8 个），所以：

• weight packed_dim = 528 实际代表 528 个值（不是 528*8）
• scales groups = 33 代表 528/16 = 33（使用 sub-block quantization）

MXFP4 格式说明

MXFP4 (Mixed-Format Floating Point 4-bit) 是一种特殊的量化格式：

• 不是标准的 4-bit integer quantization
• 使用特殊的浮点编码
• 可能使用 sub-block quantization（每个 block 内有 sub-blocks）
• 与我们使用的 "uint32 packed 4-bit" 格式完全不同

兼容性问题总结

1. 量化格式不兼容

• 我们: 标准 4-bit packed uint32（每个 uint32 存储 8 个 4-bit 值）
• MLX 26B: MXFP4（特殊浮点格式）+ 8-bit（MLP 层）

2. Group size 不一致

• 我们: 固定 group_size=64
• MLX 26B:
  • Attention: group_size=32 (MXFP4)
  • MLP: group_size=64, bits=8

3. Biases 处理不同

• 我们: biases 可选（某些权重没有 biases）
• MLX 26B: MLP 层有特殊的 biases（用于 sub-block quantization）

4. MoE 结构

• 26B: 有 128 个 MoE experts (experts.switch_glu.*)
• 我们的代码: 尚未实现 MoE 支持

解决方案

方案 1: 实现 MXFP4 + 8-bit 支持（复杂）

• 需要实现 MXFP4 解码器
• 需要实现 8-bit quantization kernel
• 需要实现 MoE routing logic
• 需要实现 sub-block quantization
• 工作量: 2-3周

方案 2: 重新量化模型（推荐）

• 从原始 bfloat16 Gemma-4 26B 重新量化
• 使用标准的 4-bit quantization（group_size=64）
• 移除 MoE 或简化为 dense layers
• 工作量: 1-2天（需要下载原始模型并量化）

方案 3: 等待 HuggingFace 支持

• HuggingFace transformers 目前不支持 Gemma-4
• 等待官方支持后，使用标准量化工具
• 时间: 不确定

方案 4: 使用其他 4-bit 模型（最简单）

• 继续使用 E4B/12B 4-bit 模型（已完美支持）
• 等待社区提供标准 4-bit 量化的 Gemma-4 26B
• 立即可用

代码改进

尽管 26B 加载失败，但我们做出了重要改进：

1. 支持可选 biases

• quantizedGroup() 现在支持缺失 biases 的权重
• 自动创建 zero biases 如果缺失
• 用途: MLX 格式的某些权重没有 biases

2. 权重名称自动匹配

• 自动尝试去除 language_model.model. 前缀
• 支持原始 MLX 格式和转换后格式
• 用途: 兼容不同来源的模型

3. Layer 数量动态检测

• 从实际权重推断层数（30层）
• 不依赖 config.json（可能不准确）

4. 调试输出增强

• 显示每个权重的形状和 dtype
• 显示 scales groups 计算
• 便于诊断量化格式问题

下一步建议

立即可行

1. 继续使用 E4B/12B: 已完美支持，性能优秀
2. 等待社区: 等待标准 4-bit 量化的 Gemma-4 26B 发布
3. 文档更新: 说明 MXFP4 不兼容性

长期规划

1. 实现 MoE: 为未来更大模型做准备
2. 扩展量化支持: 支持 8-bit, MXFP4, GPTQ 等多种格式
3. 自动量化工具: 提供从 bfloat16 → 4-bit 的转换工具

结论

MLX Gemma-4 26B 使用 MXFP4 混合量化格式，与我们的标准 4-bit packed uint32 格式不兼容。虽然成功加载了部分权重（embed_tokens, attention），但 MLP 层的 8-bit quantization 导致了数组越界错误。

建议使用方案 4（继续使用 E4B/12B），这是最稳定、最快速的解决方案。对于 26B+ 模型，建议等待社区提供标准 4-bit 量化版本，或实现完整的 MXFP4/MoE 支持。

---

测试状态: 部分成功（权重加载）→ 失败（MLP 量化格式不兼容） 根本原因: MXFP4 + 8-bit 混合量化 vs 标准 4-bit 建议: 使用 E4B/12B 或等待标准 4-bit 26B