--- title: "Transformers.js 浏览器本地 AI：隐私、成本与生产部署" canonical: https://wavect.io/zh/blog/transformers-js-browser-ai-guide/ language: zh description: "什么时候应在浏览器运行 AI？比较 Transformers.js 的隐私、API 成本、WebGPU 支持、适用场景、限制和生产发布清单。" image: "https://wavect.io/img/blog/headers/header_transformers-js-browser-ai-guide.png" --- [**返回**](/zh/blog/overview/) [![Kevin Riedl](/img/team/kevin.webp)](/zh/team/kevin-riedl/) [Kevin Riedl](/zh/team/kevin-riedl/) https://linkedin.com/in/wsdt 8 分钟 阅读 · 2026年8月15日 最近审核 2026年8月15日 [**下一篇**](/zh/blog/github-spec-kit-production-guide/) # Transformers.js 浏览器本地 AI：什么时候适合放进产品 要点速览 Transformers.js 可以让受支持的 AI 推理留在用户设备上，避免逐次模型 API 费用，并在完整缓存后离线运行，但成本会转移到下载、用户设备计算和产品工程。当前和旧 npm 包在截至 2026 年 8 月 9 日的 30 天内合计下载 10,694,755 次，约为六个月前可比窗口的 4.7 倍。适合的生产场景包括 embedding、分类、PII 检测、文档、视觉和语音任务。生产方案需要 Web Worker、固定模型资源、可见的下载与缓存控制、任务评测、隐私检查、WebGPU 能力检测、经过测试的 WASM 或 API 备用路径，以及受控发布。 **当 AI 任务边界明确、用户可以接受首次模型下载，而且文本、图片或音频不应发送到推理 API 时，Transformers.js 已经是可靠的生产候选。**模型缓存后可以离线运行，不再为每次推理支付 API 费用，并让输入留在设备上。但它不是通用的云端替代方案。用户仍要承担带宽、内存、电量和硬件成本，产品团队仍要负责模型质量、浏览器兼容性、许可证、隐私边界和备用路径。 本文只负责客户端架构决策。如果要比较服务器或私有云的经济性，请阅读 [本地模型与 API 盈亏平衡计算指南](/zh/blog/local-models-vs-apis-break-even-eu-2026/) 。如果要评估手机硬件上的具体压缩模型，请阅读 [Bonsai 27B 端侧评测](/zh/blog/bonsai-27b-phone-local-ai-review/) 。明确划分搜索意图，可以避免本文与自托管和硬件适配页面互相竞争。 | 问题 | 简短答案 | 商业含义 | | --- | --- | --- | | 它是什么？ | 通过 ONNX Runtime 在浏览器和 JavaScript 运行时执行受支持 Hugging Face 模型的库 | 不用把每次推理都变成服务器请求 | | 推理私密吗？ | 推理可以留在设备上，但应用的其他数据路径不会自动消失 | 隐私是整个系统的属性 | | 免费吗？ | 本地推理没有按 token 收取的模型 API 费 | 工程、下载、支持、测试和用户设备计算仍有成本 | | 生产模式是什么？ | Web Worker、能力检测、量化模型、缓存、评测和备用路径 | 按最弱的受支持设备设计，不按发布演示设计 | ## Transformers.js 的月下载量真的超过一千万了吗？ **把当前包名和旧包名相加后，答案是肯定的，但增长倍数必须使用一致口径。**npm 公共 API 显示，截至 2026 年 8 月 9 日的 30 天内， [`@huggingface/transformers` 下载 8,251,156 次](https://api.npmjs.org/downloads/point/2026-07-11:2026-08-09/%40huggingface%2Ftransformers) ， [旧包 `@xenova/transformers` 下载 2,443,599 次](https://api.npmjs.org/downloads/point/2026-07-11:2026-08-09/%40xenova%2Ftransformers) ，合计 10,694,755 次。 六个月前的可比 30 天窗口中， [当前包下载 1,113,605 次](https://api.npmjs.org/downloads/point/2026-01-11:2026-02-09/%40huggingface%2Ftransformers) ， [旧包下载 1,158,603 次](https://api.npmjs.org/downloads/point/2026-01-11:2026-02-09/%40xenova%2Ftransformers) 。合计增长约 4.7 倍，当前包单独增长约 7.4 倍。增长信号非常强，但同口径数据不支持把“接近十倍”当作两个包合计后的精确数字。 ## 为什么浏览器 AI 现在快速增长？ [Hugging Face 发布的 Transformers.js v4](https://huggingface.co/blog/transformersjs-v4) 带来了用 C++ 重写的 WebGPU 运行时，并在大约 200 种受支持模型架构上测试。官方报告 BERT embedding 模型约有四倍加速，默认 Web bundle 缩小 53%，生产控制能力更完整，并支持超过 8B 参数的模型。GPT-OSS 20B 在 M4 Pro Max 上约 60 token 每秒，只能证明高端设备的能力，不能代表普通客户电脑。 `ModelRegistry` 可以检查所需文件、下载大小、缓存状态和可用数据类型，也可以清理模型缓存。对产品而言，这比峰值跑分更重要。界面需要在下载前解释大小，显示进度，支持重试，并允许用户释放存储空间。 截至复核日期， [Transformers.js 4.2.0 是当前稳定版](https://github.com/huggingface/transformers.js/releases/tag/4.2.0) ，发布于 2026 年 4 月 23 日。生产环境要固定库版本、模型 revision、量化格式和运行时文件。“latest”不是部署策略。 ## 哪些内容留在本地，哪些仍会访问网络？ 浏览器可以在不把输入发送到推理服务器的情况下完成模型计算。默认配置仍会下载模型权重和 WebAssembly 文件。分析工具、错误报告、远程字体和业务 API 都是独立的数据路径。 1. **首次加载：** JavaScript、运行时、tokenizer 和模型权重进入设备。 2. **缓存：** 浏览器可以保存资源，供重复访问和离线使用。 3. **推理：** WebGPU 或 WebAssembly 在设备上处理输入。 4. **应用逻辑：** 只有你的代码不再传输结果，结果才真正留在本地。 5. **备用路径：** 云端路由会把数据送出设备，需要明确政策和用户提示。 [官方自定义模型指南](https://huggingface.co/docs/transformers.js/main/en/custom_usage) 说明了如何设置本地模型路径、禁用远程模型，并从自己的 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](https://huggingface.co/docs/transformers.js/en/guides/private) ，因为浏览器可能向用户暴露凭据。如果模型权重必须保密，公开交付给客户端通常就是错误架构。 ## 浏览器 AI 什么时候优于 API？ | 因素 | 浏览器中的 Transformers.js | 托管 API | | --- | --- | --- | | 可变成本 | 资源交付后没有逐次模型费用 | 按用量或预留容量收费 | | 首次体验 | 模型下载和编译可能明显 | 客户端很小，但每次任务都要网络往返 | | 敏感输入 | 可以留在设备上 | 在合同和供应商控制下离开设备 | | 一致性 | 受浏览器、GPU、内存、温度和电量影响 | 基础设施更可控 | | 模型上限 | 适合小模型或精心量化的模型 | 适合 frontier 和超大模型 | | 离线 | 完整缓存后可以实现 | 通常不可用 | | 模型保密 | 交付的权重可以被检查 | 权重可以留在服务端 | [ONNX Runtime Web 部署指南](https://onnxruntime.ai/docs/tutorials/web/) 列出的核心收益包括：适用模型的低延迟、更好的输入隐私、离线运行和更低云端 serving 成本。它也指出不同硬件 backend 支持的 operator 子集不同。模型可能在 WebAssembly 上可用，却在 WebGPU 上失败，因此备用路径也必须单独测试。 ## 哪些商业场景最适合？ - **私有语义搜索：** 为笔记、文件或浏览历史生成 embedding，不上传原文。 - **分类和路由：** 在服务器调用前完成工单标签、意图检测或下一步选择。 - **云端 AI 前的 PII 检测：** 先在本地识别姓名、地址和标识符。我们的 [LLM prompt 前 PII 编辑指南](/zh/blog/pii-redaction-before-llm-prompts/) 介绍完整控制方案。 - **文档、图片和音频：** OCR、图片分类、背景移除、信息抽取、转录和音频分类。 - **离线现场软件：** 让技术人员和检查人员在网络不稳定时继续使用 AI 功能。 - **混合生成：** 本地模型处理常规任务，强 API 只处理困难且获准的案例。 第一个项目通常不该是通用聊天机器人，而应该是输入清晰、结果可测，并存在高隐私成本或 API 瓶颈的窄工作流。Wavect 的 [AI 落地服务](/zh/services/ai-enablement/) 覆盖用例选择、评测、模型、隐私边界、集成和发布。 [Twinsoft AI 案例](/zh/case-studies/twinsoft-ai/) 说明，真正创造业务价值的是模型周围的流程和控制。 ## 什么时候不该使用 Transformers.js？ - 产品核心需要 frontier 推理，只有大模型能通过评测。 - 访客大多只来一次，首次下载会损害转化。 - 模型权重必须保密。 - 内存、发热、电量或标签页回收会形成支持负担。 - 业务必须集中执行访问控制、留存和审计。 - 不存在可接受的 WebAssembly 或 API 备用路径。 [MDN 仍把 WebGPU 标为有限可用](https://developer.mozilla.org/en-US/docs/Web/API/WebGPU_API) ，并要求 HTTPS 安全上下文。WebAssembly 覆盖更广，但会改变性能和模型选择。支持矩阵必须基于真实客户设备。 ## 生产架构检查清单 1. 定义一个任务、目标用户、输入边界和质量门槛。 2. 固定库、模型、tokenizer、量化、运行时、许可证和文件 hash。 3. 展示下载大小、进度、存储、取消、重试和清理缓存。 4. 在 Web Worker 中加载和执行模型。 5. 按能力路由，不按浏览器名称路由。 6. 用任务评测比较本地路径、备用路径和现有系统。 7. 检查网络请求、分析、日志、错误报告和云端切换。 8. 先 opt-in 发布，并测量下载完成率、p50、p95、错误、电量反馈和升级率。 9. 保留旧模型和 API 路由，以便回滚。 ## 一个 30 天试点 | 周 | 交付物 | 决策门 | | --- | --- | --- | | 1 | 用例、评测集、设备矩阵、隐私数据流 | 是否存在合理的小模型候选？ | | 2 | WebGPU 和 WASM Worker 原型、下载与缓存体验 | 延迟和内存是否达标？ | | 3 | 本地资源、网络检查、许可证、API 备用路径 | 团队能否证明隐私和恢复能力？ | | 4 | Opt-in 用户组和每个成功任务的成本 | 扩大、保持混合、换模型还是停止？ | ## Transformers.js 常见问题 ### Transformers.js 可以免费商用吗？ 库本身使用 Apache 2.0。每个模型都有自己的许可证和使用条件。商业批准必须覆盖确切模型 revision、数据和应用义务。 ### Transformers.js 完全私密吗？ 推理可以留在本地，但模型下载、分析、日志、错误报告、云端备用和其他脚本仍是网络路径，必须测试并告知用户。 ### Transformers.js 支持所有浏览器吗？ WebAssembly 覆盖较广，WebGPU 更快但并非统一可用。生产应用需要能力检测、经过测试的备用路径和目标设备矩阵。 ### Transformers.js 能运行大语言模型吗？ 可以。版本 4 支持超过 8B 参数的模型。M4 Pro Max 上的结果不能代表普通客户设备，下载、内存、延迟、发热和质量都要测量。 ### 浏览器 AI 什么时候比 API 更便宜？ 通常是重复用户、高任务量、边界明确、小模型、热缓存，并达到同一质量门槛时。其他情况往往适合 API 或混合架构。 ## 最终思考 Transformers.js 已经从醒目的浏览器演示成长为可信的产品基础设施。更好的架构会在隐私、离线、延迟和重复任务量真正重要时使用本地推理，同时为不达标的设备和案例提供明确备用路径。从一个可测工作流开始，证明隐私边界，并只在每个成功任务的成本改善后扩大。 模型与基础设施 ## 继续浏览此集群 模型选择、推理经济性、本地部署、压缩与服务架构。 [从核心文章开始**在欧盟自托管 LLM：开放权重模型何时才真正划算**](/zh/blog/self-hosting-llms-eu-cost/) - [LiteLLM 生产级自托管指南：2026 架构与安全](/zh/blog/self-host-litellm-production-2026/) - [AI 就绪企业 Wiki：架构与实施指南](/zh/blog/ai-ready-company-wiki/) - [Claude 会给文本加水印吗？2026 API 实战解读](/zh/blog/claude-text-watermark-api-2026/) - [OpenKB 评测：知识编译器 vs RAG](/zh/blog/openkb-review-vs-rag/) - [Unsloth Desktop 评测：私有本地 AI 工作站？](/zh/blog/unsloth-desktop-local-ai-workstation-review/) 只收重要内容 ## 关注与你相关的内容 每当我们发布新文章，你会收到一封简短邮件。你可以关注整个博客，也可以只选感兴趣的主题。 [**返回**](/zh/blog/overview/) [![Kevin Riedl](/img/team/kevin.webp)](/zh/team/kevin-riedl/) [Kevin Riedl](/zh/team/kevin-riedl/) https://linkedin.com/in/wsdt 8 分钟 阅读 · 2026年8月15日 最近审核 2026年8月15日 [**下一篇**](/zh/blog/github-spec-kit-production-guide/) 邮件订阅新文章 × × 通过邮件获取新文章 我们发布时给你一封简短邮件。免费，不做跟踪。 ## Structured Data ```json { "@context": "https://schema.org", "@graph": [ { "@id": "https://wavect.io/#organization", "@type": [ "Organization", "ProfessionalService", "LocalBusiness" ], "employee": [ { "@id": "https://wavect.io/team/kevin-riedl/#person", "@type": "Person", "jobTitle": "Managing Director", "name": "Kevin Riedl", "url": "https://wavect.io/team/kevin-riedl/", "worksFor": { "@id": "https://wavect.io/#organization", "@type": [ "Organization", "ProfessionalService", "LocalBusiness" ] } }, { "@id": "https://wavect.io/team/christof-jori/#person", "@type": "Person", "jobTitle": "Managing Director", "name": "Christof Jori", "url": "https://wavect.io/team/christof-jori/", "worksFor": { "@id": "https://wavect.io/#organization", "@type": [ "Organization", "ProfessionalService", "LocalBusiness" ] } } ], "founder": [ { "@id": "https://wavect.io/team/kevin-riedl/#person", "@type": "Person", "jobTitle": "Managing Director", "name": "Kevin Riedl", "url": "https://wavect.io/team/kevin-riedl/", "worksFor": { "@id": "https://wavect.io/#organization", "@type": [ "Organization", "ProfessionalService", "LocalBusiness" ] } }, { "@id": "https://wavect.io/team/christof-jori/#person", "@type": "Person", "jobTitle": "Managing Director", "name": "Christof Jori", "url": "https://wavect.io/team/christof-jori/", "worksFor": { "@id": "https://wavect.io/#organization", "@type": [ "Organization", "ProfessionalService", "LocalBusiness" ] } } ], "legalRepresentative": [ { "@id": "https://wavect.io/team/kevin-riedl/#person", "@type": "Person", "jobTitle": "Managing Director", "name": "Kevin Riedl", "url": "https://wavect.io/team/kevin-riedl/", "worksFor": { "@id": "https://wavect.io/#organization", "@type": [ "Organization", "ProfessionalService", "LocalBusiness" ] } }, { "@id": "https://wavect.io/team/christof-jori/#person", "@type": "Person", "jobTitle": "Managing Director", "name": "Christof Jori", "url": "https://wavect.io/team/christof-jori/", "worksFor": { "@id": "https://wavect.io/#organization", "@type": [ "Organization", "ProfessionalService", "LocalBusiness" ] } } ], "name": "Wavect GmbH", "subjectOf": { "@id": "https://wavect.io/verified-claims.json#dataset", "@type": "Dataset", "creator": { "@id": "https://wavect.io/#organization", "@type": [ "Organization", "ProfessionalService", "LocalBusiness" ] }, "description": "A machine-readable registry of quantitative and qualitative claims published by Wavect, with review dates, localized page appearances and public third-party citations where available.", "inLanguage": "en", "isAccessibleForFree": true, "license": "https://creativecommons.org/licenses/by/4.0/", "name": "Wavect verified publication claims", "url": "https://wavect.io/verified-claims.json" }, "url": "https://wavect.io/" }, { "@id": "https://wavect.io/team/kevin-riedl/#person", "@type": "Person", "jobTitle": "Managing Director", "name": "Kevin Riedl", "sameAs": [ "https://www.wikidata.org/wiki/Q139796365", "https://www.linkedin.com/in/wsdt", "https://github.com/wsdt" ], "url": "https://wavect.io/team/kevin-riedl/", "worksFor": { "@id": "https://wavect.io/#organization", "@type": [ "Organization", "ProfessionalService", "LocalBusiness" ] } }, { "@id": "https://wavect.io/team/christof-jori/#person", "@type": "Person", "jobTitle": "Managing Director", "name": "Christof Jori", "sameAs": [ "https://www.wikidata.org/wiki/Q139796367", "https://www.linkedin.com/in/jocr77/", "https://github.com/jo-chris" ], "url": "https://wavect.io/team/christof-jori/", "worksFor": { "@id": "https://wavect.io/#organization", "@type": [ "Organization", "ProfessionalService", "LocalBusiness" ] } }, { "@id": "https://wavect.io/#website", "@type": "WebSite", "inLanguage": [ "en", "de", "es", "zh" ], "name": "Wavect", "potentialAction": { "@type": "SearchAction", "query-input": "required name=search_term_string", "target": { "@type": "EntryPoint", "urlTemplate": "https://wavect.io/search/?q={search_term_string}" } }, "publisher": { "@id": "https://wavect.io/#organization", "@type": [ "Organization", "ProfessionalService", "LocalBusiness" ] }, "url": "https://wavect.io/" }, { "@id": "https://wavect.io/zh/blog/transformers-js-browser-ai-guide/#webpage", "@type": "WebPage", "dateModified": "2026-08-15", "inLanguage": "zh", "isPartOf": { "@id": "https://wavect.io/#website", "@type": "WebSite" }, "lastReviewed": "2026-08-15", "url": "https://wavect.io/zh/blog/transformers-js-browser-ai-guide/" } ] } ``` ```json { "@context": "https://schema.org", "@type": "BlogPosting", "abstract": "Transformers.js 可以让受支持的 AI 推理留在用户设备上，避免逐次模型 API 费用，并在完整缓存后离线运行，但成本会转移到下载、用户设备计算和产品工程。当前和旧 npm 包在截至 2026 年 8 月 9 日的 30 天内合计下载 10,694,755 次，约为六个月前可比窗口的 4.7 倍。适合的生产场景包括 embedding、分类、PII 检测、文档、视觉和语音任务。生产方案需要 Web Worker、固定模型资源、可见的下载与缓存控制、任务评测、隐私检查、WebGPU 能力检测、经过测试的 WASM 或 API 备用路径，以及受控发布。", "articleBody": " 博客概览/AI 与智能体/模型与基础设施 Transformers.js 浏览器本地 AI：什么时候适合放进产品 要点速览 Transformers.js 可以让受支持的 AI 推理留在用户设备上，避免逐次模型 API 费用，并在完整缓存后离线运行，但成本会转移到下载、用户设备计算和产品工程。当前和旧 npm 包在截至 2026 年 8 月 9 日的 30 天内合计下载 10,694,755 次，约为六个月前可比窗口的 4.7 倍。适合的生产场景包括 embedding、分类、PII 检测、文档、视觉和语音任务。生产方案需要 Web Worker、固定模型资源、可见的下载与缓存控制、任务评测、隐私检查、WebGPU 能力检测、经过测试的 WASM 或 API 备用路径，以及受控发布。 当 AI 任务边界明确、用户可以接受首次模型下载，而且文本、图片或音频不应发送到推理 API 时，Transformers.js 已经是可靠的生产候选。模型缓存后可以离线运行，不再为每次推理支付 API 费用，并让输入留在设备上。但它不是通用的云端替代方案。用户仍要承担带宽、内存、电量和硬件成本，产品团队仍要负责模型质量、浏览器兼容性、许可证、隐私边界和备用路径。 本文只负责客户端架构决策。如果要比较服务器或私有云的经济性，请阅读本地模型与 API 盈亏平衡计算指南。如果要评估手机硬件上的具体压缩模型，请阅读Bonsai 27B 端侧评测。明确划分搜索意图，可以避免本文与自托管和硬件适配页面互相竞争。 一分钟了解 Transformers.js，2026 年 8 月 15 日复核 问题简短答案商业含义 它是什么？通过 ONNX Runtime 在浏览器和 JavaScript 运行时执行受支持 Hugging Face 模型的库不用把每次推理都变成服务器请求 推理私密吗？推理可以留在设备上，但应用的其他数据路径不会自动消失隐私是整个系统的属性 免费吗？本地推理没有按 token 收取的模型 API 费工程、下载、支持、测试和用户设备计算仍有成本 生产模式是什么？Web Worker、能力检测、量化模型、缓存、评测和备用路径按最弱的受支持设备设计，不按发布演示设计 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 都是独立的数据路径。 首次加载：JavaScript、运行时、tokenizer 和模型权重进入设备。 缓存：浏览器可以保存资源，供重复访问和离线使用。 推理：WebGPU 或 WebAssembly 在设备上处理输入。 应用逻辑：只有你的代码不再传输结果，结果才真正留在本地。 备用路径：云端路由会把数据送出设备，需要明确政策和用户提示。 官方自定义模型指南说明了如何设置本地模型路径、禁用远程模型，并从自己的 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？ 因素浏览器中的 Transformers.js托管 API 可变成本资源交付后没有逐次模型费用按用量或预留容量收费 首次体验模型下载和编译可能明显客户端很小，但每次任务都要网络往返 敏感输入可以留在设备上在合同和供应商控制下离开设备 一致性受浏览器、GPU、内存、温度和电量影响基础设施更可控 模型上限适合小模型或精心量化的模型适合 frontier 和超大模型 离线完整缓存后可以实现通常不可用 模型保密交付的权重可以被检查权重可以留在服务端 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 覆盖更广，但会改变性能和模型选择。支持矩阵必须基于真实客户设备。 生产架构检查清单 定义一个任务、目标用户、输入边界和质量门槛。 固定库、模型、tokenizer、量化、运行时、许可证和文件 hash。 展示下载大小、进度、存储、取消、重试和清理缓存。 在 Web Worker 中加载和执行模型。 按能力路由，不按浏览器名称路由。 用任务评测比较本地路径、备用路径和现有系统。 检查网络请求、分析、日志、错误报告和云端切换。 先 opt-in 发布，并测量下载完成率、p50、p95、错误、电量反馈和升级率。 保留旧模型和 API 路由，以便回滚。 一个 30 天试点 周交付物决策门 1用例、评测集、设备矩阵、隐私数据流是否存在合理的小模型候选？ 2WebGPU 和 WASM Worker 原型、下载与缓存体验延迟和内存是否达标？ 3本地资源、网络检查、许可证、API 备用路径团队能否证明隐私和恢复能力？ 4Opt-in 用户组和每个成功任务的成本扩大、保持混合、换模型还是停止？ Transformers.js 常见问题 Transformers.js 可以免费商用吗？ 库本身使用 Apache 2.0。每个模型都有自己的许可证和使用条件。商业批准必须覆盖确切模型 revision、数据和应用义务。 Transformers.js 完全私密吗？ 推理可以留在本地，但模型下载、分析、日志、错误报告、云端备用和其他脚本仍是网络路径，必须测试并告知用户。 Transformers.js 支持所有浏览器吗？ WebAssembly 覆盖较广，WebGPU 更快但并非统一可用。生产应用需要能力检测、经过测试的备用路径和目标设备矩阵。 Transformers.js 能运行大语言模型吗？ 可以。版本 4 支持超过 8B 参数的模型。M4 Pro Max 上的结果不能代表普通客户设备，下载、内存、延迟、发热和质量都要测量。 浏览器 AI 什么时候比 API 更便宜？ 通常是重复用户、高任务量、边界明确、小模型、热缓存，并达到同一质量门槛时。其他情况往往适合 API 或混合架构。 最终思考 Transformers.js 已经从醒目的浏览器演示成长为可信的产品基础设施。更好的架构会在隐私、离线、延迟和重复任", "articleSection": "工程实践", "author": { "@id": "https://wavect.io/team/kevin-riedl/#person", "@type": "Person", "name": "Kevin Riedl", "sameAs": [ "https://www.wikidata.org/wiki/Q139796365", "https://www.linkedin.com/in/wsdt", "https://github.com/wsdt" ], "url": "https://wavect.io/team/kevin-riedl/" }, "citation": [ { "@type": "WebPage", "name": "@huggingface/transformers 下载 8,251,156 次", "url": "https://api.npmjs.org/downloads/point/2026-07-11:2026-08-09/%40huggingface%2Ftransformers" }, { "@type": "WebPage", "name": "旧包 @xenova/transformers 下载 2,443,599 次", "url": "https://api.npmjs.org/downloads/point/2026-07-11:2026-08-09/%40xenova%2Ftransformers" }, { "@type": "WebPage", "name": "当前包下载 1,113,605 次", "url": "https://api.npmjs.org/downloads/point/2026-01-11:2026-02-09/%40huggingface%2Ftransformers" }, { "@type": "WebPage", "name": "旧包下载 1,158,603 次", "url": "https://api.npmjs.org/downloads/point/2026-01-11:2026-02-09/%40xenova%2Ftransformers" }, { "@type": "WebPage", "name": "Hugging Face 发布的 Transformers.js v4", "url": "https://huggingface.co/blog/transformersjs-v4" }, { "@type": "WebPage", "name": "Transformers.js 4.2.0 是当前稳定版", "url": "https://github.com/huggingface/transformers.js/releases/tag/4.2.0" }, { "@type": "WebPage", "name": "官方自定义模型指南", "url": "https://huggingface.co/docs/transformers.js/main/en/custom_usage" }, { "@type": "WebPage", "name": "Hugging Face 只在服务端环境支持私有或 gated 模型 token", "url": "https://huggingface.co/docs/transformers.js/en/guides/private" }, { "@type": "WebPage", "name": "ONNX Runtime Web 部署指南", "url": "https://onnxruntime.ai/docs/tutorials/web/" }, { "@type": "WebPage", "name": "MDN 仍把 WebGPU 标为有限可用", "url": "https://developer.mozilla.org/en-US/docs/Web/API/WebGPU_API" } ], "dateModified": "2026-08-15", "datePublished": "2026-08-15", "description": "Transformers.js 可以让受支持的 AI 推理留在用户设备上，避免逐次模型 API 费用，并在完整缓存后离线运行，但成本会转移到下载、用户设备计算和产品工程。当前和旧 npm 包在截至 2026 年 8 月 9 日的 30 天内合计下载 10,694,755 次，约为六个月前可比窗口的 4.7 倍。适合的生产场景包括 embedding、分类、PII 检测、文档、视觉和语音任务。生产方案需要 Web Worker、固定模型资源、可见的下载与缓存控制、任务评测、隐私检查、WebGPU 能力检测、经过测试的 WASM 或 API 备用路径，以及受控发布。", "headline": "Transformers.js 浏览器本地 AI：什么时候适合放进产品", "image": "https://wavect.io/img/blog/headers/header_transformers-js-browser-ai-guide.svg", "inLanguage": "zh", "keywords": "浏览器 AI, AI 工程", "mainEntityOfPage": { "@id": "https://wavect.io/zh/blog/transformers-js-browser-ai-guide/", "@type": "WebPage" }, "publisher": { "@id": "https://wavect.io/#organization", "@type": [ "Organization", "ProfessionalService", "LocalBusiness" ] }, "url": "https://wavect.io/zh/blog/transformers-js-browser-ai-guide/", "wordCount": 514 } ``` ```json { "@context": "https://schema.org", "@type": "BreadcrumbList", "itemListElement": [ { "@type": "ListItem", "item": "https://wavect.io/zh/", "name": "首页", "position": 1 }, { "@type": "ListItem", "item": "https://wavect.io/zh/blog/overview/", "name": "博客概览", "position": 2 }, { "@type": "ListItem", "item": "https://wavect.io/zh/blog/topics/ai-agents/", "name": "AI 与智能体", "position": 3 }, { "@type": "ListItem", "item": "https://wavect.io/zh/blog/clusters/models-infrastructure/", "name": "模型与基础设施", "position": 4 }, { "@type": "ListItem", "item": "https://wavect.io/zh/blog/transformers-js-browser-ai-guide/", "name": "Transformers.js 浏览器本地 AI：隐私、成本与生产部署 | ", "position": 5 } ] } ``` ```json { "@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [ { "@type": "Question", "acceptedAnswer": { "@type": "Answer", "text": "库本身使用 Apache 2.0。每个模型都有自己的许可证和使用条件。商业批准必须覆盖确切模型 revision、数据和应用义务。" }, "name": "Transformers.js 可以免费商用吗？" }, { "@type": "Question", "acceptedAnswer": { "@type": "Answer", "text": "推理可以留在本地，但模型下载、分析、日志、错误报告、云端备用和其他脚本仍是网络路径，必须测试并告知用户。" }, "name": "Transformers.js 完全私密吗？" }, { "@type": "Question", "acceptedAnswer": { "@type": "Answer", "text": "WebAssembly 覆盖较广，WebGPU 更快但并非统一可用。生产应用需要能力检测、经过测试的备用路径和目标设备矩阵。" }, "name": "Transformers.js 支持所有浏览器吗？" }, { "@type": "Question", "acceptedAnswer": { "@type": "Answer", "text": "可以。版本 4 支持超过 8B 参数的模型。M4 Pro Max 上的结果不能代表普通客户设备，下载、内存、延迟、发热和质量都要测量。" }, "name": "Transformers.js 能运行大语言模型吗？" }, { "@type": "Question", "acceptedAnswer": { "@type": "Answer", "text": "通常是重复用户、高任务量、边界明确、小模型、热缓存，并达到同一质量门槛时。其他情况往往适合 API 或混合架构。" }, "name": "浏览器 AI 什么时候比 API 更便宜？" } ] } ```