企业官网建设流程全解析

Transformers.js 安装指南：从 NPM 到 CDN 的完整接入方案

【免费下载链接】transformers.jsState-of-the-art Machine Learning for the web. Run 🤗 Transformers directly in your browser, with no need for a server!项目地址: https://gitcode.com/GitHub_Trending/tr/transformers.js

本篇技术指南围绕 Transformers.js 官方安装文档 展开，系统讲解@huggingface/transformers在 Node.js 环境下的 NPM 安装方式、浏览器端零构建（vanilla JS）的 CDN 引入方式，并结合 package.json 与 env.js 源码，深入说明安装背后的模块导出机制、运行时环境探测与默认加载路径。读完本文，你将能在 Node.js 或浏览器环境中独立完成 Transformers.js 的安装、引入、验证与基础配置，跑通第一个端到端推理示例。

一、安装前须知：包结构与运行时支持

@huggingface/transformers当前版本为4.2.0（见 package.json 中version字段），是一个支持浏览器与 Node.js 双端运行的纯 JavaScript 机器学习库。它依赖 ONNX Runtime 在浏览器或 Node.js 中执行模型推理，安装时无需引入任何 Python 环境或后端服务。

从 package.json 的exports字段可以看出，该包针对不同运行环境提供了不同入口：

• Node.js 环境：通过node条件导出，ESM 使用./dist/transformers.node.mjs，CommonJS 使用./dist/transformers.node.cjs（同时main字段指向./dist/transformers.node.cjs，types字段指向./types/transformers.d.ts）；
• 浏览器等 Web 环境：通过default条件导出./dist/transformers.web.js，供打包器与浏览器直接消费。

同时，包的jsdelivr与unpkg字段均指向./dist/transformers.min.js，这是 CDN 引入时的默认入口。理解这一导出结构，有助于在安装后排查"装上了却无法 import"的问题——不同运行环境会命中不同的构建产物。

二、方式一：通过 NPM 安装（Node.js 场景）

在具备 Node.js 环境的项目中，运行以下命令即可安装：

npm i @huggingface/transformers

该命令会将包及其运行时依赖一并安装到node_modules。从 package.json 的dependencies字段可以看到，核心运行时依赖包括：

• onnxruntime-node（Node.js 侧推理后端）；
• onnxruntime-web（浏览器侧推理后端）；
• @huggingface/tokenizers与@huggingface/jinja（分词与模板渲染）；
• sharp（Node.js 场景下的图像处理）。

安装完成后，在项目代码中即可按 ESM 或 CommonJS 方式引入：

// ESM import { pipeline } from '@huggingface/transformers'; // CommonJS const { pipeline } = require('@huggingface/transformers');

包本身声明为"type": "module"，Node.js 环境下的 ESM 导入会命中dist/transformers.node.mjs，而 CommonJS 的require会命中dist/transformers.node.cjs，两种方式均被官方支持（对应 package.json 中的exports.node.import与exports.node.require）。

三、方式二：通过 CDN 引入（浏览器 / 无构建工具场景）

如果希望在纯前端页面中使用 Transformers.js，且不希望引入 npm、打包器（bundler）或任何构建步骤，可以直接通过 CDN 或静态文件托管方式加载。官方安装文档给出的标准做法是利用 ES Modules：

<script type="module"> import { pipeline } from 'https://cdn.jsdelivr.net/npm/@huggingface/transformers@4.2.0'; </script>

这一方式的要点：

• 版本固定：URL 中显式写明了@4.2.0版本号，避免因版本漂移导致的接口不一致；后续如需升级，只需修改版本号；
• ES Modules 原生支持：现代浏览器原生支持<script type="module">，无需任何构建工具；
• 默认入口：CDN 解析到的是包的jsdelivr/unpkg字段指定的dist/transformers.min.js（即 Web 构建产物），与浏览器环境匹配；
• 静态托管同样适用：如果项目本身部署在静态服务器上，也可以将构建产物下载到本地站点后按相对路径引入，效果等价。

需要注意的是，CDN 方式的产物面向浏览器 Web 环境。从 env.js 的运行时探测逻辑可以看到，库会通过typeof window、self、process、fs等 API 判断当前环境（浏览器、Web Worker、Service Worker、Node.js、Deno、Bun 等），并据此决定模型文件与 WASM 二进制从何处加载。因此在浏览器中，allowLocalModels默认会被设为false，模型默认从远程加载；而在 Node.js 中allowLocalModels默认开启，可直接读取本地文件系统。

四、安装后的快速验证：跑通第一个 pipeline

无论采用 NPM 还是 CDN 方式，安装成功后都可以用一行代码验证是否可用。以情感分析（sentiment-analysis）为例，对应官方快速上手示例（见 1_quick-tour.snippet）：

