使用 Transformers.js 直接在浏览器中运行 AI 模型

如果你的 Web 应用能够分类文本、转录音频或检测图像中的物体——而且完全不需要向服务器发送数据,会怎么样?这正是 Transformers.js 所实现的功能。它仅使用 JavaScript 就能在浏览器中实现客户端 AI 推理。

什么是 Transformers.js?

Transformers.js 是来自 Hugging Face 的 JavaScript 库,它允许你直接在浏览器中运行预训练的机器学习模型——无需后端模型服务器。它的 API 与 Hugging Face 的 Python transformers 库相对应,因此如果你之前使用过该库,心智模型可以无缝迁移。

当前维护的包是 @huggingface/transformers。如果你看到对 @xenova/transformers 的旧引用,那是指该项目在转由 Hugging Face 维护之前使用的早期包名。当前稳定版本是 v3 系列,v4 开发预览版已经可用,但尚未完全稳定。

浏览器 AI 推理的实际工作原理

Transformers.js 使用为 JavaScript 环境编译的 ONNX Runtime 来执行模型。ONNX(开放神经网络交换格式)充当通用格式,使在 PyTorch、TensorFlow 或 JAX 中训练的模型能够在浏览器中运行。

默认情况下,推理通过 WebAssembly (WASM) 在 CPU 上运行——这在几乎所有现代浏览器中都可以工作。为了在支持的硬件上获得更好的性能,你可以选择使用 WebGPU,它将计算任务卸载到 GPU。

WebGPU 的可用性在各个浏览器和平台上持续演进。你可以在 webstatus.dev 上查看当前的实现状态。实际上,支持和性能仍然因浏览器、操作系统和 GPU 驱动程序而异。

当你需要最大兼容性时使用 WASM。当性能很重要且你的目标是支持 WebGPU 的现代浏览器时,切换到 WebGPU。

并非每个 Hugging Face 模型都能在浏览器中运行

这是一个重要的限制:模型需要 ONNX 兼容的权重才能与 Transformers.js 配合使用。许多流行的架构——DistilBERT、Whisper、T5、Llama、Qwen 等数十种——在 Hugging Face Hub 上已经有 ONNX 版本可用。对于没有的模型,你可以使用 Optimum 进行转换。

由于浏览器环境资源受限,量化模型是实际的默认选择。dtype 选项控制这一点:

• "fp32" — 全精度,WebGPU 的默认值
• "fp16" — 半精度,GPU 的良好平衡
• "q8" — 8 位量化,WASM 的默认值
• "q4" — 4 位量化,最小且最快

运行你的第一个 Pipeline

Pipeline API 在一次调用中处理预处理、推理和后处理。安装包:

npm install @huggingface/transformers

然后用几行代码运行情感分析:

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

// 默认使用 WASM,使用该任务的默认模型
const classifier = await pipeline("sentiment-analysis");
const result = await classifier("I love building with Transformers.js!");
console.log(result); // [{ label: 'POSITIVE', score: 0.9998 }]

要启用 WebGPU 和 fp16 精度:

const classifier = await pipeline(
  "sentiment-analysis",
  "Xenova/distilbert-base-uncased-finetuned-sst-2-english",
  { device: "webgpu", dtype: "fp16" }
);

模型文件在首次下载后会缓存在浏览器中,因此重复使用——包括离线使用——不需要重新获取它们。对于生产环境,建议自托管模型资源,而不是直接依赖 Hub。

一个实用的注意事项:默认情况下,推理在主线程上运行,这可能在大量计算期间冻结 UI。将推理移至 Web Worker 是任何生产功能的正确模式。

为什么这对前端开发者很重要

使用 Transformers.js 在浏览器中运行 AI 模型开启了服务器端推理无法同样清晰匹配的用例:

• 隐私保护推理 — 用户数据永远不会离开设备
• 离线 AI 应用 — 在初始模型下载后可以在没有网络连接的情况下工作
• 降低服务器成本 — 减少需要配置或扩展的后端 GPU 工作负载
• 低延迟功能 — 无需往返 API 端点的网络延迟

支持的任务列表很广泛:文本分类、摘要、翻译、物体检测、图像分割、语音识别、文本转语音等等。

结论

Transformers.js 使基于浏览器的 AI 对前端开发者来说越来越实用。从一个小型量化模型开始,验证任务是否适合你的用例,然后从那里优化——使用 WebGPU 提高速度,使用 Web Workers 提高 UI 响应性,使用自托管模型提高生产可靠性。官方文档 和 模型中心 是最好的下一站。

常见问题

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.