尧图网站建设 
Transformers.js 安装指南从 NPM 到 CDN 的完整接入方案【免费下载链接】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在 Node.js 环境下的 NPM 安装方式、浏览器端零构建vanilla JS的 CDN 引入方式并结合 package.json 与 env.js 源码深入说明安装背后的模块导出机制、运行时环境探测与默认加载路径。读完本文你将能在 Node.js 或浏览器环境中独立完成 Transformers.js 的安装、引入、验证与基础配置跑通第一个端到端推理示例。一、安装前须知包结构与运行时支持huggingface/transformers当前版本为4.2.0见 package.json 中version字段是一个支持浏览器与 Node.js 双端运行的纯 JavaScript 机器学习库。它依赖 ONNX Runtime 在浏览器或 Node.js 中执行模型推理安装时无需引入任何 Python 环境或后端服务。从 package.json 的exports字段可以看出该包针对不同运行环境提供了不同入口Node.js 环境通过node条件导出ESM 使用./dist/transformers.node.mjsCommonJS 使用./dist/transformers.node.cjs同时main字段指向./dist/transformers.node.cjstypes字段指向./types/transformers.d.ts浏览器等 Web 环境通过default条件导出./dist/transformers.web.js供打包器与浏览器直接消费。同时包的jsdelivr与unpkg字段均指向./dist/transformers.min.js这是 CDN 引入时的默认入口。理解这一导出结构有助于在安装后排查装上了却无法 import的问题——不同运行环境会命中不同的构建产物。二、方式一通过 NPM 安装Node.js 场景在具备 Node.js 环境的项目中运行以下命令即可安装npm i huggingface/transformers该命令会将包及其运行时依赖一并安装到node_modules。从 package.json 的dependencies字段可以看到核心运行时依赖包括onnxruntime-nodeNode.js 侧推理后端onnxruntime-web浏览器侧推理后端huggingface/tokenizers与huggingface/jinja分词与模板渲染sharpNode.js 场景下的图像处理。安装完成后在项目代码中即可按 ESM 或 CommonJS 方式引入// ESM import { pipeline } from huggingface/transformers; // CommonJS const { pipeline } require(huggingface/transformers);包本身声明为type: moduleNode.js 环境下的 ESM 导入会命中dist/transformers.node.mjs而 CommonJS 的require会命中dist/transformers.node.cjs两种方式均被官方支持对应 package.json 中的exports.node.import与exports.node.require。三、方式二通过 CDN 引入浏览器 / 无构建工具场景如果希望在纯前端页面中使用 Transformers.js且不希望引入 npm、打包器bundler或任何构建步骤可以直接通过 CDN 或静态文件托管方式加载。官方安装文档给出的标准做法是利用 ES Modulesscript typemodule import { pipeline } from https://cdn.jsdelivr.net/npm/huggingface/transformers4.2.0; /script这一方式的要点版本固定URL 中显式写明了4.2.0版本号避免因版本漂移导致的接口不一致后续如需升级只需修改版本号ES Modules 原生支持现代浏览器原生支持script typemodule无需任何构建工具默认入口CDN 解析到的是包的jsdelivr/unpkg字段指定的dist/transformers.min.js即 Web 构建产物与浏览器环境匹配静态托管同样适用如果项目本身部署在静态服务器上也可以将构建产物下载到本地站点后按相对路径引入效果等价。需要注意的是CDN 方式的产物面向浏览器 Web 环境。从 env.js 的运行时探测逻辑可以看到库会通过typeof window、self、process、fs等 API 判断当前环境浏览器、Web Worker、Service Worker、Node.js、Deno、Bun 等并据此决定模型文件与 WASM 二进制从何处加载。因此在浏览器中allowLocalModels默认会被设为false模型默认从远程加载而在 Node.js 中allowLocalModels默认开启可直接读取本地文件系统。四、安装后的快速验证跑通第一个 pipeline无论采用 NPM 还是 CDN 方式安装成功后都可以用一行代码验证是否可用。以情感分析sentiment-analysis为例对应官方快速上手示例见 1_quick-tour.snippetimport { pipeline } from huggingface/transformers; // 分配一个 sentiment-analysis pipeline const pipe await pipeline(sentiment-analysis); const out await pipe(I love transformers!); // [{label: POSITIVE, score: 0.999817686}]pipelineAPI 将预训练模型 输入预处理 输出后处理封装在一起是最快捷的模型调用方式与 Python 版 transformers 的用法保持一致。你也可以通过第二个参数指定任意模型 ID 或本地路径// 使用不同的模型 const pipe await pipeline( sentiment-analysis, Xenova/bert-base-multilingual-uncased-sentiment, );在资源受限的浏览器环境中可通过dtype参数选择量化精度以降低带宽与内存占用典型取值包括fp32WebGPU 默认、fp16、q8WASM 默认与q4const pipe await pipeline(sentiment-analysis, Xenova/distilbert-base-uncased-finetuned-sst-2-english, { dtype: q4, });五、安装后的关键配置env 环境变量安装完成后Transformers.js 默认使用托管在 Hugging Face Hub 上的预训练模型与 CDN 上的预编译 WASM 二进制开箱即用详见 3_custom-usage.snippet 与 custom_usage.md。如果需要对加载行为做定制可以通过导出的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.js 源码可以看到env还提供了更丰富的配置项常见的有配置项默认值说明env.allowRemoteModelstrue是否允许加载远程模型文件置为false等效于 Python 版的local_files_onlytrueenv.allowLocalModels浏览器为falseNode.js 为true是否允许加载本地模型文件env.localModelPath/models/Node.js 下为包目录下的绝对路径本地模型根目录env.remoteHosthttps://huggingface.co/远程模型的主机地址env.cacheDir./.cache文件系统缓存目录env.useBrowserCache有 Cache API 时为true是否使用浏览器 Cache API 缓存模型env.useFSCache有文件系统时为true是否使用文件系统缓存env.useWasmCache有缓存能力时为true是否预加载并缓存 WASM 二进制及 ONNX Runtime 工厂文件env.logLevelLogLevel.WARNING日志级别可取值DEBUG/INFO/WARNING/ERROR/NONEenv.fetch全局fetch自定义 fetch 实现这些配置在安装后即可生效无需重新构建。若需要加载本地自有的 ONNX 模型可配合 Optimum 系列工具将 PyTorch、TensorFlow 或 JAX 模型转换为 ONNX 格式后放入localModelPath指定目录。六、从源码理解安装与加载链路安装只是第一步理解包的加载链路有助于排查问题。结合 package.json 与 env.js可以梳理出以下关键机制1. 环境分流由 exports 完成。exports字段中的node与default两个条件分别指向不同的 dist 构建产物Node.js 的模块解析器会根据运行环境自动选择避免把浏览器专用代码引入 Node.js也避免将 Node.js 专用的fs、path操作引入浏览器。2. 运行时能力探测决定默认行为。env.js 在模块加载时即完成一系列环境探测通过caches in self判断 Web Cache API 是否可用通过process?.release?.name node判断是否为 Node.js通过navigator.gpu判断 WebGPU 是否可用等。这些探测结果被冻结在导出的apis对象中并直接决定useBrowserCache、useFSCache、allowLocalModels等默认值——这就是同一份代码在不同环境行为不同的根源。3. WASM 与模型资源按需加载。浏览器端的 CPU 推理依赖 ONNX Runtime Web 的 WASM 二进制。默认情况下这些.wasm文件从 CDN 加载你也可以通过env.backends.onnx.wasm.wasmPaths改为自有静态资源路径这在离线部署或内网环境中尤为关键。七、安装后的排错建议结合上述机制常见的安装与加载问题可按以下思路排查模块找不到或入口不对确认安装版本为 4.2.0并检查运行环境——Node.js 项目请确认exports解析正常浏览器直接引入时请确认使用的是带版本号的 CDN URL 或本地静态托管路径浏览器中加载不到模型检查env.allowRemoteModels是否被误设为false或网络环境是否允许访问remoteHost内网环境请改用本地模型 localModelPathWASM 加载失败确认env.backends.onnx.wasm.wasmPaths指向的目录确实存在.wasm文件且静态服务器返回了正确的 MIME 类型日志排查将env.logLevel临时调低如LogLevel.DEBUG可看到模型、权重与 WASM 资源的实际加载过程快速定位是哪一步失败。八、延伸阅读安装与使用入口installation.md、custom_usage.md包导出与依赖声明package.json环境配置源码与完整参数说明env.js浏览器端 GPU 加速指南webgpu.md量化dtype使用指南dtypes.md仓库根 README 的安装章节README.md【免费下载链接】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 安装指南：从 NPM 到 CDN 的完整接入方案
Transformers.js 安装指南从 NPM 到 CDN 的完整接入方案【免费下载链接】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在 Node.js 环境下的 NPM 安装方式、浏览器端零构建vanilla JS的 CDN 引入方式并结合 package.json 与 env.js 源码深入说明安装背后的模块导出机制、运行时环境探测与默认加载路径。读完本文你将能在 Node.js 或浏览器环境中独立完成 Transformers.js 的安装、引入、验证与基础配置跑通第一个端到端推理示例。一、安装前须知包结构与运行时支持huggingface/transformers当前版本为4.2.0见 package.json 中version字段是一个支持浏览器与 Node.js 双端运行的纯 JavaScript 机器学习库。它依赖 ONNX Runtime 在浏览器或 Node.js 中执行模型推理安装时无需引入任何 Python 环境或后端服务。从 package.json 的exports字段可以看出该包针对不同运行环境提供了不同入口Node.js 环境通过node条件导出ESM 使用./dist/transformers.node.mjsCommonJS 使用./dist/transformers.node.cjs同时main字段指向./dist/transformers.node.cjstypes字段指向./types/transformers.d.ts浏览器等 Web 环境通过default条件导出./dist/transformers.web.js供打包器与浏览器直接消费。同时包的jsdelivr与unpkg字段均指向./dist/transformers.min.js这是 CDN 引入时的默认入口。理解这一导出结构有助于在安装后排查装上了却无法 import的问题——不同运行环境会命中不同的构建产物。二、方式一通过 NPM 安装Node.js 场景在具备 Node.js 环境的项目中运行以下命令即可安装npm i huggingface/transformers该命令会将包及其运行时依赖一并安装到node_modules。从 package.json 的dependencies字段可以看到核心运行时依赖包括onnxruntime-nodeNode.js 侧推理后端onnxruntime-web浏览器侧推理后端huggingface/tokenizers与huggingface/jinja分词与模板渲染sharpNode.js 场景下的图像处理。安装完成后在项目代码中即可按 ESM 或 CommonJS 方式引入// ESM import { pipeline } from huggingface/transformers; // CommonJS const { pipeline } require(huggingface/transformers);包本身声明为type: moduleNode.js 环境下的 ESM 导入会命中dist/transformers.node.mjs而 CommonJS 的require会命中dist/transformers.node.cjs两种方式均被官方支持对应 package.json 中的exports.node.import与exports.node.require。三、方式二通过 CDN 引入浏览器 / 无构建工具场景如果希望在纯前端页面中使用 Transformers.js且不希望引入 npm、打包器bundler或任何构建步骤可以直接通过 CDN 或静态文件托管方式加载。官方安装文档给出的标准做法是利用 ES Modulesscript typemodule import { pipeline } from https://cdn.jsdelivr.net/npm/huggingface/transformers4.2.0; /script这一方式的要点版本固定URL 中显式写明了4.2.0版本号避免因版本漂移导致的接口不一致后续如需升级只需修改版本号ES Modules 原生支持现代浏览器原生支持script typemodule无需任何构建工具默认入口CDN 解析到的是包的jsdelivr/unpkg字段指定的dist/transformers.min.js即 Web 构建产物与浏览器环境匹配静态托管同样适用如果项目本身部署在静态服务器上也可以将构建产物下载到本地站点后按相对路径引入效果等价。需要注意的是CDN 方式的产物面向浏览器 Web 环境。从 env.js 的运行时探测逻辑可以看到库会通过typeof window、self、process、fs等 API 判断当前环境浏览器、Web Worker、Service Worker、Node.js、Deno、Bun 等并据此决定模型文件与 WASM 二进制从何处加载。因此在浏览器中allowLocalModels默认会被设为false模型默认从远程加载而在 Node.js 中allowLocalModels默认开启可直接读取本地文件系统。四、安装后的快速验证跑通第一个 pipeline无论采用 NPM 还是 CDN 方式安装成功后都可以用一行代码验证是否可用。以情感分析sentiment-analysis为例对应官方快速上手示例见 1_quick-tour.snippetimport { pipeline } from huggingface/transformers; // 分配一个 sentiment-analysis pipeline const pipe await pipeline(sentiment-analysis); const out await pipe(I love transformers!); // [{label: POSITIVE, score: 0.999817686}]pipelineAPI 将预训练模型 输入预处理 输出后处理封装在一起是最快捷的模型调用方式与 Python 版 transformers 的用法保持一致。你也可以通过第二个参数指定任意模型 ID 或本地路径// 使用不同的模型 const pipe await pipeline( sentiment-analysis, Xenova/bert-base-multilingual-uncased-sentiment, );在资源受限的浏览器环境中可通过dtype参数选择量化精度以降低带宽与内存占用典型取值包括fp32WebGPU 默认、fp16、q8WASM 默认与q4const pipe await pipeline(sentiment-analysis, Xenova/distilbert-base-uncased-finetuned-sst-2-english, { dtype: q4, });五、安装后的关键配置env 环境变量安装完成后Transformers.js 默认使用托管在 Hugging Face Hub 上的预训练模型与 CDN 上的预编译 WASM 二进制开箱即用详见 3_custom-usage.snippet 与 custom_usage.md。如果需要对加载行为做定制可以通过导出的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.js 源码可以看到env还提供了更丰富的配置项常见的有配置项默认值说明env.allowRemoteModelstrue是否允许加载远程模型文件置为false等效于 Python 版的local_files_onlytrueenv.allowLocalModels浏览器为falseNode.js 为true是否允许加载本地模型文件env.localModelPath/models/Node.js 下为包目录下的绝对路径本地模型根目录env.remoteHosthttps://huggingface.co/远程模型的主机地址env.cacheDir./.cache文件系统缓存目录env.useBrowserCache有 Cache API 时为true是否使用浏览器 Cache API 缓存模型env.useFSCache有文件系统时为true是否使用文件系统缓存env.useWasmCache有缓存能力时为true是否预加载并缓存 WASM 二进制及 ONNX Runtime 工厂文件env.logLevelLogLevel.WARNING日志级别可取值DEBUG/INFO/WARNING/ERROR/NONEenv.fetch全局fetch自定义 fetch 实现这些配置在安装后即可生效无需重新构建。若需要加载本地自有的 ONNX 模型可配合 Optimum 系列工具将 PyTorch、TensorFlow 或 JAX 模型转换为 ONNX 格式后放入localModelPath指定目录。六、从源码理解安装与加载链路安装只是第一步理解包的加载链路有助于排查问题。结合 package.json 与 env.js可以梳理出以下关键机制1. 环境分流由 exports 完成。exports字段中的node与default两个条件分别指向不同的 dist 构建产物Node.js 的模块解析器会根据运行环境自动选择避免把浏览器专用代码引入 Node.js也避免将 Node.js 专用的fs、path操作引入浏览器。2. 运行时能力探测决定默认行为。env.js 在模块加载时即完成一系列环境探测通过caches in self判断 Web Cache API 是否可用通过process?.release?.name node判断是否为 Node.js通过navigator.gpu判断 WebGPU 是否可用等。这些探测结果被冻结在导出的apis对象中并直接决定useBrowserCache、useFSCache、allowLocalModels等默认值——这就是同一份代码在不同环境行为不同的根源。3. WASM 与模型资源按需加载。浏览器端的 CPU 推理依赖 ONNX Runtime Web 的 WASM 二进制。默认情况下这些.wasm文件从 CDN 加载你也可以通过env.backends.onnx.wasm.wasmPaths改为自有静态资源路径这在离线部署或内网环境中尤为关键。七、安装后的排错建议结合上述机制常见的安装与加载问题可按以下思路排查模块找不到或入口不对确认安装版本为 4.2.0并检查运行环境——Node.js 项目请确认exports解析正常浏览器直接引入时请确认使用的是带版本号的 CDN URL 或本地静态托管路径浏览器中加载不到模型检查env.allowRemoteModels是否被误设为false或网络环境是否允许访问remoteHost内网环境请改用本地模型 localModelPathWASM 加载失败确认env.backends.onnx.wasm.wasmPaths指向的目录确实存在.wasm文件且静态服务器返回了正确的 MIME 类型日志排查将env.logLevel临时调低如LogLevel.DEBUG可看到模型、权重与 WASM 资源的实际加载过程快速定位是哪一步失败。八、延伸阅读安装与使用入口installation.md、custom_usage.md包导出与依赖声明package.json环境配置源码与完整参数说明env.js浏览器端 GPU 加速指南webgpu.md量化dtype使用指南dtypes.md仓库根 README 的安装章节README.md【免费下载链接】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），仅供参考