gpuemu

在静默错误的 GPU kernel 进入生产环境之前将其捕获。

文档 • 快速开始 • 问题所在 • 研究 • 社区

## 问题所在：每个 benchmark 都显示你的 kernel 是“正确”的 业界标准用于检验 GPU kernel 正确性的准则（oracle）只有一行： ``` torch.allclose(my_kernel(x), reference(x), atol=1e-5, rtol=1e-2) ``` 一个 shape。一个 dtype。一个 seed。目前所有主流的 LLM-kernel benchmark —— **KernelBench**、 **TritonBench**、**GEAK**、**KernelBand**、**STARK** —— 都在使用相同的 oracle。通过测试的 kernel 就会直接被部署到生产环境。 这种 oracle 对 LLM 生成的 CUDA/Triton 代码中经常出现的某些完整 bug 类型视而不见： | Bug 类型 | 示例 | 为什么 allclose 会漏掉它 | |---|---|---| | **尾部掩码泄漏 (Tail-mask leak)** | softmax 忘记掩码最后一个部分 tile | 只有当 `H` 不是 `BLOCK` 的倍数时才会触发 —— `H=256` 看起来没问题 | | **累加器缩放 (Accumulator scale)** | matmul 写成了 `acc =` 而不是 `acc +=` | 结果恰好在所选 shape 的 `rtol` 范围内匹配 | | **缺失归一化 (Missing normalisation)** | attention 缺少了 `1/√D` | 导致 softmax 的饱和方式不同；某一种 shape 看起来是正确的 | | **在线 softmax 重缩放 (Online-softmax rescale)** | flash-attention 在 max 更新后忘记了 `acc *= α` | 只有当 `N > BLOCK_N` 时才会出错 | 在针对五类 GPU（RTX 3060、A10、L40S、A100 SXM4、H100 NVL）测量的 26 个 op 语料库中，标准的单一 shape oracle 将这 10 个 LLM 风格的错误 kernel **全部（10/10）** 误认为正确。而使用带有 seed 的 oracle 测量相同的 26 个 op 语料库时，10 个错误全部被抓出，并且在 16 个正确的对照组（P1）中实现了 0 次误报。 ## 为什么这很重要：静默的正确性回归正在 LLM 规模下被发布 现在，每个主流的 LLM 训练和推理技术栈都会发布 LLM 生成的 CUDA/Triton kernel —— 诸如融合 attention、自定义 matmul 变体、归一化层 —— 而一旦某个静默出错的 kernel 被大规模运行，错误就会被放大。计算错误的 matmul 会将偏差传递到每一次前向传播中；损坏的 flash-attention 会在不崩溃的情况下悄无声息地降低长上下文的质量；未掩码的 reduction 会污染没人检查的指标。其代价就是 **GPU 算力被浪费在了静默损坏的任务上**，以及 **缓慢且难以追踪的质量回归**，这些问题能够在持续数月的 CI 绿灯构建中存活下来。 这并非假设。LLM-kernel 领域文献中的每一个 benchmark 都存在相同的 oracle 漏洞；它们认可的 kernel 就是最终被部署的 kernel。 ## gpuemu 的作用 gpuemu 用一种感知算子域 (operator-domain–aware) 的正确性验证机制取代了“单一 shape 上的 allclose”。 **验证步骤无需 GPU 即可运行**（它会与高精度的 CPU 参考实现进行对比）；只有可选的 artifact 生成步骤才需要 GPU。 | 功能 | 它的作用 | 你能获得的收益 | |---|---|---| | **fp64 参考 oracle** | 按 dtype 将 kernel 输出与高精度的 CPU 参考实现进行比对 | 真正的正确性信号 —— 而不是“它恰好在某一次随意尝试的 shape 上匹配了” | | **感知 Op-schema 的模糊测试** | 带有边界、常规和对抗性值分布的逐 op 生成器 | 覆盖了你的 kernel 实际会崩溃的部分 tile 和边缘情况 | | **按 op 校准的容差** | 为每个 op 和 dtype 适配的 p95-of-controls × 1.5 包络线 | 能够捕捉到真实的回归，而不会误报正常的浮点噪声 | | **静态 PTX/SASS lint** | 对比基线的寄存器压力、溢出和指令计数 | 在编译后的 artifact 上设置的性能回归门控 | | **可复现的 RNG** | 在 Rust 和 Python 中实现位级一致的 xorshift128+；精确的输入快照 | 每一次失败都可以通过其 seed 在任何机器上实现逐字节复现 | 上述的每一个默认设置都有实测研究作为支撑 —— 参见 **[研究与证据](#research--evidence)**。 ## 团队能获得什么 gpuemu 将“静默错误输出”这种无形的失败模式转化为带有可复现 seed 的 CI 红灯报警。它服务于三类人群 —— 每一页都以该工作流所能预防的、真实且已引用的回归案例作为开头： - **[前沿实验室 kernel 团队](https://docs.skelfresearch.com/gpuemu/who-uses-gpuemu/frontier-lab-kernel-team)** (Anthropic / OpenAI / DeepMind / Meta / xAI) —— 扩展到数百个 op 的合并前正确性门控，通过带有可复现 seed 的链接来阻止有问题的 PR。 - **[OSS 推理维护者](https://docs.skelfresearch.com/gpuemu/who-uses-gpuemu/oss-inference-maintainer)** (vLLM / SGLang / TensorRT-LLM / llama.cpp / MLC-LLM) —— 只需一行的 GitHub Action，即可在发布前捕捉到诸如 SGLang #21238 和 vLLM #26378 这样的数值回归。 - **[推理即服务供应商](https://docs.skelfresearch.com/gpuemu/who-uses-gpuemu/inference-vendor)** (Fireworks / Together / Anyscale / Modal / Replicate / Baseten / Modular) —— 客户可离线验证的签名版 Kernel 正确性报告，作为 SLA 的证据。 想要试用企业版（私有规则包、本地部署 daemon、签名报告）？请查看 [设计合作伙伴](https://docs.skelfresearch.com/gpuemu/why-gpuemu/design-partners)。 ## 快速开始 ### 安装 ``` # Rust daemon + CLI cargo install gpuemu # Python client pip install gpuemu # VS Code extension（可选） code --install-extension gpuemu.gpuemu ``` ### 验证 kernel ``` from gpuemu import Client client = Client() # 使用 op-schema-aware 输入和 fp64 reference oracle 进行 Fuzz。 results = client.fuzz_op_client_side( "flash_attention", run_op=lambda inputs: my_flash_attn(inputs["q"], inputs["k"], inputs["v"]), iterations=100, value_distribution="adversarial", # recommended default ) print(f"Passed: {results.passed}/{results.total}") ``` 失败时会报告 seed、dtype、shape 以及失败输入的 base64 快照。可以在任何机器上逐字节重新运行。 ## 对比工具 支持者最先被问到的问题是“这不就是 `torch.testing.assert_close` 吗？”或者“这不就是 KernelBench 做的事吗？”。简而言之： | 工具 | 它的优势 | gpuemu 填补的空白 | |---|---|---| | `torch.testing.assert_close` | 标准、简单、内置 | 单一 shape、单一 dtype、单一 seed；在我们的 5 类 GPU 的 26 个 op 语料库中，对 0/10 个 LLM 风格的 bug 做出了响应 | | KernelBench / TritonBench / GEAK / KernelBand / STARK | 针对 LLM 生成 kernel 的排行榜 | 内部使用的是相同的单一 shape oracle；不对用户透明 | | NVIDIA Compute Sanitizer | Memcheck / racecheck / synccheck | 仅限内存 bug —— 对静默的错误数值输出视而不见 | | Triton 内置测试 | 相同的 `assert_close` 逻辑 | 没有 op-schema 模糊测试，也没有 fp64 参考 | | HF Kernel Hub | 分发与 ABI 检查 | 明确假定上游存在正确性验证工具 —— 这正是 gpuemu 的位置 | | ncu / cuobjdump / ptxas | 静态 PTX/SASS 内省 | 没有 lint 策略，没有基线差异比对，没有回归门控 | | FreeFuzz / DocTer / NablaFuzz / FuzzGPT | API 级别的深度学习框架模糊测试器 | 位于 API 层，而不是 kernel 层；根据 ACL TOSEM 2025 的测量，只能捕获 6.5% 的真实世界 bug | 完整的演练、引文以及它所呈现的五个护城河信号，请参阅[对比替代方案页面](https://docs.skelfresearch.com/gpuemu/why-gpuemu/compared-to)。 ## 执行模式 gpuemu 支持三种方式来运行你的 kernel： ``` # Client-side（推荐）：你的代码运行 GPU op；gpuemu 进行验证。 results = client.fuzz_op_client_side("matmul", run_op=lambda i: torch.matmul(i["a"], i["b"]), iterations=100) # Daemon-orchestrated：获取用例，自行运行，提交输出。 for case in client.get_test_batch("my_op", count=50): out = my_gpu_op(case["inputs"]) client.submit_output("my_op", case["inputs"], out, case["seed"]) # Script-based：在 gpuemu.toml 中注册 reference + op 脚本；daemon 运行所有内容。 ``` ## VS Code 集成 验证失败会以红色波浪线显示，并提供代码操作 (code actions)： - **问题面板 (Problems panel)** —— 每次失败的 seed、dtype、shape - **代码操作 (Code actions)** —— “复现失败”或“最小化测试用例” - **测试资源管理器 (Test Explorer)** —— op 会显示在测试侧边栏中 - **保存时验证 (On-save validation)** —— 在保存参考脚本时自动触发 ## 架构 ``` ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ gpuemu CLI │ │ Python Client │ │ VS Code Ext │ │ (Rust) │ │ (gpuemu) │ │ (TypeScript) │ └────────┬─────────┘ └────────┬─────────┘ └────────┬─────────┘ │ │ │ └────────────────────────┼────────────────────────┘ │ IPC (NNG/Unix sockets) ▼ ┌─────────────────────────────┐ │ gpuemu-daemon │ │ ├── Validation engine │ │ ├── Op-schema fuzzer │ │ ├── Artifact analyzer │ │ └── Failure storage (sled) │ └─────────────────────────────┘ ``` ## 框架支持 | 框架 | 状态 | 安装 | |---|---|---| | PyTorch | 稳定版 | `pip install gpuemu[torch]` | | JAX | 稳定版 | `pip install gpuemu[jax]` | | TensorFlow | 稳定版 | `pip install gpuemu[tensorflow]` | | 原生 CUDA/Triton | 稳定版 | `pip install gpuemu` | ## gpuemu 不是什么 - **不是周期精确的 GPU 模拟器** —— 关注正确性，而非时间模拟。 - **不是真实硬件的替代品** —— 最终的 benchmark 仍需在目标 GPU 上进行。 - **不是训练框架** —— 是 kernel 级别的 oracle，而不是模型级别的。 ## 研究 & 证据 gpuemu 是一项研究计划的工程化产品。上面的默认设置并非手动调整的猜测 —— 每一项都基于实测研究，并且这四项研究都附带有包含可复现运行记录和 kernel 语料库的 LaTeX 手稿。 | # | 研究 | 核心发现 | |---|---|---| | **P1** | LLM 生成的 GPU kernel 中的正确性错觉 | 在 24 个 op 的单 GPU 语料库中，带 seed 的 oracle 捕获了 **9/9** 个 LLM 风格的 bug；而在扩展到 5 类 GPU（RTX 3060、A10、L40S、A100 SXM4、H100 NVL）的 26 个 op 跨 GPU 语料库中捕获了 **10/10** 个，且对照组 **0 次误报** | | **P2** | 感知算子的混合精度容差校准 | 相比固定的 `atol/rtol`，p95-of-controls × 1.5 包络线在不损失精度的前提下，将 kernel-bug 的召回率从 **65% 提升至 82%** | | **P3** | 针对张量程序的测试输入生成 | 七策略消融实验：对抗性采样以 **93% 的召回率** 胜出；“仅常规 shape”会漏掉 **100%** 的尾部掩码 bug | | **P4** | 静态 PTX 指标能追踪结构性回归但会漏掉语义回归 | 结构性 Δregs / Δinstrs 可预测跨 5 类 GPU 的 Δperf%；语义错误会编译成 **完全相同的 PTX**，因此需要依靠正确性 oracle | 完整手稿、run-id 记录以及可复现的语料库位于 [gpuemu 研究计划][paper-repo]。单页摘要请参阅 [证据](https://docs.skelfresearch.com/gpuemu/why-gpuemu/the-evidence)。 ## 文档 完整文档：**[docs.skelfresearch.com/gpuemu](https://docs.skelfresearch.com/gpuemu)** - [问题所在](https://docs.skelfresearch.com/gpuemu/why-gpuemu/the-problem) —— allclose 漏掉了什么 - [行业影响](https://docs.skelfresearch.com/gpuemu/why-gpuemu/the-industry-impact) —— 静默 bug 造成的代价 - [证据](https://docs.skelfresearch.com/gpuemu/why-gpuemu/the-evidence) —— 一页纸了解 P1–P4 - [快速开始](https://docs.skelfresearch.com/gpuemu/getting-started/quickstart) —— 5 分钟内完成首次验证 - [架构深度剖析](https://docs.skelfresearch.com/gpuemu/concepts/architecture) ## 平台支持 | 平台 | 状态 | |---|---| | Linux | 主要目标平台 | | macOS | 完全支持 (CPU 验证) | | Windows | 计划中 | ## 许可证 根据您的选择，采用 [MIT](LICENSE-MIT) 或 [Apache 2.0](LICENSE-APACHE) 双重许可。

_{由 Skelf Research 团队用心打造}

标签：GPU, Python, Rust, Vectored Exception Handling, 内核, 凭据扫描, 可视化界面, 无后门, 测试, 网络流量审计, 逆向工具, 通知系统