DeepSeek 闪电索引器落地昇腾:DeepGEMM-Ascend MQA Logits 内核完全指南
DeepSeek 闪电索引器落地昇腾:DeepGEMM-Ascend MQA Logits 内核完全指南
DeepGEMM-Ascend 是面向华为昇腾 NPU 的简洁高效矩阵乘法内核库(matrix multiplication kernel library)。本文将围绕 DeepSeek 闪电索引器(Lightning Indexer)的核心算子 MQA Logits,带你完整看懂它的原理、如何在昇腾上安装调用、性能有多强,以及如何复现官方测试。
什么是 DeepGEMM-Ascend?📦
DeepGEMM-Ascend 是 DeepGEMM 在昇腾平台上的移植版本,与 DeepGEMM 完全 API 兼容——如果你熟悉 NVIDIA 平台上的 DeepGEMM,这里的用法几乎零成本迁移。它提供:
- BF16 / FP8 / FP4 GEMM(含 M-Grouped、K-Grouped 分组矩阵乘法)
- MQA Logits:DeepSeek 闪电索引器的核心评分内核(本文主角)
- MegaMoE:融合 EP 分发、双 GEMM、SwiGLU 与合并的 MoE 超级内核
它的设计哲学是"轻抽象、重性能":对昇腾的矩阵乘加原语(MAD)做一层薄封装,隐藏分形矩阵布局、对齐约束与地址计算等细节,同时大量使用稀疏数据加载和协程流水线等昇腾特有优化,在多种矩阵形状下逼近硬件性能极限(Dense GEMM 最高可达硬件上限的 99.8%)。
MQA Logits 是什么?闪电索引器的核心数学 🧠
DeepSeek 的闪电索引器要在做完整注意力之前,先从超长上下文的 KV 缓存中挑出真正重要的 KV token。它用的是一种轻量 MQA(Multi-Query Attention)打分:对每个 query token 与每个 KV token 的配对,计算一个"重要性分数"。
这个内核做的事情,等价于下面这个公式:
logits[q, k] = Σ_h weights[q, h] × max(0, q[q, h, :] · kv[k, :])
即:每个注意力头先与 KV token 做点积 → 取 ReLU → 用权重 weights 对所有头加权求和 → 得到一个分数。上层再对分数做 topk 选出重要 KV。你可以把它理解为一次带 ReLU 与加权的批量 QK 点积。
DeepGEMM-Ascend 的 MQA Logits 内核提供了两种形态:
| 形态 | 适用场景 | API |
|---|---|---|
| 连续版 | KV 连续存放(Prefill / 单机推理) | fp8_fp4_mqa_logits |
| Paged 版 | KV 分页缓存(Paged KV Cache,Decode 场景) | get_paged_mqa_logits_metadata + fp8_fp4_paged_mqa_logits |
两个版本都支持 FP8(e4m3)与 FP4 两种低精度输入,并支持每行独立的 KV 有效区间 [cu_seq_len_k_start, cu_seq_len_k_end),天然覆盖因果掩码与上下文并行(CP)切分。
快速安装 DeepGEMM-Ascend:环境要求与一条命令 🚀
环境要求(基于 README.md):
- 华为昇腾 NPU(在 Ascend 950 系列上开发与验证)
- CANN 9.20 工具包(提供
bin/bisheng、bin/ld.lld编译器) torch_npu包 + Python 3.10 及以上- 支持 C++20
<format>的编译器;tilelang、tree-sitter(仅源码构建类型桩时需要)
安装步骤:
git clone --recursive https://gitcode.com/gh_mirrors/de/DeepGEMM-Ascend
cd DeepGEMM-Ascend
pip install . --no-build-isolation
如果你要参与开发或调试内核,也可以运行仓库自带的 develop.sh,它会构建 C++ 扩展并把 .so 软链进 deep_gemm/ 包目录,省去重复安装。
内核采用 JIT 即时编译:首次调用某个形状组合时,由 DeepJIT 驱动 Bisheng 编译器现场编译并缓存到 $HOME/.dj,之后直接复用。设置环境变量 DG_JIT_DEBUG=1 可打印编译命令与每次形状选中的配置,DG_PRINT_CONFIGS=1 可打印配置详情——排障时非常有用。
调用连续版 MQA Logits:Python 接口详解 ✍️
连续版入口在 csrc/apis/attention.hpp,Python 侧通过 deep_gemm 暴露(见 deep_gemm/init.py):
import deep_gemm
logits = deep_gemm.fp8_fp4_mqa_logits(
(q, sf_q), # q: [num_q, num_heads, head_dim] FP8/FP4;sf_q: 缩放因子
(kv, sf_kv), # kv: [num_kv_tokens, head_dim] FP8/FP4;sf_kv: 缩放因子
weights, # [num_q, num_heads] BF16,逐头加权
cu_seq_len_k_start, # [num_q] int32,每行 KV 有效区间起点
cu_seq_len_k_end, # [num_q] int32,每行 KV 有效区间终点
max_seqlen_k, # 输出宽度
) # 返回 [num_q, max_seqlen_k] 的 BF16 logits,区间外位置为 -inf
输入的几个关键点:
- 缩放因子(SF)格式与 NVIDIA 不同:昇腾上,K 方向每对 UE8M0 缩放因子打包进一个
int16,且按 MN-major 顺序存放以获得最优硬件效率。sf_q最后一维是head_dim / 64,sf_kv形状为[num_kv_tokens, head_dim / 64] - 量化精度:q/kv 必须是 FP8 e4m3 或 packed FP4 之一,
weights必须是 BF16 - 输出 logits 行步长自动按 512 字节对齐,便于内核做对齐搬运
调用 Paged 版:在分页 KV 缓存上跑 MQA Logits 📄
Decode 阶段 KV 通常以分页缓存(Paged KV Cache)组织,DeepGEMM-Ascend 的 paged 版内核原生支持 page_size = 64 / 128,且每个物理页把 [KV 数据 | SF] 融合存放在一起(fused_kv_cache,形状 [num_pages, page_size, 1, head_dim_storage + sf_bytes]),一次搬页同时取到数据与缩放因子。
调用分两步:
# 第一步:在 CPU/NPU 上构建调度元数据(每个 AI 核心的任务切分)
metadata = deep_gemm.get_paged_mqa_logits_metadata(context_lens, num_heads, indices)
# 第二步:执行分页 MQA Logits
logits = deep_gemm.fp8_fp4_paged_mqa_logits(
(q, sf_q), # q: [num_q, 1, num_heads, head_dim]
fused_kv_cache, # [num_pages, page_size, 1, head_dim_storage + sf_bytes]
weights, context_lens, block_table, metadata,
max_context_len, indices,
use_ascend_kv_layout=False,
)
其中 block_table 是请求到物理页的映射表,context_lens 是每行已缓存的 KV 长度。调度元数据内核的实现在 deep_gemm/include/deep_gemm/scheduler/paged_mqa_logits_metadata.hpp,分页调度器在 deep_gemm/include/deep_gemm/scheduler/paged_mqa_logits.hpp。
分页版有个精巧的细节:物理页在内存中未必按逻辑顺序排列,内核先在物理地址序批量加载(对硬件最友好),再在向量单元里把每对页换回逻辑顺序——page_size=64 时在一个向量寄存器内换半区,page_size=128 时交换相邻两个向寄存器的目的地,零额外开销(见 deep_gemm/include/deep_gemm/mqa_logits.hpp)。
性能实测:离硬件极限有多近?📊
官方在 Ascend 950DT(CANN 9.20) 上用 bench_msprof 冷 L2 条件实测(数据来自 README.md 的 Performance 章节)。值得注意:MQA Logits 内核是 FIX 管线(矩阵乘加单元)受限而非算力受限,FIX 管线利用率高达 99%。
| 场景 | 类型 | Q tokens | KV tokens | Heads | Dim | 延迟 (us) | 算力 (TFLOPS) | 显存带宽 (GB/s) |
|---|---|---|---|---|---|---|---|---|
| Prefill | FP8 | 4096 | 8192 | 32 | 128 | 302.6 | 681 | 283 |
| Prefill | FP4 | 4096 | 8192 | 32 | 128 | 277.4 | 743 | 277 |
| Decode | FP8 | 256 | 8192 | 32 | 128 | 150.9 | 565 | 2006 |
| Decode | FP4 | 256 | 8192 | 32 | 128 | 124.2 | 708 | 1349 |
可以看到:
- Prefill 是大算力场景(4096 Q × 8192 KV),FP8 即可跑到 681 TFLOPS,FP4 再快约 8%
- Decode 是访存密集场景(256 Q × 8192 KV),FP8 配置下显存带宽打到 2006 GB/s,接近硬件带宽极限
- 同样形状下 FP4 比 FP8 快 8%~15%,对显存带宽压力也更小
内核为什么快?四大设计要点解析 ⚙️
MQA Logits 内核主体在 deep_gemm/include/deep_gemm/mqa_logits.hpp,用 C++ 模板把一切参数"烤进"编译期。四个关键设计:
- Split-KV = 512 分段并行:KV 维度被切成 512 token 的段,各 AI 核心按 Q block 交错领取任务(调度器见 deep_gemm/include/deep_gemm/scheduler/mqa_logits.hpp),长序列天然填满所有核心
- 多级双缓冲流水线:Q 双缓冲(2 stages)、KV 四缓冲(4 stages)、累加器与 logits 各配独立缓冲组,MTE2/MTE3 搬运、MAD 计算、向量归约三者完全重叠,数据"永远在飞的路上"
- AIC/AIV 混合分工:内核以
__mix__(1, 2)混合模式启动——AIC(矩阵核)专注跑 MAD 乘累加,AIV(向量核)负责跨头加权归约(sum_h w_h·ReLU(...))与结果写回,两条执行路径互不阻塞 - JIT + 编译期特化:所有流水级数、块大小、头数都是模板参数,由 DeepJIT 按当前硬件形状即时编译,没有运行时分支开销;配置选择逻辑在 csrc/jit_kernels/mqa_logits.hpp
运行测试与复现官方数据 🧪
MQA Logits 的完整测试在 tests/test_attention.py,覆盖了 FullRange、Causal、Context-Parallel、Random 四种 KV 区间模式,以及 heads 从 4 到 64 的边界值:
cd DeepGEMM-Ascend
python tests/test_attention.py # 完整测试(含精度校验与 msprof 性能采集)
python tests/test_attention.py --skip-prof # 只校验精度,跳过性能采集
精度参考实现就在同一文件里(tests/test_attention.py),逐 split 做 einsum + relu + 加权求和 再按区间掩码填 -inf,与内核输出做逐元素比对——想理解"正确答案长什么样",读这 20 行最直观。
常见约束与 FAQ 💡
| 问题 | 答案 |
|---|---|
| 支持哪些头数? | num_heads ∈ [4, 64] 且必须为 4 的倍数(接口层有断言检查) |
| 支持哪些 head_dim? | 仅 64 或 128(首版内核限制) |
| 输入精度? | q/kv:FP8 e4m3 或 packed FP4;weights:BF16;SF:int16 打包 UE8M0 对 |
| Paged 版页大小? | page_size = 64 或 128,且 SPLIT_KV(512) 必须覆盖整页 |
| 输出是什么? | BF16,形状 [num_q, max_seqlen_k],行步长 512 字节对齐 |
| 编译很慢 / 报错? | 设 DG_JIT_DEBUG=1 看 Bisheng 编译命令;确认 CANN 9.20 的 bin/bisheng 在 PATH 中 |
| 想限制核心数? | 用 deep_gemm.set_num_sms(n) 控制内核可用的 AI 核心数量 |
关键文件索引
- 项目总览与性能数据:README.md
- 内核主体(AIC 计算路径 + AIV 归约路径):deep_gemm/include/deep_gemm/mqa_logits.hpp
- Python 接口与参数校验:csrc/apis/attention.hpp
- JIT 代码生成与配置选择:csrc/jit_kernels/mqa_logits.hpp
- 连续版 / 分页版调度器:deep_gemm/include/deep_gemm/scheduler/mqa_logits.hpp、deep_gemm/include/deep_gemm/scheduler/paged_mqa_logits.hpp
- 分页调度元数据内核:deep_gemm/include/deep_gemm/scheduler/paged_mqa_logits_metadata.hpp
- 测试与参考实现:tests/test_attention.py
- 开发构建脚本:develop.sh
小结
DeepGEMM-Ascend 让 DeepSeek 闪电索引器的 MQA Logits 评分内核完整落地昇腾:一个 API 兼容的矩阵乘法内核库、FP8/FP4 低精度输入、连续与分页 KV 双形态、FIX 管线 99% 利用率——从 pip install 到跑出 681 TFLOPS 的 Prefill 评分,只需要几行 Python 代码。对想在昇腾上部署长上下文稀疏注意力模型的开发者来说,这套内核是性能优化的优秀起点与参考范本。