Hugging Face 示範 Claude 和 Codex 如何編寫自訂 CUDA kernels
Custom Kernels for All from Codex and Claude
Hugging Face 製作 CUDA kernel 技能,Claude 和 Codex 依此為 diffusers 與 transformers 目標產生可運行的 kernel。
文章拆解如何把 GPU 架構知識、PyTorch 整合範式與基準測試流程封裝成技能,讓編碼智能體產出可構建、可測試的 CUDA kernel 專案。
簡而言之:我們建立了一項 Agent skill,教導 coding agent 如何編寫可用於正式環境的 CUDA kernel。接着,我們讓 Claude 和 Codex 分別處理兩個真實目標:一個 diffusers pipeline 和一個 transformers 模型。兩個目標的 agent 都端到端產生了可運作的 kernel,並提供正確的 PyTorch bindings 和基準測試。
編寫 CUDA kernel 並不容易;要讓 CUDA kernel 正確整合 transformers 和 diffusers,難度更高。這涉及按架構特性設計記憶體存取模式、向量化策略、warp shuffle 歸約,以及多種連經驗豐富的開發者也會踩中的整合陷阱。這正是 Agent skill 大派用場的專業而關鍵問題。
我們向 coding agent 提供所需的領域知識,例如應以哪種 GPU 架構為目標、如何組織 kernel-builder 專案、何時使用 shared memory 而非 registers,以及如何編寫 PyTorch bindings。其餘工作就由 agent 完成。如果你用過 LLM 訓練 skill,或讀過我們讓 Claude 教導開放模型一文,便會覺得這個模式很熟悉:把領域專長打包成 skill,讓 agent 著手解決問題,再由它執行工作。
為甚麼要有 kernel skill?
Kernel Hub 解決了自訂硬件 kernel 的分發問題。你只需呼叫一次 get_kernel,便可從 Hub 載入預先編譯的 kernel,不用自行建置或設定旗標。不過,仍然需要有人編寫 kernel;這項 skill 正好填補這個空缺。
CUDA kernel 開發涉及的範圍極廣:
- 每一代 GPU 都有專屬的硬件最佳化指南。H100、A100 和 T4 的計算能力、shared memory 大小及頻寬特性各有不同。
- 在程式庫方面,
diffusers和transformers的模組階層、正規化慣例及整合模式各不相同。自訂 kernel 必須在 PyTorch 註冊,torch.compile才能識別。 - 至於分發,kernel 可能依賴不同版本的 CUDA、Pytorch 和 Python,因而產生龐大的環境組合矩陣。
這些領域知識散落在文件分頁和 Stack Overflow 答案中,容易遺失。Agent skill 會把它們打包成按需要載入的上下文。
我們先示範如何立即使用這項 skill,然後再深入講解 kernel 基準測試的方法。
安裝 skill
這項 skill 隨 kernels 程式庫一併提供。只需一條指令,便可將它安裝至你的 coding 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
這會把 skill 放到 .claude/skills/cuda-kernels/,Claude Code 和 Cursor 便會自動載入。至於其他 agent:
# Codex
kernels skills add cuda-kernels --codex
# OpenCode
kernels skills add cuda-kernels --opencode
# Custom destination
kernels skills add cuda-kernels --dest ./my-agent/skills/
# Install globally (available across all projects)
kernels skills add cuda-kernels --global
# Overwrite an existing installation
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 會讀取 skill、選擇合適的架構參數、生成 CUDA 原始碼、編寫 PyTorch bindings、設定 build.toml,並建立基準測試指令碼。
如果你要開發更複雜的 kernel,或處理 skill 未涵蓋的架構專屬最佳化,skill 會提供基本構件及模式,助你起步。我們亦歡迎大家為skill 本身作出貢獻。
skill 內容
這項 skill 大約包含 550 tokens 的結構化指引,另附參考指令碼、GPU 最佳化指南、疑難排解文件及完整可運作範例。Codex、Claude 等 Agent coding 工具可讀取這些內容,並產生可運作的 kernel 專案。
內容涵蓋:
- NVIDIA GPU 架構感知最佳化,適用於 H100、A100 和 T4(計算能力、記憶體頻寬、shared memory 大小、區塊大小)
- 適用於
diffusers和transformers的整合模式,包括各程式庫特有的注意事項 - 採用向量化記憶體存取模式的 kernel 範本,支援 BF16、FP16 和 FP32
- 基準測試流程,涵蓋獨立 kernel 微基準測試及端到端 pipeline 比較
- 透過
get_kernel整合 HuggingFace Kernel Hub,以載入社羣 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 kernel」轉化成可建置、可作基準測試專案所需的一切。它會使用 grep 和 glob 搜尋 skill,找出相關檔案和目錄,因此 skill 的組織方式必須方便查找。
Agent 會按 references/kernel-templates.md 中的範本產生 kernel,並建立完整的 kernel 專案:
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
我們以兩個真實目標測試這項 skill。
Kernel 基準測試:Diffusers(H100 上的 LTX-Video)
Agent 為 LTX-Video 建立了 RMSNorm、RoPE 3D、GEGLU 及 AdaLN kernel;這是一個以 diffusers 建立的影片生成 pipeline。完整範例位於 examples/ltx_video/。我們針對 H100 最佳化 RMSNorm kernel。兩項基準測試均在 H100 80GB HBM3 上以 BFloat16 精度執行。
如要查看生成的 kernel,請參閲這個範例。
獨立 RMSNorm 基準測試
首先,我們將獨立 RMSNorm kernel 的效能與 PyTorch 基準比較。這項比較展示最佳化 pipeline 的主要加速效果。
表格
| 形狀 | 自訂(毫秒) | PyTorch(毫秒) | 加速比 |
|---|---|---|---|
| [1x1024x2048] | 0.039 | 0.064 | 1.64x |
| [2x1024x2048] | 0.040 | 0.073 | 1.82x |
| [4x1024x2048] | 0.052 | 0.093 | 1.78x |
| [1x4096x2048] | 0.052 | 0.093 | 1.79x |
| [2x4096x3072] | 0.102 | 0.209 | 2.04x |
| [1x8192x2048] | 0.083 | 0.150 | 1.81x |
| [4x4096x3072] | 0.173 | 0.393 | 2.26x |
平均加速比:1.88x,頻寬效率為 H100 理論值(3,350 GB/s)的 34.7%。
端到端影片生成(49 幀、30 步、H100 80GB)
接着,我們比較最佳化 kernel 的端到端影片生成效能,並以基準版本(未編譯)及 torch.compile 基準作比較。
表格
| 設定 | 時間(秒) | 每秒迭代次數 | 加速比 |
|---|---|---|---|
| 基準(未編譯) | 2.87 | 12.58 | 1.00x |
| 生成的最佳化 kernel | 2.70 | 13.52 | 1.06x |
| 基準 + torch.compile | 2.14 | 19.05 | 1.34x |
| 最佳化 + torch.compile | 2.01 | 18.45 | 1.43x |
RMSNorm 約佔 LTX-Video 總運算量的 5%。其餘時間用於 attention、linear projections 及 VAE 解碼。單一類型 kernel 帶來端到端 6% 加速,與這個比例相符。
Kernel 基準測試:Transformers(H100 上的 Qwen3-8B)
Agent 為 Qwen3-8B 建立了 RMSNorm kernel。這是以 transformers 建立的大型語言模型,共有 32 層、65 個 RMSNorm 模組。完整範例位於 examples/qwen3_8b/。我們針對 H100 最佳化 RMSNorm kernel。兩項基準測試均在 H100 80GB HBM3 上以 BFloat16 精度執行。
如想了解這個 kernel,請到此查看。
獨立 RMSNorm 基準測試
我們再次將獨立 RMSNorm kernel 的效能與 PyTorch 基準作比較。
平均加速比:1.94x,頻寬效率為 H100 理論值(3,350 GB/s)的 22.3%。
表格
| 形狀 | 自訂(毫秒) | PyTorch(毫秒) | 加速比 |
|---|---|---|---|
| [1x128x4096] | 0.040 | 0.062 | 1.58x |
| [1x512x4096] | 0.038 | 0.064 | 1.69x |
| [1x1024x4096] | 0.037 | 0.071 | 1.90x |
| [1x2048x4096] | 0.045 | 0.091 | 2.03x |
| [1x4096x4096] | 0.071 | 0.150 | 2.12x |
| [4x512x4096] | 0.056 | 0.093 | 1.67x |
| [8x256x4096] | 0.045 | 0.092 | 2.06x |
| [1x8192x4096] | 0.109 | 0.269 | 2.47x |
序列長度愈長,加速比愈高:128 tokens 時為 1.58x,8192 tokens 時為 2.47x。對長上下文推論而言,自訂 kernel 大約可令 RMSNorm 延遲減半。
將你的 kernel 發布到 Hub
Agent 會為你產生可運作的 kernel。透過 Kernel Hub 分享後,任何人都可免編譯載入。以下説明如何由 agent 的輸出一路發布 kernel。
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 kernel 必須支援所有近期 PyTorch 和 CUDA 組態。kernel-builder 的 Nix flake 會自動處理。把範例 flake.nix複製到你的專案,然後執行:
nix flake update
nix run .#build-and-copy -L
這會為每個所需的 PyTorch/CUDA 變體建置 kernel,並將結果放入 build/。如要加快建置,可啟用 HuggingFace Nix 快取:
nix run nixpkgs#cachix -- use huggingface
3. 建立 Hub 儲存庫並推送
在 Hub 建立模型儲存庫,並上載已建置的 kernel:
huggingface-cli repo create your-org/your-kernel --type model
huggingface-cli upload your-org/your-kernel ./build
4. 其他人只需一行便可載入
發布後,任何人都可使用你的 kernel,完全不用編譯:
from kernels import get_kernel
rmsnorm = get_kernel("your-org/your-kernel")
get_kernel 會偵測用戶的 Python、PyTorch 和 CUDA 版本,並下載相符的預先編譯二進位檔。不用建置、不用旗標,通常數秒內即可使用。
Skill 和 Hub 互相配合:skill 負責開發,Hub 負責分發。使用 skill 建置 kernel,以基準測試指令碼驗證,再發布到 Hub,其他人便可用一行指令載入。
總結
我們建立了一項 Agent skill,教導 coding agent 如何編寫可用於正式環境的 CUDA kernel。接着,我們讓 Claude 和 Codex 分別處理兩個真實目標:一個 diffusers pipeline 和一個 transformers 模型。兩個目標的 agent 都端到端產生了可運作的 kernel,並提供正確的 PyTorch bindings 和基準測試。我們測試了這些 kernel,發現最佳化版本在獨立測試和端到端效能上都能帶來加速。
資源
來源:Hugging Face Blog · huggingface.co



