Transformers.js 源码深度解析 ​

本文档基于仓库内 @huggingface/transformers 4.0.1 源码（根目录 monorepo 版本 0.0.1），结合官方文档、Release 说明与典型 Issue/PR 线索，系统梳理 在浏览器与 Node 中运行 Hugging Face 模型 的分层架构、关键设计与优化手段。

说明：库的定位是 与 Python transformers API 尽量对齐，底层推理统一走 ONNX Runtime（浏览器多为 onnxruntime-web，Node 为 onnxruntime-node），模型需以 ONNX（通常经 Optimum 导出）形式提供。

目录 ​

1. 核心架构与分层
2. Pipeline 与任务注册系统
3. Hub 加载、路径与缓存
4. ONNX 后端、执行提供者与推理串行化
5. 设备、dtype 与量化选择
6. PreTrainedModel、生成与 KV Cache
7. 多 ONNX Session、多模态与 text-only 加载
8. Tensor、后处理与自定义 ONNX 算子
9. 性能优化与工程最佳实践
10. 版本演进、Issue/PR 线索与设计依据
11. 常见问题

源码版本 ​

• @huggingface/transformers: 4.0.1（见 packages/transformers/package.json）
• 根 monorepo: 0.0.1
• 分析时间: 2026 年 4 月

参考资料 ​

• Transformers.js 官方文档
• GitHub: huggingface/transformers.js
• Issues
• Releases（v4 含 WebGPU 原生 EP、monorepo 等说明）
• PR #1382 — Transformers.js V4 等大型变更
• Hugging Face Blog: Transformers.js V4（与 ORT 团队协作、算子与性能叙述）
• ONNX Runtime Web / WebGPU