From e82162e96b878faf6d119e2d45bbd9d4434160cf Mon Sep 17 00:00:00 2001
From: MarkBase Admin <admin@markbase.local>
Date: Wed, 24 Jun 2026 02:05:45 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20MoE=E6=9E=B6=E6=9E=84=E8=AF=A6=E7=BB=86?=
 =?UTF-8?q?=E8=AF=B4=E6=98=8E=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

关键内容：
✅ MoE基本原理：128专家，每token激活4B参数
✅ 内存需求：必须加载全部26B参数（14.5GB）
✅ 工作流程：Token → Router → Top-K → Expert → Output
✅ 26B-A4B bug推测：Token ID路由索引问题

对比分析：
26B-A4B: bits=8, group_size=64 → NaN依赖token ⚠️
26B-Standard: bits=4, group_size=32 → 0 NaN ✅

关键发现：
量化参数不匹配可能是根本原因
Router计算可能错误地使用Token ID
导致特定位置的logits变成NaN

文件：MoE_Architecture_Explanation.md
---
 MoE_Architecture_Explanation.md | 255 ++++++++++++++++++++++++++++++++
 1 file changed, 255 insertions(+)
 create mode 100644 MoE_Architecture_Explanation.md

diff --git a/MoE_Architecture_Explanation.md b/MoE_Architecture_Explanation.md
new file mode 100644
index 0000000..1ca98fe
--- /dev/null
+++ b/MoE_Architecture_Explanation.md
@@ -0,0 +1,255 @@
+# 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代替