缓存参考Transformers.js 模型在不同环境中缓存策略的完整指南。目录概述浏览器缓存Node.js 缓存自定义缓存实现缓存配置概述Transformers.js 模型可能很大从几 MB 到数 GB因此缓存对性能至关重要。缓存策略因环境而异浏览器使用 Cache API浏览器缓存存储Node.js使用~/.cache/huggingface/中的文件系统缓存自定义实现你自己的缓存数据库、云存储等默认行为import{pipeline}fromhuggingface/transformers;// 首次加载下载模型constpipeawaitpipeline(sentiment-analysis);// 后续加载使用缓存模型constpipe2awaitpipeline(sentiment-analysis);// 快缓存是自动的默认启用。模型在首次下载后被缓存。浏览器缓存使用 Cache API在浏览器环境中Transformers.js 使用 Cache API 存储模型import{env,pipeline}fromhuggingface/transformers;// 浏览器缓存默认启用console.log(env.useBrowserCache);// true// 加载模型自动缓存constclassifierawaitpipeline(sentiment-analysis);工作原理模型文件从 Hugging Face Hub 下载文件存储在浏览器的 Cache Storage 中后续加载从缓存获取无网络请求缓存在页面刷新和浏览器会话之间持久化缓存位置浏览器缓存存储于Chrome/EdgeDevTools → Application 标签 → Cache storage 中的Cache StorageFirefoxabout:cache→ StorageSafariWeb Inspector → Storage 标签禁用浏览器缓存import{env}fromhuggingface/transformers;// 禁用浏览器缓存不推荐env.useBrowserCachefalse;// 每次页面加载都会重新下载模型使用场景测试、开发或调试缓存问题。浏览器存储限制浏览器施加存储配额Chrome约可用磁盘空间的 60%但可以驱逐数据Firefox约可用磁盘空间的 50%Safari每个源约 1GB更多会提示提示使用 Storage API 监控存储使用if(storageinnavigatorestimateinnavigator.storage){constestimateawaitnavigator.storage.estimate();constpercentUsed(estimate.usage/estimate.quota)*100;console.log(Storage:${percentUsed.toFixed(2)}% used);console.log(Available:${((estimate.quota-estimate.usage)/1024/1024).toFixed(2)}MB);}Node.js 缓存文件系统缓存在 Node.js 中模型被缓存到文件系统import{env,pipeline}fromhuggingface/transformers;// 默认缓存目录Node.jsconsole.log(env.cacheDir);// ./.cache相对于当前目录// 文件系统缓存默认启用console.log(env.useFSCache);// true// 加载模型缓存到磁盘constclassifierawaitpipeline(sentiment-analysis);默认缓存位置默认行为缓存目录./.cache相对于 Node.js 进程运行的位置使用 Hugging Face 工具时的完整默认路径~/.cache/huggingface/注意性能提示中模型自动缓存在~/.cache/huggingface/的说法是特指 Hugging Face Python 工具的约定。在 Transformers.js 的 Node.js 中默认是./.cache除非另行配置。自定义缓存目录import{env,pipeline}fromhuggingface/transformers;// 设置自定义缓存目录env.cacheDir/var/cache/transformers;// 或使用环境变量Node.js 约定env.cacheDirprocess.env.HF_HOME||~/.cache/huggingface;// 现在加载模型constclassifierawaitpipeline(sentiment-analysis);// 缓存到/var/cache/transformers/models--Xenova--distilbert-base-uncased-finetuned-sst-2-english/模式models--{organization}--{model-name}/禁用文件系统缓存import{env}fromhuggingface/transformers;// 禁用文件系统缓存不推荐env.useFSCachefalse;// 每次加载都会重新下载模型使用场景测试、CI/CD 环境或使用临时存储的容器。自定义缓存实现为专门的存储后端实现你自己的缓存。自定义缓存接口interfaceCacheInterface{/** * 检查 URL 是否已缓存 */match(url:string):PromiseResponse|undefined;/** * 存储 URL 及其响应 */put(url:string,response:Response):Promisevoid;}示例云存储缓存S3import{env,pipeline}fromhuggingface/transformers;import{S3Client,GetObjectCommand,PutObjectCommand}fromaws-sdk/client-s3;import{Readable}fromstream;classS3Cache{constructor(bucket,regionus-east-1){this.bucketbucket;this.s3newS3Client({region});}asyncmatch(url){constkeythis.urlToKey(url);try{constcommandnewGetObjectCommand({Bucket:this.bucket,Key:key});constresponseawaitthis.s3.send(command);// 将流转换为缓冲区constchunks[];forawait(constchunkofresponse.Body){chunks.push(chunk);}constbodyBuffer.concat(chunks);returnnewResponse(body,{status:200,headers:JSON.parse(response.Metadata.headers||{})});}catch(error){if(error.nameNoSuchKey)returnundefined;throwerror;}}asyncput(url,response){constkeythis.urlToKey(url);constclonedResponseresponse.clone();constbodyBuffer.from(awaitclonedResponse.arrayBuffer());constheadersJSON.stringify(Object.fromEntries(response.headers.entries()));constcommandnewPutObjectCommand({Bucket:this.bucket,Key:key,Body:body,Metadata:{headers}});awaitthis.s3.send(command);}urlToKey(url){// 将 URL 转换为 S3 键移除协议替换斜杠returnurl.replace(/^https?:\/\//,).replace(/\//g,_);}}// 配置 S3 缓存env.useCustomCachetrue;env.customCachenewS3Cache(my-transformers-cache,us-east-1);env.useFSCachefalse;// 使用 S3 缓存constclassifierawaitpipeline(sentiment-analysis);缓存配置环境变量使用环境变量配置缓存import{env}fromhuggingface/transformers;// 从环境配置缓存目录env.cacheDirprocess.env.TRANSFORMERS_CACHE||./.cache;// 在 CI/CD 中禁用缓存if(process.env.CItrue){env.useFSCachefalse;env.useBrowserCachefalse;}// 生产环境使用预缓存模型if(process.env.NODE_ENVproduction){env.allowRemoteModelsfalse;env.allowLocalModelstrue;env.localModelPathprocess.env.MODEL_PATH||/app/models;}配置模式开发启用所有缓存import{env}fromhuggingface/transformers;env.allowRemoteModelstrue;env.useFSCachetrue;// Node.jsenv.useBrowserCachetrue;// 浏览器env.cacheDir./.cache;生产仅本地模型import{env}fromhuggingface/transformers;env.allowRemoteModelsfalse;env.allowLocalModelstrue;env.localModelPath/app/models;env.useFSCachetrue;测试禁用缓存import{env}fromhuggingface/transformers;env.useFSCachefalse;env.useBrowserCachefalse;env.allowRemoteModelstrue;// 每次都下载混合缓存 远程回退import{env}fromhuggingface/transformers;// 先尝试本地缓存回退到远程env.allowRemoteModelstrue;env.allowLocalModelstrue;env.useFSCachetrue;env.localModelPath./models;总结Transformers.js 提供灵活的缓存选项浏览器Cache API自动、持久Node.js文件系统缓存默认./.cache可配置自定义实现你自己的数据库、云存储等要点缓存默认启用且自动在加载模型之前配置缓存浏览器使用 Cache APINode.js 使用文件系统自定义缓存支持高级存储后端监控缓存大小并实现清理策略为生产部署预下载模型更多配置选项参见配置参考Pipeline 选项