NPU 多流优化案例手册
本文收录仓库内与 NPU 多流优化相关的案例，按“每次优化算一个案例”整理，而不是按模型统计。目录中的每个 Markdown 文件只讲一个案例，聚焦优化动机、执行编排、关键代码片段、适用场景和复用价值。
收录原则
- 文档中明确描述了多流、双流、stream overlap 或多流并行。
- 代码中存在显式多流编排，例如
npu_stream_switch、torch.npu.Stream()、wait_event、record_event、wait_stream。 - 相同优化方法在不同模型中复用时，合并到同一类案例中统一整理。
分类导航
MoE 多流
Attention / Prolog 多流
KVCache Offload 异步流
Prefill 双流流水
多流 + 控核 / 分离式编排
快速选型表
使用顺序
- 先确定当前优化属于哪一类模式。
- 先读对应案例文档，确认模块边界、依赖关系和同步方式。
- 再读代表代码或补丁，确认实际 API 风格和 enable 开关设计。
- 如果一个实现同时落在多类模式里，先选主模式，再把其他能力当补充手段。
案例清单
| 案例名称 | 优化方法 | 代表模型 | 概述 |
|---|---|---|---|
| MoE 共享专家双流并行 | 共享专家与路由专家并行 | DeepSeek-V3.2-Exp / DeepSeek-R1 | 把共享专家放到副流，与路由专家路径重叠，减少 decode 可见耗时。 |
| Indexer Prolog 多流并行 | Attention 前处理多流 | DeepSeek-V3.2-Exp / GLM-5 | 将 Q 路径与权重投影路径拆到不同流，缩短 Indexer 前处理串行段。 |
| KVCache Offload 异步搬运流 | Cache 异步卸载/回迁 | DeepSeek-V3.2-Exp / GLM-5 | 用独立流完成 KVCache 搬运，降低主计算流阻塞。 |
| Prefill Micro-Batch 双流流水 | 计算通信双流掩盖 | DeepSeek-R1 | 两个 micro-batch 分别跑在两条流上，并通过 event 编排 dispatch/combine。 |
| LongCat-Flash 多流与控核联动 | 多流 + limit_core_num | LongCat-Flash | 把 Attention 路径和 MoE 路径拆流后再分核，减少拖尾。 |
| LongCat-Flash AFD 通信计算 overlap | 分离部署下的双流编排 | LongCat-Flash | 通过 Stream0/Stream1 overlap Send/Recv 与主计算，隐藏分离式通信耗时。 |
| HunyuanImage-3.0 MoE 多流变体 | Shared MLP 独立流 | HunyuanImage-3.0 | 用独立 NPU stream 承载共享 MLP，形成多模态模型里的 MoE 双流变体。 |
| Qwen3-Next Patch 形态的 MoE 双流 | Patch 级 NPU 双流改造 | Qwen3-Next | 在 SGLang patch 中引入 shared expert stream，与 DeePEP 路由过程并行。 |
常见误用
- 不要把
MoE shared expert 双流和Prefill micro-batch 双流当成同一种流水，它们的同步粒度完全不同。 - 不要看到有两条流就默认需要
limit_core_num，控核只在资源争抢和拖尾明显时再引入。 - 不要把
KVCache offload这类搬运流当成计算流优化，它优先关注的是状态一致性和带宽掩盖。 - 不要直接拼接多个案例的代码片段，必须先按当前执行模式选一套主路径。