企业官网建设流程全解析

Transformers.js 自定义使用指南：模型本地化、离线运行与 ONNX 转换全配置

【免费下载链接】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）的“自定义使用（Custom Usage）”主题展开，完整讲解如何通过全局环境对象env指定模型本地路径、禁用远程模型下载、自定义 ONNX Runtime WASM 二进制位置，以及如何使用 Optimum 将自有 PyTorch 模型转换为 ONNX 格式。读完本文，你将掌握在浏览器与 Node.js 环境中配置模型加载来源、实现完全离线推理，以及接入自有模型的完整实战方案。

背景：默认行为与自定义切入点

Transformers.js 的设计目标是“开箱即用”：默认情况下，它会从 Hugging Face Hub 加载托管的预训练模型（支持 transformers.js 库格式的模型仓库），并从 CDN 加载预编译的 ONNX Runtime WASM 二进制文件。这一默认链路在浏览器和 Node.js 环境下均无需任何配置即可工作。

但在实际项目中，我们往往需要打破这一默认行为：

• 模型文件需要部署在自有服务器或 CDN，而非依赖 Hub；
• 出于离线、内网或隐私要求，需要完全禁用远程模型下载；
• 自建环境需要把.wasm运行时文件托管到指定位置（如规避 CDN 不可达、加速加载）；
• 需要将自己训练的 PyTorch 模型接入 Transformers.js。

所有这些自定义能力都通过env全局对象暴露，其定义位于 src/env.js，是整个库的“配置中心”。官方文档 custom_usage.md 正是围绕这一主题展开。

核心设置项：三行代码搞定最常见的自定义需求

文档给出的自定义配置非常精简，只需从@huggingface/transformers导入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是全局单例，所有字段都应在首次加载模型（调用pipeline()或直接实例化模型类）之前设置，否则配置不会生效。

下面逐一拆解这三个字段的行为与底层实现。

env.localModelPath：模型文件的本地根路径

默认值在源码中定义：

// src/env.js const DEFAULT_LOCAL_MODEL_PATH = '/models/';

在浏览器环境下，默认值就是/models/（相对站点根路径），意味着模型目录默认从站点的/models/路径加载；在 Node.js 等具备文件系统的环境中，默认值会被拼接到库安装目录下。

本地模型目录的组织结构遵循 Hub 仓库布局，例如模型onnx-community/bert-base-uncased的本地路径应为：

/path/to/models/onnx-community/bert-base-uncased/ ├── config.json ├── tokenizer.json ├── tokenizer_config.json └── onnx/ ├── model.onnx └── model_quantized.onnx

在 src/utils/hub.js 的buildResourcePaths中可以看到本地路径的拼接逻辑：当传入的path_or_repo_id是合法的 Hub 模型 ID 时，localPath由env.localModelPath与模型ID/文件名拼接而成；如果传入的本身就是绝对路径或 URL，则直接使用该路径。

env.allowRemoteModels：是否允许远程模型

默认值为true。设置为false后，效果等同于在加载pipeline、模型、分词器、处理器等时传入了local_files_only=true——即完全禁止向远程发起模型文件请求。

这一行为在源码中有清晰的错误分支支撑。在getModelFile（hub.js 的getModelFile函数）中：

