Transformers.js v4 現已登上 NPM,新增 WebGPU runtime
Transformers.js v4: Now Available on NPM!
Hugging Face 宣佈 Transformers.js v4 已上架 NPM,安裝命令為 `npm i @huggingface/transformers`。
v4 支援 Node、Bun 和 Deno 的 WebGPU 加速,預設網頁版縮小 53%,呈現跨環境部署與下載、啟動效率的具體改進。
![]()
我們很高興宣佈 Transformers.js v4 現已在 NPM 上推出!經過一年的開發(我們於 2025 年 3 月開始 🤯),終於可以讓大家使用了。
npm i @huggingface/transformers
效能和執行環境改進
最大改變無疑是採用全新 WebGPU 執行環境,整個執行環境以 C++ 重新編寫。我們與 ONNX Runtime 團隊緊密合作,徹底測試此執行環境是否支援我們約 200 種模型架構,以及多種 v4 專屬新架構。
這個全新 WebGPU 執行環境除了改進運算子支援(提升效能、準確度和涵蓋範圍),亦讓同一套 transformers.js 程式碼可在多種 JavaScript 環境中使用,包括瀏覽器、伺服器端執行環境和桌面應用程式。沒錯,現在你可以直接在 Node、Bun 和 Deno 執行 WebGPU 加速模型!

我們已證明最先進 AI 模型可以 100% 在瀏覽器本機執行,現在則專注提升效能,令這些模型即使在資源受限環境下也能盡可能快速執行。為此,我們徹底重新思考匯出策略,尤其是大型語言模型。我們逐個操作重新實作新模型,並善用 ONNX Runtime 專用擴展運算子,例如 com.microsoft.GroupQueryAttention、com.microsoft.MatMulNBits 和 com.microsoft.QMoE,以發揮最高效能。
例如,採用 com.microsoft.MultiHeadAttention 運算子後,我們成功令 BERT 嵌入模型提速約 4 倍。

