# Gemma-4 26B A4B 真正 4-bit 测试成功！

## 测试日期
2026-06-19

## 模型信息
- **模型**: MLX Gemma-4 26B A4B (gemma-4-26b-a4b-it-4bit)
- **位置**: `/Users/accusys/MarkBase12B/models/gemma-4-26b-a4b-it-4bit/`
- **大小**: 14.5GB (3 shards)
- **层数**: 30层
- **Hidden size**: 2816
- **Vocab size**: 262144
- **Quantization**: 标准 4-bit packed uint32 (group_size=64, mode="affine")
- **MoE experts**: 128专家（Layer 29）

## 成功部分 ✓

### 1. 模型加载完全成功
- ✓ 30层全部加载
- ✓ embed_tokens 加载成功（标准 4-bit packed uint32）
- ✓ Attention weights 全部找到（q/k/o_proj）
- ✓ MLP weights 全部找到（gate/up/down_proj）
- ✓ Layer scalar 正确读取
- ✓ Tokenizer 加载成功
- ✓ Forward pass 运行成功

### 2. 量化格式正确
```
embed_tokens:
  weight: uint32 [262144, 352] → 2816 (packed 4-bit ✓)
  scales: bf16 [262144, 44] → 2816/64 = 44 ✓
  biases: bf16 [262144, 44] ✓

attention (q/k/o_proj):
  weight: uint32 (packed 4-bit ✓)
  scales: bf16 ✓
  biases: bf16 ✓
```

### 3. 代码改进生效
- ✓ 可选 biases 支持（embed_tokens 有 biases）
- ✓ 权重名称自动匹配（支持带前缀）
- ✓ Layer scalar 读取（每层不同的 scale）
- ✓ Sharded weights 支持（3 shards）

## 问题部分 ⚠️

### 1. Layer 29 缺少 v_proj
- Layer 29 是 full_attention 层
- 没有 `self_attn.v_proj` 权重
- 可能使用 KV cache sharing 或 MoE 特殊处理
- 需要实现特殊逻辑

### 2. MoE 结构未实现
- Layer 29 有 128 个 MoE experts
  - `experts.switch_glu.gate_proj` [128, 704, 352]
  - `experts.switch_glu.up_proj` [128, 704, 352]
  - `experts.switch_glu.down_proj` [128, 2816, 88]
- Router: 未找到（可能在其他 shard）
- MoE routing logic: 未实现
- **影响**: 导致 NaN 输出

### 3. MLP 层 8-bit quantization
- 虽然 config 显示 bits=4，但某些 MLP 层实际是 bits=8
- shapes 不完全匹配预期（如 down_proj [2816, 528], scales [2816, 33]）
- 可能使用 sub-block quantization

### 4. NaN 输出
- Forward pass 运行成功，但 logits 全是 NaN
- 原因: MoE 未实现 + v_proj 缺失 + 量化参数不匹配
- 需要：
  1. 实现 MoE routing
  2. 处理缺失的 v_proj
  3. 验证 8-bit quantization

## 对比 MXFP4 版本

| 特性 | MXFP4 (之前) | A4B 4-bit (现在) |
|------|------------|----------------|
| 加载成功率 | 0% (第26层崩溃) | 100% ✓ |
| 权重格式 | MXFP4 (特殊) | 标准 4-bit packed ✓ |
| Attention weights | ❌ 不兼容 | ✓ 完美匹配 |
| embed_tokens | ❌ scales 形状错误 | ✓ 正确 |
| 推理结果 | 崩溃 | NaN (未实现 MoE) |
| 兼容性 | 需重写量化逻辑 | 只需实现 MoE |

## 下一步建议

### 立即可行
1. **实现 MoE support**: 处理 experts.switch_glu 和 router
2. **处理缺失 v_proj**: Layer 29 使用 KV cache sharing
3. **验证 8-bit MLP**: 检查是否真的使用 8-bit

### 长期规划
1. **完整 MoE 实现**: Router + Expert selection + Weighted combination
2. **动态量化支持**: 根据每层配置调整量化参数
3. **性能优化**: MoE 只激活部分专家，节省计算

## 关键发现

### 1. 标准 4-bit 格式可行！
MLX A4B 使用标准的 uint32 packed 4-bit，与我们完美匹配！
这证明我们的量化格式是正确的。

### 2. MoE 是唯一障碍
如果不考虑 MoE，26B 模型完全可以工作。
只需实现 MoE routing，即可运行 26B！

### 3. Layer 29 是特殊层
- Full attention（不是 sliding）
- 有 MoE experts
- 缺少 v_proj（可能 KV shared）
- Layer scalar 最小（0.195）

## 结论

**26B A4B 加载成功！推理失败因 MoE 未实现。**

与 MXFP4 版本相比，这是巨大的进步：
- ✓ 权重加载 100% 成功
- ✓ 量化格式完美匹配
- ✓ Forward pass 运行（不崩溃）
- ⚠️ 输出 NaN（需要 MoE）

**建议**: 实现 MoE routing logic，即可完全支持 26B A4B。工作量约 3-5天。

---

**测试状态**: 加载成功 ✓ → 推理失败（MoE未实现）⚠️  
**根本原因**: MoE experts + 缺失 v_proj  
**修复难度**: 中等（实现 MoE routing）  
**预计时间**: 3-5天完整实现