# https://github.com/huggingface/kernels 项目说明书

生成时间：2026-06-17 13:26:34 UTC

## 目录

- [项目概览与整体架构](#page-overview)
- [kernels Python 包：加载、内核层与 CLI](#page-runtime)
- [kernel-builder CLI 与 Nix 可复现构建](#page-builder)
- [内核编写规范、示例与社区生态](#page-authoring)

<a id='page-overview'></a>

## 项目概览与整体架构

### 相关页面

相关主题：[kernels Python 包：加载、内核层与 CLI](#page-runtime), [kernel-builder CLI 与 Nix 可复现构建](#page-builder), [内核编写规范、示例与社区生态](#page-authoring)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [nix-builder/README.md](https://github.com/huggingface/kernels/blob/main/nix-builder/README.md)
- [kernels-data/src/lib.rs](https://github.com/huggingface/kernels/blob/main/kernels-data/src/lib.rs)
- [kernels-data/bindings/python/src/lib.rs](https://github.com/huggingface/kernels/blob/main/kernels-data/bindings/python/src/lib.rs)
- [kernels-data/src/config/v1.rs](https://github.com/huggingface/kernels/blob/main/kernels-data/src/config/v1.rs)
- [kernels-data/src/config/deps.rs](https://github.com/huggingface/kernels/blob/main/kernels-data/src/config/deps.rs)
- [kernel-builder/src/pyproject/torch/mod.rs](https://github.com/huggingface/kernels/blob/main/kernel-builder/src/pyproject/torch/mod.rs)
- [kernel-builder/src/pyproject/tvm_ffi/mod.rs](https://github.com/huggingface/kernels/blob/main/kernel-builder/src/pyproject/tvm_ffi/mod.rs)
- [kernel-builder/src/upload.rs](https://github.com/huggingface/kernels/blob/main/kernel-builder/src/upload.rs)
- [kernel-builder/src/init.rs](https://github.com/huggingface/kernels/blob/main/kernel-builder/src/init.rs)
- [kernel-builder/src/nix.rs](https://github.com/huggingface/kernels/blob/main/kernel-builder/src/nix.rs)
- [kernel-builder/src/init/templates/CARD.md](https://github.com/huggingface/kernels/blob/main/kernel-builder/src/init/templates/CARD.md)
- [kernels/src/kernels/utils.py](https://github.com/huggingface/kernels/blob/main/kernels/src/kernels/utils.py)
- [kernels/src/kernels/lockfile.py](https://github.com/huggingface/kernels/blob/main/kernels/src/kernels/lockfile.py)
- [kernels/src/kernels/layer/func.py](https://github.com/huggingface/kernels/blob/main/kernels/src/kernels/layer/func.py)
- [kernel-builder/skills/xpu-kernels/README.md](https://github.com/huggingface/kernels/blob/main/kernel-builder/skills/xpu-kernels/README.md)
</details>

# 项目概览与整体架构

## 1. 项目定位与目标

`huggingface/kernels` 是一个面向**机器学习算子内核（kernel）**的统一分发、构建与加载框架，服务于两类核心用户：

- **使用者**：通过 Python 包 `kernels` 从 Hugging Face Hub 拉取预编译内核，按版本/分支锁定后集成到 PyTorch 模型中。
- **构建者/发布者**：通过 `kernel-builder` CLI 将 C++/CUDA/ROCm/Metal/XPU/Neuron 等源码构建为可在 Hub 分发的预编译产物。

项目通过三条核心保证机制解决「同一份内核到处编译」的传统痛点（资料来源：[nix-builder/README.md](https://github.com/huggingface/kernels/blob/main/nix-builder/README.md)）：

- **可移植（Portable）**：内核可从 `PYTHONPATH` 之外的路径加载。
- **唯一性（Unique）**：同一进程中可加载同一内核的多个版本。
- **兼容性（Compatible）**：支持主流 Python 版本与不同 PyTorch 构建（CUDA 变体、C++ ABI 等）。

自 v0.14.0 起，Hub 引入独立的 `kernel` 仓库类型，并提供按后端（CUDA/XPU/Metal 等）筛选的概览页 [huggingface.co/kernels](https://huggingface.co/kernels)；v0.15.1 进一步强制要求加载时显式指定 `version`（社区 release notes v0.15.1）。

## 2. 仓库结构与模块划分

仓库由四个相互独立又彼此协作的子项目组成：

| 模块 | 语言/路径 | 角色 |
|------|----------|------|
| `kernels`（Python 客户端） | `kernels/src/kernels/` | 运行时：Hub 通信、版本解析、动态加载、模块注册 |
| `kernel-builder`（CLI） | Rust，`kernel-builder/src/` | 构建/上传：生成 `setup.py`、`pyproject.toml`、CMake 与元数据 |
| `kernels-data`（共享核心） | Rust，`kernels-data/src/` | 配置（`config`）、元数据（`metadata`）、版本（`version`）、摘要（`digest`）的单一事实源 |
| `kernels-data` Python 绑定 | `kernels-data/bindings/python/src/lib.rs` | 通过 PyO3 暴露 `Backend` 枚举等给 Python |
| `nix-builder` | `nix-builder/` | 基于 Nix 的可复现沙箱构建环境 |

`kernels-data` 是 Rust 核心库，被构建端（`kernel-builder`）与运行端（Python 绑定）共用，避免配置解析逻辑重复（资料来源：[kernels-data/src/lib.rs](https://github.com/huggingface/kernels/blob/main/kernels-data/src/lib.rs)）。

## 3. 核心架构：构建与加载流水线

整个系统沿「**源码 → build.toml → 多后端变体 → Hub 仓库 → 运行时加载**」链路运行：

```mermaid
flowchart LR
    A[Kernel 源码] --> B[kernel-builder init]
    B --> C[build.toml + Jinja 模板]
    C --> D[Nix / 本地构建]
    D --> E[多后端变体<br/>torch-cuda, torch-rocm, ...]
    E --> F[kernel-builder upload]
    F --> G[Hub kernel 仓库<br/>独立 repo type]
    G --> H[kernels.get_kernel]
    H --> I[lockfile 锁定]
    I --> J[动态加载 .so / .dylib]
    J --> K[PyTorch nn.Module / 函数]
```

关键节点说明：

- **配置层**：`build.toml` 通过 `general.backends` 声明后端集合；构建器据此为每个后端渲染独立的 `setup.py` 与 CMake 工程（资料来源：[kernel-builder/src/pyproject/torch/mod.rs](https://github.com/huggingface/kernels/blob/main/kernel-builder/src/pyproject/torch/mod.rs)）。
- **依赖图**：后端相关的 C++/Nix/Python 依赖由 `kernels-data::config::deps` 统一描述，未知后端会返回 `Backend` 错误（资料来源：[kernels-data/src/config/deps.rs](https://github.com/huggingface/kernels/blob/main/kernels-data/src/config/deps.rs)）。
- **沙箱构建**：`SandboxMode` 支持 `Enabled`/`Relaxed`/`Disabled` 三态，便于在 CI 与本地灵活切换（资料来源：[kernel-builder/src/nix.rs](https://github.com/huggingface/kernels/blob/main/kernel-builder/src/nix.rs)）。
- **上传层**：`run_upload` 优先使用 CLI 参数的 `--repo-id`/`--branch`，否则回退到 `build.toml` 中 `general.hub`；`repo_type` 支持 `Model` 与 `Kernel`（资料来源：[kernel-builder/src/upload.rs](https://github.com/huggingface/kernels/blob/main/kernel-builder/src/upload.rs)）。上传后由模板自动生成仓库 `CARD.md`（资料来源：[kernel-builder/src/init/templates/CARD.md](https://github.com/huggingface/kernels/blob/main/kernel-builder/src/init/templates/CARD.md)）。
- **加载层**：运行时调用 `get_kernel` 将 `version` 解析为 commit SHA，并以 lockfile 形式锁定所有变体文件，跳过 `.pyc` 与 `__pycache__`（资料来源：[kernels/src/kernels/lockfile.py](https://github.com/huggingface/kernels/blob/main/kernels/src/kernels/lockfile.py)）；已加载内核由 `_loaded_kernels` 注册表缓存（资料来源：[kernels/src/kernels/utils.py](https://github.com/huggingface/kernels/blob/main/kernels/src/kernels/utils.py)）。
- **函数式映射**：`FuncRepository` 通过 `func_name` 字段从已加载的内核模块中取出一个函数并包装为 `nn.Module`，`revision` 与 `version` 必选其一（资料来源：[kernels/src/kernels/layer/func.py](https://github.com/huggingface/kernels/blob/main/kernels/src/kernels/layer/func.py)）。
- **旧版配置兼容**：`build.toml` v1 通过 `kernels-data::config::v1` 归一化到统一结构（资料来源：[kernels-data/src/config/v1.rs](https://github.com/huggingface/kernels/blob/main/kernels-data/src/config/v1.rs)）。

## 4. 支持的后端、框架与社区关注点

`kernels-data` 通过 `Backend` 枚举（经 PyO3 暴露为 `PyBackend`）列出官方硬件目标：`CANN`、`CPU`、`CUDA`、`Metal`、`Neuron`、`ROCm`、`XPU`（资料来源：[kernels-data/bindings/python/src/lib.rs](https://github.com/huggingface/kernels/blob/main/kernels-data/bindings/python/src/lib.rs)）。

在框架层面，构建器目前输出两大适配路径：

- **Torch**（核心）：生成标准 `setup.py`，并支持无 GPU 依赖的 `noarch` 变体（资料来源：[kernel-builder/src/pyproject/torch/mod.rs](https://github.com/huggingface/kernels/blob/main/kernel-builder/src/pyproject/torch/mod.rs)）。
- **TVM FFI**（技术预览）：通过独立模板生成 `setup.py`，与 Torch 并列（资料来源：[kernel-builder/src/pyproject/tvm_ffi/mod.rs](https://github.com/huggingface/kernels/blob/main/kernel-builder/src/pyproject/tvm_ffi/mod.rs)）。
- **XPU 优化技能**：仓库内置 `kernel-builder/skills/xpu-kernels/`，改编自 Xe-Forge，将 LLM 驱动的 Triton 优化工作流集成到 hf-kernels 技能格式中（资料来源：[kernel-builder/skills/xpu-kernels/README.md](https://github.com/huggingface/kernels/blob/main/kernel-builder/skills/xpu-kernels/README.md)）。

社区中几个被广泛关注的演进方向也已反映在架构中：

- **可复现性**（#648）：构建元数据需携带 `kernel-builder` 的 git commit SHA 与 `dirty` 标记，以便识别未提交版本。
- **发布治理**（#651）：非 trusted publisher 的发布请求需要引导至 `kernels-community` 讨论区而非直接创建 PR。
- **生态扩展**（#317）：与 FlagOS 等自动生成 Triton 内核的项目存在协作可能。

## See Also

- 安装与快速开始：[`/docs/source/installation.md`](/docs/source/installation.md)
- `kernel-builder` CLI 与 `build.toml` 规范：[`/kernel-builder/README.md`](/kernel-builder/README.md)
- Nix 沙箱与二进制缓存：[`/nix-builder/README.md`](/nix-builder/README.md)
- `FuncRepository` / `LayerRepository` 加载与映射：[`/kernels/src/kernels/layer/func.py`](/kernels/src/kernels/layer/func.py)

---

<a id='page-runtime'></a>

## kernels Python 包：加载、内核层与 CLI

### 相关页面

相关主题：[项目概览与整体架构](#page-overview), [kernel-builder CLI 与 Nix 可复现构建](#page-builder), [内核编写规范、示例与社区生态](#page-authoring)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [kernels/README.md](https://github.com/huggingface/kernels/blob/main/kernels/README.md)
- [kernels/src/kernels/utils.py](https://github.com/huggingface/kernels/blob/main/kernels/src/kernels/utils.py)
- [kernels/src/kernels/layer/func.py](https://github.com/huggingface/kernels/blob/main/kernels/src/kernels/layer/func.py)
- [kernels/src/kernels/lockfile.py](https://github.com/huggingface/kernels/blob/main/kernels/src/kernels/lockfile.py)
- [kernels/src/kernels/benchmark.py](https://github.com/huggingface/kernels/blob/main/kernels/src/kernels/benchmark.py)
- [kernels/src/kernels/cli/__init__.py](https://github.com/huggingface/kernels/blob/main/kernels/src/kernels/cli/__init__.py)
- [kernels-data/bindings/python/src/lib.rs](https://github.com/huggingface/kernels/blob/main/kernels-data/bindings/python/src/lib.rs)
- [kernel-builder/src/pyproject/torch/mod.rs](https://github.com/huggingface/kernels/blob/main/kernel-builder/src/pyproject/torch/mod.rs)
- [kernel-builder/src/upload.rs](https://github.com/huggingface/kernels/blob/main/kernel-builder/src/upload.rs)
- [kernel-builder/src/card.rs](https://github.com/huggingface/kernels/blob/main/kernel-builder/src/card.rs)
</details>

# kernels Python 包：加载、内核层与 CLI

## 一、概述与设计目标

`kernels` 是 Hugging Face Kernel Hub 的官方 Python 客户端，负责在运行时从 Hub 拉取、缓存并按需加载预编译的算子扩展。其核心定位在 [kernels/README.md](https://github.com/huggingface/kernels/blob/main/kernels/README.md) 中明确说明：Hub 内核与传统 Python 内核包的关键差异在于 **可移植（Portable）**、**可并存（Unique）** 与 **可兼容（Compatible）**。可移植指内核可从 `PYTHONPATH` 之外的路径加载；可并存指同一进程中可加载同一内核的多个版本；可兼容指需同时支持多 Python 版本与多种 PyTorch 构建（不同 CUDA 版本与 C++ ABI）。

围绕这三点设计目标，包内提供了三组主要能力：(1) 动态加载入口 `get_kernel` / `get_local_kernel`；(2) 抽象的 `Layer` / `Func` 内核层接口；(3) 命令行工具 `kernels`（含 `benchmark`、`lock`、`verify-signature` 等子命令）。包入口的导出在 [kernels/src/kernels/utils.py](https://github.com/huggingface/kernels/blob/main/kernels/src/kernels/utils.py) 的 `get_loaded_kernels` 中维护了一个进程级注册表 `_loaded_kernels: dict[Path, LoadedKernel]`，用于追踪已加载的变体，避免重复导入。

## 二、加载模型与 `get_kernel`

### 2.1 公开 API

在 [kernels/README.md](https://github.com/huggingface/kernels/blob/main/kernels/README.md) 给出的快速开始示例中，调用形式为：

```python
from kernels import get_kernel
activation = get_kernel("kernels-community/activation", version=1)
activation.gelu_fast(y, x)
```

自 v0.15.1 起，**显式指定版本**已成为强制要求（参见 [v0.15.1 release notes](https://github.com/huggingface/kernels/releases/tag/v0.15.1)）：不传 `version` 或 `revision` 的旧用法会被拒绝。该变更解决了「不同版本号映射到不同构建产物」时的歧义问题。

### 2.2 远端拉取与本地覆写

`get_kernel` 在内部借助 `huggingface_hub` 的 `hf_hub_download` 拉取构建产物，再通过 `torch.ops` 注册机制挂入当前进程。如果开发者希望跳过远端下载，可使用 `get_local_kernel` 直接从本地目录加载。`utils.py` 中的 `_get_local_kernel_overrides` 解析 `LOCAL_KERNELS` 环境变量（`name=path` 形式），让用户能在不修改代码的前提下临时替换特定内核：

```
LOCAL_KERNELS="activation=/home/me/activation:rmsnorm=/tmp/rms"
```

### 2.3 锁文件机制

为保证可复现性，引入锁文件（lockfile）机制，源代码见 [kernels/src/kernels/lockfile.py](https://github.com/huggingface/kernels/blob/main/kernels/src/kernels/lockfile.py)。它会调用 Hub API `repo_info(repo_type="kernel", ...)` 解析版本标签到具体 commit，并遍历 `build/torch*` 变体下的文件。对每个文件记录其 `blob_id`（普通文件）或 LFS 对象的 `sha256`，从而在锁文件中固化内容哈希。当上游 `metadata.json` 中 `version` 字段变更时，锁文件能立刻反映出「未匹配」的差异，避免静默升级。

## 三、内核层（Layer / Func）

`kernels.layer` 子包提供把任意 `torch.nn.Module` 或函数「内核化」的能力。

### 3.1 `LayerRepository` 与 `FuncRepository`

`LayerRepository` 引用 Hub 上的整模块（包含 `__init__.py` 中导出的若干 `nn.Module` 类），而 [kernels/src/kernels/layer/func.py](https://github.com/huggingface/kernels/blob/main/kernels/src/kernels/layer/func.py) 定义的 `FuncRepository` 与 `LocalFuncRepository` 则只引用一个具名函数，对应 [v0.15.2 release notes](https://github.com/huggingface/kernels/releases/tag/v0.15.2) 新增的 `can_torch_compile` / `can_backward` 能力，使函数级内核也能被 `torch.compile` 与自动微分识别。

两者的等值比较 (`__eq__` / `__hash__`) 显式覆盖了 `repo_id`、`revision`/`version`、`func_name` 与 `trust_remote_code`，确保 Python 容器（如 `set`）中能正确去重。

### 3.2 装饰器 `use_kernel_func_from_hub`

[func.py](https://github.com/huggingface/kernels/blob/main/kernels/src/kernels/layer/func.py) 末尾提供了 `use_kernel_func_from_hub(func_name)` 装饰器工厂：它将用户函数封装为一个 `nn.Module`，其 `forward` 调用指定的内核函数。该机制允许库作者无需修改调用方代码即可替换实现，为 [#317 FlagOS 集成讨论](https://github.com/huggingface/kernels/issues/317) 等「跨框架 Triton 内核」协作场景提供了轻量接入点。

### 3.3 元数据（Metadata）

构建产物根目录下的 `metadata.json` 由 `kernels-data` 解析，绑定到 Rust 结构体（参见 [kernels-data/bindings/python/src/lib.rs](https://github.com/huggingface/kernels/blob/main/kernels-data/bindings/python/src/lib.rs) 中的 `PyMetadata`）。`PyBackend` 枚举覆盖 `CANN / CPU / CUDA / Metal / Neuron / ROCm / XPU` 七种后端，PyO3 通过 `From<Backend>` 自动转换；该枚举驱动了 Hub 端按后端过滤的检索页（参见 [v0.14.0 release notes](https://github.com/huggingface/kernels/releases/tag/v0.14.0)）。

## 四、命令行工具（CLI）

[kernels/src/kernels/cli/__init__.py](https://github.com/huggingface/kernels/blob/main/kernels/src/kernels/cli/__init__.py) 使用 `argparse` 注册了多组子命令。下表为常用命令及其职责：

| 子命令 | 主要职责 | 关键参数 |
| --- | --- | --- |
| `kernels benchmark <repo_id>` | 自动加载内核并执行性能基准 | `--version`、`--iterations`、`--warmup`、`--visual` |
| `kernels lock <project_dir>` | 为项目目录中的内核引用生成 / 更新锁文件 | 项目目录路径 |
| `kernels verify-signature` | 通过 Hub API 校验发布者是否可信（v0.14.1 修复） | — |
| `kernels kernel-versions` | 列出 Hub 仓库上已发布的所有版本 | 仓库 ID |

基准类基于 [kernels/src/kernels/benchmark.py](https://github.com/huggingface/kernels/blob/main/kernels/src/kernels/benchmark.py) 中的 `Benchmark` 基类。子类声明 `seed`、`device`，并以 `setup` / `benchmark_*` / `verify_*` 三类方法组织一次测例；runner 负责调用、自动注入 `self.kernel`、`self.out`、计时并与参考张量对比。

## 五、与 `kernel-builder` 的协作

虽然加载路径完全发生在 `kernels` 包内，但配套的 [kernel-builder/src/upload.rs](https://github.com/huggingface/kernels/blob/main/kernel-builder/src/upload.rs) 与 [kernel-builder/src/card.rs](https://github.com/huggingface/kernels/blob/main/kernel-builder/src/card.rs) 负责生产可被加载的产物：`upload` 子命令把 `build/` 下的各后端变体推送到 Hub（按 `kernel` 仓库类型组织分支），`card` 模块则基于仓库内 `torch-ext/<module>/layers/__init__.py` 提取 `nn.Module` 类名并填充 `CARD.md` 模板，使 Hub 端展示一致的内核索引页。社区问题 [#648](https://github.com/huggingface/kernels/issues/648) 中提议的「标记 dirty build」能力，正是在该上传路径上加入 `git_commit_sha` + `dirty` 布尔，以便加载端能够识别。

## 六、常见使用与排错

| 场景 | 建议 |
| --- | --- |
| 不想下载 Hub 产物 | 使用 `get_local_kernel(Path('build'), name)`，或设置 `LOCAL_KERNELS=foo=/abs/path` |
| 想要可复现构建 | 提交锁文件，配合 `kernels lock` 重新生成 |
| 想跳过未版本化的调用 | v0.15.1+ 必须显式传 `version` 或 `revision` |
| 需要函数级注入 | 用 `use_kernel_func_from_hub('func_name')` 装饰目标函数 |

## See Also

- kernel-builder CLI 与上传流程
- Hub 端 `kernel` 仓库类型与卡片渲染
- `kernels-data` 配置层（`Build` / `General` / `Backend`）

---

<a id='page-builder'></a>

## kernel-builder CLI 与 Nix 可复现构建

### 相关页面

相关主题：[项目概览与整体架构](#page-overview), [kernels Python 包：加载、内核层与 CLI](#page-runtime), [内核编写规范、示例与社区生态](#page-authoring)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [kernel-builder/src/main.rs](https://github.com/huggingface/kernels/blob/main/kernel-builder/src/main.rs)
- [kernel-builder/src/upload.rs](https://github.com/huggingface/kernels/blob/main/kernel-builder/src/upload.rs)
- [kernel-builder/src/init.rs](https://github.com/huggingface/kernels/blob/main/kernel-builder/src/init.rs)
- [kernel-builder/src/pyproject/ops_identifier.rs](https://github.com/huggingface/kernels/blob/main/kernel-builder/src/pyproject/ops_identifier.rs)
- [kernel-builder/src/pyproject/torch/mod.rs](https://github.com/huggingface/kernels/blob/main/kernel-builder/src/pyproject/torch/mod.rs)
- [kernel-builder/src/pyproject/tvm_ffi/mod.rs](https://github.com/huggingface/kernels/blob/main/kernel-builder/src/pyproject/tvm_ffi/mod.rs)
- [kernel-builder/src/pyproject/deps.rs](https://github.com/huggingface/kernels/blob/main/kernel-builder/src/pyproject/deps.rs)
- [kernel-builder/src/pyproject/kernel.rs](https://github.com/huggingface/kernels/blob/main/kernel-builder/src/pyproject/kernel.rs)
- [kernel-builder/src/pyproject/templates/torch/noarch/setup.py](https://github.com/huggingface/kernels/blob/main/kernel-builder/src/pyproject/templates/torch/noarch/setup.py)
- [kernel-builder/src/init/templates/CARD.md](https://github.com/huggingface/kernels/blob/main/kernel-builder/src/init/templates/CARD.md)
- [nix-builder/README.md](https://github.com/huggingface/kernels/blob/main/nix-builder/README.md)
- [kernels-data/src/config/mod.rs](https://github.com/huggingface/kernels/blob/main/kernels-data/src/config/mod.rs)
- [kernels-data/src/config/v1.rs](https://github.com/huggingface/kernels/blob/main/kernels-data/src/config/v1.rs)
- [kernels/src/kernels/utils.py](https://github.com/huggingface/kernels/blob/main/kernels/src/kernels/utils.py)
</details>

# kernel-builder CLI 与 Nix 可复现构建

## 1. 概述与设计目标

`kernel-builder` 是 Hugging Face `kernels` 生态中负责"把本地 C++/CUDA/Metal/ROCm/XPU 源码转成可在 Hub 上分发、并被 Python 端 `kernels.get_kernel` 加载"的构建/打包/上传一体化 CLI。它由 v0.13.0 正式取代旧的 `build2cmake` 命名，定位是"开发、构建、上传"三合一工具链 资料来源：[nix-builder/README.md:1-18]()。

整个体系有三条互相耦合的设计目标：第一，**可移植 (Portable)**，构建产物能被加载到 `PYTHONPATH` 之外的任意路径；第二，**唯一性 (Unique)**，同一进程内允许同一内核的多个版本共存；第三，**兼容性 (Compatible)**，必须同时支持较新的多个 Python 解释器以及各种 CUDA 版本与 C++ ABI 组合的 PyTorch 资料来源：[nix-builder/README.md:5-9]()。`Build` 命令底层通过 `setup.py` 模板中的自定义 `build` 子类 `BuildKernel` 实现，按 `build.toml` 中声明的 `general.backends` 列表逐个 backend 进行构建 资料来源：[kernel-builder/src/pyproject/templates/torch/noarch/setup.py:11-79]()。

## 2. CLI 子命令体系

`kernel-builder` 的入口定义在 `main.rs`，其子命令由 `clap` 派生，按"开发 → 构建 → 校验 → 打包 → 上传"的工作流排列：

| 子命令 | 作用 | 关键参数 |
| --- | --- | --- |
| `Build` | 调用 `CreatePyproject` 之后再触发构建 | `--variants`, `--release` |
| `Develop` | 以可编辑模式安装到当前 Python 环境 | `--variant` |
| `Init` | 在指定 owner/repo 路径下生成脚手架 | `--backends` (默认 `all`), `--overwrite` |
| `CreatePyproject` | 仅生成 `pyproject.toml`/`setup.py`/CMake 等中间产物 | `--unique-id`, `--force` |
| `CheckConfig` / `CheckBuilds` / `CheckAbi` | 校验 build.toml、构建产物与 ABI 兼容性 | `KERNEL_DIR` |
| `Devshell` | 启动 Nix 开发 shell | `--variant`, 透传 `NixArgs` |
| `Upload` | 将 `build/<backend>` 推送到 Hub | `--repo-type {model,kernel}`, `--repo-id`, `--branch` |
| `FillCard` | 渲染 `CARD.md` 模板 | `KERNEL_DIR` |

资料来源：[kernel-builder/src/main.rs:1-110]()、`kernel-builder/src/init.rs:1-80]()`。

`Init` 子命令允许 `owner/repo` 形式的 `RepoInfo`，并通过 `BackendSelection` 枚举在 `all` 与具体后端之间切换 资料来源：[kernel-builder/src/init.rs:32-66]()。`Upload` 优先使用 CLI 显式传入的 `repo_id` / `branch`，否则回落到 `build.toml` 的 `[general.hub]` 段；若 `metadata.json` 存在则从中推断分支（`detect_branch_from_metadata`） 资料来源：[kernel-builder/src/upload.rs:1-43]()。

## 3. Nix 集成与可复现性

可复现性由 `nix-builder` 目录下的 Nix 包提供。官方推荐启用 `cachix use huggingface` 以复用 Hugging Face 的二进制缓存，单个 `build-and-copy` 任务可通过 `--max-jobs` / `--cores` 控制并发度 资料来源：[nix-builder/README.md:24-50]()。硬件支持分级如下（Tier 1 全部经过 CI 验证，Tier 2 仅运行时支持、CI 缺失，Tier 3 实验性）：

| 硬件 | 内核支持 | kernel-builder 支持 | CI 验证 |
| --- | --- | --- | --- |
| CUDA | ✓ | ✓ | ✓ |
| ROCm | ✓ | ✓ | ✗ |
| XPU | ✓ | ✓ | ✗ |
| Metal | ✓ | ✓ | ✗ |
| Huawei NPU | ✓ | ✗ | ✗ |
| Neuron | ✓（实验） | ✗ | ✗ |

资料来源：[nix-builder/README.md:53-63]()。

构建唯一性靠 `KernelIdentifier` 实现：当 `unique_id` 未在 `CreatePyproject --unique-id` 显式传入时，构造器尝试从 `target_dir` 所在仓库提取 Git 短哈希；若失败则退化为随机 ID 资料来源：[kernel-builder/src/pyproject/ops_identifier.rs:1-24]()。该 ID 会拼到模块名 `_${name}_${backend}_${unique_id}` 上，从而保证同一进程内不同 revision 不会冲突。社区 issue #648 进一步建议将 git SHA 与 `dirty` 标记写入构建元数据，以在用户拿到产物时明确告知是否来自未提交版本 资料来源：[community: issue #648]()。

## 4. 构建配置与多后端打包

构建描述统一位于 `build.toml`，由 `kernels-data` crate 解析。`Backend` 枚举当前共 7 个值（`cann`、`cpu`、`cuda`、`metal`、`neuron`、`rocm`、`xpu`），`Backend::all()` 常量是构建管线枚举的权威来源 资料来源：[kernels-data/src/config/mod.rs:1-60]()。`v1.rs` 负责把旧版 build.toml 升级为内部规范 IR，例如自动把 `language = "cuda-hipify"` 的条目复制为带 `_rocm` 后缀的 ROCm kernel 资料来源：[kernels-data/src/config/v1.rs:1-50]()。

中间产物由 `minijinja` 模板按后端分别渲染。Torch 后端模板（`pyproject/torch/mod.rs`）会输出 `build-variants.cmake`、`utils.cmake`、`kernel.cmake`、metal 用的 `compile-metal.cmake`、cuda 用的 `hipify.py` 等 资料来源：[kernel-builder/src/pyproject/torch/mod.rs:1-25]()；`pyproject/kernel.rs` 再按 `Kernel::Cpu/Cuda/Rocm/Metal/Xpu` 分发到不同渲染函数 资料来源：[kernel-builder/src/pyproject/kernel.rs:1-60]()。TVM FFI 后端则额外生成 `setup.py` 与 `pyproject.toml`，模板中会把 `data_extensions` 展开成 globs 列表，并注入 `kernel_name` / `kernel_unique_id` / `python_name` 三个变量 资料来源：[kernel-builder/src/pyproject/tvm_ffi/mod.rs:1-40]()。

`deps.rs` 集中处理 CUTLASS 等可选依赖（当前提供 `cutlass-2.10.0`、`cutlass-3.5.1`、`cutlass-3.6.0` 三个版本常量），由模板消费方按 `Kernel::Cuda { depends }` 引用 资料来源：[kernel-builder/src/pyproject/deps.rs:1-40]()。

构建完成后，元数据由 `LoadedKernel` 数据类承载，运行期可调用 `kernels.get_loaded_kernels()` 获取快照；`KERNELS_CACHE` 与 `LOCAL_KERNELS` 环境变量分别控制缓存目录与本地覆写映射 资料来源：[kernels/src/kernels/utils.py:1-90]()。`Init` 阶段同步生成的 `CARD.md` 模板会渲染函数列表、是否带 `Benchmark` 脚本、`upstream` / `source` 链接等字段 资料来源：[kernel-builder/src/init/templates/CARD.md:1-50]()。

## 5. 常见失败模式与最佳实践

- **`build.toml` 字段缺失**：`Upload` 找不到 `[general.hub].repo-id` 时直接报错"Use --repo-id to specify it"，应同时回填 `build.toml` 与命令行参数 资料来源：[kernel-builder/src/upload.rs:18-25]()。
- **唯一 ID 漂移**：本地未提交时 Git 哈希会变，导致下游 `import` 名称不稳定；建议在 CI 中固定 `CreatePyproject --unique-id`。
- **后端不可用**：Neuron 支持标注为"实验性"且需要预发布包，落地前需确认目标环境已安装 Neuron SDK 资料来源：[nix-builder/README.md:65-67]()。
- **PyTorch ABI 变更**：release candidate 期间 ABI 通常稳定，但若正式版 break，必须用最终版重新构建所有已发布内核 资料来源：[nix-builder/README.md:15-19]()。
- **发布权限缺失**：无内核发布权限时，社区当前流程是引导用户在 `kernels-community` 讨论区开贴 资料来源：[community: issue #651]()。

## See Also

- `kernels` Python 包加载机制与 `get_kernel` API
- `kernels-community` Hub 仓库结构与 `KERNEL` repo type
- `build.toml` v1 → 内部 IR 的迁移路径（`kernels-data/src/config/v1.rs`）

---

<a id='page-authoring'></a>

## 内核编写规范、示例与社区生态

### 相关页面

相关主题：[项目概览与整体架构](#page-overview), [kernels Python 包：加载、内核层与 CLI](#page-runtime), [kernel-builder CLI 与 Nix 可复现构建](#page-builder)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [kernels-data/src/config/mod.rs](https://github.com/huggingface/kernels/blob/main/kernels-data/src/config/mod.rs)
- [kernels-data/src/config/v1.rs](https://github.com/huggingface/kernels/blob/main/kernels-data/src/config/v1.rs)
- [kernels/src/kernels/utils.py](https://github.com/huggingface/kernels/blob/main/kernels/src/kernels/utils.py)
- [kernels/src/kernels/lockfile.py](https://github.com/huggingface/kernels/blob/main/kernels/src/kernels/lockfile.py)
- [kernel-builder/src/card.rs](https://github.com/huggingface/kernels/blob/main/kernel-builder/src/card.rs)
- [kernel-builder/src/init/templates/CARD.md](https://github.com/huggingface/kernels/blob/main/kernel-builder/src/init/templates/CARD.md)
- [kernel-builder/src/upload.rs](https://github.com/huggingface/kernels/blob/main/kernel-builder/src/upload.rs)
- [kernel-builder/src/pyproject/torch/mod.rs](https://github.com/huggingface/kernels/blob/main/kernel-builder/src/pyproject/torch/mod.rs)
- [kernel-builder/src/pyproject/common.rs](https://github.com/huggingface/kernels/blob/main/kernel-builder/src/pyproject/common.rs)
- [kernel-builder/src/nix.rs](https://github.com/huggingface/kernels/blob/main/kernel-builder/src/nix.rs)
- [kernel-builder/src/init.rs](https://github.com/huggingface/kernels/blob/main/kernel-builder/src/init.rs)
- [nix-builder/README.md](https://github.com/huggingface/kernels/blob/main/nix-builder/README.md)
- [kernel-builder/skills/xpu-kernels/README.md](https://github.com/huggingface/kernels/blob/main/kernel-builder/skills/xpu-kernels/README.md)
</details>

# 内核编写规范、示例与社区生态

## 1. 概述

`huggingface/kernels` 项目为社区提供了一套完整的"内核即仓库"(kernels-as-repos) 生态系统：开发者使用 `kernel-builder` CLI（基于 Rust）将 C++/CUDA/Metal/XPU/ROCm 源码打包成可分发的 wheel 变体，并上传到 Hugging Face Hub；用户侧则通过 `kernels` Python 包按版本号加载这些远程构建产物。整个工作流强调可复现、可追溯与多后端兼容。

`backend` 枚举明确定义了七种受支持的目标平台，包括 `CANN`、`CPU`、`CUDA`、`Metal`、`Neuron`、`ROCm`、`XPU`（[kernels-data/src/config/mod.rs:Backend](kernels-data/src/config/mod.rs)）。`kernel-builder` 与 `nix-builder` 协同工作，在沙盒化的 Nix 环境中产出针对每个 backend 的 wheel 变体，再以 `kernel` 仓库类型上传到 Hub，从而在 v0.14.0 之后支持 Hub 概览页 [https://huggingface.co/kernels](https://huggingface.co/kernels) 的过滤与浏览体验（参考 v0.14.0 release notes）。

## 2. 内核规范：`build.toml` 与元数据

`kernels-data` crate 负责描述一个内核的完整配置。`Build` 结构体由三部分组成：`general`（仓库级元数据）、`kernels`（按名字索引的具体 kernel 实现）、`framework`（`Torch` / `TorchNoarch` / `TvmFfi`）（[kernels-data/src/config/mod.rs:Build](kernels-data/src/config/mod.rs)）。

| 字段 | 含义 | 来源 |
| --- | --- | --- |
| `general.name` | 仓库在 Python 端的模块名 | [config/mod.rs:KernelName](kernels-data/src/config/mod.rs) |
| `general.backends` | 该构建目标支持的 backend 集合 | [config/mod.rs:General::backends](kernels-data/src/config/mod.rs) |
| `general.license` / `upstream` / `source` | License、上游仓库、源码包 URL | [config/mod.rs:General](kernels-data/src/config/mod.rs) |
| `general.hub.repo-id` | 上传至 Hub 的 `<owner>/<repo>` 标识 | [kernel-builder/src/upload.rs:get_repo_and_branch](kernel-builder/src/upload.rs) |
| `framework = TorchNoarch` | 表示无 Python 端 C++ 扩展的纯 Python 内核 | [pyproject/templates/torch/noarch/setup.py](kernel-builder/src/pyproject/templates/torch/noarch/setup.py) |

`v1.rs` 还保留了 v1 旧配置到 v4 的迁移路径，对 `CudaHipify` 的 kernel 会自动派生出 `<name>_rocm` 变体以避免命名冲突（[kernels-data/src/config/v1.rs:convert_kernels](kernels-data/src/config/v1.rs)）。

## 3. 编写流程：从源码到 Hub 仓库

下图展示了从本地源代码到 Hub 可加载内核的完整生命周期：

```mermaid
flowchart LR
    A[本地内核源码] --> B[编写 build.toml]
    B --> C[kernel-builder dev/构建]
    C --> D[Nix 沙盒编译]
    D --> E[生成 wheel 变体 + metadata.json]
    E --> F[生成 CARD.md]
    F --> G[kernel-builder upload]
    G --> H[HF Hub: kernel 仓库]
    H --> I[kernels.get_kernel 加载]
```

关键节点说明：

- **沙盒构建**：`kernel-builder` 调用 Nix flake 进行隔离编译，开发者可选择 `Enabled`（严格）、`Relaxed`（允许网络）或 `Disabled`（关闭）三种沙盒模式（[kernel-builder/src/nix.rs:SandboxMode](kernel-builder/src/nix.rs)）。`nix-builder/README.md` 推荐使用 `cachix use huggingface` 来复用 HF 的二进制缓存。
- **元数据生成**：`common.rs::write_metadata` 为每个 backend 写出一份 `metadata.json`，其中 `id` 形如 `<unique_id>--<backend>`，`python_depends` 列出该变体所需的 Python 依赖（[kernel-builder/src/pyproject/common.rs:write_metadata](kernel-builder/src/pyproject/common.rs)）。
- **CARD.md 渲染**：`card.rs` 通过 MiniJinja 模板引擎解析仓库根目录下的 `CARD.md`，自动注入 `repo_id`、`version`、`functions`、`layers`、`upstream`、`source` 等变量，并附带"如何使用"代码片段（[kernel-builder/src/card.rs:render_card](kernel-builder/src/card.rs)、[init/templates/CARD.md](kernel-builder/src/init/templates/CARD.md)）。
- **上传解析**：`upload.rs::get_repo_and_branch` 优先使用 CLI 参数，否则回退到 `build.toml` 中 `[general.hub].repo-id`；分支若未显式指定，则尝试从构建产物的元数据中推断（[kernel-builder/src/upload.rs:get_repo_and_branch](kernel-builder/src/upload.rs)）。
- **TVM FFI 框架**：`tvm_ffi/mod.rs` 为 `TvmFfi` 框架生成 `setup.py` 与 `pyproject.toml`，并支持 data 文件 glob 模式（[kernel-builder/src/pyproject/tvm_ffi/mod.rs:write_setup_py](kernel-builder/src/pyproject/tvm_ffi/mod.rs)）。

## 4. 用户侧加载与版本契约

`kernels` Python 端遵循严格的版本契约。v0.15.1 起，调用 `get_kernel` **必须**显式提供 `version` 参数，缺省的 `kernels.get_kernel("kernels-community/activation")` 不再合法，必须写成 `get_kernel("kernels-community/activation", version=1)`（参考 v0.15.1 release notes）。

`utils.py` 中的核心解析函数包括：

- `has_kernel`：探测当前环境是否存在匹配 backend 的变体（[kernels/src/kernels/utils.py:has_kernel](kernels/src/kernels/utils.py)）。
- `get_kernel_variants`：返回按兼容性排序的全部 `Decision`，方便高级用户做诊断（[utils.py:get_kernel_variants](kernels/src/kernels/utils.py)）。
- `get_loaded_kernels`：返回进程内已加载内核的快照，便于调试重复加载。
- `LOCAL_KERNELS` 环境变量：允许在不改 Hub 仓库的情况下注入本地路径覆盖（[utils.py:_get_local_kernel_overrides](kernels/src/kernels/utils.py)）。

为保证加载结果可复现，`lockfile.py` 会在解析版本标签后枚举仓库文件树，提取 `build/torch*` 下的变体文件并记录 LFS/Blob 哈希，作为后续完整性校验的来源（[kernels/src/kernels/lockfile.py:variant_files](kernels/src/kernels/lockfile.py)）。

## 5. 社区生态与运营流程

`kernels-community` 组织是官方认证的内核发布渠道，社区贡献流程的核心痛点已被多个 issue 跟踪：

- **发布权限引导**：当普通用户尝试上传一个 `kernel` 仓库但没有发布权限时，应引导其到 `kernels-community` 开 Discussion 讨论，而不是生成无意义的"kernel publishing request"（[issue #651](https://github.com/huggingface/kernels/issues/651)）。
- **构建可复现性**：应在构建元数据中追加 `kernel-builder` 的 git commit SHA 与 `dirty` 布尔位，以便在构建来自未提交修改时向用户发出明确信号（[issue #648](https://github.com/huggingface/kernels/issues/648)）。
- **安全审计报告**：计划把由 Claude 生成的安全分析报告推送到 `kernels-community` 各仓库页面，类似其他仓库的 security 扫描展示（[issue #657](https://github.com/huggingface/kernels/issues/657)）。
- **跨生态协作**：FlagOS 团队提议将其基于 Triton 的自动生成内核集成进 HF Kernels（[issue #317](https://github.com/huggingface/kernels/issues/317)），目前仍处于探索阶段。
- **文档结构**：[issue #621](https://github.com/huggingface/kernels/issues/621) 建议 CLI 参考、`docs/source/builder/writing-kernels.md` 与 `integrating-kernels.md` 的受众应进一步分离（"使用内核" vs "构建内核"）。

此外，仓库内 `kernel-builder/skills/` 目录提供了针对特定 backend 的"技能包"，例如 `xpu-kernels/README.md` 适配了 Intel 的 [Xe-Forge](https://github.com/IntelLabs/Xe-Forge) 框架，把 CLI、知识库与优化工作流整合进 hf-kernels 技能格式（[kernel-builder/skills/xpu-kernels/README.md](kernel-builder/skills/xpu-kernels/README.md)），这为贡献者撰写新 backend 模板提供了范例。Torch 2.11 支持与 TVM FFI 技术预览同样在 v0.13.0 中被引入（参考 v0.13.0 release notes）。

> 常用链接：`kernels` Python 包入口 [kernels/src/kernels/utils.py](kernels/src/kernels/utils.py)、`kernel-builder` CLI 主入口 [kernel-builder/src/init.rs](kernel-builder/src/init.rs)、Hub 内核总览 [https://huggingface.co/kernels](https://huggingface.co/kernels)、Discord [https://discord.gg/H6Tkmd88N3](https://discord.gg/H6Tkmd88N3)。

## See Also

- 使用内核：`docs/source/integrating-kernels.md` 与 `kernels/src/kernels/utils.py`
- 构建内核：`docs/source/builder/writing-kernels.md` 与 `kernel-builder/src/pyproject/torch/mod.rs`
- 安全与可复现性：`docs/source/builder/security.md` 与 issue #648
- 社区协作流程：issue #317、#651、#657
- 配置文件迁移：`docs/source/migration.md` 与 `kernels-data/src/config/v1.rs`

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：huggingface/kernels

摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Guide users without kernel publishing access to open a discussion on kernels-community。

## 1. 安装坑 · 来源证据：Guide users without kernel publishing access to open a discussion on kernels-community

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Guide users without kernel publishing access to open a discussion on kernels-community
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/huggingface/kernels/issues/651 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 安装坑 · 来源证据：Signal when a kernel build comes from an uncommitted (dirty) kernel-builder version

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Signal when a kernel build comes from an uncommitted (dirty) kernel-builder version
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/huggingface/kernels/issues/648 | 来源类型 github_issue 暴露的待验证使用条件。

## 3. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/huggingface/kernels | README/documentation is current enough for a first validation pass.

## 4. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/huggingface/kernels | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/huggingface/kernels | no_demo; severity=medium

## 6. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/huggingface/kernels | no_demo; severity=medium

## 7. 安全/权限坑 · 来源证据：Push security analysis reports on the Hub for kernels-community kernel repos

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Push security analysis reports on the Hub for kernels-community kernel repos
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/huggingface/kernels/issues/657 | 来源类型 github_issue 暴露的待验证使用条件。

## 8. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/huggingface/kernels | issue_or_pr_quality=unknown

## 9. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/huggingface/kernels | release_recency=unknown

<!-- canonical_name: huggingface/kernels; human_manual_source: deepwiki_human_wiki -->