前言¶
要在前端或 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
