Claude和Codex开放自定义计算内核

tl;dr

我们构建了一个 agent 技能，教会编码 agent 如何编写生产级 CUDA 内核。然后我们将 Claude 和 Codex 指向两个真实场景：一个 diffusers 管道和一个 transformers 模型。这些 agent 为两者都生成了可工作的内核，包括正确的 PyTorch 绑定和基准测试，全流程完整。

编写 CUDA 内核很困难。编写与 transformers 和 diffusers 正确集成的 CUDA 内核更困难。涉及特定架构的内存访问模式、向量化策略、warp shuffle 规约，以及十几个集成陷阱，甚至资深开发者也容易踩坑。这正是 agent 技能大展身手的领域——一类专业性强、风险高的问题。

我们为编码 agent 提供了所需的领域知识：要针对哪个 GPU 架构、如何组织内核构建项目、什么时候用共享内存还是寄存器、如何编写 PyTorch 绑定。agent 负责完成其余工作。如果你用过 LLM 训练技能或读过《We Got Claude to Teach Open Models》，这个模式会很熟悉：把领域专业知识封装成技能，指向一个问题，让 agent 工作。

为什么要为内核做技能？

Kernel Hub 解决了自定义硬件内核的分发问题。你可以通过一个 get_kernel 调用从 Hub 加载预编译内核，无需构建，无需命令行参数。但内核仍然需要有人来写。这个技能填补的就是这个空白。

CUDA 内核开发有着陡峭的学习曲线：

• 硬件特定优化指南涵盖每代 GPU。H100、A100 和 T4 有不同的计算能力、共享内存大小和带宽配置
• 库集成：diffusers 和 transformers 有不同的模块层级、归一化约定和集成模式。自定义内核需要注册到 PyTorch，这样 torch.compile 才能识别
• 分发：内核可能依赖 CUDA、PyTorch 和 Python 版本，形成庞大的环境矩阵

这些领域知识散落在文档标签页和 Stack Overflow 答案里。一个 agent 技能把它统一打包成按需加载的上下文。

首先，我们展示如何立即使用这个技能，然后深入讲基准测试内核的细节。

该技能随内核库一起发布。用一条命令把它安装到你的编码 agent 中：

# we need to install kernels from main for this
pip install git+https://github.com/huggingface/kernels.git#subdirectory=kernels
kernels skills add cuda-kernels --claude

这会把技能放进 .claude/skills/cuda-kernels/，Claude Code 和 Cursor 会自动识别。如果用其他 agent：

# Codex
kernels skills add cuda-kernels --codex

# OpenCode
kernels skills add cuda-kernels --opencode

# 自定义位置
kernels skills add cuda-kernels --dest ./my-agent/skills/

# 全局安装（所有项目都可用）
kernels skills add cuda-kernels --global

# 覆盖已有安装
kernels skills add cuda-kernels --claude --force

安装后，向 agent 提示：

Build a vectorized RMSNorm kernel for H100 targeting the Qwen3-8B model in transformers.

或者尝试更开放的方向：

Build an optimized attention kernel for H100 targeting the Qwen3-8B model in transformers. Benchmark it against the PyTorch baseline and validate improvements in end-to-end performance.

agent 可以读取技能，选择正确的架构参数，生成 CUDA 源代码，编写 PyTorch 绑定，设置 build.toml，并创建基准脚本。

如果你在开发技能未覆盖的复杂内核或架构特定优化，技能会提供基本的构建块和模式帮你入门。我们也欢迎对技能本身的贡献。

该技能包含约 550 个标记的结构化指导，加上参考脚本、GPU 优化指南、故障排查文档和完整工作示例。像 Codex 和 Claude 这样的 agent 编码工具可以读取这些并生成工作的内核项目。

