Transformers.js 浏览器本地 AI：什么时候适合放进产品

当 AI 任务边界明确、用户可以接受首次模型下载，而且文本、图片或音频不应发送到推理 API 时，Transformers.js 已经是可靠的生产候选。模型缓存后可以离线运行，不再为每次推理支付 API 费用，并让输入留在设备上。但它不是通用的云端替代方案。用户仍要承担带宽、内存、电量和硬件成本，产品团队仍要负责模型质量、浏览器兼容性、许可证、隐私边界和备用路径。

本文只负责客户端架构决策。如果要比较服务器或私有云的经济性，请阅读本地模型与 API 盈亏平衡计算指南。如果要评估手机硬件上的具体压缩模型，请阅读Bonsai 27B 端侧评测。明确划分搜索意图，可以避免本文与自托管和硬件适配页面互相竞争。

Transformers.js 的月下载量真的超过一千万了吗？

把当前包名和旧包名相加后，答案是肯定的，但增长倍数必须使用一致口径。npm 公共 API 显示，截至 2026 年 8 月 9 日的 30 天内，@huggingface/transformers 下载 8,251,156 次，旧包 @xenova/transformers 下载 2,443,599 次，合计 10,694,755 次。

六个月前的可比 30 天窗口中，当前包下载 1,113,605 次，旧包下载 1,158,603 次。合计增长约 4.7 倍，当前包单独增长约 7.4 倍。增长信号非常强，但同口径数据不支持把“接近十倍”当作两个包合计后的精确数字。

为什么浏览器 AI 现在快速增长？

Hugging Face 发布的 Transformers.js v4带来了用 C++ 重写的 WebGPU 运行时，并在大约 200 种受支持模型架构上测试。官方报告 BERT embedding 模型约有四倍加速，默认 Web bundle 缩小 53%，生产控制能力更完整，并支持超过 8B 参数的模型。GPT-OSS 20B 在 M4 Pro Max 上约 60 token 每秒，只能证明高端设备的能力，不能代表普通客户电脑。

ModelRegistry 可以检查所需文件、下载大小、缓存状态和可用数据类型，也可以清理模型缓存。对产品而言，这比峰值跑分更重要。界面需要在下载前解释大小，显示进度，支持重试，并允许用户释放存储空间。

截至复核日期，Transformers.js 4.2.0 是当前稳定版，发布于 2026 年 4 月 23 日。生产环境要固定库版本、模型 revision、量化格式和运行时文件。“latest”不是部署策略。

哪些内容留在本地，哪些仍会访问网络？

浏览器可以在不把输入发送到推理服务器的情况下完成模型计算。默认配置仍会下载模型权重和 WebAssembly 文件。分析工具、错误报告、远程字体和业务 API 都是独立的数据路径。

1. 首次加载：JavaScript、运行时、tokenizer 和模型权重进入设备。
2. 缓存：浏览器可以保存资源，供重复访问和离线使用。
3. 推理：WebGPU 或 WebAssembly 在设备上处理输入。
4. 应用逻辑：只有你的代码不再传输结果，结果才真正留在本地。
5. 备用路径：云端路由会把数据送出设备，需要明确政策和用户提示。

官方自定义模型指南说明了如何设置本地模型路径、禁用远程模型，并从自己的 origin 提供 WebAssembly 文件。

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

env.allowRemoteModels = false;
env.localModelPath = "/models/";
env.backends.onnx.wasm.wasmPaths = "/wasm/";

const task = "text-classification";
const model = "approved-model";
const wasmOptions = { device: "wasm", dtype: "q8" };

async function createClassifier() {
  let adapter;
  if ("gpu" in navigator) {
    try {
      adapter = await navigator.gpu.requestAdapter();
    } catch (error) {
      console.warn("WebGPU adapter request failed.", error);
    }
  }

  if (adapter?.features.has("shader-f16")) {
    try {
      return await pipeline(task, model, {
        device: "webgpu",
        dtype: "q4f16",
      });
    } catch (error) {
      console.warn(
        "WebGPU model initialization failed; using WASM.",
        error,
      );
    }
  }

  return pipeline(task, model, wasmOptions);
}

const classify = await createClassifier();

适配器探测可以避免在缺少 shader-f16 时选择 q4f16。捕获的 pipeline 错误也覆盖模型或后端拒绝的情况，随后会使用 WASM 重新创建分类器。

不要把 Hugging Face access token 放进浏览器代码。Hugging Face 只在服务端环境支持私有或 gated 模型 token，因为浏览器可能向用户暴露凭据。如果模型权重必须保密，公开交付给客户端通常就是错误架构。

浏览器 AI 什么时候优于 API？

ONNX Runtime Web 部署指南列出的核心收益包括：适用模型的低延迟、更好的输入隐私、离线运行和更低云端 serving 成本。它也指出不同硬件 backend 支持的 operator 子集不同。模型可能在 WebAssembly 上可用，却在 WebGPU 上失败，因此备用路径也必须单独测试。

哪些商业场景最适合？

• 私有语义搜索：为笔记、文件或浏览历史生成 embedding，不上传原文。
• 分类和路由：在服务器调用前完成工单标签、意图检测或下一步选择。
• 云端 AI 前的 PII 检测：先在本地识别姓名、地址和标识符。我们的LLM prompt 前 PII 编辑指南介绍完整控制方案。
• 文档、图片和音频：OCR、图片分类、背景移除、信息抽取、转录和音频分类。
• 离线现场软件：让技术人员和检查人员在网络不稳定时继续使用 AI 功能。
• 混合生成：本地模型处理常规任务，强 API 只处理困难且获准的案例。

第一个项目通常不该是通用聊天机器人，而应该是输入清晰、结果可测，并存在高隐私成本或 API 瓶颈的窄工作流。Wavect 的AI 落地服务覆盖用例选择、评测、模型、隐私边界、集成和发布。Twinsoft AI 案例说明，真正创造业务价值的是模型周围的流程和控制。

什么时候不该使用 Transformers.js？

• 产品核心需要 frontier 推理，只有大模型能通过评测。
• 访客大多只来一次，首次下载会损害转化。
• 模型权重必须保密。
• 内存、发热、电量或标签页回收会形成支持负担。
• 业务必须集中执行访问控制、留存和审计。
• 不存在可接受的 WebAssembly 或 API 备用路径。

MDN 仍把 WebGPU 标为有限可用，并要求 HTTPS 安全上下文。WebAssembly 覆盖更广，但会改变性能和模型选择。支持矩阵必须基于真实客户设备。

生产架构检查清单

1. 定义一个任务、目标用户、输入边界和质量门槛。
2. 固定库、模型、tokenizer、量化、运行时、许可证和文件 hash。
3. 展示下载大小、进度、存储、取消、重试和清理缓存。
4. 在 Web Worker 中加载和执行模型。
5. 按能力路由，不按浏览器名称路由。
6. 用任务评测比较本地路径、备用路径和现有系统。
7. 检查网络请求、分析、日志、错误报告和云端切换。
8. 先 opt-in 发布，并测量下载完成率、p50、p95、错误、电量反馈和升级率。
9. 保留旧模型和 API 路由，以便回滚。

一个 30 天试点