Transformers.js v3 发行版添加了 WebGPU 加速、扩展的模型支持以及服务器端 JavaScript 兼容性

TL;DR

Transformers.js v3 添加了 WebGPU 加速（比 WASM 快至 100 倍），新的量化格式，支持 120 种模型架构，并兼容 Node.js（ESM + CJS）、Deno 和 Bun，使得在浏览器和服务器端 JavaScript 运行时直接进行高性能推理成为可能。

快速安装

您可以通过 NPM 安装此库：

npm i @huggingface/transformers

通过 ES 模块或 CDN 导入 pipeline：

import { pipeline } from "@huggingface/transformers";
// or
import { pipeline } from "https://cdn.jsdelivr.net/npm/@huggingface/transformers@3.0.0";

完整文档位于 https://hf.co/docs/transformers.js。

WebGPU 支持 – 大幅加速

WebGPU 是一种现代的 Web 标准，可将 GPU 暴露用于通用计算，取代了 WebGL。截至 2024 年 10 月，约有 70% 的浏览器支持 WebGPU，尽管有些浏览器可能需要启用特性标志（Firefox dom.webgpu.enabled、Safari WebGPU、旧版 Chromium enable-unsafe-webgpu）。

在 Transformers.js 中启用 WebGPU

该库与 ONNX Runtime Web 集成；只需在加载模型时传入 device: "webgpu" 即可启用 GPU 加速。

文本嵌入示例

const extractor = await pipeline(
  "feature-extraction",
  "mixedbread-ai/mxbai-embed-xsmall-v1",
  { device: "webgpu" }
);
const embeddings = await extractor(["Hello world!", "Example sentence."], { pooling: "mean", normalize: true });
console.log(embeddings.tolist());

Whisper ASR 示例

const transcriber = await pipeline(
  "automatic-speech-recognition",
  "onnx-community/whisper-tiny.en",
  { device: "webgpu" }
);
const output = await transcriber("https://huggingface.co/datasets/Xenova/transformers.js-docs/resolve/main/jfk.wav");
console.log(output);

图像分类示例

const classifier = await pipeline(
  "image-classification",
  "onnx-community/mobilenetv4_conv_small.e2400_r224_in1k",
  { device: "webgpu" }
);
const result = await classifier("https://huggingface.co/datasets/Xenova/transformers.js-docs/resolve/main/tiger.jpg");
console.log(result);

这些演示表明，以前在 WASM 上需要数秒的推理现在可以在 GPU 上实时运行。

新的量化格式（dtype 参数）

之前库使用二进制 quantized 标志（q8 与 fp32）。第 3 版用灵活的 dtype 参数取代，可从多种精度中选择，包括：

  • 全精度："fp32"
  • 半精度："fp16"
  • 8 位："q8"、"int8"、"uint8"
  • 4 位："q4"、"bnb4"、"q4f16"

基本用法 – 4 位 Qwen2.5

const generator = await pipeline(
  "text-generation",
  "onnx-community/Qwen2.5-0.5B-Instruct",
  { dtype: "q4", device: "webgpu" }
);
const msgs = [{ role: "system", content: "You are a helpful assistant." }, { role: "user", content: "Tell me a funny joke." }];
const out = await generator(msgs, { max_new_tokens: 128 });
console.log(out[0].generated_text.at(-1).content);

编码器‑解码器模型的每模块 dtype

某些模型（例如 Whisper、Florence‑2）对量化较为敏感。现在您可以提供模块名称到 dtype 的映射：

const model = await Florence2ForConditionalGeneration.from_pretrained(
  "onnx-community/Florence-2-base-ft",
  {
    dtype: {
      embed_tokens: "fp16",
      vision_encoder: "fp16",
      encoder_model: "q4",
      decoder_model_merged: "q4",
    },
    device: "webgpu",
  }
);

完整示例加载模型、处理器、分词器，准备图像并生成详细的标题，展示了每模块量化的实际影响。

