我把 DeepGEMM 搬进生产才发现:这 5 个坑 README 里一个字都没写

原创2026-10-11 19:41:381,406 阅读
文章标签:人工智能算子库大模型高性能计算深度学习DeepSeek

我把 DeepGEMM 搬进生产才发现:这 5 个坑 README 里一个字都没写

2025 年开源周第三天,DeepSeek 甩出 DeepGEMM 时,社区里铺天盖地都是"300 行代码干翻 cuBLAS""H800 上 1550 TFLOPS"的惊叹。作为被 V3/R1 训练推理效率吸引、又恰好手握一批 Hopper 卡的技术团队,我们几乎是第一时间就把这套 FP8 GEMM 库接进了自己的 MoE 训练链路。理想很丰满:JIT 免编译、API 极简、性能对标专家调优库。现实很骨感:从 import deep_gemm 到第一个 batch 跑通,从单卡 benchmark 到 8 卡 EP 集群,我们踩了一串 README 里完全没提的坑。

这篇文章不否定 DeepGEMM 的价值——它确实是我见过最干净的 tensor core kernel 库之一,源码值得精读。但"干净"的另一面是大量隐式契约:布局要求、量化粒度、JIT 行为、架构分水岭,都散落在代码与测试的角落。以下 5 个坑,全部基于仓库源码逐一核实,希望能让后来者少走弯路。

坑 1:JIT 冷启动——第一次调用不是"秒开"

README 开篇就写着一句让人安心的承诺:"All kernels are compiled at runtime through DeepJIT, requiring no CUDA compilation during installation." 字面意思没错,但"无需编译安装"不等于"无需编译"——它只是把编译从 pip install 挪到了第一次调用。csrc/runtime/jit.hpp 里写得明明白白:

inline deep_jit::LazyInit<deep_jit::Runtime<deep_jit::CUDA>> jit(nullptr);

inline void init_jit(const std::string& library_root_path) {
    ...
    jit = deep_jit::LazyInit<deep_jit::Runtime<deep_jit::CUDA>>([config] {
        auto runtime = std::make_shared<deep_jit::Runtime<deep_jit::CUDA>>(config);
        runtime->default_compiler_options.nvcc_flags->
            emplace_back("--diag-suppress=39,161,174,177,186,940");
        ...
    });
}

每次进程启动、每个新形状,都可能触发一次 NVCC + PTXAS 全流程。更隐蔽的是:不同形状会编译不同的 kernel。看 csrc/jit_kernels/heuristics/common.hpp,get_best_config 会对每个 GemmDesc 枚举 layout 候选、计算 wave 效率、比较存储与流水线配置后选出最优解——这是纯运行时的启发式,不是预编译的静态模板。也就是说,你线上 token 数一变、M 维一抖,冷启动延迟就会重新出现。

配合 setup.py 再看一层:安装时 CachedWheelsCommand 会先去 GitHub Releases 下载预编译 wheel(1 秒超时),下载失败才回退本地 nvcc 编译,而 wheel 文件名里同时编码了 torch 小版本、Python 小版本、CUDA 大版本和 CXX11 ABI——任何一个不对齐都只能走源码构建。离线内网集群踩的就是这一脚。

实战建议:

  • 预热:服务启动后用代表性形状各跑一次,把 JIT 冷启动挡在流量外面;
  • 用 compiled_dims 收敛编译维度。fp8_fp4_gemm_nt 等 API 默认 compiled_dims="nk",即把 N/K 维度当作可忽略项来命中同一份缓存;生产上固定 M 的范围,配合 csrc/jit_kernels/heuristics/runtime.hpp 的 set_ignore_compile_dims 效果更好;
  • 持久化缓存:默认缓存目录是 $HOME/.dj,务必用 DG_JIT_CACHE_DIR 指到稳定的共享盘,并接受"多机首跑各自编译一遍"的现实;
  • 调优诊断靠环境变量:DG_JIT_PRINT_COMPILER_COMMAND=1 看编译命令、DG_JIT_PTXAS_VERBOSE=1 看 PTXAS、DG_JIT_CHECK_NO_SPILLS=1 检查寄存器溢出、DG_JIT_DUMP_ASM=1 导出 PTX/SASS,详见 README.md 的环境变量清单。

坑 2:FP8 精度在真实业务数据上的漂移

