前言¶

要在前端或 Node 裏做情感分析、圖像分類或語音識別，常見做法是起 Python 推理服務，或把請求打到雲端 API。對純 JavaScript/TypeScript 棧的團隊，這會多出部署、密鑰和網絡依賴。Transformers.js 本身可以在瀏覽器與 Node.js、Bun、Deno 中直接加載 Hub 上的預訓練模型，用 WebGPU 或 WASM 推理。Hugging Face 在官方 Skills 倉庫裏提供了 transformers-js Skill，把 Pipeline API、任務類型、設備與量化選項、內存釋放等約定寫進 Agent 可遵循的 SKILL.md，便於在 Cursor、Codex、Claude Code 等環境裏讓編碼助手按同一套方式寫端側 ML 代碼。

這是什麼¶

transformers-js 是 Hugging Face skills 倉庫中的一個 Agent Skill（遵循 Agent Skills 標準），元數據標明作者爲 huggingface、類別爲 machine-learning、許可爲 Apache-2.0，對應底層庫爲 transformers.js。

Skill 的定位是：在 JavaScript/TypeScript 中用 Transformers.js 運行 NLP（文本分類、翻譯、摘要等）、計算機視覺（圖像分類、目標檢測等）、音頻（語音識別、音頻分類等）以及多模態任務；支持瀏覽器與 Node.js、Bun、Deno，通過 WebGPU/WASM 使用 Hugging Face Hub 上的預訓練模型，無需單獨搭 Python 服務。

運行環境要求（來自 Skill 說明）：Node.js 18+（或兼容的 Bun/Deno），或支持 ES modules 的現代瀏覽器；WebGPU 需運行時與硬件支持，WASM 爲更通用的後備；從 Hub 拉取模型通常需要網絡（也可使用本地模型）。

核心功能¶

下面介紹 Skill 文檔中強調、且與庫能力一致的幾塊內容。

Pipeline API¶

Pipeline 把預處理、推理與後處理串在一起，是官方推薦的上手方式。創建任務對應的 pipeline，傳入文本或媒體路徑即可得到結果。用完後必須調用 dispose() 釋放內存，否則容易泄漏；Skill 在多處用警告標出這一點。

模型與任務¶

第二個參數可指定 Hub 上的模型 ID（例如多語言情感分析 Xenova/bert-base-multilingual-uncased-sentiment）。文檔給出按 library=transformers.js 與 pipeline_tag 篩選模型的 Hub 鏈接，便於按任務選型。

設備與量化¶

可通過選項選擇運行設備，例如 device: 'webgpu' 使用 GPU；通過 dtype 控制精度（文檔列出的選項包括 fp32、fp16、q8、q4），在體積與速度之間取捨。

支持的任務範圍（節選）¶

Skill 內附各任務的最小示例，涵蓋：

• NLP：文本分類、命名實體識別（token-classification）、問答、文本生成、翻譯、摘要、零樣本分類等。
• 視覺：圖像分類、目標檢測、分割、深度估計、零樣本圖像分類等。
• 音頻：自動語音識別、音頻分類、文本轉語音等。
• 多模態：圖像描述（image-to-text）、文檔問答、零樣本目標檢測等。

文本生成、流式輸出與對話格式等更深入內容，Skill 指向倉庫內 references/TEXT_GENERATION.md 等參考文檔。

安裝與啓用¶

分兩層理解：安裝 Transformers.js 庫（寫業務代碼），以及把 Agent Skill 裝進你的編碼助手（讓 Agent 按 Skill 寫代碼）。

安裝 npm 包¶

在 Node 或打包後的前端項目中安裝官方包：

npm install @huggingface/transformers

瀏覽器也可通過 CDN 以 ES module 方式引入（Skill 示例使用 jsDelivr）：

<script type="module">
  import { pipeline } from 'https://cdn.jsdelivr.net/npm/@huggingface/transformers';
</script>

在 Agent 環境中啓用 Skill¶

Hugging Face Skills 與 Claude Code、Codex、Gemini CLI、Cursor 等兼容。倉庫說明中，Cursor 市場默認側重 hf-cli；安裝其他 workflow skill 可使用 Hugging Face CLI：

hf skills add transformers-js

Claude Code 可先註冊 marketplace 再安裝 CLI skill，同樣用 hf skills add <skill-name> 添加 transformers-js。Codex 可將 skills/transformers-js 目錄複製或軟鏈到 Codex 約定的 .agents/skills 路徑。具體步驟以 huggingface/skills 當前文檔爲準。

Skill 本體路徑：

https://github.com/huggingface/skills/tree/main/skills/transformers-js

典型用法¶

情感分析（最小閉環）¶

創建 pipeline、推理、釋放資源三步是文檔反覆強調的模式：

import { pipeline } from '@huggingface/transformers';

const pipe = await pipeline('sentiment-analysis');

const result = await pipe('I love transformers!');
// Output: [{ label: 'POSITIVE', score: 0.999817686 }]

await pipe.dispose();

指定模型與 WebGPU¶

const pipe = await pipeline(
  'sentiment-analysis',
  'Xenova/bert-base-multilingual-uncased-sentiment',
  {
    device: 'webgpu',
  }
);

量化模型¶

const pipe = await pipeline('sentiment-analysis', 'model-id', {
  dtype: 'q4',
});

其他任務示例¶

問答：

const qa = await pipeline('question-answering');
const answer = await qa({
  question: 'What is the capital of France?',
  context: 'Paris is the capital and largest city of France.'
});

自動語音識別：

const transcriber = await pipeline('automatic-speech-recognition');
const result = await transcriber('audio.wav');

圖像分類可傳入圖片 URL 或本地路徑（具體輸入形式以當前庫文檔爲準）。更完整的任務列表與參數見 Skill 倉庫中的 SKILL.md 與 references/ 目錄。

適用場景與注意¶

適合誰

• 需要在瀏覽器裏做客戶端推理、減少後端 ML 服務的 JS/TS 開發者。
• 在 Node.js、Bun 或 Deno 側做批處理或輕量推理，且希望模型來自 Hugging Face Hub 的團隊。
• 希望 Agent 生成 Transformers.js 代碼時統一遵循 dispose、設備與量化約定，而不是每次從零猜 API 的場景。

限制與注意

• 首次使用需從 Hub 下載模型（體積與任務相關），要有網絡或提前準備本地模型。
• WebGPU 並非所有環境都可用；不支持時應依賴 WASM/CPU 路徑。
• 大模型在端側受內存與算力限制，Skill 中的 dtype 與模型選型很重要。
• Agent Skill 是操作指南，不替代閱讀 transformers.js 發行說明與 Hub 模型卡片。

結尾¶

transformers-js 把 Transformers.js 在瀏覽器與 Node 生態中的 Pipeline 用法、任務覆蓋與運維細節（尤其是 pipe.dispose()）固化成 Agent 可執行的說明，適合端側 AI 與 Web ML 方向、且主力棧是 JavaScript 的團隊。官方 Skill 地址：

https://github.com/huggingface/skills/tree/main/skills/transformers-js