大模型深度学习算子库后端高性能计算【免费下载链接】flashinferFlashInfer: Kernel Library for LLM Serving项目地址https://gitcode.com/gh_mirrors/fl/flashinfer点击查看免费下载本文围绕 FlashInfer 中flashinfer.mhc模块展开系统讲解其专为 Agentic 风格残差混合residual mixing设计的 Multi-head Residual CombinationmHC系列 CUDA 核函数后映射mhc_post与两大前映射融合核mhc_pre_big_fuse/mhc_pre_big_fuse_with_prenorm。你将掌握这三个 API 的数学语义、全部形状约束与参数默认值、CUDA 底层实现原理以及它们在 tests/mhc 中的数值验证方法可直接用于 Agentic 架构中4 子头残差混合场景的推理接入与调试。1. 模块定位Agentic 残差混合与固定 HC4 子头布局flashinfer.mhc是 FlashInfer 中专用于 Agentic 风格残差混合Agentic-style residual mixing的核函数集合其官方定位见 docs/api/mhc.rstMulti-head residual Combination (mHC) kernels used by Agentic-style residual mixing with a fixedHC4sub-head layout.核心要点是固定HC4子头布局hard-wired to 4 sub-heads。所谓残差混合是指在一个 Transformer 层中将上层的多层残差状态按可学习的混合系数重新组合后注入当前层。mHC 把这一过程拆成两个阶段前映射pre-map根据投影 logits 计算出混合权重pre / post / comb 三组系数并生成下一层的实际输入后映射post-map在当前层输出x与旧的 4 头残差residual之间按系数完成最终组合得到新的 4 头残差。该模块共导出三个函数全部以flashinfer_api装饰并配套 trace 模板因此同时支持 FlashInfer 的 trace 录制/回放机制见 flashinfer/mhc.py 等处的trace参数。模块中两个关键常量定义在 flashinfer/mhc.py_MHC_HC 4 # 固定的子头数 _MHC_MIX _MHC_HC * (2 _MHC_HC) # 4 * 6 24即 pre(4) post(4) comb(16)24 维的投影 logits 布局贯穿全部三个 API前 4 维给 pre、中间 4 维给 post、后 16 维按 4×4 排布给 comb残差组合矩阵。2. 后映射核flashinfer.mhc.mhc_post2.1 数学语义mhc_post完成 mHC 的 post 映射其公式在 flashinfer/mhc.py 中明确给出out[..., new_hc, h] x[..., h] * post_layer_mix[..., new_hc] Σ_old residual[..., old_hc, h] * comb_res_mix[..., old_hc, new_hc]即对每个新子头new_hc输出 当前层输出x乘以其专属后混合系数post_layer_mix[..., new_hc]再加上 4 个旧残差子头按组合矩阵comb_res_mix[..., old_hc, new_hc]加权求和的结果。2.2 函数签名与输入输出形状flashinfer.mhc.mhc_post( x: torch.Tensor, # [..., H]层输出bf16 residual: torch.Tensor, # [..., HC4, H]多子头残差bf16 post_layer_mix: torch.Tensor, # [..., HC4] 或 [..., HC4, 1]float32 comb_res_mix: torch.Tensor, # [..., HC4, HC4]float32 ) - torch.Tensor # 与 residual 同形状 [..., HC4, H]形状校验逻辑在_check_mhc_post_inputsflashinfer/mhc.py中输入要求说明residualndim 3shape[-2] 4倒数第二维即 HC 轴必须等于 4否则抛ValueError(residual.shape[-2] / HC must be 4)xshape residual.shape[:-2] (residual.shape[-1],)外层维度需与 residual 一致隐藏维 H 相同post_layer_mix[..., 4]或[..., 4, 1]两种形状都接受内部统一 reshapecomb_res_mix[..., 4, 4]每个[old_hc, new_hc]条目是旧头old_hc混入新头new_hc的系数内部会先做reshape(-1, ...)摊平 token 维度保证 contiguous 后调用底层实现_mhc_post_impl最后reshape_as(residual)还原形状flashinfer/mhc.py。2.3 CUDA 实现多路径分发的内存布局底层实现在 csrc/mhc/mhc_post.cu入口flashinfer::mhc::mhc_post第 556-599 行先做类型/形状强校验x、residual、out必须为dl_bfloat16post_layer_mix、comb_res_mix必须为dl_float32形状必须满足residual [T, 4, H]、x [T, H]、post_layer_mix [T, 4]、comb_res_mix [T, 4, 4]、out [T, 4, H]total_tokens 0时直接返回避免空启动。该文件为 BF16 HC4 准备了五条 kernel 路径由launch_bf16_hc4第 513-552 行按H是否 8 对齐和取值区间分发路径适用场景关键点token-vec kernelmhc_post_bf16_hc4_token_vec_kernelH ≤ 1536 / ≤ 2048 / ≤ 8192 / ≤kMaxTokenVecHidden每个 CTA 处理TokensPerBlock个 token4 或 1每 token 多线程并行系数可经 warp shuffleWarpCoeffLoadtrue或共享内存广播加载split-vec kernelmhc_post_bf16_hc4_split_vec_kernel1536 H ≤ 4096 等按 H 维分 tileTileElems1280每 CTA 160 线程 × vec8grid.y 在 token 维上循环persistent split kernelH 4096、H 7168token ≥ 4096静态 H 特化compute_vec8_head_serial逐头串行写回以缓解访存压力注释明确标注 DeepSeek V4 / V4 Pro shape 场景scalar kernelmhc_post_bf16_hc4_scalar_kernelH 非 8 的倍数线性平铺逐元素回退路径vec 化层面使用 8 元素kVecWidth8BF16 向量通过内联 PTXld.global.v4.u32/st.global.v4.u32完成 128 位访存Bf16x8第 47-59 行每个 token 的 20 个混合系数4 post 16 comb被组织为Hc4Mix一个float4 post 四个float4 from0..from3配合fmaf累加与__shfl_sync跨 lane 广播将公式展开为 4 个新头并行、每次处理 8 个隐藏维的 FMA 流水compute_vec8第 144-191 行。3. 前映射大融合核mhc_pre_big_fuse3.1 功能与公式mhc_pre_big_fuse完成 mHC 的 pre-map 大融合big-fuse它接收外部已经算好的投影 logitsdot_mix与残差平方和sqrsum在一个 kernel 内完成 RMS 归一化、三组系数激活/归一化含 Sinkhorn 迭代并直接生成下一层的输入layer_input。签名flashinfer/mhc.pyflashinfer.mhc.mhc_pre_big_fuse( dot_mix: torch.Tensor, # [..., 24] 或 [num_splits, ..., 24]float32 sqrsum: torch.Tensor, # [...] 或 [num_splits, ...]float32 residual: torch.Tensor, # [..., HC4, H]bf16 mhc_scale: torch.Tensor, # [3]float32 mhc_base: torch.Tensor, # [24]float32 k: int, rms_eps: float 1e-6, mhc_pre_eps: float 1e-6, mhc_sinkhorn_eps: float 1e-6, mhc_post_mult_value: float 1.0, sinkhorn_repeat: int 20, num_splits: int 1, block_size: int 0, ) - tuple[torch.Tensor, torch.Tensor, torch.Tensor] # (post_mix, comb_mix, layer_input)返回三个张量形状分别为[..., HC4, 1]、[..., HC4, HC4]、[..., H]即后续mhc_post所需的 post 系数、comb 矩阵以及下一层的输入向量。3.2 参数语义与校验可复制的默认值速查表参数默认值语义与约束dot_mix—原始投影 logits尾部 24 pre(4) post(4) comb(16)num_splits 1时带前导 split 维sqrsum—每个 token 的残差平方和用于 RMS 归一化split 模式下 kernel 内部跨 split 归约k—mHC 算法参数直接传给 CUDA kernel测试中取k 4 * hidden_size4 头 × H作为 RMS 的归一化分母mhc_scale—形状必须为[3]分别缩放 pre / post / comb 三组 logitsmhc_base—形状必须为[24]三组 logits 的偏置rms_eps1e-6RMSNorm 数值稳定项必须严格为正否则抛 ValueErrormhc_pre_eps1e-6pre-map 步的数值稳定项必须严格为正mhc_sinkhorn_eps1e-6Sinkhorn 迭代的稳定项必须严格为正mhc_post_mult_value1.0post 输出的乘性因子sinkhorn_repeat20Sinkhorn 行/列归一化迭代次数C 侧要求 1num_splits1前导维的 split 因子只能是 {1, 2, 4, 8, 16}否则抛 ValueError 1时dot_mix/sqrsum各带前导 split 轴kernel 内求和归约block_size0CUDA block 大小提示0表示用 kernel 默认pre_big_fuse 为 256、with_prenorm 为 128512/256/ 其余分别派发 512 / 256 / 1283.3 split 模式的形状细节num_splits 1时flashinfer/mhc.pydot_mix形状必须为outer_shape (24,)sqrsum形状必须为outer_shape。num_splits 1时第 280-292 行dot_mix形状必须为(num_splits,) outer_shape (24,)sqrsum形状必须为(num_splits,) outer_shape摊平后 kernel 在 split 轴上求和见下文源码。3.4 CUDA 实现逐 token 三阶段流水核心 kernel 为mhc_pre_big_fuse_kernelcsrc/mhc/mhc_pre_big_fuse.cu采用one CTA per token的 grid 布局dim3 grid(total_tokens)每个 block 内分三阶段协作RMS 归一化可选计算 sqrsumwarp_sumblock_sum通过__shfl_down_sync与共享内存完成跨 warp 归约rstd rsqrtf(sq_total / K rms_eps)其中K即传入的k。系数生成write_token_metadata第 101-164 行仅 warp 0 的前 4 个 lane 参与复用 32 线程 warp 的广播机制pre_mix[lane] sigmoid(pre_logit) mhc_pre_epspost_mix[lane] sigmoid(post_logit) * mhc_post_mult_valuecomb 矩阵先做 softmax行归一减行最大值保证数值稳定再用__shfl_xor_sync在 lane 间完成列和归约随后执行sinkhorn_repeat次行归一 → 列归一交替迭代这正是测试参考实现中_sinkhorn_normalize_ref的双随机doubly stochastic归一化。生成 layer_inputwrite_layer_input第 166-200 行warp 0 之外的所有线程按 vec8 遍历隐藏维累加layer_input[h] Σ_j pre_mix[j] * residual[j, h]。当num_splits 1时第 241-256 行的分支会把各 split 的sqrsum与dot_mix逐项累加后再进入归一化实现跨 split 归约而mhc_pre_big_fuse_with_prenorm则通过COMPUTE_SQRSUMtrue的模板特化在 kernel 内直接计算sqrsumresidual_square_sum_vec8省去外部预计算static_assert保证该路径仅支持num_splits1。C 侧公共形状校验集中在check_common_shapes第 370-409 行residual [T,4,H]、mhc_scale [3]、mhc_base [24]且H必须能被 8 整除vec8 对齐前提post_mix [T,4]、comb_mix [T,4,4]、layer_input [T,H]全部要与 token 数对齐。4. 免预计算变体mhc_pre_big_fuse_with_prenorm当外部没有预先算好sqrsum时应使用mhc_pre_big_fuse_with_prenorm。它对应 Agentic 的mhc_pre_finalize边界在 kernel 内部从residual计算 RMS 平方和。签名flashinfer/mhc.pyflashinfer.mhc.mhc_pre_big_fuse_with_prenorm( dot_mix: torch.Tensor, # [..., 24] 或 [1, ..., 24]float32 residual: torch.Tensor, # [..., HC4, H]bf16 mhc_scale: torch.Tensor, # [3] mhc_base: torch.Tensor, # [24] rms_eps: float 1e-6, mhc_pre_eps: float 1e-6, mhc_sinkhorn_eps: float 1e-6, mhc_post_mult_value: float 1.0, sinkhorn_repeat: int 20, block_size: int 0, ) - tuple[torch.Tensor, torch.Tensor, torch.Tensor]与mhc_pre_big_fuse的差异点无k与num_splits参数RMS 分母固定为kHc4 * H即4 * H且内部 sqrsum 路径只支持单 splitdot_mix可带前导1维[..., 24]或[1, ..., 24]两种形状都接受flashinfer/mhc.py自动 squeeze/reshape 为[T, 24]默认 block size 为 128select_pre_big_fuse_with_prenorm_block_sizecsrc/mhc/mhc_pre_big_fuse.cu低于外部 sqrsum 路径的 256。5. 完整调用示例与数值验证5.1 一个可复现的最小调用参照 tests/mhc/test_mhc_post.py 与 tests/mhc/test_mhc_pre_big_fuse.py 的输入构造方式注意 mHC 的 BF16 核要求SM80 GPU测试中通过get_compute_capability跳过旧架构import torch import flashinfer # ---- 后映射mhc_post ---- outer (2, 3) # 任意外层维度batch × seq 等 H 4096 # 隐藏维8 的倍数走向量化路径 x torch.randn((*outer, H), dtypetorch.bfloat16, devicecuda) residual torch.randn((*outer, 4, H), dtypetorch.bfloat16, devicecuda) post_layer_mix torch.randn((*outer, 4), dtypetorch.float32, devicecuda) comb_res_mix torch.randn((*outer, 4, 4), dtypetorch.float32, devicecuda) new_residual flashinfer.mhc.mhc_post(x, residual, post_layer_mix, comb_res_mix) assert new_residual.shape residual.shape # ---- 前映射外部 sqrsum 版mhc_pre_big_fuse ---- k 4 * H dot_mix torch.randn((*outer, 24), dtypetorch.float32, devicecuda) * 0.01 sqrsum torch.rand(outer, dtypetorch.float32, devicecuda) * float(k) mhc_scale torch.randn((3,), dtypetorch.float32, devicecuda) * 0.1 mhc_base torch.randn((24,), dtypetorch.float32, devicecuda) * 0.1 post_mix, comb_mix, layer_input flashinfer.mhc.mhc_pre_big_fuse( dot_mix, sqrsum, residual, mhc_scale, mhc_base, k, num_splits1, sinkhorn_repeat20, ) assert post_mix.shape (*outer, 4, 1) assert comb_mix.shape (*outer, 4, 4) assert layer_input.shape (*outer, H) # ---- 前映射免预计算版mhc_pre_big_fuse_with_prenorm ---- post_mix2, comb_mix2, layer_input2 flashinfer.mhc.mhc_pre_big_fuse_with_prenorm( dot_mix, residual, mhc_scale, mhc_base, )5.2 测试参考实现数学定义的权威对照测试中的参考实现完整刻画了 mHC 的数学流程tests/mhc/test_mhc_pre_big_fuse.pyrstd torch.rsqrt(sqrsum.float().unsqueeze(-1) / float(k) RMS_EPS) # RMS 归一化 mixes dot_mix.float() * rstd pre_logits mixes[..., :4] * mhc_scale[0] mhc_base[:4] # pre 头 post_logits mixes[..., 4:8] * mhc_scale[1] mhc_base[4:8] # post 头 comb_logits mixes[..., 8:] * mhc_scale[2] mhc_base[8:] # comb 矩阵 pre_mix torch.sigmoid(pre_logits).unsqueeze(-1) MHC_PRE_EPS post_mix (torch.sigmoid(post_logits) * MHC_POST_MULT_VALUE).unsqueeze(-1) comb_mix _sinkhorn_normalize_ref(comb_logits.view(..., 4, 4)) # Sinkhorn 双随机归一化 layer_input (pre_mix * residual.float()).sum(dim-2).bfloat16() # 加权求和生成下一层输入_sinkhorn_normalize_ref第 21-31 行展示了 Sinkhorn 迭代的语义softmax(dim-1) eps后交替执行行归一除以行和→ 列归一除以列和共sinkhorn_repeat轮。5.3 测试覆盖与验收标准test_mhc_post_matches_referencetests/mhc/test_mhc_post.py参数化覆盖了H ∈ {64, 127, 1536, 2048, 4096, 7168, 8192, 16392}与post_ndim ∈ {1, 2}其中 4096 / 7168 分别标注为 DeepSeek V4 Flash 与 V4 Pro 形状用于触发 persistent split 与静态 vec 路径127 这种非 8 对齐的 H 触发 scalar 回退路径。验收标准为相对范数误差 0.005且atolrtol1e-2。test_mhc_pre_big_fuse_matches_referencetests/mhc/test_mhc_pre_big_fuse.py对num_splits ∈ {1, 2, 4, 8, 16}全枚举验证 split 归约与[..., 4, 1]/[..., 4, 4]/[..., H]输出形状。test_mhc_pre_big_fuse_with_prenorm_matches_reference第 166-202 行验证dot_mix带/不带前导1维两种输入以及 kernel 内计算 sqrsum 与参考实现的等价性输出容差atolrtol2e-3系数与1e-2layer_input。6. JIT 编译与内核装配flashinfer.mhc的三个 API 均通过 flashinfer/jit/mhc.py 走 FlashInfer 的 JIT 流水线gen_mhc_module()把csrc/mhc/mhc_post.cu与csrc/mhc/mhc_pre_big_fuse.cu两个翻译单元打包为一个名为mhc的JitSpec经build_and_load()编译后由get_mhc_module()functools.cache缓存flashinfer/mhc.py加载。Python 侧的_mhc_post_impl、_mhc_pre_big_fuse_impl、_mhc_pre_big_fuse_with_prenorm_impl分别用register_custom_op注册为flashinfer::mhc_post/flashinfer::mhc_pre_big_fuse/flashinfer::mhc_pre_big_fuse_with_prenorm自定义算子mutates_args声明输出张量原地写入并配套register_fake_op假算子以支持 torch.compile 等元数据推导对应的TVM_FFI_DLL_EXPORT_TYPED_FUNC在 C 侧导出同名 FFI 函数csrc/mhc/mhc_post.cu、csrc/mhc/mhc_pre_big_fuse.cu。模块已在flashinfer/__init__.py第 240 行以from . import mhc as mhc顶层导出因此直接import flashinfer后即可通过flashinfer.mhc.mhc_post等路径调用。7. 使用要点小结固定 HC4residual的倒数第二维、post_layer_mix的尾维、comb_res_mix的两个尾维都硬编码为 4违反即抛异常BF16 SM80所有核只接受 BF16 残差/输出float32 仅用于混合系数与 scale/base测试在 SM80 以下自动跳过8 对齐的 H 走向量化路径mhc_pre_big_fuse系列要求H % 8 0vec8 访存mhc_post对非对齐 H 会回退到 scalar kernelSinkhorn 迭代sinkhorn_repeat控制双随机归一化轮数默认 20C 侧要求 1更多迭代通常带来更接近双随机矩阵的 comb 系数但增加计算量split 归约当投影 logits 过大需分片计算时使用num_splits ∈ {1,2,4,8,16}kernel 内部自动跨 split 求和无需在 Python 侧预归约两类前映射的选择手头已有sqrsum例如与投影一起算好用mhc_pre_big_fuse否则用mhc_pre_big_fuse_with_prenorm让 kernel 内部现算后者还兼容带前导1维的dot_mix。若需深入内核细节可直接阅读 csrc/mhc/mhc_post.cu向量化加载与多路径分发与 csrc/mhc/mhc_pre_big_fuse.cuwarp 内 Sinkhorn 归约与 block 协作并以 tests/mhc 中的参考实现作为数值语义的权威对照。赞分享大模型深度学习算子库后端高性能计算【免费下载链接】flashinferFlashInfer: Kernel Library for LLM Serving项目地址https://gitcode.com/gh_mirrors/fl/flashinfer点击查看免费下载相关推荐Gradle Kotlin DSL Samples最佳实践总结避免常见陷阱的20个技巧Gradle Kotlin DSL Samples最佳实践总结避免常见陷阱的20个技巧 Gradle Kotlin DSL Samples是Gradle官方提如何在 KernelSU 上跑起 LSPosed3 步装好 ZygiskNext 并配置 Xposed 模块如何在 KernelSU 上跑起 LSPosed3 步装好 ZygiskNext 并配置 Xposed 模块 结论先说LSPosed 和其他现代 Xpose操作系统驱动开发Kubernetes component-helpers 模块深度解读面向多组件复用的核心辅助函数库Kubernetes component helpers 模块深度解读面向多组件复用的核心辅助函数库 本文以仓库内 staging/src/k8s.io/co云原生容器编排集群管理微服务上一篇Zeroclaw 依赖安全审计策略cargo audit 与 cargo deny 双工具、双锁文件治理实战下一篇QMK Clueboard 66% HotSwap 默认键位详解66_ansi 布局与 QK_GESC 按键实现创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
大模型深度学习算子库后端高性能计算【免费下载链接】flashinferFlashInfer: Kernel Library for LLM Serving项目地址https://gitcode.com/gh_mirrors/fl/flashinfer点击查看免费下载本文围绕 FlashInfer 中flashinfer.mhc模块展开系统讲解其专为 Agentic 风格残差混合residual mixing设计的 Multi-head Residual CombinationmHC系列 CUDA 核函数后映射mhc_post与两大前映射融合核mhc_pre_big_fuse/mhc_pre_big_fuse_with_prenorm。你将掌握这三个 API 的数学语义、全部形状约束与参数默认值、CUDA 底层实现原理以及它们在 tests/mhc 中的数值验证方法可直接用于 Agentic 架构中4 子头残差混合场景的推理接入与调试。1. 模块定位Agentic 残差混合与固定 HC4 子头布局flashinfer.mhc是 FlashInfer 中专用于 Agentic 风格残差混合Agentic-style residual mixing的核函数集合其官方定位见 docs/api/mhc.rstMulti-head residual Combination (mHC) kernels used by Agentic-style residual mixing with a fixedHC4sub-head layout.核心要点是固定HC4子头布局hard-wired to 4 sub-heads。所谓残差混合是指在一个 Transformer 层中将上层的多层残差状态按可学习的混合系数重新组合后注入当前层。mHC 把这一过程拆成两个阶段前映射pre-map根据投影 logits 计算出混合权重pre / post / comb 三组系数并生成下一层的实际输入后映射post-map在当前层输出x与旧的 4 头残差residual之间按系数完成最终组合得到新的 4 头残差。该模块共导出三个函数全部以flashinfer_api装饰并配套 trace 模板因此同时支持 FlashInfer 的 trace 录制/回放机制见 flashinfer/mhc.py 等处的trace参数。模块中两个关键常量定义在 flashinfer/mhc.py_MHC_HC 4 # 固定的子头数 _MHC_MIX _MHC_HC * (2 _MHC_HC) # 4 * 6 24即 pre(4) post(4) comb(16)24 维的投影 logits 布局贯穿全部三个 API前 4 维给 pre、中间 4 维给 post、后 16 维按 4×4 排布给 comb残差组合矩阵。2. 后映射核flashinfer.mhc.mhc_post2.1 数学语义mhc_post完成 mHC 的 post 映射其公式在 flashinfer/mhc.py 中明确给出out[..., new_hc, h] x[..., h] * post_layer_mix[..., new_hc] Σ_old residual[..., old_hc, h] * comb_res_mix[..., old_hc, new_hc]即对每个新子头new_hc输出 当前层输出x乘以其专属后混合系数post_layer_mix[..., new_hc]再加上 4 个旧残差子头按组合矩阵comb_res_mix[..., old_hc, new_hc]加权求和的结果。2.2 函数签名与输入输出形状flashinfer.mhc.mhc_post( x: torch.Tensor, # [..., H]层输出bf16 residual: torch.Tensor, # [..., HC4, H]多子头残差bf16 post_layer_mix: torch.Tensor, # [..., HC4] 或 [..., HC4, 1]float32 comb_res_mix: torch.Tensor, # [..., HC4, HC4]float32 ) - torch.Tensor # 与 residual 同形状 [..., HC4, H]形状校验逻辑在_check_mhc_post_inputsflashinfer/mhc.py中输入要求说明residualndim 3shape[-2] 4倒数第二维即 HC 轴必须等于 4否则抛ValueError(residual.shape[-2] / HC must be 4)xshape residual.shape[:-2] (residual.shape[-1],)外层维度需与 residual 一致隐藏维 H 相同post_layer_mix[..., 4]或[..., 4, 1]两种形状都接受内部统一 reshapecomb_res_mix[..., 4, 4]每个[old_hc, new_hc]条目是旧头old_hc混入新头new_hc的系数内部会先做reshape(-1, ...)摊平 token 维度保证 contiguous 后调用底层实现_mhc_post_impl最后reshape_as(residual)还原形状flashinfer/mhc.py。2.3 CUDA 实现多路径分发的内存布局底层实现在 csrc/mhc/mhc_post.cu入口flashinfer::mhc::mhc_post第 556-599 行先做类型/形状强校验x、residual、out必须为dl_bfloat16post_layer_mix、comb_res_mix必须为dl_float32形状必须满足residual [T, 4, H]、x [T, H]、post_layer_mix [T, 4]、comb_res_mix [T, 4, 4]、out [T, 4, H]total_tokens 0时直接返回避免空启动。该文件为 BF16 HC4 准备了五条 kernel 路径由launch_bf16_hc4第 513-552 行按H是否 8 对齐和取值区间分发路径适用场景关键点token-vec kernelmhc_post_bf16_hc4_token_vec_kernelH ≤ 1536 / ≤ 2048 / ≤ 8192 / ≤kMaxTokenVecHidden每个 CTA 处理TokensPerBlock个 token4 或 1每 token 多线程并行系数可经 warp shuffleWarpCoeffLoadtrue或共享内存广播加载split-vec kernelmhc_post_bf16_hc4_split_vec_kernel1536 H ≤ 4096 等按 H 维分 tileTileElems1280每 CTA 160 线程 × vec8grid.y 在 token 维上循环persistent split kernelH 4096、H 7168token ≥ 4096静态 H 特化compute_vec8_head_serial逐头串行写回以缓解访存压力注释明确标注 DeepSeek V4 / V4 Pro shape 场景scalar kernelmhc_post_bf16_hc4_scalar_kernelH 非 8 的倍数线性平铺逐元素回退路径vec 化层面使用 8 元素kVecWidth8BF16 向量通过内联 PTXld.global.v4.u32/st.global.v4.u32完成 128 位访存Bf16x8第 47-59 行每个 token 的 20 个混合系数4 post 16 comb被组织为Hc4Mix一个float4 post 四个float4 from0..from3配合fmaf累加与__shfl_sync跨 lane 广播将公式展开为 4 个新头并行、每次处理 8 个隐藏维的 FMA 流水compute_vec8第 144-191 行。3. 前映射大融合核mhc_pre_big_fuse3.1 功能与公式mhc_pre_big_fuse完成 mHC 的 pre-map 大融合big-fuse它接收外部已经算好的投影 logitsdot_mix与残差平方和sqrsum在一个 kernel 内完成 RMS 归一化、三组系数激活/归一化含 Sinkhorn 迭代并直接生成下一层的输入layer_input。签名flashinfer/mhc.pyflashinfer.mhc.mhc_pre_big_fuse( dot_mix: torch.Tensor, # [..., 24] 或 [num_splits, ..., 24]float32 sqrsum: torch.Tensor, # [...] 或 [num_splits, ...]float32 residual: torch.Tensor, # [..., HC4, H]bf16 mhc_scale: torch.Tensor, # [3]float32 mhc_base: torch.Tensor, # [24]float32 k: int, rms_eps: float 1e-6, mhc_pre_eps: float 1e-6, mhc_sinkhorn_eps: float 1e-6, mhc_post_mult_value: float 1.0, sinkhorn_repeat: int 20, num_splits: int 1, block_size: int 0, ) - tuple[torch.Tensor, torch.Tensor, torch.Tensor] # (post_mix, comb_mix, layer_input)返回三个张量形状分别为[..., HC4, 1]、[..., HC4, HC4]、[..., H]即后续mhc_post所需的 post 系数、comb 矩阵以及下一层的输入向量。3.2 参数语义与校验可复制的默认值速查表参数默认值语义与约束dot_mix—原始投影 logits尾部 24 pre(4) post(4) comb(16)num_splits 1时带前导 split 维sqrsum—每个 token 的残差平方和用于 RMS 归一化split 模式下 kernel 内部跨 split 归约k—mHC 算法参数直接传给 CUDA kernel测试中取k 4 * hidden_size4 头 × H作为 RMS 的归一化分母mhc_scale—形状必须为[3]分别缩放 pre / post / comb 三组 logitsmhc_base—形状必须为[24]三组 logits 的偏置rms_eps1e-6RMSNorm 数值稳定项必须严格为正否则抛 ValueErrormhc_pre_eps1e-6pre-map 步的数值稳定项必须严格为正mhc_sinkhorn_eps1e-6Sinkhorn 迭代的稳定项必须严格为正mhc_post_mult_value1.0post 输出的乘性因子sinkhorn_repeat20Sinkhorn 行/列归一化迭代次数C 侧要求 1num_splits1前导维的 split 因子只能是 {1, 2, 4, 8, 16}否则抛 ValueError 1时dot_mix/sqrsum各带前导 split 轴kernel 内求和归约block_size0CUDA block 大小提示0表示用 kernel 默认pre_big_fuse 为 256、with_prenorm 为 128512/256/ 其余分别派发 512 / 256 / 1283.3 split 模式的形状细节num_splits 1时flashinfer/mhc.pydot_mix形状必须为outer_shape (24,)sqrsum形状必须为outer_shape。num_splits 1时第 280-292 行dot_mix形状必须为(num_splits,) outer_shape (24,)sqrsum形状必须为(num_splits,) outer_shape摊平后 kernel 在 split 轴上求和见下文源码。3.4 CUDA 实现逐 token 三阶段流水核心 kernel 为mhc_pre_big_fuse_kernelcsrc/mhc/mhc_pre_big_fuse.cu采用one CTA per token的 grid 布局dim3 grid(total_tokens)每个 block 内分三阶段协作RMS 归一化可选计算 sqrsumwarp_sumblock_sum通过__shfl_down_sync与共享内存完成跨 warp 归约rstd rsqrtf(sq_total / K rms_eps)其中K即传入的k。系数生成write_token_metadata第 101-164 行仅 warp 0 的前 4 个 lane 参与复用 32 线程 warp 的广播机制pre_mix[lane] sigmoid(pre_logit) mhc_pre_epspost_mix[lane] sigmoid(post_logit) * mhc_post_mult_valuecomb 矩阵先做 softmax行归一减行最大值保证数值稳定再用__shfl_xor_sync在 lane 间完成列和归约随后执行sinkhorn_repeat次行归一 → 列归一交替迭代这正是测试参考实现中_sinkhorn_normalize_ref的双随机doubly stochastic归一化。生成 layer_inputwrite_layer_input第 166-200 行warp 0 之外的所有线程按 vec8 遍历隐藏维累加layer_input[h] Σ_j pre_mix[j] * residual[j, h]。当num_splits 1时第 241-256 行的分支会把各 split 的sqrsum与dot_mix逐项累加后再进入归一化实现跨 split 归约而mhc_pre_big_fuse_with_prenorm则通过COMPUTE_SQRSUMtrue的模板特化在 kernel 内直接计算sqrsumresidual_square_sum_vec8省去外部预计算static_assert保证该路径仅支持num_splits1。C 侧公共形状校验集中在check_common_shapes第 370-409 行residual [T,4,H]、mhc_scale [3]、mhc_base [24]且H必须能被 8 整除vec8 对齐前提post_mix [T,4]、comb_mix [T,4,4]、layer_input [T,H]全部要与 token 数对齐。4. 免预计算变体mhc_pre_big_fuse_with_prenorm当外部没有预先算好sqrsum时应使用mhc_pre_big_fuse_with_prenorm。它对应 Agentic 的mhc_pre_finalize边界在 kernel 内部从residual计算 RMS 平方和。签名flashinfer/mhc.pyflashinfer.mhc.mhc_pre_big_fuse_with_prenorm( dot_mix: torch.Tensor, # [..., 24] 或 [1, ..., 24]float32 residual: torch.Tensor, # [..., HC4, H]bf16 mhc_scale: torch.Tensor, # [3] mhc_base: torch.Tensor, # [24] rms_eps: float 1e-6, mhc_pre_eps: float 1e-6, mhc_sinkhorn_eps: float 1e-6, mhc_post_mult_value: float 1.0, sinkhorn_repeat: int 20, block_size: int 0, ) - tuple[torch.Tensor, torch.Tensor, torch.Tensor]与mhc_pre_big_fuse的差异点无k与num_splits参数RMS 分母固定为kHc4 * H即4 * H且内部 sqrsum 路径只支持单 splitdot_mix可带前导1维[..., 24]或[1, ..., 24]两种形状都接受flashinfer/mhc.py自动 squeeze/reshape 为[T, 24]默认 block size 为 128select_pre_big_fuse_with_prenorm_block_sizecsrc/mhc/mhc_pre_big_fuse.cu低于外部 sqrsum 路径的 256。5. 完整调用示例与数值验证5.1 一个可复现的最小调用参照 tests/mhc/test_mhc_post.py 与 tests/mhc/test_mhc_pre_big_fuse.py 的输入构造方式注意 mHC 的 BF16 核要求SM80 GPU测试中通过get_compute_capability跳过旧架构import torch import flashinfer # ---- 后映射mhc_post ---- outer (2, 3) # 任意外层维度batch × seq 等 H 4096 # 隐藏维8 的倍数走向量化路径 x torch.randn((*outer, H), dtypetorch.bfloat16, devicecuda) residual torch.randn((*outer, 4, H), dtypetorch.bfloat16, devicecuda) post_layer_mix torch.randn((*outer, 4), dtypetorch.float32, devicecuda) comb_res_mix torch.randn((*outer, 4, 4), dtypetorch.float32, devicecuda) new_residual flashinfer.mhc.mhc_post(x, residual, post_layer_mix, comb_res_mix) assert new_residual.shape residual.shape # ---- 前映射外部 sqrsum 版mhc_pre_big_fuse ---- k 4 * H dot_mix torch.randn((*outer, 24), dtypetorch.float32, devicecuda) * 0.01 sqrsum torch.rand(outer, dtypetorch.float32, devicecuda) * float(k) mhc_scale torch.randn((3,), dtypetorch.float32, devicecuda) * 0.1 mhc_base torch.randn((24,), dtypetorch.float32, devicecuda) * 0.1 post_mix, comb_mix, layer_input flashinfer.mhc.mhc_pre_big_fuse( dot_mix, sqrsum, residual, mhc_scale, mhc_base, k, num_splits1, sinkhorn_repeat20, ) assert post_mix.shape (*outer, 4, 1) assert comb_mix.shape (*outer, 4, 4) assert layer_input.shape (*outer, H) # ---- 前映射免预计算版mhc_pre_big_fuse_with_prenorm ---- post_mix2, comb_mix2, layer_input2 flashinfer.mhc.mhc_pre_big_fuse_with_prenorm( dot_mix, residual, mhc_scale, mhc_base, )5.2 测试参考实现数学定义的权威对照测试中的参考实现完整刻画了 mHC 的数学流程tests/mhc/test_mhc_pre_big_fuse.pyrstd torch.rsqrt(sqrsum.float().unsqueeze(-1) / float(k) RMS_EPS) # RMS 归一化 mixes dot_mix.float() * rstd pre_logits mixes[..., :4] * mhc_scale[0] mhc_base[:4] # pre 头 post_logits mixes[..., 4:8] * mhc_scale[1] mhc_base[4:8] # post 头 comb_logits mixes[..., 8:] * mhc_scale[2] mhc_base[8:] # comb 矩阵 pre_mix torch.sigmoid(pre_logits).unsqueeze(-1) MHC_PRE_EPS post_mix (torch.sigmoid(post_logits) * MHC_POST_MULT_VALUE).unsqueeze(-1) comb_mix _sinkhorn_normalize_ref(comb_logits.view(..., 4, 4)) # Sinkhorn 双随机归一化 layer_input (pre_mix * residual.float()).sum(dim-2).bfloat16() # 加权求和生成下一层输入_sinkhorn_normalize_ref第 21-31 行展示了 Sinkhorn 迭代的语义softmax(dim-1) eps后交替执行行归一除以行和→ 列归一除以列和共sinkhorn_repeat轮。5.3 测试覆盖与验收标准test_mhc_post_matches_referencetests/mhc/test_mhc_post.py参数化覆盖了H ∈ {64, 127, 1536, 2048, 4096, 7168, 8192, 16392}与post_ndim ∈ {1, 2}其中 4096 / 7168 分别标注为 DeepSeek V4 Flash 与 V4 Pro 形状用于触发 persistent split 与静态 vec 路径127 这种非 8 对齐的 H 触发 scalar 回退路径。验收标准为相对范数误差 0.005且atolrtol1e-2。test_mhc_pre_big_fuse_matches_referencetests/mhc/test_mhc_pre_big_fuse.py对num_splits ∈ {1, 2, 4, 8, 16}全枚举验证 split 归约与[..., 4, 1]/[..., 4, 4]/[..., H]输出形状。test_mhc_pre_big_fuse_with_prenorm_matches_reference第 166-202 行验证dot_mix带/不带前导1维两种输入以及 kernel 内计算 sqrsum 与参考实现的等价性输出容差atolrtol2e-3系数与1e-2layer_input。6. JIT 编译与内核装配flashinfer.mhc的三个 API 均通过 flashinfer/jit/mhc.py 走 FlashInfer 的 JIT 流水线gen_mhc_module()把csrc/mhc/mhc_post.cu与csrc/mhc/mhc_pre_big_fuse.cu两个翻译单元打包为一个名为mhc的JitSpec经build_and_load()编译后由get_mhc_module()functools.cache缓存flashinfer/mhc.py加载。Python 侧的_mhc_post_impl、_mhc_pre_big_fuse_impl、_mhc_pre_big_fuse_with_prenorm_impl分别用register_custom_op注册为flashinfer::mhc_post/flashinfer::mhc_pre_big_fuse/flashinfer::mhc_pre_big_fuse_with_prenorm自定义算子mutates_args声明输出张量原地写入并配套register_fake_op假算子以支持 torch.compile 等元数据推导对应的TVM_FFI_DLL_EXPORT_TYPED_FUNC在 C 侧导出同名 FFI 函数csrc/mhc/mhc_post.cu、csrc/mhc/mhc_pre_big_fuse.cu。模块已在flashinfer/__init__.py第 240 行以from . import mhc as mhc顶层导出因此直接import flashinfer后即可通过flashinfer.mhc.mhc_post等路径调用。7. 使用要点小结固定 HC4residual的倒数第二维、post_layer_mix的尾维、comb_res_mix的两个尾维都硬编码为 4违反即抛异常BF16 SM80所有核只接受 BF16 残差/输出float32 仅用于混合系数与 scale/base测试在 SM80 以下自动跳过8 对齐的 H 走向量化路径mhc_pre_big_fuse系列要求H % 8 0vec8 访存mhc_post对非对齐 H 会回退到 scalar kernelSinkhorn 迭代sinkhorn_repeat控制双随机归一化轮数默认 20C 侧要求 1更多迭代通常带来更接近双随机矩阵的 comb 系数但增加计算量split 归约当投影 logits 过大需分片计算时使用num_splits ∈ {1,2,4,8,16}kernel 内部自动跨 split 求和无需在 Python 侧预归约两类前映射的选择手头已有sqrsum例如与投影一起算好用mhc_pre_big_fuse否则用mhc_pre_big_fuse_with_prenorm让 kernel 内部现算后者还兼容带前导1维的dot_mix。若需深入内核细节可直接阅读 csrc/mhc/mhc_post.cu向量化加载与多路径分发与 csrc/mhc/mhc_pre_big_fuse.cuwarp 内 Sinkhorn 归约与 block 协作并以 tests/mhc 中的参考实现作为数值语义的权威对照。赞分享大模型深度学习算子库后端高性能计算【免费下载链接】flashinferFlashInfer: Kernel Library for LLM Serving项目地址https://gitcode.com/gh_mirrors/fl/flashinfer点击查看免费下载相关推荐Gradle Kotlin DSL Samples最佳实践总结避免常见陷阱的20个技巧Gradle Kotlin DSL Samples最佳实践总结避免常见陷阱的20个技巧 Gradle Kotlin DSL Samples是Gradle官方提如何在 KernelSU 上跑起 LSPosed3 步装好 ZygiskNext 并配置 Xposed 模块如何在 KernelSU 上跑起 LSPosed3 步装好 ZygiskNext 并配置 Xposed 模块 结论先说LSPosed 和其他现代 Xpose操作系统驱动开发Kubernetes component-helpers 模块深度解读面向多组件复用的核心辅助函数库Kubernetes component helpers 模块深度解读面向多组件复用的核心辅助函数库 本文以仓库内 staging/src/k8s.io/co云原生容器编排集群管理微服务上一篇Zeroclaw 依赖安全审计策略cargo audit 与 cargo deny 双工具、双锁文件治理实战下一篇QMK Clueboard 66% HotSwap 默认键位详解66_ansi 布局与 QK_GESC 按键实现创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
