DeepSeek 闪电索引器落地昇腾:DeepGEMM-Ascend MQA Logits 内核完全指南

原创2026-11-14 14:03:501,407 阅读

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++ 模板把一切参数"烤进"编译期。四个关键设计:

  1. Split-KV = 512 分段并行:KV 维度被切成 512 token 的段,各 AI 核心按 Q block 交错领取任务(调度器见 deep_gemm/include/deep_gemm/scheduler/mqa_logits.hpp),长序列天然填满所有核心
  2. 多级双缓冲流水线:Q 双缓冲(2 stages)、KV 四缓冲(4 stages)、累加器与 logits 各配独立缓冲组,MTE2/MTE3 搬运、MAD 计算、向量归约三者完全重叠,数据"永远在飞的路上"
  3. AIC/AIV 混合分工:内核以 __mix__(1, 2) 混合模式启动——AIC(矩阵核)专注跑 MAD 乘累加,AIV(向量核)负责跨头加权归约(sum_h w_h·ReLU(...))与结果写回,两条执行路径互不阻塞
  4. 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 核心数量

关键文件索引

小结

DeepGEMM-Ascend 让 DeepSeek 闪电索引器的 MQA Logits 评分内核完整落地昇腾:一个 API 兼容的矩阵乘法内核库、FP8/FP4 低精度输入、连续与分页 KV 双形态、FIX 管线 99% 利用率——从 pip install 到跑出 681 TFLOPS 的 Prefill 评分,只需要几行 Python 代码。对想在昇腾上部署长上下文稀疏注意力模型的开发者来说,这套内核是性能优化的优秀起点与参考范本。

登录后查看全文
DeepGEMM-Ascend