Transformers.js v4 上线 NPM，采用全新 WebGPU 运行时

我们很高兴地宣布，Transformers.js v4 现已在 NPM 上发布！经过一年的开发（我们于 2025 年 3 月启动 🤯），我们终于准备好让你使用了。

npm i @huggingface/transformers

性能与运行时改进

最大的变化无疑是采用了全新的 WebGPU 运行时，完全用 C++ 重写。我们与 ONNX Runtime 团队密切合作，在我们支持的约 200 种模型架构以及许多 v4 独有的新架构上对该运行时进行了全面测试。

除了更好的算子支持（在性能、准确性和覆盖范围方面）之外，这个新的 WebGPU 运行时还允许相同的 transformers.js 代码在各种各样的 JavaScript 环境中使用，包括浏览器、服务端运行时和桌面应用程序。没错，你现在可以直接在 Node、Bun 和 Deno 中运行 WebGPU 加速的模型了！

我们已经证明，在浏览器中 100% 本地运行最先进的 AI 模型是可能的，现在我们专注于性能：让这些模型尽可能快地运行，即使在资源受限的环境中也是如此。这要求我们彻底重新思考导出策略，尤其是对于大语言模型。我们通过逐算子重新实现新模型来实现这一点，利用专门的 ONNX Runtime Contrib Operators，如 com.microsoft.GroupQueryAttention、com.microsoft.MatMulNBits 或 com.microsoft.QMoE 来最大化性能。

例如，采用 com.microsoft.MultiHeadAttention 算子后，我们在基于 BERT 的嵌入模型上实现了约 4 倍的速度提升。

代码仓库重构

开发一个新的主版本让我们有机会对代码库进行投入，并处理早就该进行的重构工作。

PNPM Workspaces

到目前为止，GitHub 仓库就是我们的 npm 包。只要仓库只暴露一个库，这种方式就运行良好。然而，着眼于未来，我们看到了对多个子包的需求，这些子包既高度依赖 Transformers.js 核心，又要解决不同的用例，比如特定于库的实现，或者大多数用户不需要但对某些用户必不可少的更小的工具。

这就是为什么我们将仓库转换为使用 pnpm workspaces 的 monorepo。这使我们能够发布依赖 @huggingface/transformers 的更小的包，而无需维护多个独立仓库的开销。

模块化类结构

另一项重大重构工作针对的是不断增长的 models.js 文件。在 v3 中，所有可用的模型都定义在一个超过 8,000 行的单一文件中，越来越难以维护。对于 v4，我们将其拆分为更小、更专注的模块，清晰区分实用函数、核心逻辑和特定于模型的实现。这种新结构提高了可读性，并使添加新模型变得容易得多。开发者现在可以专注于特定于模型的逻辑，而无需浏览数千行不相关的代码。

示例仓库

在 v3 中，许多 Transformers.js 示例项目直接放在主仓库中。对于 v4，我们将它们移到了一个专用仓库，使我们能够维护一个更干净、专注于核心库的代码库。这也使用户更容易找到示例并为其做出贡献，而无需在主仓库中翻找。

Prettier

我们更新了 Prettier 配置，并重新格式化了仓库中的所有文件。这确保了整个代码库的格式一致，所有未来的 PR 都会自动遵循相同的风格。不再有关于格式的争论……Prettier 会处理一切，让代码对每个人来说都保持整洁易读。

新模型与架构

得益于我们新的导出策略以及 ONNX Runtime 对自定义算子不断扩展的支持，我们得以向 Transformers.js v4 中新增许多新模型和架构。其中包括 GPT-OSS、Chatterbox、GraniteMoeHybrid、LFM2-MoE、HunYuanDenseV1、Apertus、Olmo3、FalconH1 和 Youtu-LLM 等热门模型。其中许多需要我们实现对高级架构模式的支持，包括 Mamba（状态空间模型）、多头潜在注意力（MLA）和专家混合（MoE）。也许最重要的是，这些模型都兼容 WebGPU，允许用户直接在浏览器或服务端 JavaScript 环境中借助硬件加速运行它们。到目前为止，我们已经发布了多个 Transformers.js v4 演示……我们还会继续发布更多！

新的构建系统

我们已将构建系统从 Webpack 迁移到 esbuild，结果令人难以置信。构建时间从 2 秒降至仅 200 毫秒，提升了 10 倍，使开发迭代速度显著加快。不过，速度并不是唯一的好处：所有构建的打包体积平均也减少了 10%。最显著的改进是我们的默认导出 transformers.web.js，它现在缩小了 53%，这意味着用户下载更快、启动时间更短。

新的库功能

版本 4 还增加了新的库功能，使构建健壮、可用于生产环境的应用程序变得更加容易。

ModelRegistry