• NVIDIA GPU 架构感知优化：针对 H100、A100 和 T4 的优化（计算能力、内存带宽、共享内存大小、块大小）
• diffusers 和 transformers 的集成模式，包括特定于各库的陷阱
• 向量化内存访问模式的内核模板，支持 BF16、FP16 和 FP32
• 基准工作流用于隔离内核微基准和端到端管道对比
• HuggingFace Kernel Hub 集成，通过 get_kernel 加载社区内核

.claude/skills/cuda-kernels/
├── SKILL.md                              # Main instructions (~550 tokens)
├── scripts/
│   ├── benchmark_example.py              # End-to-end benchmark template
│   ├── benchmark_rmsnorm.py              # Isolated kernel micro-benchmark
│   ├── ltx_kernel_injection_example.py   # Diffusers integration pattern
│   ├── transformers_injection_example.py # Transformers integration pattern
│   └── huggingface_kernels_example.py    # Kernel Hub integration
└── references/
    ├── diffusers-integration.md          # Diffusers guide with pitfalls
    ├── transformers-integration.md       # Transformers guide
    ├── huggingface-kernels-integration.md
    ├── h100-optimization-guide.md
    ├── a100-optimization-guide.md
    ├── t4-optimization-guide.md
    ├── kernel-templates.md
    └── troubleshooting.md

当 agent 加载这个时，它获得了从"给我写一个 RMSNorm 内核"到生成可构建、可基准的项目所需的全部信息。它会 grep 和 glob 技能来找到相关文件和目录。所以以易于搜索的方式组织技能很重要。

agent 被指示生成符合 references/kernel-templates.md 中模板的内核，并生成一个完整的内核项目：

examples/your_model/
├── kernel_src/
│   └── rmsnorm.cu              # Vectorized CUDA kernel
├── torch-ext/
│   ├── your_kernels/__init__.py
│   └── torch_binding.cpp       # PyTorch C++ bindings
├── benchmark_rmsnorm.py        # Micro-benchmark script
├── build.toml                  # kernel-builder config
├── setup.py                    # pip install -e .
└── pyproject.toml

我们在两个真实目标上测试了这个。

基准测试内核：Diffusers（H100 上的 LTX-Video）

agent 为 diffusers 的视频生成管道 LTX-Video 构建了 RMSNorm、RoPE 3D、GEGLU 和 AdaLN 内核。完整示例见 examples/ltx_video/。我们针对 H100 优化了 RMSNorm 内核。两个基准都在 H100 80GB HBM3 上以 BFloat16 精度运行。

想查看生成的内核，请访问这个示例。

隔离的 RMSNorm 基准

首先，我们对比隔离的 RMSNorm 内核性能与 PyTorch 基线。这是优化管道的主要加速来源。

平均加速：1.88x，带宽效率：H100 理论值的 34.7%（3,350 GB/s）

端到端视频生成（49 帧，30 步，H100 80GB）

接下来，我们对比优化内核的端到端视频生成性能与基线（无编译）和 torch.compile 基线。

RMSNorm 占 LTX-Video 总计算的约 5%。剩余时间花在注意力、线性投影和 VAE 解码。单个内核类型带来的 6% 端到端加速与这个配置文件一致。

基准测试内核：Transformers（H100 上的 Qwen3-8B）

agent 为 transformers 中的大语言模型 Qwen3-8B 构建了一个 RMSNorm 内核，该模型跨 32 层有 65 个 RMSNorm 模块。完整示例见 examples/qwen3_8b/。我们针对 H100 优化了 RMSNorm 内核。两个基准都在 H100 80GB HBM3 上以 BFloat16 精度运行。

想探索内核，请看这里。

隔离的 RMSNorm 基准

再一次，我们对比隔离的 RMSNorm 内核性能与 PyTorch 基线。

平均加速：1.94x，带宽效率：H100 理论值的 22.3%（3,350 GB/s）

加速随序列长度缩放：在 128 标记处为 1.58x，在 8192 标记处为 2.47x。对于长上下文推理，自定义内核大约将 RMSNorm 延迟减半。

将内核发布到 Hub

