跳到正文
Hugging Face Blog·· 2026-02-13精選AI 評分70

Hugging Face 示範 Claude 和 Codex 如何編寫自訂 CUDA kernels

Custom Kernels for All from Codex and Claude

AI 導讀

Hugging Face 製作 CUDA kernel 技能,Claude 和 Codex 依此為 diffusers 與 transformers 目標產生可運行的 kernel。

推薦理由

文章拆解如何把 GPU 架構知識、PyTorch 整合範式與基準測試流程封裝成技能,讓編碼智能體產出可構建、可測試的 CUDA kernel 專案。

正文 · 繁體中文

oprah custom cuda kernels

簡而言之:我們建立了一項 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 的主要加速效果。

isolated rmsnorm benchmark ltx-video

表格

形狀 自訂(毫秒) 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 基準作比較。

e2e benchmark ltx-video

表格

設定 時間(秒) 每秒迭代次數 加速比
基準(未編譯) 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 基準作比較。

isolated rmsnorm benchmark qwen3-8b

平均加速比: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