120 种支持的架构 – 更广的模态覆盖

Transformers.js v3 现在支持 120 种模型族，涵盖文本、视觉、音频和多模态任务。值得注意的新增包括：

  • Phi‑3 与 Phi‑3.5（高能力的在设备上运行的 LLM）
  • Gemma 与 Gemma 2（Google 的开源模型）
  • LLaVA、Moondream、Florence‑2（视觉‑语言）
  • MusicGen（音频生成）
  • Depth Pro、RT‑DETR、Sapiens、PyAnnote（专用视觉和音频任务）

原文中的气泡图可视化了这些新族。完整列表位于 https://huggingface.co/docs/transformers.js/index#models。

示例项目和模板 – WebGPU 展示

此次发布包含 25 个新的示例仓库，许多展示了 WebGPU 加速。亮点包括：

  • Phi‑3.5 WebGPU – 在浏览器中完整运行 3.8 B 参数的 LLM。
  • Whisper Turbo WebGPU – 使用 Whisper 模型在 GPU 上实现实时语音转文字。

所有示例均托管在 https://github.com/huggingface/transformers.js-examples，并将在该处统一。

Hub 上已有超过 1,200 个预转换模型

社区已经将超过 1,200 个模型转换为 Transformers.js 所需的 ONNX 格式。可搜索的列表位于 https://hf.co/models?library=transformers.js。

要转换自定义模型，请使用提供的脚本：

python -m scripts.convert --quantize --model_id <model_name_or_path>

上传后，为仓库添加 transformers.js 标签，以便发现。

服务器端 JavaScript 运行时支持

Transformers.js v3 可在三大流行运行时上运行：

运行时 兼容性 示例仓库
Node.js (ESM + CJS) 完全支持，npm 包 https://github.com/huggingface/transformers.js-examples/tree/main/node-esm
Deno 安全默认，实验性 WebGPU https://github.com/huggingface/transformers.js-examples/tree/main/deno-embed
Bun 高性能打包器与运行时 https://github.com/huggingface/transformers.js-examples/tree/main/bun

这使开发者能够在服务器、边缘设备或无 Python 依赖的无服务器函数中运行推理。

NPM 与 GitHub 新地址

该包现已在官方 Hugging Face 作用域下发布为 @huggingface/transformers（之前为 @xenova/transformers）。

源码已迁移至 https://github.com/huggingface/transformers.js。这将问题跟踪、拉取请求贡献以及社区互动统一到 Hugging Face 组织下。

影响

  • 性能：WebGPU 将基于浏览器的推理提升至桌面级速度，解锁实时应用，如交互式聊天、实时转录和设备端视觉。
  • 灵活性：扩展的 dtype API 与每模块量化让开发者在各种硬件上平衡内存、延迟和精度。
  • 生态系统增长：支持 120 种架构和超过 1,200 个预转换模型，降低了在 JavaScript 环境中使用最前沿模型的门槛。
  • 可移植性：兼容 Node.js、Deno 和 Bun，意味着相同代码可在浏览器、无服务器后端或边缘运行时运行，简化部署流程。
  • 社区统一：将包和仓库迁至 Hugging Face 组织下，统一品牌并鼓励更广泛的 HF 生态系统贡献。

入门检查清单

  1. 通过 npm 或 CDN 安装 @huggingface/transformers。
  2. 从 Hub 选择模型（确保其带有 transformers.js 标签）。
  3. 决定使用的设备（"cpu"、"wasm" 或 "webgpu"）。
  4. 可选地为量化选择 dtype 或每模块 dtype 映射。
  5. 使用高级 pipeline API 或低级模型类进行推理。
  6. 根据需要将相同代码部署到 Node.js、Deno 或 Bun。

参考文献

本文总结了 Hugging Face 官方博客文章 “Transformers.js v3: WebGPU Support, New Models & Tasks, and More…” 于 2024‑10‑22 发布。

Sources