企业官网建设流程全解析

环境配置参考

使用env对象配置 Transformers.js 行为的完整指南。

目录

1. 概述
2. 远程模型配置
3. 本地模型配置
4. 缓存配置
5. WASM 配置
6. 网络与日志控制
7. 常见配置模式
8. 环境最佳实践

概述

env对象提供对 Transformers.js 执行、缓存和模型加载的全面控制：

import{env}from'@huggingface/transformers';// 查看当前版本console.log(env.version);// 例如 '4.x'

可用属性

interfaceTransformersEnvironment{// 版本信息version:string;// 后端配置backends:{onnx:Partial<ONNXEnv>;};// 远程模型设置allowRemoteModels:boolean;remoteHost:string;remotePathTemplate:string;// 本地模型设置allowLocalModels:boolean;localModelPath:string;useFS:boolean;// 缓存设置useBrowserCache:boolean;useFSCache:boolean;cacheDir:string|null;useCustomCache:boolean;customCache:CacheInterface|null;useWasmCache:boolean;cacheKey:string;// 网络与日志（v4）fetch:typeofglobalThis.fetch;logLevel:LogLevel;}

远程模型配置

控制如何从远程源加载模型（默认：Hugging Face Hub）。

禁用远程加载

import{env}from'@huggingface/transformers';// 强制仅本地模式（无网络请求）env.allowRemoteModels=false;

使用场景：离线应用、安全要求或隔离环境。

自定义模型主机

import{env}from'@huggingface/transformers';// 使用你自己的 CDN 或模型服务器env.remoteHost='https://cdn.example.com/models';// 自定义 URL 模式// 默认：'{model}/resolve/{revision}/{file}'env.remotePathTemplate='custom/{model}/{file}';

使用场景：自托管模型、使用 CDN 加快下载速度或企业代理。

示例：私有模型服务器

import{env,pipeline}from'@huggingface/transformers';// 配置自定义模型主机env.remoteHost='https://models.mycompany.com';env.remotePathTemplate='{model}/{file}';// 模型将从以下地址加载：// https://models.mycompany.com/my-model/model.onnxconstpipe=awaitpipeline('sentiment-analysis','my-model');

本地模型配置

控制从本地文件系统加载模型。

启用本地模型

import{env}from'@huggingface/transformers';// 启用本地文件系统加载env.allowLocalModels=true;// 设置本地模型的基础路径env.localModelPath='/path/to/models/';

默认值：

• 浏览器：allowLocalModels = false、localModelPath = '/models/'
• Node.js：allowLocalModels = true、localModelPath = '/models/'

文件系统控制

import{env}from'@huggingface/transformers';// 完全禁用文件系统使用（仅 Node.js）env.useFS=false;

示例：本地模型目录结构

/app/models/ ├── onnx-community/ │ ├── Supertonic-TTS-ONNX/ │ │ ├── config.json │ │ ├── tokenizer.json │ │ ├── model.onnx │ │ └── ... │ └── yolo26l-pose-ONNX/ │ ├── config.json │ ├── preprocessor_config.json │ ├── model.onnx │ └── ...

env.allowLocalModels=true;env.localModelPath='/app/models/';env.allowRemoteModels=false;// 离线模式constclassifier=awaitpipeline('sentiment-analysis','Xenova/distilbert-base-uncased-finetuned-sst-2-english');

缓存配置

Transformers.js 支持多种缓存策略以提高性能并减少网络使用。

快速配置

import{env}from'@huggingface/transformers';// 浏览器缓存（Cache API）env.useBrowserCache=true;// 默认：trueenv.cacheKey='my-app-transformers-cache';// 默认：'transformers-cache'// Node.js 文件系统缓存env.useFSCache=true;// 默认：trueenv.cacheDir='./custom-cache-dir';// 默认：'./.cache'// 自定义缓存实现env.useCustomCache=true;env.customCache=newCustomCache();// 实现 Cache API 接口// WASM 二进制缓存env.useWasmCache=true;// 默认：true

禁用缓存

import{env}from'@huggingface/transformers';// 禁用所有缓存（每次加载重新下载）env.useFSCache=false;env.useBrowserCache=false;env.useWasmCache=false;env.cacheDir=null;

全面的缓存文档包括：

• 浏览器 Cache API 细节和存储限制
• Node.js 文件系统缓存结构和维护
• 自定义缓存实现（Redis、数据库、S3）
• 缓存清除和监控策略
• 最佳实践和故障排除

参见**缓存参考**

WASM 配置

配置 ONNX Runtime Web Assembly 后端设置。

基本 WASM 设置

import{env}from'@huggingface/transformers';// 设置自定义 WASM 路径env.backends.onnx.wasm.wasmPaths='https://cdn.jsdelivr.net/npm/onnxruntime-web/dist/';// 配置线程数（仅 Node.js）env.backends.onnx.wasm.numThreads=4;// 启用/禁用 SIMD（单指令多数据）env.backends.onnx.wasm.simd=true;

代理配置

import{env}from'@huggingface/transformers';// 为 WASM 下载配置代理env.backends.onnx.wasm.proxy=true;

自托管 WASM 文件

import{env}from'@huggingface/transformers';// 在你自己的服务器上托管 WASM 文件env.backends.onnx.wasm.wasmPaths='/static/wasm/';

所需文件：

• ort-wasm.wasm- 主 WASM 二进制
• ort-wasm-simd.wasm- 启用 SIMD 的 WASM 二进制
• ort-wasm-threaded.wasm- 多线程 WASM 二进制
• ort-wasm-simd-threaded.wasm- SIMD + 多线程 WASM 二进制

网络与日志控制

Transformers.js v4 添加了用于认证获取和更干净的运行时日志的环境控制。

自定义 Fetch（env.fetch）

使用env.fetch注入认证头、重试、自定义路由或中止处理。

import{env}from'@huggingface/transformers';constHF_TOKEN=process.env.HF_TOKEN;env.fetch=(url,options)=>fetch(url,{...options,headers:{...options?.headers,Authorization:`Bearer${HF_TOKEN}`,},});

日志级别（env.logLevel）

使用env.logLevel覆盖运行时冗长程度。默认为LogLevel.WARNING。

import{env,LogLevel}from'@huggingface/transformers';// 开发期间启用更详细的日志env.logLevel=LogLevel.INFO;

常见值：

• LogLevel.DEBUG
• LogLevel.INFO
• LogLevel.WARNING
• LogLevel.ERROR
• LogLevel.NONE

ONNX Runtime 会话级日志控制，参见**Pipeline 选项**中的session_options。

常见配置模式

开发设置

import{env}from'@huggingface/transformers';// 带缓存的快速迭代env.allowRemoteModels=true;env.useBrowserCache=true;// 浏览器env.useFSCache=true;// Node.jsenv.cacheDir='./.cache';

生产环境（本地模型）

import{env}from'@huggingface/transformers';// 安全、支持离线的设置env.allowRemoteModels=false;env.allowLocalModels=true;env.localModelPath='/app/models/';env.useFSCache=false;// 模型已经是本地的

离线优先应用

import{env}from'@huggingface/transformers';// 先尝试本地，回退到远程env.allowLocalModels=true;env.localModelPath='./models/';env.allowRemoteModels=true;env.useFSCache=true;env.cacheDir='./cache';

自定义 CDN

import{env}from'@huggingface/transformers';// 使用你自己的模型托管env.remoteHost='https://cdn.example.com/ml-models';env.remotePathTemplate='{model}/{file}';env.useBrowserCache=true;

内存受限环境

import{env}from'@huggingface/transformers';// 最小化磁盘/内存使用env.useFSCache=false;env.useBrowserCache=false;env.useWasmCache=false;env.cacheDir=null;

测试/CI 环境

import{env}from'@huggingface/transformers';// 可预测、隔离的测试env.allowRemoteModels=false;env.allowLocalModels=true;env.localModelPath='./test-fixtures/models/';env.useFSCache=false;

环境最佳实践

1. 尽早配置

在加载任何模型之前设置env属性：

import{env,pipeline}from'@huggingface/transformers';// ✓ 好：在加载之前配置env.allowRemoteModels=false;env.localModelPath='/app/models/';constpipe=awaitpipeline('sentiment-analysis');// ✗ 差：加载后再配置可能不生效constpipe=awaitpipeline('sentiment-analysis');env.allowRemoteModels=false;// 太晚了！

2. 使用环境变量

import{env}from'@huggingface/transformers';// 基于环境配置env.allowRemoteModels=process.env.NODE_ENV==='development';env.cacheDir=process.env.MODEL_CACHE_DIR||'./.cache';env.localModelPath=process.env.LOCAL_MODELS_PATH||'/app/models/';

3. 优雅地处理错误

import{pipeline,env}from'@huggingface/transformers';try{env.allowRemoteModels=false;constpipe=awaitpipeline('sentiment-analysis','my-model');}catch(error){if(error.message.includes('not found')){console.error('Model not found locally. Enable remote models or download the model.');}throwerror;}

4. 记录配置

import{env}from'@huggingface/transformers';console.log('Transformers.js Configuration:',{version:env.version,allowRemoteModels:env.allowRemoteModels,allowLocalModels:env.allowLocalModels,localModelPath:env.localModelPath,cacheDir:env.cacheDir,useFSCache:env.useFSCache,useBrowserCache:env.useBrowserCache});

相关文档

• 缓存参考- 全面的缓存指南（浏览器、Node.js、自定义实现）
• Pipeline 选项 - 用progress_callback、device、dtype等配置 pipeline 加载
• 模型架构 - 支持的模型和架构
• 示例 - 不同运行时的代码示例
• 主技能指南 - 入门和常见用法