if (!env.allowLocalModels) { // 本地模型也被禁用时的配置合法性检查 if (options.local_files_only) { throw Error('... local models are disabled ... but you have requested to only use local models ...'); } else if (!env.allowRemoteModels) { throw Error( 'Invalid configuration detected: both local and remote models are disabled. Fix by setting `env.allowLocalModels` or `env.allowRemoteModels` to `true`.', ); } }

在loadResourceFile中，当本地查找失败且!env.allowRemoteModels时，会抛出错误：`env.allowRemoteModels=false`, but attempted to load a remote file from: ${requestURL}.。由此可以确认：

• env.allowRemoteModels = false意味着本地文件是唯一数据来源，若本地缺失对应文件，加载将直接失败并给出明确报错；
• 测试 tests/configs.test.js 首行即设置env.allowLocalModels = false，验证了在仅远程模式下跳过本地检查的行为路径。

env.backends.onnx.wasm.wasmPaths：WASM 运行时位置

ONNX Runtime 的 WebAssembly 后端需要加载两类文件：.wasm二进制与.mjs（WASM factory）。默认情况下，Transformers.js 在非 Service Worker 环境下会自动将wasmPaths指向 jsDelivr CDN 上与当前 onnxruntime-web 版本匹配的构建产物（见 src/backends/onnx.js）：

const wasmPathPrefix = `https://cdn.jsdelivr.net/npm/onnxruntime-web@${ONNX_ENV.versions.web}/dist/`; let wasmPathSuffix = '.asyncify'; // 默认使用 asyncify 构建 // Safari 低于 26 且无 WebGPU 时回退到非 asyncify 构建 ONNX_ENV.wasm.wasmPaths = { mjs: `${wasmPathPrefix}ort-wasm-simd-threaded${wasmPathSuffix}.mjs`, wasm: `${wasmPathPrefix}ort-wasm-simd-threaded${wasmPathSuffix}.wasm`, };

因此你可以用字符串路径直接覆盖（如文档示例/path/to/files/），也可以进一步指定对象形式，分别指向.wasm与.mjs文件，例如：

env.backends.onnx.wasm.wasmPaths = { wasm: '/wasm/ort-wasm-simd-threaded.asyncify.wasm', mjs: '/wasm/ort-wasm-simd-threaded.asyncify.mjs', };

将 WASM 文件自托管的好处包括：规避公共 CDN 的可用性与速度问题、满足离线部署要求、便于自定义构建（如精简指令集或线程策略）。此外，src/backends/onnx.js 中还默认将ONNX_ENV.wasm.proxy = false（WebGPU 场景下无需代理），并默认设置 WebGPU 的powerPreference = 'high-performance'，这些也可以通过env.backends.onnx覆盖。

模型加载的完整链路：理解配置如何生效

要真正用好自定义配置，有必要理解模型文件的解析与加载流程。核心逻辑集中在 src/utils/hub.js：

1. 路径构建（buildResourcePaths）：根据path_or_repo_id与文件名同时计算本地路径localPath、远程 URLremoteURL与缓存键。远程 URL 由env.remoteHost（默认https://huggingface.co/）与env.remotePathTemplate（默认{model}/resolve/{revision}/）模板填充得到。
2. 缓存检查（checkCachedResource）：先尝试从缓存命中，命中则直接返回，避免重复下载。
3. 本地尝试：若env.allowLocalModels为true（浏览器/Web Worker 默认false，Node.js 等默认true），先尝试从env.localModelPath读取；读不到且不允许远程时才报错。
4. 远程回退：本地失败后，若模型 ID 合法（validModelId），从远程 URL 下载并写入缓存。

因此，完全离线部署的正确组合是：

env.allowRemoteModels = false; // 禁止远程 env.localModelPath = '/models/'; // 指向部署好的本地模型

若还需关闭本地文件系统/缓存访问，可进一步配合env.useFS、env.useBrowserCache、env.useFSCache等字段精细控制。

更多可用的env配置项

官方文档指引读者查阅 API Reference 获取完整列表；结合 src/env.js 的实现，以下几个高价值字段值得重点说明：

自定义缓存示例（在 tests/utils/custom_cache.test.js 中有完整可运行实现）：只需实现match与put两个方法，例如用一个内存Map承接，然后在加载前挂载：

env.useCustomCache = true; env.customCache = { async match(request) { /* 返回缓存的 Response 或 undefined */ }, async put(request, response) { /* 写入缓存 */ }, };

该测试文件同时演示了测试前后保存/恢复env原始值的良好实践，供你在自己项目中参考。

日志级别配置（源码 src/env.js 中的示例）：

import { env, LogLevel } from '@huggingface/transformers'; env.logLevel = LogLevel.ERROR; // 只显示错误 env.logLevel = LogLevel.INFO; // 显示错误、警告与信息 env.logLevel = LogLevel.NONE; // 完全关闭日志

env.logLevel是 getter/setter：设置时会通过env.backends.onnx.setLogLevel同步到 ONNX Runtime，保证两套日志级别一致。

将自有 PyTorch 模型转换为 ONNX

自定义使用的另一半核心工作是“接入自己的模型”。官方推荐使用Optimum（huggingface/optimum-onnx 仓库）以单条命令完成 PyTorch → ONNX 转换：

optimum-cli export onnx --model <模型ID或本地目录路径> <输出目录>

关键要点：

• --model既可以是 Hub 上的模型 ID，也可以是本地模型目录路径；
• 输出目录中会生成model.onnx（以及可选的量化版本model_quantized.onnx）与配套配置；
• 支持转换的架构范围取决于 Optimum 对对应架构的 ONNX 导出支持情况，接入前建议先确认目标架构是否在支持列表中；
• 转换产物应按照“本地模型目录组织”一节的结构放置，再通过env.localModelPath指向部署目录，即可被 Transformers.js 直接加载。

转换完成后，推荐同时验证模型在目标环境（浏览器或 Node.js）中能否正确加载与推理，确保config.json、分词器等配套文件齐全。

实际部署场景组合速查

场景一：浏览器完全离线（模型与 WASM 均本地托管）

import { env } from '@huggingface/transformers'; env.allowRemoteModels = false; env.localModelPath = '/models/'; env.backends.onnx.wasm.wasmPaths = '/wasm/';

场景二：Node.js 使用本地文件系统模型

import { env } from '@huggingface/transformers'; env.allowRemoteModels = false; // 只读本地 env.localModelPath = '/opt/models/'; // 绝对路径 env.useFSCache = true; // 使用文件系统缓存（默认即开启）

场景三：私有模型服务器（不依赖 Hugging Face Hub）

env.remoteHost = 'https://models.example.com/'; // 若私有服务器的 URL 结构与 Hub 不同，可自定义模板： env.remotePathTemplate = '{model}/revision/{revision}/';

场景四：仅远程、禁止本地回退（服务端/CDN 场景）

env.allowLocalModels = false; // 跳过本地检查，直接走远程

总结

自定义使用是 Transformers.js 从“演示可用”走向“生产可用”的关键环节。通过env上的少量配置，即可：

1. 将模型与 ONNX Runtime WASM 全部本地化/自托管，摆脱对公共 CDN 与 Hub 的依赖；
2. 通过allowRemoteModels、allowLocalModels、useFS、useBrowserCache、useFSCache、customCache等字段精确控制数据来源与缓存策略；
3. 配合 Optimum 将自有 PyTorch 模型转换为 ONNX，无缝接入 Transformers.js 的加载链路。

上述所有配置的行为均有源码与测试佐证：配置定义见 src/env.js，加载链路见 src/utils/hub.js，WASM 后端初始化见 src/backends/onnx.js，行为验证参考 tests/configs.test.js 与 tests/utils/custom_cache.test.js。配置全部就位后，再通过 pipelines.md 所描述的pipeline()API 即可完成端到端推理。

【免费下载链接】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