介绍@huggingface/kernels：用于本地AI的200+个WebGPU内核

来源：https://huggingface.co/blog/webgpu-kernels Hugging Face WebAI团队的核心目标之一是让浏览器推理尽可能快速且用户友好。实现这一目标需要多层次的努力：模型需要浏览器友好的表示形式，运行时需要构建高效的执行计划，而底层的单个GPU操作则需要充分利用众多不同的设备和浏览器实现。

今天，我们发布了这项工作的第一层成果：@huggingface/kernels（https://www.npmjs.com/package/@huggingface/kernels），这是一个用于加载和运行来自Hugging Face Hub优化WebGPU内核的极简库，同时发布了huggingface.co/webgpu-kernels（https://huggingface.co/webgpu-kernels）上的207个内核初始合集。

该合集涵盖了广泛机器学习架构和工作负载中使用的操作。更重要的是，每个内核都作为完整的、版本化的软件包发布：其接口、着色器模板、正确性测试用例、基准测试用例和使用说明都共同存放在Hub上。

我们还推出了Fleet（https://webgpu-kernels-fleet.hf.space/），一个在浏览器内运行的GPU基准测试和测试套件，可在您的硬件上对内核进行运行和评分。除了您自己机器的结果外，Fleet还为社区提供了一种贡献来自我们传统测试实验室无法覆盖的设备的性能和正确性证据的方式。在您同意的情况下，每次运行都会添加私有证据，帮助我们发现故障（错误的结果、异常缓慢的情况等）、改进内核变体，并在实际硬件中做出更好的优化决策。

https://huggingface.co/blog/webgpu-kernels#tldr摘要

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

https://huggingface.co/blog/webgpu-kernels#why-start-with-kernels为什么从内核开始？

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

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

这就是为什么内核构成了快速浏览器推理的基础层。高级运行时的效率只能等同于它们分发的操作。通过使这些操作单独可发现、可测试、可基准测试和可版本化，我们可以独立改进基础，同时为上层提供稳定的契约。

https://huggingface.co/blog/webgpu-kernels#a-kernel-repository-not-just-a-shader是内核代码库，而不仅仅是着色器

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

例如，ai.onnx.Add（https://huggingface.co/webgpu-kernels/ai.onnx.Add）实现了具有多方向广播的逐元素加法。这是神经网络中最简单的操作之一，从残差连接到添加偏置都无处不在。它的卡片记录了两个输入、广播后的输出形状、支持的数据类型以及适用于不同形状和设备的变体。

ai.onnx.Add WebGPU内核代码库中的文件ai.onnx.Add代码库将其清单、正确性和基准测试用例以及WGSL着色器模板打包在一起。卡片背后，代码库包含了理解和评估实现所需的制品：

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

这种结构将着色器转变为可重用的软件制品。接口无需阅读WGSL即可检查，正确性和性能用例与实现一起提供，发布的版本可以显式加载，而不是依赖于无版本的文件URL。我们的内核也可以作为构建自定义WebGPU内核或将这些操作集成到自己的运行时中的开发者的参考实现。

https://huggingface.co/blog/webgpu-kernels#loading-a-kernel-from-the-hub从Hub加载内核

从npm安装该包：

npm install @huggingface/kernels@preview

运行这些内核需要支持WebGPU（https://developer.mozilla.org/en-US/docs/Web/API/WebGPU_API）的浏览器。WebGPU的可用性取决于浏览器、操作系统、GPU和驱动程序。您可以在JavaScript中使用"gpu" in navigator来检查它。

@huggingface/kernels提供了内核代码库与您的应用程序之间的桥梁。使用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往返开销远大于数学运算本身。重点在于调用模式：它对于真正能体现优化内核价值的重量级操作（如矩阵乘法ai.onnx.MatMul）完全相同。只有代码库ID和输入会改变。

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

version: 1选项选择发布内核契约的第1版。它独立于ONNX opset、算子的since_version或模型修订版。保持这些概念的分离使应用程序可以依赖于稳定的JavaScript接口契约，而内核实现在其背后演进。

https://huggingface.co/blog/webgpu-kernels#how-fast-are-the-kernels内核速度如何？

那么，优化的内核到底能带来多大的差异呢？我们使用ONNX Runtime Web 1.30.0-dev.20260826-b1f76d586a，在Apple M4 GPU上将我们的合集与ORT WebGPU进行了正面对比。我们从所有207个操作的1756个测试用例开始，保留了双方产生匹配输出和可靠计时的809个用例。

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

操作 对比用例数 我们的WebGPU内核 ORT WebGPU 加速比 Add 50 0.064 ms 0.227 ms 3.52x MatMul 29 0.115 ms 0.131 ms 1.14x Softmax 12 0.114 ms 0.240 ms 2.11x LayerNormalization 6 0.061 ms 0.135 ms 2.22x

一些单独的胜出幅度要大得多。一个特别困难的双线性Einsum用例（i,ij,j，大小为4096）使用我们的内核运行时间为0.136 ms，而使用ORT WebGPU为1396 ms：快了超过10000倍。一个在[256, 4096]上的逐行CumSum快了301倍，时间为0.016 ms对比4.784 ms。这些是特例，而非您应该在所有地方都预期的加速比，但它们表明当通用实现遇到慢路径时，专用内核能带来多大的帮助。

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

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

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

https://huggingface.co/blog/webgpu-kernels#from-one-device-to-a-fleet从单个设备到一个集群

WebGPU性能因GPU、浏览器和驱动程序而异，因此来自一台机器的结果只能说明部分故事。Fleet（https://webgpu-kernels-fleet.hf.space/）让任何人都可以在浏览器中运行正确性和性能检查，并查看内核在他们的硬件上的表现。

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

https://huggingface.co/blog/webgpu-kernels#building-a-shared-foundation-for-webai为WebAI构建共享基础

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

该合集也是Hub更广泛内核生态系统的一部分：在Kernels页面（https://huggingface.co/kernels?platform=webgpu&sort=trending）上，WebGPU内核与CUDA、ROCm、Metal和其他平台的内核并列，并且可以像Hub上的任何其他制品一样被过滤、排序和探索。

Hub Kernels页面筛选到WebGPU平台，列出了207个已发布的内核 Hub Kernels页面（https://huggingface.co/kernels?platform=webgpu&sort=trending）上所有207个WebGPU内核，按平台筛选。 这些部分相互加强：

1. 内核代码库定义了透明、版本化的操作契约。
2. @huggingface/kernels使这些操作可以轻松地从JavaScript加载和运行。
3. Fleet通过众包方式收集比传统基准测试实验室能覆盖的更广泛设备的真实世界证据。
4. 每次贡献的运行都可以揭示故障、指导调优、改进变体选择并帮助验证未来的内核版本。

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

探索WebGPU内核合集（https://huggingface.co/webgpu-kernels），尝试@huggingface/kernels（https://www.npmjs.com/package/@huggingface/kernels），并加入Fleet（https://webgpu-kernels-fleet.hf.space/）以从您的设备贡献证据，帮助我们为每个人改进内核。