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

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.jshuggingface/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_onlytrue——即完全禁止向远程发起模型文件请求。这一行为在源码中有清晰的错误分支支撑。在getModelFilehub.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.allowRemoteModelsfalse, but attempted to load a remote file from: ${requestURL}.。由此可以确认env.allowRemoteModels false意味着本地文件是唯一数据来源若本地缺失对应文件加载将直接失败并给出明确报错测试 tests/configs.test.js 首行即设置env.allowLocalModels false验证了在仅远程模式下跳过本地检查的行为路径。env.backends.onnx.wasm.wasmPathsWASM 运行时位置ONNX Runtime 的 WebAssembly 后端需要加载两类文件.wasm二进制与.mjsWASM factory。默认情况下Transformers.js 在非 Service Worker 环境下会自动将wasmPaths指向 jsDelivr CDN 上与当前 onnxruntime-web 版本匹配的构建产物见 src/backends/onnx.jsconst 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 falseWebGPU 场景下无需代理并默认设置 WebGPU 的powerPreference high-performance这些也可以通过env.backends.onnx覆盖。模型加载的完整链路理解配置如何生效要真正用好自定义配置有必要理解模型文件的解析与加载流程。核心逻辑集中在 src/utils/hub.js路径构建buildResourcePaths根据path_or_repo_id与文件名同时计算本地路径localPath、远程 URLremoteURL与缓存键。远程 URL 由env.remoteHost默认https://huggingface.co/与env.remotePathTemplate默认{model}/resolve/{revision}/模板填充得到。缓存检查checkCachedResource先尝试从缓存命中命中则直接返回避免重复下载。本地尝试若env.allowLocalModels为true浏览器/Web Worker 默认falseNode.js 等默认true先尝试从env.localModelPath读取读不到且不允许远程时才报错。远程回退本地失败后若模型 ID 合法validModelId从远程 URL 下载并写入缓存。因此完全离线部署的正确组合是env.allowRemoteModels false; // 禁止远程 env.localModelPath /models/; // 指向部署好的本地模型若还需关闭本地文件系统/缓存访问可进一步配合env.useFS、env.useBrowserCache、env.useFSCache等字段精细控制。更多可用的env配置项官方文档指引读者查阅 API Reference 获取完整列表结合 src/env.js 的实现以下几个高价值字段值得重点说明字段默认值作用env.allowRemoteModelstrue是否允许从 Hub 加载远程文件env.remoteHosthttps://huggingface.co/模型远程下载的 Host 根地址可指向私有 Hub 镜像或自有服务器env.remotePathTemplate{model}/resolve/{revision}/远程路径模板{model}与{revision}会被实际值替换适合定制私有 Hub 的 URL 结构env.allowLocalModels浏览器默认falseNode.js 默认true是否尝试从本地路径加载文件env.localModelPath/models/本地模型根目录env.useFS文件系统可用时为true是否使用文件系统加载文件env.useBrowserCacheCache API 可用时为true是否使用浏览器 Cache API 缓存模型env.useFSCache文件系统可用时为true是否使用文件系统缓存文件env.cacheDir./.cacheNode.js文件系统缓存的目录env.useCustomCache/env.customCachefalse/null启用自定义缓存系统对象需实现 Web Cache API 的match与put接口env.useWasmCache缓存可用时为true是否预加载并缓存 WASM 二进制与 factory.mjs提升性能并支持离线env.cacheKeytransformers-cache缓存键前缀env.logLevelWARNING日志级别使用LogLevel枚举DEBUG/INFO/WARNING/ERROR/NONE对应数值 10–50设置时会同步映射到 ONNX Runtime 的日志级别env.fetch全局fetch自定义 fetch 函数可替换请求实现env.backends.onnx由 onnxruntime 填充透出 ONNX Runtime 的后端环境变量如wasm、webgpu相关配置自定义缓存示例在 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自定义使用的另一半核心工作是“接入自己的模型”。官方推荐使用Optimumhuggingface/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 Hubenv.remoteHost https://models.example.com/; // 若私有服务器的 URL 结构与 Hub 不同可自定义模板 env.remotePathTemplate {model}/revision/{revision}/;场景四仅远程、禁止本地回退服务端/CDN 场景env.allowLocalModels false; // 跳过本地检查直接走远程总结自定义使用是 Transformers.js 从“演示可用”走向“生产可用”的关键环节。通过env上的少量配置即可将模型与 ONNX Runtime WASM 全部本地化/自托管摆脱对公共 CDN 与 Hub 的依赖通过allowRemoteModels、allowLocalModels、useFS、useBrowserCache、useFSCache、customCache等字段精确控制数据来源与缓存策略配合 Optimum 将自有 PyTorch 模型转换为 ONNX无缝接入 Transformers.js 的加载链路。上述所有配置的行为均有源码与测试佐证配置定义见 src/env.js加载链路见 src/utils/hub.jsWASM 后端初始化见 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

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

相关推荐

Grist 关系型电子表格：完整指南，3 步 Docker 跑起来

微电网鲁棒优化：Matlab实现与不确定性管理

用 Atlas 系统优化解锁显卡性能：三步调优实战指南

更多资讯

Windmill 品牌与设计系统指南：从视觉规范到前端实现的设计语言

TigerBeetle Java 多笔两阶段转账实战：从 pending 预留到交替 post/void 的余额验证

172、MLIR的Deterministic（确定性）编译与调试