Hugging Face 发布 @huggingface/kernels，提供 207 个 WebGPU 内核用于浏览器本地 AI 推理

我们在 Hugging Face 的 WebAI 团队最大的目标之一，就是让浏览器推理尽可能快速、尽可能易用。要实现这一目标需要多层努力：模型需要适合浏览器的表示形式，运行时需要构建高效的执行计划，而位于栈底层的各个 GPU 操作则需要充分利用众多不同的设备和浏览器实现。今天，我们发布这一努力的第一层成果：@huggingface/kernels一个用于从 Hugging Face Hub 加载并运行优化后的 WebGPU 内核的极简库，以及一批初始的207 个内核位于huggingface.co/webgpu-kernels.

该合集涵盖了广泛应用于各类机器学习架构与工作负载的算子。更重要的是，每个 kernel 都以完整、带版本号的软件包形式发布：其接口、shader 模板、正确性测试用例、基准测试用例以及使用说明都一并托管在 Hub 上。

我们还推出了 Fleet，这是一套在浏览器内运行的 GPU 基准测试与测试套件，可在你的硬件上运行并对内核进行评分。除了为你自己的机器给出结果之外，Fleet 还为社区提供了一种途径，让来自我们永远无法在传统测试实验室中覆盖的设备的性能与正确性证据得以贡献出来。在获得你同意的情况下，每一次运行都会添加私有证据，帮助我们发现问题（结果不正确、异常缓慢的情况等）、改进内核变体，并在真实世界的硬件上做出更好的优化决策。

简而言之

• 207 个 WebGPU 内核，以独立仓库的形式发布在 webgpu-kernels 组织下。采用 Apache-2.0 许可。
• 一个 JavaScript 加载器，@huggingface/kernels，可直接从 Hub 下载、准备并运行内核。
• 为每个内核提供明确的契约与可复现的证据，包括清单、正确性测试、基准测试用例以及 WGSL 着色器模板。
• Fleet，一个基于浏览器的基准测试工具，通过众包方式在真实世界的 GPU 上收集正确性与性能证据，帮助我们改进内核及其变体。

为什么从内核开始？

在浏览器中运行的模型最终会变成一系列 GPU 操作：矩阵乘法、归一化、卷积、注意力原语、量化操作、数据布局变换等等。WebGPU 通过可移植的 API 让这些操作在现代浏览器中可用，而 WGSL 则为执行这些操作的着色器提供了通用语言。

然而，可移植性并不自动意味着性能。两个着色器可以实现相同的操作并产生相同的输出，但在不同的加速器上表现却可能截然不同。工作组大小、内存访问模式、向量化、数据类型以及融合策略都会影响性能。最佳选择还可能随输入形状、设备、浏览器以及可用的 WebGPU 特性而变化。

这就是为什么内核构成了快速浏览器推理的基础层。更高层的运行时最多只能做到与其所调度的操作一样高效。通过让这些操作能够被单独发现、测试、基准测试和版本化，我们就可以独立地改进这一基础层，同时为上层的各层保持稳定的契约。

一个内核仓库，而不仅仅是一个着色器

该集合中的每个内核都有自己的仓库和内核卡片。卡片记录了操作的语义、输入、输出、属性、支持的数据类型、源文件，以及一个可直接运行的 @huggingface/kernels 示例。

例如，ai.onnx.Add 实现了带多向广播的逐元素加法。它是神经网络中最简单的操作之一，从残差连接到添加偏置，处处都在使用。它的卡片记录了两个输入、广播后的输出形状、支持的数据类型，以及针对不同形状和设备可用的变体。

ai.onnx.Add 仓库将其清单、正确性与基准测试用例，以及 WGSL 着色器模板打包在一起。

在模型卡背后，该仓库还包含理解和评估该实现所需的各类产物：

• manifest.json 是操作契约的权威来源。它定义了输入、输出、属性、类型约束以及形状推导规则。
• metadata.json 记录了 kernel 标识符、摘要和来源信息。
• test.json 包含正确性用例，因此可以对照预期行为来检查实现。
• bench.json 包含基准测试和调优用例，代表了用于评估该 kernel 的工作负载。
• *.wgsl.jinja 文件包含参数化的 WGSL 实现，用于为特定请求和设备生成 shader。

这一结构将 shader 转变为可复用的软件产物。无需阅读 WGSL 即可检查接口，正确性和性能用例随实现一同提供，已发布的版本可以被显式加载，而不必依赖未版本化的文件 URL。我们的 kernel 还可以作为参考实现，供构建自定义 WebGPU kernel 或将这些操作集成到自有运行时中的开发者使用。

从 Hub 加载 kernel

从 npm 安装该软件包：

npm install @huggingface/kernels@preview

运行这些 kernel 需要支持 WebGPU 的浏览器。WebGPU 的可用性取决于浏览器、操作系统、GPU 和驱动程序。你可以在 JavaScript 中用 "gpu" in navigator 检查它是否可用。

@huggingface/kernels 提供了 kernel 仓库与你的应用程序之间的桥梁。用 Hub 仓库 ID 和 contract 版本调用 getKernel，然后用带类型的输入数据和张量形状调用返回的函数。下面是一个简单的 bias-add 示例：

import { getKernel } from "@huggingface/kernels";

