Hugging Face 发布 @huggingface/kernels：207 个 WebGPU 内核用于本地 AI

在 HF Mirror 的 WebAI 团队，我们最大的目标之一就是让浏览器推理尽可能快速、尽可能易用。要实现这一目标需要多层的努力：模型需要适合浏览器的表示形式，运行时需要构建高效执行计划，而底层栈中的单个 GPU 操作需要充分利用各种不同的设备和浏览器实现。

今天，我们发布这项努力的第一层：@huggingface/kernels，一个用于从 HF Mirror Hub 加载并运行优化 WebGPU 内核的最小化库，同时还有初始的 207 个内核集合，位于 hf-mirror.com/webgpu-kernels。

该集合涵盖了多种机器学习架构和工作负载中使用的操作。更重要的是，每个内核都以完整、带版本的包形式发布：其接口、着色器模板、正确性用例、基准用例和使用说明都一起存放在 Hub 上。

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

TL;DR

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

为什么从内核开始？

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

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

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

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

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

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

在卡片背后，仓库包含了理解和评估该实现所需的产物：

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

这种结构将着色器转变为一个可复用的软件产物。无需阅读 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 和契约版本调用 getKernel，然后用带类型的输入数据和张量形状调用返回的函数。下面是一个小型偏置加法示例：

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] 的输出。加载器从清单契约和输入中推导出该输出形状和逻辑数据类型，然后自动分配 c。

对六个浮点数做加法，是刻意设计的最小演示。在这个规模下，GPU 往返的开销远大于计算本身。重点在于调用模式：对于真正能从优化 kernel 中获益的重型操作，比如矩阵乘法（ai.onnx.MatMul），调用模式完全不变。只有仓库 ID 和输入会改变。

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

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

这些内核有多快？

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

在这些比较中，我们的内核几何平均快 2.57 倍，中位数快 1.90 倍，其中 629 胜、176 负、4 平。以下是四个常见操作的详细对比：

有些单项胜出要大得多。一个特别困难的双线性 Einsum 用例（i,ij,j，大小为 4096）使用我们的内核运行耗时 0.136 ms，而 ORT WebGPU 为 1,396 ms：快了超过 10,000 倍。对 [256, 4096] 的逐行 CumSum 快了 301 倍，为 0.016 ms 对 4.784 ms。这些是个别特殊用例，而非你在各处都能预期的加速，但它们表明当通用实现遇到慢路径时，专用内核能带来多大帮助。

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

这些也是单个操作的结果，而非完整模型。确切性能会因 GPU 和浏览器而异，这就是为什么 Fleet 对于构建更全面的图景如此重要。

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

从单台设备到设备群

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

在获得同意的情况下，每次运行都会私下贡献证据，帮助我们识别设备特定的故障、比较变体并改进选择规则。目标很简单：利用广泛的真实世界覆盖，让内核对每个人都更快、更可靠。

为 WebAI 构建共享基础

最初的 207 个内核只是起点，而非最终状态。在 Hub 上独立发布内核，为我们提供了一个共同的地方来检查契约、比较实现、复现正确性检查并提升性能，而无需将每个着色器直接嵌入到每个运行时中。

该集合也是 Hub 更广泛内核生态系统的一部分：在 Kernels 页面上，WebGPU 内核与用于 CUDA、ROCm、Metal 及其他平台的内核并列展示，并且可以像 Hub 上的任何其他产物一样进行筛选、排序和探索。

这些部分相互强化：

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

这是我们浏览器推理栈下一步工作的底层基础。我们很期待将这些内核连接到更高层的模型工具，继续扩展操作覆盖范围，并让快速的本地推理在整个 WebAI 生态系统中更易于使用。

探索 WebGPU 内核合集，试用 @huggingface/kernels，并加入 Fleet，用你的设备贡献证据，帮助我们让这些内核对每个人都更好。