儲存庫重整
開發新的主要版本,讓我們有機會投資改善程式碼庫,處理早就應進行的重構工作。
PNPM Workspaces
一直以來,GitHub 儲存庫同時就是我們的 npm 套件。只要儲存庫只提供單一函式庫,這種做法便運作良好。不過,展望未來,我們發現需要建立多個子套件,既能大量依賴 Transformers.js 核心,又可支援不同用途,例如函式庫專用實作,或大部分用戶不需要、但對部分人不可或缺的小型工具。
因此,我們透過 pnpm workspaces 將儲存庫改為 monorepo。這樣便能發布較小型、依賴 @huggingface/transformers 的套件,同時毋須維護多個獨立儲存庫。
模組化類別結構
另一項大型重構針對日益臃腫的 models.js 檔案。v3 把所有可用模型定義在同一檔案中,超過 8,000 行,愈來愈難維護。v4 將內容拆分為較小、各有專注用途的模組,清楚區分工具函數、核心邏輯和模型專用實作。新結構提高可讀性,也令新增模型容易得多。開發者現在可專注處理模型邏輯,毋須在數千行無關程式碼中搜尋。
範例儲存庫
在 v3 中,許多 Transformers.js 範例項目直接放在主儲存庫。v4 把它們移至專用儲存庫,讓我們能整理程式碼庫,專注開發核心函式庫。用戶也更容易找到範例並參與貢獻,不必在主儲存庫中費力搜尋。
Prettier
我們更新了 Prettier 設定,並重新格式化儲存庫內所有檔案,確保整個程式碼庫格式一致,日後所有 PR 亦會自動遵循同一風格。再也不用爭論格式……Prettier 會處理一切,讓程式碼對所有人都保持整潔易讀。
全新模型和架構
得益於全新匯出策略,以及 ONNX Runtime 持續擴展自訂運算子的支援,我們已能在 Transformers.js v4 加入大量新模型和架構,包括 GPT-OSS、Chatterbox、GraniteMoeHybrid、LFM2-MoE、HunYuanDenseV1、Apertus、Olmo3、FalconH1 和 Youtu-LLM 等熱門模型。為支援其中許多模型,我們實作了 Mamba(狀態空間模型)、多頭潛在注意力(MLA)和混合專家(MoE)等進階架構模式。更重要的是,所有這些模型都兼容 WebGPU,讓用戶能直接在瀏覽器或伺服器端 JavaScript 環境中,以硬件加速執行。我們目前已發布數個 Transformers.js v4 示範,之後會繼續推出更多!
全新建置系統
我們把建置系統由 Webpack 遷移至 esbuild,成果令人驚喜。建置時間由 2 秒縮短至 200 毫秒,提升 10 倍,令開發迭代快得多。不過,效能提升並非唯一好處:所有建置版本的套件大小平均減少 10%。最顯著改進是預設匯出 transformers.web.js,現在體積縮小 53%,用戶下載更快、啟動時間更短。
全新函式庫功能
v4 亦加入新函式庫功能,讓你更容易建立穩健、可投入生產環境的應用程式。
ModelRegistry
全新的 ModelRegistry API 專為生產工作流程設計。載入任何內容前,都可明確查看所需的 pipeline 資產:使用 get_pipeline_files 列出所需檔案、透過 get_file_metadata 檢視每個檔案的中繼資料(計算總下載大小時相當有用)、用 is_pipeline_cached 檢查快取狀態,以及透過 clear_pipeline_cache 清除快取資產。你也可使用 get_available_dtypes 查詢模型可用的精度類型。配合這個新 API,progress_callback 現在會提供 progress_total 事件,讓你無須手動彙總每個檔案的更新,也能呈現端對端載入進度。
查看 `ModelRegistry` 範例
import { ModelRegistry, pipeline } from "@huggingface/transformers";
const modelId = "onnx-community/all-MiniLM-L6-v2-ONNX";
const modelOptions = { dtype: "fp32" };
const files = await ModelRegistry.get_pipeline_files(
"feature-extraction",
modelId,
modelOptions
);
// ['config.json', 'onnx/model.onnx', ..., 'tokenizer_config.json']
const metadata = await Promise.all(
files.map(file => ModelRegistry.get_file_metadata(modelId, file))
);
const downloadSize = metadata.reduce((total, item) => total + item.size, 0);
const cached = await ModelRegistry.is_pipeline_cached(
"feature-extraction",
modelId,
modelOptions
);
const dtypes = await ModelRegistry.get_available_dtypes(modelId);
// ['fp32', 'fp16', 'q4', 'q4f16']
if (cached) {
await ModelRegistry.clear_pipeline_cache(
"feature-extraction",
modelId,
modelOptions
);
}
const pipe = await pipeline(
"feature-extraction",
modelId,
{
progress_callback: e => {
if (e.status === "progress_total") {
console.log(`${Math.round(e.progress)}%`);
}
},
}
);
全新環境設定
我們亦新增模型載入環境控制項。env.useWasmCache 可快取 WASM 執行環境檔案(若快取儲存空間可用),讓應用程式在首次載入後可以完全離線運作。
env.fetch 讓你提供自訂 fetch 實作,支援驗證後的模型存取、自訂標頭和可中止請求等用途。
查看 env 範例
import { env } from "@huggingface/transformers";
env.useWasmCache = true;
env.fetch = (url, options) =>
fetch(url, {
...options,
headers: {
...options?.headers,
Authorization: `Bearer ${MY_TOKEN}`,
},
});
改良日誌控制
最後,實際部署中更容易管理日誌。ONNX Runtime WebGPU 警告現在預設隱藏,而你可分別為 Transformers.js 和 ONNX Runtime 設定明確詳細程度。這項更新同樣來自社羣意見,讓主控台專注顯示可採取行動的訊號,減少價值不高的雜訊。
查看 `logLevel` 範例
import { env, LogLevel } from "@huggingface/transformers";
// LogLevel.DEBUG
// LogLevel.INFO
// LogLevel.WARNING
// LogLevel.ERROR
// LogLevel.NONE
env.logLevel = LogLevel.WARNING;
獨立 Tokenizers.js 函式庫
用戶經常要求把 tokenization 邏輯抽取成獨立函式庫,v4 正式實現了這項功能。@huggingface/tokenizers 全面重構了 tokenization 邏輯,能在瀏覽器和伺服器端執行環境中無縫運作。壓縮後只有 8.8kB,沒有任何依賴,極為輕量,同時保有完整類型安全。
查看程式碼範例
import { Tokenizer } from "@huggingface/tokenizers";
// Load from Hugging Face Hub
const modelId = "HuggingFaceTB/SmolLM3-3B";
const tokenizerJson = await fetch(
`https://huggingface.co/${modelId}/resolve/main/tokenizer.json`
).then(res => res.json());
const tokenizerConfig = await fetch(
`https://huggingface.co/${modelId}/resolve/main/tokenizer_config.json`
).then(res => res.json());
// Create tokenizer
const tokenizer = new Tokenizer(tokenizerJson, tokenizerConfig);
// Tokenize text
const tokens = tokenizer.tokenize("Hello World");
// ['Hello', 'ĠWorld']
const encoded = tokenizer.encode("Hello World");
// { ids: [9906, 4435], tokens: ['Hello', 'ĠWorld'], ... }
這項拆分讓 Transformers.js 核心保持精簡專注,同時提供功能多元的獨立工具,任何 WebML 項目都可自行使用。
其他改進
我們亦在函式庫各處作出多項提升使用體驗的改進。類型系統新增動態 pipeline 類型,會根據輸入內容調整,改善開發體驗和類型安全。

此外,我們新增對超過 8B 參數大型模型的支援。在測試中,我們能以約每秒 60 個 token 的速度,在 M4 Pro Max 上執行 GPT-OSS 20B(q4f16)。
鳴謝
我們衷心感謝所有促成這次重大發布的人,特別是 ONNX Runtime 團隊。他們全力投入全新 WebGPU 執行環境,也在整個開發過程中給予支援;我們同時感謝所有外部貢獻者和早期測試人員。
來源:Hugging Face Blog · huggingface.co