# 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）
```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