docs: MoE架构详细说明文档

关键内容： ✅ 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
2026-06-24 02:05:45 +08:00
parent a8c58c76d6
commit e82162e96b
1 changed files with 255 additions and 0 deletions
@@ -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代替