# MoE架构说明

**日期**: 2026-06-24  
**适用**: 26B-A4B和26B-Standard MoE模型

---

## 一、MoE基本原理

### 1.1 专家混合架构

**MoE (Mixture of Experts)**:
- 模型包含多个"专家"（Experts）
- 每个token只激活少数专家（Top-K routing）
- 其他专家保持静默（不参与计算）

**26B-A4B/26B-Standard**:
- 总参数: 26B（260亿）
- 专家数量: 128个专家/层
- 激活参数: ~4B（每个token）
- 激活专家: Top-K（通常是2-4个专家）

---

## 二、内存需求特性

### 2.1 全量参数加载

**关键特性**:
```
虽然每个token只激活4B参数
但必须加载全部26B参数到内存
```

**原因**:
1. **快速路由决策**
   - Router需要评估所有128个专家
   - 计算每个专家的得分
   - 选择Top-K专家

2. **推理速度**
   - 避免频繁加载/卸载专家
   - 内存中常驻专家权重
   - 维持高速推理

3. **基准内存需求**
   - 与26B密集模型相近
   - 约14.5GB（量化后）
   - 不是4B模型的内存需求

---

## 三、MoE工作流程

### 3.1 Forward Pass流程

**步骤**:
```
1. Token输入 → Embedding
2. Router计算：评估128个专家得分
3. Top-K选择：选出最相关的K个专家
4. Expert计算：激活的专家处理token
5. Output融合：合并专家输出
6. 下一层或最终logits
```

**26B-A4B可能的bug位置**:
- Step 2: Router使用Token ID作为索引 ⚠️
- Step 3: Expert选择受Token ID影响 ⚠️
- Step 4: 专家计算产生NaN ⚠️
- Step 5: 输出融合错误 ⚠️
- Step 6: 最终logits特定位置NaN ⚠️

---

## 四、对比分析

### 4.1 26B-A4B vs 26B-Standard

| 特性 | 26B-A4B | 26B-Standard |
|-----|---------|-------------|
| 专家数量 | 128/层 | 128/层 |
| 总参数 | 26B | 26B |
| 激活参数 | ~4B | ~4B |
| 量化bits | **8** | **4** |
| Quant group_size | **64** | **32** |
| Forward NaN | **依赖token** | **0** |
| **状态** | ⚠️ **Bug** | ✅ **完美** |

**关键差异**: 量化参数

---

## 五、推测的Bug机制

### 5.1 Token ID路由索引问题

**假设机制**:
```
Token ID → Router错误地用作索引
→ 影响Expert选择或计算位置
→ 特定位置的logits变成NaN
```

**证据**:
- Token 1 → NaN at [1]
- Token 100 → NaN at [100]
- Token 255999 → NaN at [255999]
- Token ID和NaN位置高度相关

**影响**:
- Router的128专家得分计算
- Token ID可能被用作mask或索引
- 导致特定专家或位置的计算出错

---

### 5.2 量化参数不匹配

**26B-A4B量化**:
- bits: 8（每层）
- group_size: 64
- mode: affine

**26B-Standard量化**:
- bits: 4
- group_size: 32
- quant_method: custom

**推测**:
- bits=8可能不适合MoE架构
- group_size=64可能导致计算精度问题
- Router/Expert的量化反量化出错

---

## 六、为什么26B-Standard无问题

### 6.1 正确的量化参数

**26B-Standard**:
- bits=4: 更标准的量化
- group_size=32: 更细粒度的量化
- quant_method=custom: 自定义量化方法

**结果**:
- Router计算正常 ✅
- Expert计算正常 ✅
- 最终logits无NaN ✅
- 完美稳定 ✅

---

### 6.2 MoE架构处理正确

**26B-Standard的MoE**:
- 128专家正确加载
- Router正确评估专家
- Top-K选择正常
- Expert计算正常
- Output融合正常

---

## 七、建议和结论

### 7.1 使用建议

**推荐**:
- ✅ **使用26B-Standard**
- ✅ 完美的MoE实现
- ✅ 0 NaN，稳定可靠
- ✅ 相同的架构，正确的参数

**不推荐**:
- ⚠️ **停止使用26B-A4B**
- ⚠️ Forward pass bug
- ⚠️ NaN依赖token ID
- ⚠️ 不可预测的问题

---

### 7.2 MoE架构总结

**优点**:
- 激活参数少（~4B vs 26B）
- 计算效率高
- 适合大规模模型

**挑战**:
- 内存需求高（需全量加载）
- 路由计算复杂
- 量化敏感（26B-A4B的问题）

**关键**:
- 正确的量化参数（bits=4, group_size=32）
- 正确的路由实现
- 正确的专家计算

---

## 八、技术细节

### 8.1 Router计算

**公式**:
```
Router_scores = Router_layer(hidden_state)
Top_K_indices = Top_K(Router_scores)
Expert_outputs = Experts[Top_K_indices](hidden_state)
Final_output = weighted_sum(Expert_outputs, Router_scores)
```

**26B-A4B可能的bug**:
```
Router_scores可能受Token ID影响
导致Top_K_indices或权重计算错误
最终影响Expert_outputs和logits
```

---

### 8.2 Expert数量

**26B-A4B/26B-Standard**:
- 每层: 128 experts
- 30层: 30 × 128 = 3840 experts
- 但每token只激活: 2-4 experts
- 总参数: 26B

**Router权重**:
- 每层有router.proj, router.per_expert_scale
- Router需要快速计算128个专家得分
- 这可能是bug的位置

---

## 九、文件记录

**测试文件**:
- `TwentySixBA4BNaNLocationTest.swift`
- `TwentySixBA4BDeepDebugTest.swift`
- `MoE26BA4BTest.swift`
- `MoE26BStandardTest.swift`

**报告文件**:
- `26B_A4B_NaN_Truth.md`
- `26B_A4B_NaN_Analysis_Plan.md`
- `MoE_Architecture_Explanation.md`（此文件）

---

**生成时间**: 2026-06-24  
**关键结论**: MoE架构正确，但26B-A4B量化参数有问题  
**推荐**: 使用26B-Standard代替