Transformers.js v4 预览：现已在 NPM 上可用！

Source: Hugging Face Blog

Source:

目录

• 性能与运行时改进
• 仓库结构重组
• PNPM 工作区
• 模块化类结构
• 示例仓库
• Prettier
• 格式化与一致性
• 新模型与架构
• 新构建系统
• 独立的 Tokenizers.js 库
• 其他改进
• 致谢

我们很高兴宣布 Transformers.js v4（预览版） 现已在 npm 上发布！经过近一年的开发（我们于 2025 年 3 月开始 🤯），现在终于可以让大家进行测试了。之前，用户必须通过 GitHub 从源码直接安装 v4；现在只需运行一条命令即可：

npm i @huggingface/transformers@next

在正式发布之前，我们将继续在 npm 上使用 next 标签发布 v4 版本，因此请期待定期更新！

性能与运行时改进

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

除了更好的算子支持（在性能、精度和覆盖范围方面），全新的 WebGPU 运行时还能让相同的 transformers.js 代码在各种 JavaScript 环境中运行——包括浏览器、服务器端运行时以及桌面应用。这意味着你现在可以在 Node、Bun 和 Deno 中直接运行 WebGPU 加速的模型！

我们已经证明，在浏览器中本地运行最先进的 AI 模型 100 % 是可行的。现在我们专注于性能：让这些模型在资源受限的环境中也能尽可能快地运行。这需要重新思考我们的导出策略，尤其是针对大型语言模型。我们通过逐个算子重新实现新模型，利用专门的 ONNX Runtime Contrib Operators，例如：

• com.microsoft.GroupQueryAttention
• com.microsoft.MatMulNBits
• com.microsoft.QMoE

这些算子最大化了性能。例如，采用 com.microsoft.MultiHeadAttention 算子后，我们在基于 BERT 的嵌入模型上实现了 约 4 倍加速。

此更新还通过在浏览器本地缓存 WASM 文件，实现了完整的离线支持，用户在首次下载后即可在没有网络连接的情况下运行 Transformers.js 应用。

仓库重构

开发一个新的主要版本让我们有机会投入代码库并着手长期拖延的重构工作。

PNPM 工作区

直到现在，GitHub 仓库充当我们的 npm 包。当仓库只暴露单个库时，这种方式可行，但我们需要一种更灵活的结构，以便将来能够创建大量依赖 Transformers.js 核心的子包（例如，特定库的实现或更小的工具）。

因此，我们使用 pnpm workspaces 将仓库转换为 monorepo。这使我们能够发布依赖 @huggingface/transformers 的更小的包，而无需维护单独的仓库所带来的额外负担。

模块化类结构

另一个主要的重构针对日益庞大的 models.js 文件。在 v3 中，所有可用模型都定义在一个超过 8 000 行的单文件中，维护起来非常困难。对于 v4，我们将其拆分为更小、更专注的模块，并明确区分：

• 实用函数
• 核心逻辑
• 模型特定实现

新的结构提升了可读性，并且大大简化了添加新模型的过程。开发者现在可以专注于模型特定的逻辑，而无需在成千上万行无关代码中来回查找。

示例仓库

在 v3 中，许多 Transformers.js 示例项目直接位于主仓库。对于 v4，我们已将它们迁移到一个 专用仓库：. 这使核心库保持整洁，并且让用户更容易在不浏览主代码库的情况下找到并贡献示例。

Prettier

我们更新了 Prettier 配置，并重新格式化了所有文件，以遵循一致的风格。（本节的其余部分在完整文章中继续。）

Formatting and Consistency

现在仓库中的所有文件都使用统一的 Prettier 配置。这确保了代码库整体的格式保持一致，所有后续的 PR 将自动遵循相同的风格。再也不用为格式争论——Prettier 全部搞定，让代码对每个人都保持整洁可读。

新模型和架构

得益于我们新的导出策略以及 ONNX Runtime 对自定义算子的支持不断扩展，我们在 Transformers.js v4 中添加了许多新模型和架构。这些包括流行的模型，例如：

• GPT‑OSS
• Chatterbox
• GraniteMoeHybrid
• LFM2‑MoE
• HunYuanDenseV1
• Apertus
• Olmo3
• FalconH1
• Youtu‑LLM

其中许多模型需要我们实现对高级架构模式的支持，包括：

• Mamba（状态空间模型）
• Multi‑head Latent Attention (MLA)（多头潜在注意力）
• Mixture of Experts (MoE)（专家混合）

所有这些模型均兼容 WebGPU，使用户能够在浏览器或服务器端 JavaScript 环境中直接运行，并获得硬件加速。

新的构建系统

我们已将构建系统从 Webpack 迁移至 esbuild，结果令人惊叹：

• 构建时间： 从约 2 秒降至约 200 毫秒（≈提升 10 倍）
• 打包体积： 所有构建平均减少约 10 %
• transformers.web.js： 体积缩小 53 %，下载更快，用户启动时间更短

Source: …

独立的 Tokenizers.js 库

用户经常提出的需求是将分词逻辑提取到一个单独的库中。 在 v4 中，我们正是这样实现的。

@huggingface/tokenizers 是对分词逻辑的完整重构，旨在在浏览器和服务器端运行时无缝工作。 体积仅 8.8 kB（gzip 后），零依赖，既轻量又保持完整的类型安全。

示例

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

// Load from Hugging Face Hub
const modelId = "HuggingFaceTB/SmolLM3-3B";
const tokenizerJson = await fetch(
  `https://huggingface.co/${modelId}/resolve/main/tokenizer.json`
).then(res => res.json());

const tokenizerConfig = await fetch(
  `https://huggingface.co/${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 项目都可以独立使用。

杂项改进

我们在整个库中做了多项提升开发体验的改进：

• 动态管道类型 能根据输入自适应，提供更好的开发者体验和类型安全。

  

• 增强日志，在模型执行期间提供更好的控制和更清晰的反馈。

• 支持更大的模型，超过 8 B 参数。在我们的测试中，我们在 M4 Pro Max 上运行 GPT‑OSS 20B (q4f16)，速度约为每秒 60 个 token。

致谢

我们想向所有为此重大版本做出贡献的人表达衷心的感谢，特别是：

• ONNX Runtime 团队 为新 WebGPU 运行时所做的卓越工作以及在整个开发过程中的支持。
• 所有外部贡献者和早期测试者。