SGLang DeepSeek-V4 注意力测试能力矩阵深度解析SWA / C4 / C128 压缩比模式与后端约束验证【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang本指南以 SGLang 仓库中test/registered/attention/unittests/dsv4/README.md为核心全面讲解 DeepSeek-V4 注意力后端的测试覆盖设计包括dsv4单一注意力后端在compress_ratio ∈ {0, 4, 128}三种模式下的能力矩阵、输入与配置覆盖策略、独立 PyTorch 参考实现原理以及被明确判定为生产不可达production-unreachable的组合。读者读完可以掌握 DSV4 注意力测试的完整方法论并能在仓库中准确找到后端实现、测试用例与测试工具链的对应位置。为什么 DSV4 注意力测试需要独立的目录DeepSeek-V4下文简称 DSV4的注意力机制与仓库中其他模型dense、MLA、DSA有本质差异它带有按方法区分的稀疏 / indexer 元数据以及打包的 FP8/BF16 KV 缓存布局packed FP8 nope BF16 rope因此无法被并入 dense、MLA 或 DSA 的测试目录而是单独放在test/registered/attention/unittests/dsv4/下。该目录中唯一的注意力后端是dsv4它通过flash_mla完成实际计算。能力矩阵中的每一行代表该后端在某个compress_ratio模式下的覆盖情况0仅滑动窗口注意力SWA-only4C4 稀疏压缩路径128C128 稀疏压缩路径。矩阵的列是各类 runner 执行模式覆盖 eager、CUDA graph 捕获/重放、EAGLE 投机解码等不同执行路径。相关实现位于 deepseek_v4_backend.pyCUDA 版本与 deepseek_v4_backend_hip_radix.pyHIP/radix 变体测试入口为 test_deepseek_v4.py。覆盖率矩阵Coverage Matrix详解矩阵以 runner 模式为列、compress_ratio模式为行。单元格使用以下符号语义✓ variants—— 该组合已被测试覆盖单元格内列出具体的配置变体——— 不适用 / 未被测试production-unreachable: reason—— 生产环境永远不会调用该组合因此测试 runner 会在调用点call site直接断言其不可达blocked: reason—— 一旦尝试就会触发硬断言崩溃同样在调用点被断言deferred: reason—— 未来可能落地当前处于禁用状态。完整覆盖矩阵compress_ratioEager Phase 2CG decodePCG extendBCG extendVerify eagerVerify CGDE eagerDE CGDE-V2 CGEAGLE-draft runnerEAGLE-DE runnerFKVMTP runner0(SWA-only)✓ EXTEND no-prefix / prefix-within-window / nonzeroattn_sink/ above-window / seq_lenSWA_WINDOW / seq_len below-page / seq_len at-page / seq_len above-page / prefix-exact-page / total-exact-page DECODE within-window / multi-request / above-window✓ DECODE within-window multi-request——✓ EAGLE chain (topk1)prefix_lens(64,96)✓ EAGLE chain CGprefix_lens(64,96)✓ EAGLE ragged-accept✓ EAGLE uniformextend_lens(4,4)—✓ chainprefix_lens(32,64),num_steps3DeepseekV4MultiStepBackendcapture/replay vs. per-step-init eager✓ uniformextend_lens(4,4),prefix_lens(64,96)productionEAGLEDraftExtendCudaGraphRunnerthrough_create_dsv4_prefill_backenduses looseDSV4_GRAPH_ATOL1e-1and skips stricttopk_indexexact-match to absorb CG accumulation drift—4(C4)✓ EXTENDprefix_lens(64,),extend_lens(16,) DECODEprefix_lens(64,)extra K cache written directly viaset_extra_key_buffer;c4_sparse_page_indicesseeded manually because indexer is bypassed✓ DECODEprefix_lens(64,)——✓ EAGLE chain (topk1)prefix_lens(64,96)✓ EAGLE chain CGprefix_lens(64,96)production-unreachable: draft layer is SWA-onlyproduction-unreachable: draft layer is SWA-only————128(C128)✓ EXTENDprefix_lens(128,),extend_lens(16,) DECODEprefix_lens(128,)✓ DECODEprefix_lens(128,)——✓ EAGLE chain (topk1)prefix_lens(128,160)✓ EAGLE chain CGprefix_lens(128,160)production-unreachable: draft layer is SWA-onlyproduction-unreachable: draft layer is SWA-only————从矩阵中可以读出三条核心结论SWA-onlycompress_ratio0是最完整的覆盖行几乎所有 runner 模式都对其做了验证包括 CUDA graph 捕获/重放、EAGLE draft / DE runner 等投机解码路径C4/C128 的覆盖集中在 eager / CG decode 与 verify 路径因为压缩路径只在目标模型target model的 DECODE / TARGET_VERIFY 中使用PCG extend、BCG extend 列全部为 —DSV4 的 split-op extend 在结构上不可达详见下文生产不支持的组合。矩阵在测试代码中的落地矩阵中的每一列都能在 test_deepseek_v4.py 中找到对应的测试类与用例组Eager 覆盖TestDSV4AttentionBackendCorrectness中的test_swa_only_casesmake_dsv4_cases(dsv4)生成的 SWA 全变体、test_compress_attention_casesC4/C128 的 dense extend 路径与test_compress_attention_cases_sparse_prefillC4/C128 的_forward_prefill_sparse稀疏 prefill 路径CG decodeCUDA_GRAPH_DECODE_CASES中包含 SWA decode within-window、SWA multi-requestprefix_lens(32, 96)、C4 decodeprefix_lens(64,)与 C128 decodeprefix_lens(128,)四类用例由test_runner_mode_cuda_graph_decode_cases驱动Verify eager / Verify CGTARGET_VERIFY_CASESSWA/C4/C128 各一例prefix_lens分别为(64,96)、(64,96)、(128,160)extend_lens(3,3)与EAGLE_VERIFY_CUDA_GRAPH_CASES对应三个压缩比下的 EAGLE verify CUDA graph 捕获/重放run_dsv4_eagle_verify_cuda_graph_caseEAGLE-draft runnerPRODUCTION_EAGLE_DRAFT_RUNNER_CASES走生产级EAGLEDraftExtendCudaGraphRunner链路prefix_lens(32,64)、num_steps3通过DeepseekV4MultiStepBackend每个 draft 步一个DeepseekV4AttnBackend捕获固定 batch 并重放不同请求的元数据DE eagerragged-accepttest_eagle_draft_extend_without_cpu_seq_lens以force_gpu_only_seq_lensTrue覆盖 EAGLE ragged-accept 的 GPU-only seq lens 路径。这些用例统一使用DSV4_PAGE_SIZE常量即page_size256并通过DSV4AttentionCase数据结构参数化backend、forward_mode、num_heads、page_size、prefix_lens、extend_lens与compress_ratio。测试工具链位于 dsv4_attention.py其中run_dsv4_attention_case、run_dsv4_compress_attention_case、run_dsv4_draft_extend_attention_case、run_dsv4_target_verify_attention_case分别对应矩阵中的不同列。输入与配置覆盖Input And Config CoverageDSV4 测试用例的输入与配置并非随意选取而是严格对齐生产配置与底层 kernel 约束num_heads64与 DSV4 生产配置一致flash_mla.sparse_decode_fwd对h_q有硬性取值约束如 16/32/64/12864 落在合法集合内DeepSeek-V4 形状元数据qk_nope_head_dim448、qk_rope_head_dim64、kv_lora_rank448、head_dim512nope 与 rope 维度之和page_size256这是后端硬编码并强断言的页大小——deepseek_v4_backend.pyREADME 标注的:355、HIP radix 变体:349与 metadata.py:134都要求page_size 256。因此按页边界设计的序列长度变体全部基于 256 展开seq_len255差一页、seq_len256恰好一页、seq_len257超一页、prefix_lens256extend_lens4前缀恰好占满一页、prefix_lens240extend_lens16前缀扩展恰好一页seq_len128则覆盖 SWA 窗口边界seq_len SWA_WINDOW的情况。fixture 会自动放大这些大序列的max_context_len确保req_to_token有足够空间打包的 FP8 nope BF16 rope SWA 缓存布局584 bytes/token来自DeepSeekV4TokenToKVPool实现位于 deepseek_v4_memory_pool.py测试直接使用生产级缓存池SWA 窗口 128SWA_WINDOW常量定义在 deepseek_v4_backend.py容差保持宽松DSV4_ATOL DSV4_RTOL 5e-2用于吸收flash_mla在 FP8 GEMM 累加时相对反量化参考的数值波动graph-replay 场景进一步放宽到DSV4_GRAPH_ATOL 1e-1以吸收use_prefill_cuda_graphTrue引入的 padding 累加漂移。值得注意的细节是测试中max_context_len并非固定值而是由 fixture 依据用例序列长度自动伸缩这与生产调度器中req_to_token随上下文增长而扩容的行为一致可对照后端中 apply_cp_reindex 对 token 计数与 CP round-robin 整除性的断言逻辑理解 token 数在注意力后端中的敏感地位。参考实现原理Reference Implementation Notes矩阵的每一格都依赖一个与生产路径相互独立的数值参考这是本测试体系可信度的基石。为什么参考实现不读取生产缓存参考实现是纯 PyTorch 的 vanilla softmax作用在被 fixture 保存下来的投影 BF16 K 上对 SWA 路径K 来自fixture._swa_bf16_k_per_req对 C4/C128 路径额外 K 来自fixture._extra_bf16_k。它刻意不去读回生产缓存中的字节。原因是一旦参考实现直接反量化生产缓存的 FP8 字节就会与quant_to_nope_fp8_rope_bf16_pack_triton/set_swa_key_buffer_radix耦合——如果 pack/write 环节存在静默 bug生产路径与参考路径会以完全相同的方式损坏测试将失去检测能力。参考实现的 vanilla BF16 K 与flash_mla实际读取的 FP8 反量化 K 之间存在 FP8 量化噪声这一差异由DSV4_ATOL DSV4_RTOL 5e-2容差吸收。C4/C128 参考如何获取注意力索引对于 C4/C128参考实现读取升级版DSV4AttnMetadata中每个 q token 的swa_page_indices/c4_sparse_page_indices/c128_page_indices从而得知 kernel 实际会 attend 到哪些条目。由于投机图 runner 会在init_forward_metadata*之前调用expected_outputfixture 会在每次调用时重建当前 batch 的元数据并在on_after_cuda_graph_warmup之后重新播种c4_sparse_page_indices确保参考观察到与后端 forward 完全一致的索引集合。这一重建-重播种节奏对应 dsv4_attention.py 中expected_dsv4_output_from_inputs与_pure_torch_dsv4_combined_reference的实现逻辑。attention-sink 修正的验证注意力沉没attention sink修正是通过追加一个虚拟 key 实现的该虚拟 key 带 per-head 分数attn_sink、value 为 0。默认attn_sink_value-1e30时这在数值上是 no-op而dsv4_swa_extend_nonzero_attn_sink用例以attn_sink_value0.0实际触发并验证该修正逻辑。换言之矩阵中nonzeroattn_sink变体专门用于证明 sink 修正不会破坏注意力数值。生产不支持的组合Production-UnsupportedREADME 花费大量篇幅澄清矩阵中的 — 与 production-unreachable 不是缺陷而是后端断言体系对生产约束的显式编码。这些约束逐一列在下方全部可以在后端源码中找到对应断言。1.compress_ratio ∈ {4, 128}DRAFT_EXTEND生产不可达DSV4 的 draft 模型deepseek_v4_nextn.py 中的DeepseekV4ModelNextN是单一 decoder 层且以compress_ratio_overrideCOMPRESS_RATIO_NEXTN_LAYER 0构建该常量定义在:37覆盖参数传入:97。该值经由MQALayer.__init__deepseek_v4.py 中compress_ratio_override参数的传递链强制 draft 层无论config.compress_ratios如何都只走 SWA-only。因此生产环境永远不会调用forward(compress_ratio4 或 128, forward_modeDRAFT_EXTEND)目标模型只在 DECODE / TARGET_VERIFY 路径使用 C4/C128此时通过need_compressTrue填充 C4/C128 元数据如果测试强行尝试该组合init_forward_metadata_draft_extenddeepseek_v4_backend.py 中 README 标注的:636-663硬编码need_compressFalsec4_sparse_page_indices/c128_flashmla_metadata会保持为None——forward(compress_ratio4)会触发extra_indices.shape[-1]相关错误forward(compress_ratio128)则会触发 flash_mla 的tile_scheduler_metadata断言。测试 runner 在调用点做了双重保险run_dsv4_draft_extend_attention_case与run_dsv4_eagle_draft_extend_cuda_graph_case都会断言case.compress_ratio 0把这种不可达状态在测试层面显式暴露出来。2. MTPtopk 1树式投机结构性不可能deepseek_v4_backend.pyREADME 标注的:369断言self.topk in [0, 1]HIP radix 变体deepseek_v4_backend_hip_radix.py 的:363同样如此。DSV4 的投机 draft-extend / target-verify永远是链式chaintopk1树式投机在结构上不可能。这正是矩阵中DE-V2 CG、EAGLE-draft tree runner、EAGLE-DE tree runner、FKVMTP runner列标 — 而非 deferred 的原因——这些 runner 本质依赖树式tree spec结构。3. 非 256 的 page_sizepage_size 256的硬断言存在于 deepseek_v4_backend.py:355、HIP radix 变体:349与 metadata.py:134。测试侧通过DSV4_PAGE_SIZE 256常量与全部用例的page_sizeDSV4_PAGE_SIZE保持一致。4. 非 512 的 head_dimdeepseek_v4_backend.pyREADME 标注的:345-347断言head_dim 512。DSV4 被硬编码为qk_nope448 qk_rope64的组合任何其他 head_dim 都无法通过。5. 未知的compress_ratioDSV4AttnMetadata.get_flashmla_metadata只接受Literal[0, 4, 128]超出范围会抛出ValueError(finvalid {compress_ratio})见 deepseek_v4_backend.py。这一Literal类型与运行时校验的双重约束是矩阵仅有三行的根本原因。6._GraphBucket之外的 forward 模式deepseek_v4_backend.pyREADME 标注的:320-328对不属于{decode_or_idle, target_verify, draft_extend(v1 or v2)}的 forward 模式抛出NotImplementedErrorinit_forward_metadata:713-714同理。这意味着PCG/BCG 的 split-op extend 在结构上不可达——即矩阵中 PCG extend / BCG extend 两列全部为 — 的原因。Compressor / C4Indexer有意排除在矩阵之外这是本 README 中一个容易被误读的边界值得单独展开Compressor与C4Indexer不是注意力后端的组成部分而是 DSV4 模型model拥有的nn.Module实例。从 deepseek_v4.py 的源码结构看self.compressor None/self.indexer None的初始化及后续按配置实例化的逻辑位于:942-963附近模型 forward 在注意力之前先调用self.indexer(...)再调用attn_backend.forward_core_compressor(x, ..., self.compressor)如:1138-1160所示。流入注意力后端的只有两类输出Compressor把字节写入extra_k_cache中由c4_out_loc/c128_out_loc指定的位置——而这些位置来自后端init_forward_metadata阶段的 Triton kernelREADME 标注的deepseek_v4_backend.py:182并非来自 Compressor 本身C4Indexer写入c4_sparse_page_indices字段由后端的forward_extend/forward_decode读取。因此后端与两者的契约可以概括为一句黑盒读写我给你一个写入位置你在那里写入了内容我读取你写的内容。当前 fixture 正是通过生产级 pack store 路径quant_to_nope_fp8_rope_bf16_pack_tritonset_extra_key_buffer见 dsv4_attention.py 中_populate_extra_kv_cache的实现供应已知正确的合成字节与索引并将未量化的 BF16 K 暂存在 fixture 上供参考使用从而精确验证这一契约。init_compression_metadataTriton kernel 本身被完整测试被跳过的只是 Compressor 与 C4Indexer 的nn.Module前向数学x → compressed_kv与x, q_lora → page_indices。Compressor / C4Indexer 的数学正确性属于组件级测试范畴。README 明确建议这类测试的天然归属是test/srt/下的组件单元测试针对这两个模块数学的纯 PyTorch 参考并指出这与 PLAN.md 中把 RoPE 排除在注意力后端矩阵之外的逻辑一致——预处理模块的输出是注意力后端的输入其自身正确性不属于后端矩阵的职责。测试中的两个专项契约类除矩阵覆盖外test_deepseek_v4.py 还包含两个专项测试类值得在阅读矩阵时一并了解TestDSV4BreakableCudaGraphMetadataContractCPU-only验证 BCGbreakable CUDA graph元数据重放契约。包括cuda_graph_backend_decode/cuda_graph_backend_prefill默认不选 breakable需要显式 CLI 标志才 opt-inDSV4Metadata的快照snapshot边界声明SharedReadEnds.PRE_REPLAY稀疏 prefill 快照仅在num_qo_tokens超过_LARGE_INDEXER_QUERY_THRESHOLD时构建 chunk cacherefresh_for_breakable_cuda_graph_replay_对 tensor 字段采用值拷贝、对索引/元数据字段采用引用赋值以在重放时保留捕获期的 tensor storage以及SparsePrefillWorkspace的复用与扩容语义复用不换地址、扩容换地址。TestDSV4SwaOutCacheLocResolution验证get_swa_out_cache_loc的缓存快路径 vs 存储时回退逻辑——仅当 per-forward 缓存值可证明是当前值时使用否则回退到翻译out_cache_loc同时覆盖 DP padding 导致out_cache_loc重绑、以及 IDLE 模式绝不复用陈旧缓存值否则会把哑 token 写进活 KV 造成损坏。下一步工作Next WorkREADME 明确列出的后续工作是在test/srt/下补上Compressor / C4Indexer 组件级正确性测试独立于本矩阵。该工作被标记为可选optional——因为注意力后端已经通过已知正确的合成输入验证了自身一侧的契约组件数学的验证属于独立赛道。如何在仓库中定位与本矩阵相关的代码关注点仓库相对路径能力矩阵文档test/registered/attention/unittests/dsv4/README.md矩阵测试主体test/registered/attention/unittests/dsv4/test_deepseek_v4.py测试工具链runner / 参考实现 / 缓存填充python/sglang/test/kits/attention_unittest/attention_methods/dsv4_attention.pyCUDA 注意力后端SWA_WINDOW、断言、元数据python/sglang/srt/layers/attention/deepseek_v4_backend.pyHIP radix 注意力后端变体python/sglang/srt/layers/attention/deepseek_v4_backend_hip_radix.pyDSV4 注意力元数据Literal 校验、PagedIndexerMetadatapython/sglang/srt/layers/attention/dsv4/metadata.pyDSV4 模型Compressor / C4Indexer 所有权python/sglang/srt/models/deepseek_v4.pyDSV4 draft 模型强制 SWA-only 的COMPRESS_RATIO_NEXTN_LAYERpython/sglang/srt/models/deepseek_v4_nextn.py打包 FP8/BF16 KV 缓存池python/sglang/srt/mem_cache/deepseek_v4_memory_pool.py运行本矩阵测试的前提是 CUDA 环境且安装了带flash_mla模块的sgl_kernel——测试类通过_FLASH_MLA_AVAILABLEimportlib.util.find_spec(sgl_kernel.flash_mla)与torch.cuda.is_available()双重守卫缺失任一条件都会自动跳过unittest.skipIf。测试在 CI 中注册于base-bstage4-GPU B200 与 1-GPU large 两类 runner 配置分别预计耗时 14s 与 13s可作为复现时估算资源占用的参考。【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 SGLang DeepSeek-V4 注意力测试能力矩阵深度解析：SWA / C4 / C128 压缩比模式与后端约束验证
SGLang DeepSeek-V4 注意力测试能力矩阵深度解析SWA / C4 / C128 压缩比模式与后端约束验证【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang本指南以 SGLang 仓库中test/registered/attention/unittests/dsv4/README.md为核心全面讲解 DeepSeek-V4 注意力后端的测试覆盖设计包括dsv4单一注意力后端在compress_ratio ∈ {0, 4, 128}三种模式下的能力矩阵、输入与配置覆盖策略、独立 PyTorch 参考实现原理以及被明确判定为生产不可达production-unreachable的组合。读者读完可以掌握 DSV4 注意力测试的完整方法论并能在仓库中准确找到后端实现、测试用例与测试工具链的对应位置。为什么 DSV4 注意力测试需要独立的目录DeepSeek-V4下文简称 DSV4的注意力机制与仓库中其他模型dense、MLA、DSA有本质差异它带有按方法区分的稀疏 / indexer 元数据以及打包的 FP8/BF16 KV 缓存布局packed FP8 nope BF16 rope因此无法被并入 dense、MLA 或 DSA 的测试目录而是单独放在test/registered/attention/unittests/dsv4/下。该目录中唯一的注意力后端是dsv4它通过flash_mla完成实际计算。能力矩阵中的每一行代表该后端在某个compress_ratio模式下的覆盖情况0仅滑动窗口注意力SWA-only4C4 稀疏压缩路径128C128 稀疏压缩路径。矩阵的列是各类 runner 执行模式覆盖 eager、CUDA graph 捕获/重放、EAGLE 投机解码等不同执行路径。相关实现位于 deepseek_v4_backend.pyCUDA 版本与 deepseek_v4_backend_hip_radix.pyHIP/radix 变体测试入口为 test_deepseek_v4.py。覆盖率矩阵Coverage Matrix详解矩阵以 runner 模式为列、compress_ratio模式为行。单元格使用以下符号语义✓ variants—— 该组合已被测试覆盖单元格内列出具体的配置变体——— 不适用 / 未被测试production-unreachable: reason—— 生产环境永远不会调用该组合因此测试 runner 会在调用点call site直接断言其不可达blocked: reason—— 一旦尝试就会触发硬断言崩溃同样在调用点被断言deferred: reason—— 未来可能落地当前处于禁用状态。完整覆盖矩阵compress_ratioEager Phase 2CG decodePCG extendBCG extendVerify eagerVerify CGDE eagerDE CGDE-V2 CGEAGLE-draft runnerEAGLE-DE runnerFKVMTP runner0(SWA-only)✓ EXTEND no-prefix / prefix-within-window / nonzeroattn_sink/ above-window / seq_lenSWA_WINDOW / seq_len below-page / seq_len at-page / seq_len above-page / prefix-exact-page / total-exact-page DECODE within-window / multi-request / above-window✓ DECODE within-window multi-request——✓ EAGLE chain (topk1)prefix_lens(64,96)✓ EAGLE chain CGprefix_lens(64,96)✓ EAGLE ragged-accept✓ EAGLE uniformextend_lens(4,4)—✓ chainprefix_lens(32,64),num_steps3DeepseekV4MultiStepBackendcapture/replay vs. per-step-init eager✓ uniformextend_lens(4,4),prefix_lens(64,96)productionEAGLEDraftExtendCudaGraphRunnerthrough_create_dsv4_prefill_backenduses looseDSV4_GRAPH_ATOL1e-1and skips stricttopk_indexexact-match to absorb CG accumulation drift—4(C4)✓ EXTENDprefix_lens(64,),extend_lens(16,) DECODEprefix_lens(64,)extra K cache written directly viaset_extra_key_buffer;c4_sparse_page_indicesseeded manually because indexer is bypassed✓ DECODEprefix_lens(64,)——✓ EAGLE chain (topk1)prefix_lens(64,96)✓ EAGLE chain CGprefix_lens(64,96)production-unreachable: draft layer is SWA-onlyproduction-unreachable: draft layer is SWA-only————128(C128)✓ EXTENDprefix_lens(128,),extend_lens(16,) DECODEprefix_lens(128,)✓ DECODEprefix_lens(128,)——✓ EAGLE chain (topk1)prefix_lens(128,160)✓ EAGLE chain CGprefix_lens(128,160)production-unreachable: draft layer is SWA-onlyproduction-unreachable: draft layer is SWA-only————从矩阵中可以读出三条核心结论SWA-onlycompress_ratio0是最完整的覆盖行几乎所有 runner 模式都对其做了验证包括 CUDA graph 捕获/重放、EAGLE draft / DE runner 等投机解码路径C4/C128 的覆盖集中在 eager / CG decode 与 verify 路径因为压缩路径只在目标模型target model的 DECODE / TARGET_VERIFY 中使用PCG extend、BCG extend 列全部为 —DSV4 的 split-op extend 在结构上不可达详见下文生产不支持的组合。矩阵在测试代码中的落地矩阵中的每一列都能在 test_deepseek_v4.py 中找到对应的测试类与用例组Eager 覆盖TestDSV4AttentionBackendCorrectness中的test_swa_only_casesmake_dsv4_cases(dsv4)生成的 SWA 全变体、test_compress_attention_casesC4/C128 的 dense extend 路径与test_compress_attention_cases_sparse_prefillC4/C128 的_forward_prefill_sparse稀疏 prefill 路径CG decodeCUDA_GRAPH_DECODE_CASES中包含 SWA decode within-window、SWA multi-requestprefix_lens(32, 96)、C4 decodeprefix_lens(64,)与 C128 decodeprefix_lens(128,)四类用例由test_runner_mode_cuda_graph_decode_cases驱动Verify eager / Verify CGTARGET_VERIFY_CASESSWA/C4/C128 各一例prefix_lens分别为(64,96)、(64,96)、(128,160)extend_lens(3,3)与EAGLE_VERIFY_CUDA_GRAPH_CASES对应三个压缩比下的 EAGLE verify CUDA graph 捕获/重放run_dsv4_eagle_verify_cuda_graph_caseEAGLE-draft runnerPRODUCTION_EAGLE_DRAFT_RUNNER_CASES走生产级EAGLEDraftExtendCudaGraphRunner链路prefix_lens(32,64)、num_steps3通过DeepseekV4MultiStepBackend每个 draft 步一个DeepseekV4AttnBackend捕获固定 batch 并重放不同请求的元数据DE eagerragged-accepttest_eagle_draft_extend_without_cpu_seq_lens以force_gpu_only_seq_lensTrue覆盖 EAGLE ragged-accept 的 GPU-only seq lens 路径。这些用例统一使用DSV4_PAGE_SIZE常量即page_size256并通过DSV4AttentionCase数据结构参数化backend、forward_mode、num_heads、page_size、prefix_lens、extend_lens与compress_ratio。测试工具链位于 dsv4_attention.py其中run_dsv4_attention_case、run_dsv4_compress_attention_case、run_dsv4_draft_extend_attention_case、run_dsv4_target_verify_attention_case分别对应矩阵中的不同列。输入与配置覆盖Input And Config CoverageDSV4 测试用例的输入与配置并非随意选取而是严格对齐生产配置与底层 kernel 约束num_heads64与 DSV4 生产配置一致flash_mla.sparse_decode_fwd对h_q有硬性取值约束如 16/32/64/12864 落在合法集合内DeepSeek-V4 形状元数据qk_nope_head_dim448、qk_rope_head_dim64、kv_lora_rank448、head_dim512nope 与 rope 维度之和page_size256这是后端硬编码并强断言的页大小——deepseek_v4_backend.pyREADME 标注的:355、HIP radix 变体:349与 metadata.py:134都要求page_size 256。因此按页边界设计的序列长度变体全部基于 256 展开seq_len255差一页、seq_len256恰好一页、seq_len257超一页、prefix_lens256extend_lens4前缀恰好占满一页、prefix_lens240extend_lens16前缀扩展恰好一页seq_len128则覆盖 SWA 窗口边界seq_len SWA_WINDOW的情况。fixture 会自动放大这些大序列的max_context_len确保req_to_token有足够空间打包的 FP8 nope BF16 rope SWA 缓存布局584 bytes/token来自DeepSeekV4TokenToKVPool实现位于 deepseek_v4_memory_pool.py测试直接使用生产级缓存池SWA 窗口 128SWA_WINDOW常量定义在 deepseek_v4_backend.py容差保持宽松DSV4_ATOL DSV4_RTOL 5e-2用于吸收flash_mla在 FP8 GEMM 累加时相对反量化参考的数值波动graph-replay 场景进一步放宽到DSV4_GRAPH_ATOL 1e-1以吸收use_prefill_cuda_graphTrue引入的 padding 累加漂移。值得注意的细节是测试中max_context_len并非固定值而是由 fixture 依据用例序列长度自动伸缩这与生产调度器中req_to_token随上下文增长而扩容的行为一致可对照后端中 apply_cp_reindex 对 token 计数与 CP round-robin 整除性的断言逻辑理解 token 数在注意力后端中的敏感地位。参考实现原理Reference Implementation Notes矩阵的每一格都依赖一个与生产路径相互独立的数值参考这是本测试体系可信度的基石。为什么参考实现不读取生产缓存参考实现是纯 PyTorch 的 vanilla softmax作用在被 fixture 保存下来的投影 BF16 K 上对 SWA 路径K 来自fixture._swa_bf16_k_per_req对 C4/C128 路径额外 K 来自fixture._extra_bf16_k。它刻意不去读回生产缓存中的字节。原因是一旦参考实现直接反量化生产缓存的 FP8 字节就会与quant_to_nope_fp8_rope_bf16_pack_triton/set_swa_key_buffer_radix耦合——如果 pack/write 环节存在静默 bug生产路径与参考路径会以完全相同的方式损坏测试将失去检测能力。参考实现的 vanilla BF16 K 与flash_mla实际读取的 FP8 反量化 K 之间存在 FP8 量化噪声这一差异由DSV4_ATOL DSV4_RTOL 5e-2容差吸收。C4/C128 参考如何获取注意力索引对于 C4/C128参考实现读取升级版DSV4AttnMetadata中每个 q token 的swa_page_indices/c4_sparse_page_indices/c128_page_indices从而得知 kernel 实际会 attend 到哪些条目。由于投机图 runner 会在init_forward_metadata*之前调用expected_outputfixture 会在每次调用时重建当前 batch 的元数据并在on_after_cuda_graph_warmup之后重新播种c4_sparse_page_indices确保参考观察到与后端 forward 完全一致的索引集合。这一重建-重播种节奏对应 dsv4_attention.py 中expected_dsv4_output_from_inputs与_pure_torch_dsv4_combined_reference的实现逻辑。attention-sink 修正的验证注意力沉没attention sink修正是通过追加一个虚拟 key 实现的该虚拟 key 带 per-head 分数attn_sink、value 为 0。默认attn_sink_value-1e30时这在数值上是 no-op而dsv4_swa_extend_nonzero_attn_sink用例以attn_sink_value0.0实际触发并验证该修正逻辑。换言之矩阵中nonzeroattn_sink变体专门用于证明 sink 修正不会破坏注意力数值。生产不支持的组合Production-UnsupportedREADME 花费大量篇幅澄清矩阵中的 — 与 production-unreachable 不是缺陷而是后端断言体系对生产约束的显式编码。这些约束逐一列在下方全部可以在后端源码中找到对应断言。1.compress_ratio ∈ {4, 128}DRAFT_EXTEND生产不可达DSV4 的 draft 模型deepseek_v4_nextn.py 中的DeepseekV4ModelNextN是单一 decoder 层且以compress_ratio_overrideCOMPRESS_RATIO_NEXTN_LAYER 0构建该常量定义在:37覆盖参数传入:97。该值经由MQALayer.__init__deepseek_v4.py 中compress_ratio_override参数的传递链强制 draft 层无论config.compress_ratios如何都只走 SWA-only。因此生产环境永远不会调用forward(compress_ratio4 或 128, forward_modeDRAFT_EXTEND)目标模型只在 DECODE / TARGET_VERIFY 路径使用 C4/C128此时通过need_compressTrue填充 C4/C128 元数据如果测试强行尝试该组合init_forward_metadata_draft_extenddeepseek_v4_backend.py 中 README 标注的:636-663硬编码need_compressFalsec4_sparse_page_indices/c128_flashmla_metadata会保持为None——forward(compress_ratio4)会触发extra_indices.shape[-1]相关错误forward(compress_ratio128)则会触发 flash_mla 的tile_scheduler_metadata断言。测试 runner 在调用点做了双重保险run_dsv4_draft_extend_attention_case与run_dsv4_eagle_draft_extend_cuda_graph_case都会断言case.compress_ratio 0把这种不可达状态在测试层面显式暴露出来。2. MTPtopk 1树式投机结构性不可能deepseek_v4_backend.pyREADME 标注的:369断言self.topk in [0, 1]HIP radix 变体deepseek_v4_backend_hip_radix.py 的:363同样如此。DSV4 的投机 draft-extend / target-verify永远是链式chaintopk1树式投机在结构上不可能。这正是矩阵中DE-V2 CG、EAGLE-draft tree runner、EAGLE-DE tree runner、FKVMTP runner列标 — 而非 deferred 的原因——这些 runner 本质依赖树式tree spec结构。3. 非 256 的 page_sizepage_size 256的硬断言存在于 deepseek_v4_backend.py:355、HIP radix 变体:349与 metadata.py:134。测试侧通过DSV4_PAGE_SIZE 256常量与全部用例的page_sizeDSV4_PAGE_SIZE保持一致。4. 非 512 的 head_dimdeepseek_v4_backend.pyREADME 标注的:345-347断言head_dim 512。DSV4 被硬编码为qk_nope448 qk_rope64的组合任何其他 head_dim 都无法通过。5. 未知的compress_ratioDSV4AttnMetadata.get_flashmla_metadata只接受Literal[0, 4, 128]超出范围会抛出ValueError(finvalid {compress_ratio})见 deepseek_v4_backend.py。这一Literal类型与运行时校验的双重约束是矩阵仅有三行的根本原因。6._GraphBucket之外的 forward 模式deepseek_v4_backend.pyREADME 标注的:320-328对不属于{decode_or_idle, target_verify, draft_extend(v1 or v2)}的 forward 模式抛出NotImplementedErrorinit_forward_metadata:713-714同理。这意味着PCG/BCG 的 split-op extend 在结构上不可达——即矩阵中 PCG extend / BCG extend 两列全部为 — 的原因。Compressor / C4Indexer有意排除在矩阵之外这是本 README 中一个容易被误读的边界值得单独展开Compressor与C4Indexer不是注意力后端的组成部分而是 DSV4 模型model拥有的nn.Module实例。从 deepseek_v4.py 的源码结构看self.compressor None/self.indexer None的初始化及后续按配置实例化的逻辑位于:942-963附近模型 forward 在注意力之前先调用self.indexer(...)再调用attn_backend.forward_core_compressor(x, ..., self.compressor)如:1138-1160所示。流入注意力后端的只有两类输出Compressor把字节写入extra_k_cache中由c4_out_loc/c128_out_loc指定的位置——而这些位置来自后端init_forward_metadata阶段的 Triton kernelREADME 标注的deepseek_v4_backend.py:182并非来自 Compressor 本身C4Indexer写入c4_sparse_page_indices字段由后端的forward_extend/forward_decode读取。因此后端与两者的契约可以概括为一句黑盒读写我给你一个写入位置你在那里写入了内容我读取你写的内容。当前 fixture 正是通过生产级 pack store 路径quant_to_nope_fp8_rope_bf16_pack_tritonset_extra_key_buffer见 dsv4_attention.py 中_populate_extra_kv_cache的实现供应已知正确的合成字节与索引并将未量化的 BF16 K 暂存在 fixture 上供参考使用从而精确验证这一契约。init_compression_metadataTriton kernel 本身被完整测试被跳过的只是 Compressor 与 C4Indexer 的nn.Module前向数学x → compressed_kv与x, q_lora → page_indices。Compressor / C4Indexer 的数学正确性属于组件级测试范畴。README 明确建议这类测试的天然归属是test/srt/下的组件单元测试针对这两个模块数学的纯 PyTorch 参考并指出这与 PLAN.md 中把 RoPE 排除在注意力后端矩阵之外的逻辑一致——预处理模块的输出是注意力后端的输入其自身正确性不属于后端矩阵的职责。测试中的两个专项契约类除矩阵覆盖外test_deepseek_v4.py 还包含两个专项测试类值得在阅读矩阵时一并了解TestDSV4BreakableCudaGraphMetadataContractCPU-only验证 BCGbreakable CUDA graph元数据重放契约。包括cuda_graph_backend_decode/cuda_graph_backend_prefill默认不选 breakable需要显式 CLI 标志才 opt-inDSV4Metadata的快照snapshot边界声明SharedReadEnds.PRE_REPLAY稀疏 prefill 快照仅在num_qo_tokens超过_LARGE_INDEXER_QUERY_THRESHOLD时构建 chunk cacherefresh_for_breakable_cuda_graph_replay_对 tensor 字段采用值拷贝、对索引/元数据字段采用引用赋值以在重放时保留捕获期的 tensor storage以及SparsePrefillWorkspace的复用与扩容语义复用不换地址、扩容换地址。TestDSV4SwaOutCacheLocResolution验证get_swa_out_cache_loc的缓存快路径 vs 存储时回退逻辑——仅当 per-forward 缓存值可证明是当前值时使用否则回退到翻译out_cache_loc同时覆盖 DP padding 导致out_cache_loc重绑、以及 IDLE 模式绝不复用陈旧缓存值否则会把哑 token 写进活 KV 造成损坏。下一步工作Next WorkREADME 明确列出的后续工作是在test/srt/下补上Compressor / C4Indexer 组件级正确性测试独立于本矩阵。该工作被标记为可选optional——因为注意力后端已经通过已知正确的合成输入验证了自身一侧的契约组件数学的验证属于独立赛道。如何在仓库中定位与本矩阵相关的代码关注点仓库相对路径能力矩阵文档test/registered/attention/unittests/dsv4/README.md矩阵测试主体test/registered/attention/unittests/dsv4/test_deepseek_v4.py测试工具链runner / 参考实现 / 缓存填充python/sglang/test/kits/attention_unittest/attention_methods/dsv4_attention.pyCUDA 注意力后端SWA_WINDOW、断言、元数据python/sglang/srt/layers/attention/deepseek_v4_backend.pyHIP radix 注意力后端变体python/sglang/srt/layers/attention/deepseek_v4_backend_hip_radix.pyDSV4 注意力元数据Literal 校验、PagedIndexerMetadatapython/sglang/srt/layers/attention/dsv4/metadata.pyDSV4 模型Compressor / C4Indexer 所有权python/sglang/srt/models/deepseek_v4.pyDSV4 draft 模型强制 SWA-only 的COMPRESS_RATIO_NEXTN_LAYERpython/sglang/srt/models/deepseek_v4_nextn.py打包 FP8/BF16 KV 缓存池python/sglang/srt/mem_cache/deepseek_v4_memory_pool.py运行本矩阵测试的前提是 CUDA 环境且安装了带flash_mla模块的sgl_kernel——测试类通过_FLASH_MLA_AVAILABLEimportlib.util.find_spec(sgl_kernel.flash_mla)与torch.cuda.is_available()双重守卫缺失任一条件都会自动跳过unittest.skipIf。测试在 CI 中注册于base-bstage4-GPU B200 与 1-GPU large 两类 runner 配置分别预计耗时 14s 与 13s可作为复现时估算资源占用的参考。【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考