环境配置参考使用env对象配置 Transformers.js 行为的完整指南。目录概述远程模型配置本地模型配置缓存配置WASM 配置网络与日志控制常见配置模式环境最佳实践概述env对象提供对 Transformers.js 执行、缓存和模型加载的全面控制import{env}fromhuggingface/transformers;// 查看当前版本console.log(env.version);// 例如 4.x可用属性interfaceTransformersEnvironment{// 版本信息version:string;// 后端配置backends:{onnx:PartialONNXEnv;};// 远程模型设置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;// 网络与日志v4fetch:typeofglobalThis.fetch;logLevel:LogLevel;}远程模型配置控制如何从远程源加载模型默认Hugging Face Hub。禁用远程加载import{env}fromhuggingface/transformers;// 强制仅本地模式无网络请求env.allowRemoteModelsfalse;使用场景离线应用、安全要求或隔离环境。自定义模型主机import{env}fromhuggingface/transformers;// 使用你自己的 CDN 或模型服务器env.remoteHosthttps://cdn.example.com/models;// 自定义 URL 模式// 默认{model}/resolve/{revision}/{file}env.remotePathTemplatecustom/{model}/{file};使用场景自托管模型、使用 CDN 加快下载速度或企业代理。示例私有模型服务器import{env,pipeline}fromhuggingface/transformers;// 配置自定义模型主机env.remoteHosthttps://models.mycompany.com;env.remotePathTemplate{model}/{file};// 模型将从以下地址加载// https://models.mycompany.com/my-model/model.onnxconstpipeawaitpipeline(sentiment-analysis,my-model);本地模型配置控制从本地文件系统加载模型。启用本地模型import{env}fromhuggingface/transformers;// 启用本地文件系统加载env.allowLocalModelstrue;// 设置本地模型的基础路径env.localModelPath/path/to/models/;默认值浏览器allowLocalModels false、localModelPath /models/Node.jsallowLocalModels true、localModelPath /models/文件系统控制import{env}fromhuggingface/transformers;// 完全禁用文件系统使用仅 Node.jsenv.useFSfalse;示例本地模型目录结构/app/models/ ├── onnx-community/ │ ├── Supertonic-TTS-ONNX/ │ │ ├── config.json │ │ ├── tokenizer.json │ │ ├── model.onnx │ │ └── ... │ └── yolo26l-pose-ONNX/ │ ├── config.json │ ├── preprocessor_config.json │ ├── model.onnx │ └── ...env.allowLocalModelstrue;env.localModelPath/app/models/;env.allowRemoteModelsfalse;// 离线模式constclassifierawaitpipeline(sentiment-analysis,Xenova/distilbert-base-uncased-finetuned-sst-2-english);缓存配置Transformers.js 支持多种缓存策略以提高性能并减少网络使用。快速配置import{env}fromhuggingface/transformers;// 浏览器缓存Cache APIenv.useBrowserCachetrue;// 默认trueenv.cacheKeymy-app-transformers-cache;// 默认transformers-cache// Node.js 文件系统缓存env.useFSCachetrue;// 默认trueenv.cacheDir./custom-cache-dir;// 默认./.cache// 自定义缓存实现env.useCustomCachetrue;env.customCachenewCustomCache();// 实现 Cache API 接口// WASM 二进制缓存env.useWasmCachetrue;// 默认true禁用缓存import{env}fromhuggingface/transformers;// 禁用所有缓存每次加载重新下载env.useFSCachefalse;env.useBrowserCachefalse;env.useWasmCachefalse;env.cacheDirnull;全面的缓存文档包括浏览器 Cache API 细节和存储限制Node.js 文件系统缓存结构和维护自定义缓存实现Redis、数据库、S3缓存清除和监控策略最佳实践和故障排除参见**缓存参考**WASM 配置配置 ONNX Runtime Web Assembly 后端设置。基本 WASM 设置import{env}fromhuggingface/transformers;// 设置自定义 WASM 路径env.backends.onnx.wasm.wasmPathshttps://cdn.jsdelivr.net/npm/onnxruntime-web/dist/;// 配置线程数仅 Node.jsenv.backends.onnx.wasm.numThreads4;// 启用/禁用 SIMD单指令多数据env.backends.onnx.wasm.simdtrue;代理配置import{env}fromhuggingface/transformers;// 为 WASM 下载配置代理env.backends.onnx.wasm.proxytrue;自托管 WASM 文件import{env}fromhuggingface/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 添加了用于认证获取和更干净的运行时日志的环境控制。自定义 Fetchenv.fetch使用env.fetch注入认证头、重试、自定义路由或中止处理。import{env}fromhuggingface/transformers;constHF_TOKENprocess.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}fromhuggingface/transformers;// 开发期间启用更详细的日志env.logLevelLogLevel.INFO;常见值LogLevel.DEBUGLogLevel.INFOLogLevel.WARNINGLogLevel.ERRORLogLevel.NONEONNX Runtime 会话级日志控制参见**Pipeline 选项**中的session_options。常见配置模式开发设置import{env}fromhuggingface/transformers;// 带缓存的快速迭代env.allowRemoteModelstrue;env.useBrowserCachetrue;// 浏览器env.useFSCachetrue;// Node.jsenv.cacheDir./.cache;生产环境本地模型import{env}fromhuggingface/transformers;// 安全、支持离线的设置env.allowRemoteModelsfalse;env.allowLocalModelstrue;env.localModelPath/app/models/;env.useFSCachefalse;// 模型已经是本地的离线优先应用import{env}fromhuggingface/transformers;// 先尝试本地回退到远程env.allowLocalModelstrue;env.localModelPath./models/;env.allowRemoteModelstrue;env.useFSCachetrue;env.cacheDir./cache;自定义 CDNimport{env}fromhuggingface/transformers;// 使用你自己的模型托管env.remoteHosthttps://cdn.example.com/ml-models;env.remotePathTemplate{model}/{file};env.useBrowserCachetrue;内存受限环境import{env}fromhuggingface/transformers;// 最小化磁盘/内存使用env.useFSCachefalse;env.useBrowserCachefalse;env.useWasmCachefalse;env.cacheDirnull;测试/CI 环境import{env}fromhuggingface/transformers;// 可预测、隔离的测试env.allowRemoteModelsfalse;env.allowLocalModelstrue;env.localModelPath./test-fixtures/models/;env.useFSCachefalse;环境最佳实践1. 尽早配置在加载任何模型之前设置env属性import{env,pipeline}fromhuggingface/transformers;// ✓ 好在加载之前配置env.allowRemoteModelsfalse;env.localModelPath/app/models/;constpipeawaitpipeline(sentiment-analysis);// ✗ 差加载后再配置可能不生效constpipeawaitpipeline(sentiment-analysis);env.allowRemoteModelsfalse;// 太晚了2. 使用环境变量import{env}fromhuggingface/transformers;// 基于环境配置env.allowRemoteModelsprocess.env.NODE_ENVdevelopment;env.cacheDirprocess.env.MODEL_CACHE_DIR||./.cache;env.localModelPathprocess.env.LOCAL_MODELS_PATH||/app/models/;3. 优雅地处理错误import{pipeline,env}fromhuggingface/transformers;try{env.allowRemoteModelsfalse;constpipeawaitpipeline(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}fromhuggingface/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 加载模型架构 - 支持的模型和架构示例 - 不同运行时的代码示例主技能指南 - 入门和常见用法