新的 ModelRegistry API 专为生产工作流而设计。它可以在加载任何内容之前明确查看流水线资源：使用 get_pipeline_files 列出所需文件，使用 get_file_metadata 检查每个文件的元数据（对于计算总下载大小非常有用），使用 is_pipeline_cached 检查缓存状态，并使用 clear_pipeline_cache 清除缓存产物。你还可以使用 get_available_dtypes 查询模型可用的精度类型。基于这个新 API，progress_callback 现在包含一个 progress_total 事件，使得无需手动汇总每个文件的更新，就能轻松渲染端到端的加载进度。

查看 `ModelRegistry` 示例

import { ModelRegistry, pipeline } from "@huggingface/transformers";

const modelId = "onnx-community/all-MiniLM-L6-v2-ONNX";
const modelOptions = { dtype: "fp32" };

const files = await ModelRegistry.get_pipeline_files(
  "feature-extraction",
  modelId,
  modelOptions
);
// ['config.json', 'onnx/model.onnx', ..., 'tokenizer_config.json']

const metadata = await Promise.all(
  files.map(file => ModelRegistry.get_file_metadata(modelId, file))
);

const downloadSize = metadata.reduce((total, item) => total + item.size, 0);

const cached = await ModelRegistry.is_pipeline_cached(
  "feature-extraction",
  modelId,
  modelOptions
);

const dtypes = await ModelRegistry.get_available_dtypes(modelId);
// ['fp32', 'fp16', 'q4', 'q4f16']

if (cached) {
  await ModelRegistry.clear_pipeline_cache(
    "feature-extraction",
    modelId,
    modelOptions
  );
}

const pipe = await pipeline(
  "feature-extraction",
  modelId,
  {
    progress_callback: e => {
      if (e.status === "progress_total") {
        console.log(`${Math.round(e.progress)}%`);
      }
    },
  }
);

新的环境设置

我们还为模型加载添加了新的环境控制。env.useWasmCache 启用 WASM 运行时文件的缓存（当缓存存储可用时），使应用程序在首次加载后可以完全离线工作。

env.fetch 允许你提供自定义 fetch 实现，用于诸如经过身份验证的模型访问、自定义标头和可中止请求等用例。

查看 env 示例

import { env } from "@huggingface/transformers";

env.useWasmCache = true;

env.fetch = (url, options) =>
  fetch(url, {
    ...options,
    headers: {
      ...options?.headers,
      Authorization: `Bearer ${MY_TOKEN}`,
    },
  });

改进的日志控制

最后，在实际部署中，日志管理变得更加容易。ONNX Runtime WebGPU 警告现在默认隐藏，你可以为 Transformers.js 和 ONNX Runtime 分别设置明确的详细程度级别。此次更新同样由社区反馈驱动，使控制台输出专注于可操作的信号，而不是低价值的噪音。

查看 `logLevel` 示例

import { env, LogLevel } from "@huggingface/transformers";

// LogLevel.DEBUG
// LogLevel.INFO
// LogLevel.WARNING
// LogLevel.ERROR
// LogLevel.NONE

env.logLevel = LogLevel.WARNING;

独立 Tokenizers.js 库

用户经常提出的一个需求是将分词逻辑提取到一个单独的库中，而在 v4 中，我们正是这样做的。@huggingface/tokenizers 是对分词逻辑的完整重构，旨在跨浏览器和服务器端运行时无缝运行。它仅有 8.8kB（gzip 压缩后）且零依赖，极其轻量，同时保持完全类型安全。

查看示例代码

import { Tokenizer } from "@huggingface/tokenizers";

// Load from HF Mirror Hub
const modelId = "HuggingFaceTB/SmolLM3-3B";
const tokenizerJson = await fetch(
  `https://hf-mirror.com/${modelId}/resolve/main/tokenizer.json`
).then(res => res.json());

const tokenizerConfig = await fetch(
  `https://hf-mirror.com/${modelId}/resolve/main/tokenizer_config.json`
).then(res => res.json());

// Create tokenizer
const tokenizer = new Tokenizer(tokenizerJson, tokenizerConfig);

// Tokenize text
const tokens = tokenizer.tokenize("Hello World");
// ['Hello', 'ĠWorld']

const encoded = tokenizer.encode("Hello World");
// { ids: [9906, 4435], tokens: ['Hello', 'ĠWorld'], ... }

这种分离使 Transformers.js 的核心保持专注和精简，同时提供了一个通用的独立工具，任何 WebML 项目都可以独立使用。

其他改进

我们在整个库中进行了多项体验优化。类型系统得到了增强，新增了可根据输入动态调整的管道类型，提供了更好的开发者体验和类型安全。

此外，我们增加了对超过 8B 参数的大型模型的支持。在我们的测试中，我们能够在 M4 Pro Max 上以约 60 tokens/秒的速度运行 GPT-OSS 20B（q4f16）。

致谢

我们要衷心感谢所有为这一重大版本做出贡献的人，特别是 ONNX Runtime 团队，感谢他们在新的 WebGPU 运行时上的出色工作以及在整个开发过程中的支持，同时也要感谢所有外部贡献者和早期测试者。