Introducing @huggingface/kernels: 200+ WebGPU Kernels for Local AI

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

返回文章列表

[-1

]

[0

2026年9月1日发布

GitHub 上的更新

点赞

31

[

• +25

Nico Martin

nico-martin

关注

Joshua

Xenova

在 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 的性能和正确性数据，帮助我们改进内核及其变体。

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

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

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

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

卡片背后，仓库包含用于理解和评估实现所需的各种制品：

• manifest.json 是操作契约的权威来源。它定义了输入、输出、属性、类型约束和形状推导规则。

• metadata.json 记录内核标识符、摘要和出处信息。

• test.json 包含正确性测试用例，使实现可以与预期行为进行验证。

• bench.json 包含用于评估内核的工作负载基准测试和调优用例。

• *.wgsl.jinja 文件包含参数化 WGSL 实现，用于为特定请求和设备生成着色器。

这种结构将着色器转化为可复用的软件制品。无需阅读 WGSL 即可检查接口，正确性和性能测试用例随实现一起传递，已发布的版本可以显式加载而不是依赖无版本的文件 URL。我们的内核还可以作为开发人员构建自定义 WebGPU 内核或将其集成到自己的运行时中的参考实现。

从 Hub 加载内核

从 npm 安装包：

npm install @huggingface/kernels@preview

运行这些内核需要支持 WebGPU 的浏览器。WebGPU 的可用性取决于浏览器、操作系统、GPU 和驱动程序。可以通过 JavaScript 中的 navigator.gpu 进行检查。

@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的前提下，根据当前调用和设备选择合适的实现方式。

版本：1选项会选择已发布内核协议的版本1。它与ONNX opset、操作符的since_version或模型版本是独立的。保持这些概念的独立性可以让应用依赖稳定的JavaScript接口协议，同时内核实现可以在其背后持续演进。

内核的性能表现如何？

那么，优化后的内核到底能带来多大的性能提升？我们将我们的内核集合与ORT WebGPU在苹果M4 GPU上进行对比测试，使用ONNX Runtime Web 1.30.0-dev.20260826-b1f76d586a版本。我们从所有207个操作符的1,756个测试用例中，筛选出双方输出匹配且计时可靠809个用例进行对比。

在这些对比测试中，我们的内核几何平均值快2.57倍，中位数快1.90倍，其中629个用例表现更优，176个用例表现较差，4个用例平局。以下是四个常见操作的详细对比：

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

某些特定用例的加速比更为显著。一个特别困难的双线性Einsum案例（i,ij,j尺寸为4096）使用我们的内核仅需0.136毫秒，而ORT WebGPU需要1,396毫秒：快了超过10,000倍。对[256, 4096]进行行级CumSum计算，我们的实现快了301倍，仅需0.016毫秒，而ORT WebGPU需要4.784毫秒。这些属于特殊用例而非普遍表现，但它们展示了当通用实现遇到性能瓶颈时，专用内核能带来的显著提升。

我们测量的是GPU上实际执行的工作时间，排除了加载内核、创建会话、上传输入、编译着色器和读取输出等开销。非常短的工作负载本身更难准确测量，小规模用例可能受益于GPU缓存，因此这些数据应作为有用的参考而非对所有应用的承诺。

这些结果仅针对单个操作符而非完整模型。实际性能会因GPU和浏览器的不同而变化，这也是Fleet对于构建更全面性能图景如此重要的原因。

我们也在与ONNX Runtime团队合作，将这些改进提交到上游，使更广泛的ONNX Runtime Web生态系统受益。

从单一设备到设备集群

WebGPU性能在不同GPU、浏览器和驱动程序之间存在差异，因此单一设备的测试结果只能反映部分情况。Fleet允许任何人通过浏览器运行正确性和性能检查，观察内核在他们硬件上的表现。

在获得用户同意的情况下，每次运行都会私密地贡献数据，帮助我们发现特定设备的故障、比较不同变体并优化选择规则。目标很简单：通过广泛的现实场景覆盖，让所有用户的内核都更快更可靠。

为WebAI构建共享基础

初始的 207 个内核只是一个起点，而非最终状态。将内核独立发布到 Hub 上，为我们提供了一个统一的平台，用于检查合约、比较实现、复现正确性验证，并在不将每个着色器直接嵌入每个运行时的情况下提升性能。

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

Hub 内核页面上所有 207 个 WebGPU 内核，按平台筛选后的结果。

这些组件相互强化：

• 内核仓库定义了透明且版本化的操作合约。
• @huggingface/kernels 让 JavaScript 能够轻松加载和运行这些操作。
• Fleet 通过覆盖比传统基准测试实验室更广泛的设备范围，收集真实世界的实证数据。
• 每次贡献的运行结果都可能揭示问题、指导调优、改进变体选择，并帮助验证未来的内核版本。

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

探索 WebGPU 内核集合，尝试 @huggingface/kernels，并加入 Fleet 从您的设备贡献实证数据，帮助我们让内核变得更好。

更多来自我们博客的文章

公告

多模态

转换器

欢迎使用 Thinking Machines 的 Inkling

• +1

165

2026 年 7 月 15 日

跨域存储

余弦

在 Transformers.js 中尝试新的跨域存储 API

8

2026 年 6 月 23 日

社区

mabaoguo00

1 天前

[2

1

回复

codelion

约 6 小时前

Fleet 部分可能与内核本身一样重要。M4 上的 809 个可比较案例很有用，但浏览器、驱动和设备的差异性往往是 WebGPU 的痛点。Fleet 最终会暴露每台设备的分布情况吗，还是计划仅将运行结果用于聚合选择规则？

查看翻译

编辑

预览

通过拖拽到文本输入框、粘贴或点击此处上传图片、音频和视频。

点击此处上传图片

评论

· 注册或登录以评论

• +19