benchmark 用的是 torch.randn,你的业务数据不是。FP8 的 E4M3 只有 3 位尾数、最大值 448,一旦张量分布带厚尾或个别离群值,精度表现会和"看起来很美"的测试完全脱节。

先看量化路径。仓库自带的 deep_gemm/utils/math.py 中 per_token_cast_to_fp8 的算法是:

x_amax = x_view.abs().float().amax(dim=2).view(m, padded_n // gran_k).clamp(1e-4)
sf = x_amax / 448.0
sf = ceil_to_ue8m0(sf) if use_ue8m0 else sf
x_fp8 = (x_view * (1.0 / sf.unsqueeze(2))).to(torch.float8_e4m3fn)

per-token/per-channel 的 scale 由 block 内 amax 决定,一个离群值就会压低整组的量化分辨率。而 DeepGEMM 的 SF 契约比普通 FP8 更苛刻——docs/scaling-factor-format.md 明确要求每个 float32 SF 必须是 2 的整数次幂(bit pattern [0][8-bit exponent][23 mantissa bits = 0]),设备端直接断言 (value & 0x807fffffu) == 0。所以 scale 在向上取整到 2 的幂的过程中,组内其他元素的相对精度又被打了一折。

仓库自己的测试容差其实已经给出了答案。tests/generators.py 里 QuantConfig.max_diff():纯 FP8 容差 0.001,FP8xFP4 混合 0.01,FP4xFP4 直接放到 0.02。而且注意 deep_gemm/testing/numeric.py 的 calc_diff 用的是余弦相似度度量:

sim = 2 * (x * y).sum() / denominator
return 1 - sim

这是"方向相似性"而非绝对误差——它对大值主导的向量很宽容,对稀疏小值区域的绝对偏差几乎不敏感。用这个指标过了 CI,不代表你的 loss 曲线不漂。

生产建议:MoE 的 SwiGLU 中间激活在 FP8 下必须配合 clamp。看 tests/test_mega_moe.py,Mega MoE 默认 activation_clamp=10,fp8_fp4_mega_moe 的 Python 封装也暴露了 activation_clamp 参数;量化 cast 时用 round_sf=True 保证 SF 落在合法幂集内;上线前用真实数据分布(而不是 randn)跑一遍端到端数值对比,并对齐 tests/test_fp8_fp4.py 的确定性策略——它循环 20 次断言 bitwise 相同,生产上建议把 use_deterministic_algorithms(True) 纳入发布门禁。

坑 3:SF 布局契约——MN-major、UE8M0 与 TMA 对齐

如果说精度坑还能靠"多测"缓解,布局坑则是不读懂契约就直接炸 assert 的硬伤。DeepGEMM 对 scaling factor 的布局要求,README 只有三行,真正的完整版在 docs/scaling-factor-format.md(一份被严重低估的文档)。

核心契约有三条,全是硬编码在 csrc/utils/layout.hpp 和 csrc/apis/layout.hpp 里的:

  1. MN-major:预变换后的 SF 张量,MN 维度必须是连续维,即 stride(-2) == 1;K 方向 stride 必须等于 align(mn, 4)(16 字节 TMA 对齐)。
  2. UE8M0 打包:SM100 上 4 个 8 位指数打包进一个 int32,little-endian 按 K 序排列(packed |= values[3] << 1u),shape 变成 [mn, ceil_div(k, gran_k * 4)]。
  3. gran_k 收敛:SM100 只支持 gran_k ∈ {32, 128},SM90 只有 128。

最阴险的是 view/reshape 陷阱。变换输出的张量是 MN-major 的、非连续的,一旦你图省事 sf_2d.reshape(b, h, -1) 把它拉成 3 维,连续化会悄悄改变 strides,随后 stride(-2) != 1 直接触发 DG_HOST_ASSERT。文档里专门给了反例:fp8_einsum 内部会对 SF 做 permute(如 SFA 按 (1, 0, 2) 重排),所以预变换必须在 permute 后的坐标下进行、再 permute 回去:

sfx_grouped = deep_gemm.transform_sf_into_required_layout(
    sfx_f32.permute(1, 0, 2).contiguous(),
    mn=b, k=r, recipe=(1, 128), num_groups=h,
)
sfx_int32 = sfx_grouped.permute(1, 0, 2)

另外注意 deep_gemm/utils/math.py 的 per_token_cast_to_fp8(..., use_packed_ue8m0=True):当 SF 个数不是 4 的倍数时,会用值 1.0 填充尾部(num_sf % 4 != 0 分支)——这是为了满足打包断言,但这些填充 scale 覆盖的是 padding 元素,绝不能被业务误读为真实数据。生产上正确的姿势是:权重 SF 用 transform_sf_into_required_layout 变换一次后缓存复用(命中 int32 validate-only 分支,不再启 kernel),激活 SF 直接从 cast kernel 以 int32 格式产出,把每步 GEMM 的隐式 transform kernel 开销降为零。

坑 4:多卡与 MoE 场景下的显存与对齐

DeepGEMM 的杀手锏 Mega MoE(EP dispatch、双层线性、SwiGLU、EP combine 融合进一个 kernel 并重叠 NVLink 通信)是它区别于普通 GEMM 库的核心卖点,但这也是生产落地门槛最高的部分,README 只有一段示例代码。

第一刀砍在显存:Mega MoE 要求多进程 + 对称内存(symmetric memory),deep_gemm/mega/init.py 里的 SymmBuffer 在 torch.distributed._symmetric_memory 之上用 rendezvous 建立共享缓冲区,且明确要求 PyTorch >= 2.9。缓冲区有多大?csrc/apis/mega_moe.hpp 按 ring 容量的最坏情况(跨所有候选 BLOCK_M 取最大 live pool blocks)来算,再乘以 token/权重/SF 多路 slice——测试里默认配置跑出来是数 GiB 量级。而且注意 get_symm_buffer_size_for_mega_moe 里的 TODO:"we temporarily assume the SM count is consistent with the runtime value"——SM 数变了,buffer 尺寸可能对不上。

第二刀砍在对齐:hidden % 128 == 0、intermediate_hidden % 128 == 0、num_max_tokens_per_rank 还要向上对齐到 get_token_alignment_for_mega_moe()(即候选 BLOCK_M 的 LCM)。你的模型 hidden=7168 恰好满足,但换成 6912 或别的非 128 倍数,直接 DG_HOST_ASSERT。

第三刀砍在布局变换的"双保险":Mega MoE 的权重 SF 只接受 int32 预打包,check_sf_layout(..., type_check=torch::kInt) 直接拒绝 float32——和普通 GEMM 的"传 float32 自动变换"完全不同,没有回退路径。更隐蔽的是,光做好 Section 3 的 MN-major 布局还不够,还必须再过一遍 transform_weights_for_mega_moe:它要做 gate/up 的 8 行粒度交织(_interleave_weights),以及 L1/L2 SF 的 UTCCP 内 128 行转置(reshape(-1, 4, 32, packed_sf_k).transpose(2, 3),要求 mn % 128 == 0)。

第四刀砍在调试模式:DG_COMM_KERNEL_DEBUG=1 会在每次调用后把整个对称缓冲区清零,所以 tests/test_mega_moe.py 里每次 run_fused() 都要重新 copy_inputs_to_buffer()——生产代码若照抄"初始化一次、反复调用"的惯性写法,第二次调用就是零输入。

最后别忘了多卡 GEMM 的隐性约束:csrc/jit_kernels/heuristics/config.hpp 的 check_validity 断言 num_sms % 2 == 0,csrc/jit_kernels/heuristics/sm90.hpp 与 csrc/jit_kernels/heuristics/sm100.hpp 又要求 num_sms % (cluster_m * cluster_n) == 0。同时 csrc/apis/gemm.hpp 对 K-grouped 场景强制 k_alignment % 128 == 0(FP8)或 % 256 == 0(FP4),每组 K 必须对齐;PSUM 布局下 gap 行要靠 ensure_zero_padding=True 兜底——这些参数一个漏掉,报错信息往往只在 assert 字符串里。

坑 5:架构分水岭与"你以为在跑 DeepGEMM,其实在跑 cuBLASLt"

DeepGEMM 同时支持 SM90(Hopper)和 SM100(Blackwell),但两者行为差异巨大,README 只用一句话带过,实际坑位深得很:

  • 内存布局:SM90 只支持 NT(row-major A、col-major B),SM100 才支持全部 NT/TN/NN/TT;
  • SF 格式:SM90 要 float32 SF,SM100 要打包 int32(UE8M0);fp8_fp4_requires_k_major 表明 SM90 或双 FP4 时强制 K-major;
  • FP4:只有 SM100 能跑;alpha 缩放参数也是 SM100 专属(csrc/apis/gemm.hpp 里 FP8 GEMM alpha requires SM100);
  • 对齐下限:csrc/jit_kernels/heuristics/runtime.hpp 的 get_theoretical_mk_alignment_for_contiguous_layout 在 SM90 返回 128,SM100 直接给 256;
  • kernel 形态:SM90 是 1D1D/1D2D 两套(取决于 gran_n),SM100 统一 1D1D。

最容易被忽略的是 BF16 GEMM 的静默路由。看 csrc/apis/gemm.hpp 的 bf16_gemm_nt:

if (not heuristics_runtime->get_deterministic_algorithms() and runtime->is_cublaslt_available()) {
    cublaslt_gemm(a, b, d, m, n, k, major_a, major_b, c.has_value(), alpha.value_or(1.0f));
    return;
}

默认情况下,BF16 GEMM 直接转发给 cuBLASLt,根本不进 DeepGEMM 自己的 kernel!你以为在验证 DeepGEMM,实际上 benchmark 的是 cuBLASLt。直到你调 use_deterministic_algorithms(True),才会强制走 DeepGEMM 内核——但那时精度与性能特性又变了(tests/test_bf16.py 里还特别注释了 "BF16 accumulation has lower precision than cuBLASLt's FP32 accumulation",把阈值从 6e-7 放宽到 1e-5)。同一个 use_deterministic_algorithms 开关,在不同 API 下的语义完全不同:FP8 场景它管 bitwise 确定性,BF16 场景它管 kernel 路由。生产代码必须显式、按架构、按精度分别确认自己到底跑的是什么。

绕坑清单与配置建议

把 5 个坑浓缩成一张可执行的落地清单,按接入顺序排列:

安装与首跑

  • [ ] 确认 git clone --recursive(CUTLASS 4.0+ 子模块);离线集群提前把 wheel 或源码打进内网源,避免安装时偷偷联网
  • [ ] CUDA Toolkit ≥ 12.9、C++20 工具链、PyTorch ≥ 2.3(Mega MoE 需要 ≥ 2.9)
  • [ ] 设 DG_JIT_CACHE_DIR 到共享持久化目录;服务预热代表性形状

精度与数值

  • [ ] 量化粒度:SM90 固定 gran_k=128,SM100 用 32/128;SF 必须 2 的幂,cast 时 round_sf=True
  • [ ] SwiGLU/MoE 激活设 activation_clamp,不要用默认 infinity 裸奔
  • [ ] 用真实数据分布做端到端 diff(对照 max_diff:FP8 0.001 / FP4 混合 0.01 / FP4xFP4 0.02 的语义),并跑 bitwise 确定性测试

布局与对齐

  • [ ] 权重 SF 预变换一次并缓存;激活 SF 直接从 cast kernel 产 int32;严禁 reshape 破坏 MN-major strides
  • [ ] Mega MoE:hidden % 128 == 0、mn % 128 == 0,权重过 transform_weights_for_mega_moe,对称缓冲区按最坏 ring 容量分配
  • [ ] 多卡:num_sms % 2 == 0,K-grouped 注意 k_alignment 与 PSUM gap 的 ensure_zero_padding

架构确认

  • [ ] 上线前打印 torch.cuda.get_device_capability(),按 SM90/SM100 分别走一遍接口矩阵(布局、SF dtype、FP4、alpha、alignment)
  • [ ] BF16 路径显式决定:要么接受 cuBLASLt 路由,要么 use_deterministic_algorithms(True) 强制 DeepGEMM 内核,并同步调整数值阈值

DeepGEMM 的源码确实是当前 NVIDIA GPU kernel 优化的最佳教材之一——csrc/jit_kernels/heuristics/sm100.hpp 里候选 layout 的枚举、wave 效率比较、multicast 合法性与 tmem SF 容量检查,每一行都值得对照着读。但教材不会替你踩坑:生产环境的每一毫秒延迟、每一点精度预算、每一块显存,都要靠你自己把这些隐式契约显式化。祝各位搬库顺利,少踩一个是一个。

登录后查看全文
DeepGEMM