const add = await getKernel("webgpu-kernels/ai.onnx.Add", { version: 1 });

const { c } = await add({
  a: {
    data: new Float32Array([1, 2, 3, 4, 5, 6]),
    shape: [2, 3],
  },
  b: {
    data: new Float32Array([10, 20, 30]),
    shape: [3],
  },
});

第二个输入沿第一个维度广播，产生形状为 [2, 3] 的输出。加载器从 manifest contract 和输入推导出该输出形状和逻辑数据类型，然后自动分配 c。

对六个浮点数做加法，刻意选作尽可能最小的演示。在这个规模下，GPU 往返的开销远大于数学运算本身。重点在于调用模式：对于那些优化过的 kernel 真正能带来收益的重型运算，比如矩阵乘法（ai.onnx.MatMul），调用模式完全一样。只有仓库 ID 和输入会变。

即便这个最基础的操作，也说明了 kernel 为什么需要变体。等形状加法可以使用直接的向量化路径，而广播输入则需要不同的索引逻辑。已发布的 Add kernel 包含针对等形状、向量化广播、标量处理和通用广播的变体。运行时可以选择适合当前调用和设备的实现，而无需改变面向应用程序的 API。

version: 1 选项选择已发布 kernel contract 的版本 1。它独立于 ONNX opset、算子的 since_version 或模型修订版本。将这些概念分开，可以让应用程序依赖稳定的面向 JavaScript 的契约，而 kernel 实现则在其背后不断演进。

这些 kernel 有多快？

那么，优化后的 kernel 究竟能带来多大差异？我们在 Apple M4 GPU 上，使用 ONNX Runtime Web 1.30.0-dev.20260826-b1f76d586a，将我们的集合与 ORT WebGPU 进行了正面比较。我们从全部 207 个算子的 1,756 个测试用例开始，保留了双方产生匹配输出且计时可靠的 809 个用例。

在这些比较中，我们的 kernel 按几何平均快 2.57 倍，按中位数快 1.90 倍，其中 629 胜、176 负、4 平。以下是四个常见算子的详细情况：

有些单项提升要大得多。一个特别困难的双线性 Einsum 用例（i,ij,j，尺寸为 4096）用我们的 kernel 运行耗时 0.136 ms，而 ORT WebGPU 耗时 1,396 ms：快了 10,000 倍以上。对 [256, 4096] 做逐行 CumSum 快了 301 倍，为 0.016 ms 对 4.784 ms。这些是特殊案例，而不是你在各处都应当期望的加速幅度，但它们表明，当通用实现走入慢路径时，专用 kernel 能带来多大的帮助。

我们计时的是 GPU 本身完成的工作，不包括加载 kernel、创建会话、上传输入、编译 shader 以及读回输出等准备工作。非常短的工作负载自然更难测量，而小规模用例还可能受益于 GPU 缓存，因此这些数字最好被理解为一种有用的对比，而不是对每个应用的承诺。

这些也还只是单个操作的结果，而不是完整模型的结果。确切性能会因 GPU 和浏览器而异，这正是 Fleet 如此重要的原因——它有助于构建更全面的图景。

我们还在与 ONNX Runtime 团队合作，将这些改进上游化，以便让更广泛的 ONNX Runtime Web 生态受益。

从单台设备到设备集群

WebGPU 性能会因 GPU、浏览器和驱动而异，因此来自单台机器的结果只能说明部分情况。Fleet让任何人都能在浏览器中运行正确性和性能检查，并查看这些 kernel 在其硬件上的表现。

在获得同意的前提下，每次运行都会以私密方式贡献证据，帮助我们识别特定设备上的故障、比较不同变体，并改进选择规则。目标很简单：利用广泛的真实世界覆盖，让这些 kernel 对所有人都更快、更可靠。

为 WebAI 构建共享基础

最初的 207 个 kernel 只是起点，而非终点。将 kernel 独立发布在 Hub 上，为我们提供了一个共同的场所，用以检查契约、比较实现、复现正确性检查并提升性能，而无需把每个 shader 都直接嵌入到每一个运行时中。

该集合也是 Hub 更广泛 kernel 生态系统的一部分：在 Kernels 页面上，WebGPU kernel 与面向 CUDA、ROCm、Metal 及其他平台的 kernel 并列展示，可以像 Hub 上任何其他 artifact 一样进行筛选、排序和浏览。

Hub 的 Kernels 页面上按平台筛选出的全部 207 个 WebGPU kernel。

这些部分相互强化：

1. Kernel 仓库定义了透明、带版本的操作契约。
2. @huggingface/kernels 让这些操作可以直接从 JavaScript 轻松加载和运行。
3. Fleet 以众包方式收集真实世界证据，覆盖的设备范围远超传统基准测试实验室所能覆盖的范围。
4. 每一次贡献的运行结果都能揭示失败案例、指导调优、改进变体选择，并帮助验证未来的内核版本。

这是我们浏览器推理栈后续步骤的底层基础。我们很高兴能将这些内核接入更高层的模型工具链，继续扩大算子覆盖范围，并让快速本地推理在整个 WebAI 生态中更易于使用。

探索WebGPU 内核合集，试用@huggingface/kernels，并加入 Fleet，从你的设备贡献证据，帮助我们为所有人改进这些内核。