Hugging Face 发布 @huggingface/kernels：207 个 WebGPU kernel 与 Fleet 基准工具

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

今天，我们发布这一努力的第一层：@huggingface/kernels，一个用于从 Hugging Face Hub 加载并运行优化 WebGPU 内核的极简库，同时还在 huggingface.co/webgpu-kernels 上发布了首批 207 个内核。

该集合涵盖了广泛应用于各种机器学习架构和工作负载的操作。更重要的是，每个内核都以完整、带版本的包形式发布：其接口、着色器模板、正确性用例、基准用例和使用说明都一起存放在 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 的契约，而内核实现则在其背后演进。

这些内核有多快？

那么，优化后的内核究竟能带来多大差异？我们在 Apple M4 GPU 上使用 ONNX Runtime Web 1.30.0-dev.20260826-b1f76d586a，将我们的集合与 ORT WebGPU 进行了正面比较。我们从全部 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，从你的设备贡献证据，帮助我们为所有人改进内核。