agent 给你一个工作的内核。Kernel Hub 让你分享它，这样任何人都可以无需编译即加载。这是从 agent 输出到已发布内核的完整路径。

1. 验证项目结构

agent 生成的项目已经遵循 kernel-builder 布局：

your_kernel/
├── build.toml               # Build configuration
├── kernel_src/
│   └── rmsnorm.cu           # CUDA kernel source
└── torch-ext/
    ├── torch_binding.cpp    # Registers Torch ops
    └── your_kernels/
        └── __init__.py      # Python API wrapping _ops

build.toml 告诉 kernel-builder 要构建什么。agent 为你生成它，包括针对目标 GPU 的正确 cuda-capabilities：

[general]
name = "your_kernels"
backends = ["cuda"]

[torch]
src = ["torch-ext/torch_binding.cpp"]

[kernel.rmsnorm]
backend = "cuda"
src = ["kernel_src/rmsnorm.cu"]
depends = ["torch"]
cuda-capabilities = ["9.0"]  # H100

2. 用 Nix 构建所有变体

Kernel Hub 内核必须支持所有最近的 PyTorch 和 CUDA 配置。kernel-builder Nix flake 自动处理这个。把示例 flake.nix 复制到项目中并运行：

nix flake update
nix run .#build-and-copy -L

这为每个需要的 PyTorch/CUDA 变体构建内核，并把结果放在 build/ 中。要加快构建，启用 HuggingFace Nix 缓存：

nix run nixpkgs#cachix -- use huggingface

3. 创建一个 Hub repo 并推送

在 Hub 上创建一个模型 repo 并上传构建的内核：

huggingface-cli repo create your-org/your-kernel --type model
huggingface-cli upload your-org/your-kernel ./build

4. 其他人一行加载

发布后，任何人都可以只用一行代码加载你的内核，无需编译：

from kernels import get_kernel

rmsnorm = get_kernel("your-org/your-kernel")

get_kernel 检测用户的 Python、PyTorch 和 CUDA 版本，并下载匹配的预编译二进制。无需构建，无需参数，通常几秒钟内就准备好。

技能和 Hub 互相补充。技能处理开发。Hub 处理分发。用技能构建内核，用基准脚本验证，发布到 Hub，它就成为每个人都能一行加载的东西。

我们构建了一个 agent 技能，教会编码 agent 如何编写生产级 CUDA 内核。然后我们将 Claude 和 Codex 指向两个真实场景：一个 diffusers 管道和一个 transformers 模型。这些 agent 为两者都生成了可工作的内核，包括正确的 PyTorch 绑定和基准测试，全流程完整。我们基准测试了内核，发现优化的内核可以在隔离和端到端性能中都提供加速。

参考资源

CUDA Kernels Skill in kernels

HuggingFace Kernel Hub Blog

We Got Claude to Fine-Tune an Open Source LLM

We Got Claude to Teach Open Models

HuggingFace Kernels Community

本文提及的模型 2

来自我们博客的更多文章

The Open Source Community is backing OpenEnv for Agentic RL

DeepSeek-V4: a million-token context that agents can actually use

常见问题

尝试安装时出现错误：

$ pip install git+https://github.com/huggingface/kernels.git
...
ERROR: git+https://github.com/huggingface/kernels.git does not appear to be a Python project: neither 'setup.py' nor 'pyproject.toml' found.

使用 pip install kernels 可以安装，但命令没有 skills 选项：

$ kernels skills add cuda-kernels --claude
usage: kernel [-h] {check,download,versions,upload,lock,generate-readme,benchmark} ...

kernels repo 有 kernels-builder 和 kernels 库。

这是为什么直接 pip install git+https://github.com/huggingface/kernels.git 无法工作的原因。

问题：隔离的 RMSNorm 基准部分中的基线（Pytorch baseline）是否使用了 torch.compile()？自定义内核理想情况下应该超过 torch.compiled 代码。

· 登录或注册以评论