import { pipeline } from '@huggingface/transformers'; // 分配一个 sentiment-analysis pipeline const pipe = await pipeline('sentiment-analysis'); const out = await pipe('I love transformers!'); // [{'label': 'POSITIVE', 'score': 0.999817686}]

pipelineAPI 将"预训练模型 + 输入预处理 + 输出后处理"封装在一起，是最快捷的模型调用方式，与 Python 版 transformers 的用法保持一致。你也可以通过第二个参数指定任意模型 ID 或本地路径：

// 使用不同的模型 const pipe = await pipeline( 'sentiment-analysis', 'Xenova/bert-base-multilingual-uncased-sentiment', );

在资源受限的浏览器环境中，可通过dtype参数选择量化精度以降低带宽与内存占用，典型取值包括"fp32"（WebGPU 默认）、"fp16"、"q8"（WASM 默认）与"q4"：

const pipe = await pipeline('sentiment-analysis', 'Xenova/distilbert-base-uncased-finetuned-sst-2-english', { dtype: 'q4', });

五、安装后的关键配置：env 环境变量

安装完成后，Transformers.js 默认使用托管在 Hugging Face Hub 上的预训练模型与 CDN 上的预编译 WASM 二进制，开箱即用（详见 3_custom-usage.snippet 与 custom_usage.md）。如果需要对加载行为做定制，可以通过导出的env对象进行配置：

import { env } from '@huggingface/transformers'; // 指定自定义模型加载路径（默认 '/models/'） env.localModelPath = '/path/to/models/'; // 禁止从 Hugging Face Hub 加载远程模型 env.allowRemoteModels = false; // 设置 .wasm 文件位置（默认使用 CDN） env.backends.onnx.wasm.wasmPaths = '/path/to/files/';

从 env.js 源码可以看到env还提供了更丰富的配置项，常见的有：

这些配置在安装后即可生效，无需重新构建。若需要加载本地自有的 ONNX 模型，可配合 Optimum 系列工具将 PyTorch、TensorFlow 或 JAX 模型转换为 ONNX 格式后放入localModelPath指定目录。

六、从源码理解安装与加载链路

安装只是第一步，理解包的加载链路有助于排查问题。结合 package.json 与 env.js，可以梳理出以下关键机制：

1. 环境分流由 exports 完成。exports字段中的node与default两个条件分别指向不同的 dist 构建产物，Node.js 的模块解析器会根据运行环境自动选择，避免把浏览器专用代码引入 Node.js，也避免将 Node.js 专用的fs、path操作引入浏览器。

2. 运行时能力探测决定默认行为。env.js 在模块加载时即完成一系列环境探测：通过'caches' in self判断 Web Cache API 是否可用，通过process?.release?.name === 'node'判断是否为 Node.js，通过navigator.gpu判断 WebGPU 是否可用等。这些探测结果被冻结在导出的apis对象中，并直接决定useBrowserCache、useFSCache、allowLocalModels等默认值——这就是"同一份代码在不同环境行为不同"的根源。

3. WASM 与模型资源按需加载。浏览器端的 CPU 推理依赖 ONNX Runtime Web 的 WASM 二进制。默认情况下这些.wasm文件从 CDN 加载，你也可以通过env.backends.onnx.wasm.wasmPaths改为自有静态资源路径，这在离线部署或内网环境中尤为关键。

七、安装后的排错建议

结合上述机制，常见的安装与加载问题可按以下思路排查：

• 模块找不到或入口不对：确认安装版本为 4.2.0，并检查运行环境——Node.js 项目请确认exports解析正常；浏览器直接引入时，请确认使用的是带版本号的 CDN URL 或本地静态托管路径；
• 浏览器中加载不到模型：检查env.allowRemoteModels是否被误设为false，或网络环境是否允许访问remoteHost；内网环境请改用本地模型 +localModelPath；
• WASM 加载失败：确认env.backends.onnx.wasm.wasmPaths指向的目录确实存在.wasm文件，且静态服务器返回了正确的 MIME 类型；
• 日志排查：将env.logLevel临时调低（如LogLevel.DEBUG），可看到模型、权重与 WASM 资源的实际加载过程，快速定位是哪一步失败。

八、延伸阅读

• 安装与使用入口：installation.md、custom_usage.md
• 包导出与依赖声明：package.json
• 环境配置源码与完整参数说明：env.js
• 浏览器端 GPU 加速指南：webgpu.md
• 量化（dtype）使用指南：dtypes.md
• 仓库根 README 的安装章节：README.md

【免费下载链接】transformers.jsState-of-the-art Machine Learning for the web. Run 🤗 Transformers directly in your browser, with no need for a server!项目地址: https://gitcode.com/GitHub_Trending/tr/transformers.js