---

source: "https://github.com/huggingface/skills/tree/main/skills/transformers-js" name: transformers-js description: 使用 Transformers.js 在 Node.js 或浏览器中运行 Hugging Face 模型（JavaScript 或 TypeScript）。 license: Apache-2.0 risk: unknown metadata: author: huggingface version: "3.8.1" category: machine-learning repository: https://github.com/huggingface/transformers.js compatibility: 需要 Node.js 18+ 或支持 ES 模块的现代浏览器。WebGPU 支持需要兼容的浏览器/环境。需要互联网访问以从 Hugging Face Hub 下载模型（如果使用本地模型则可选）。

Transformers.js - JavaScript 机器学习

Transformers.js 能够直接在 JavaScript 中运行最先进的机器学习模型，支持浏览器和 Node.js 环境，无需服务器。

何时使用此技能

当你需要以下功能时使用此技能：

• 在 JavaScript 中运行文本分析、生成或翻译的 ML 模型
• 执行图像分类、目标检测或分割
• 实现语音识别或音频处理
• 构建多模态 AI 应用（文本转图像、图像转文本等）
• 在浏览器客户端运行模型，无需后端

安装

NPM 安装

npm install @huggingface/transformers

浏览器使用（CDN）

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

核心概念

1. Pipeline API

Pipeline API 是使用模型最简单的方式。它将预处理、模型推理和后处理组合在一起：

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

// Create a pipeline for a specific task
const pipe = await pipeline('sentiment-analysis');

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

// IMPORTANT: Always dispose when done to free memory
await classifier.dispose();

⚠️ 内存管理： 所有 pipeline 在使用完毕后必须通过 pipe.dispose() 释放，以防止内存泄漏。参见 代码示例 了解不同环境下的清理模式。

2. 模型选择

你可以将自定义模型指定为第二个参数：

const pipe = await pipeline(
  'sentiment-analysis',
  'Xenova/bert-base-multilingual-uncased-sentiment'
);

查找模型：

在 Hugging Face Hub 上浏览可用的 Transformers.js 模型：

• 所有模型: https://huggingface.co/models?library=transformers.js&sort=trending
• 按任务: 添加 pipeline_tag 参数
  • 文本生成: https://huggingface.co/models?pipeline_tag=text-generation&library=transformers.js&sort=trending
  • 图像分类: https://huggingface.co/models?pipeline_tag=image-classification&library=transformers.js&sort=trending
  • 语音识别: https://huggingface.co/models?pipeline_tag=automatic-speech-recognition&library=transformers.js&sort=trending

提示： 按任务类型过滤，按热门/下载量排序，查看模型卡片了解性能指标和使用示例。

3. 设备选择

选择模型运行位置：

// Run on CPU (default for WASM)
const pipe = await pipeline('sentiment-analysis', 'model-id');

// Run on GPU (WebGPU - experimental)
const pipe = await pipeline('sentiment-analysis', 'model-id', {
  device: 'webgpu',
});

4. 量化选项

控制模型精度与性能的平衡：

// Use quantized model (faster, smaller)
const pipe = await pipeline('sentiment-analysis', 'model-id', {
  dtype: 'q4',  // Options: 'fp32', 'fp16', 'q8', 'q4'
});

支持的任务

注意： 以下所有示例展示基本用法。

自然语言处理

文本分类

const classifier = await pipeline('text-classification');
const result = await classifier('This movie was amazing!');

命名实体识别（NER）

const ner = await pipeline('token-classification');
const entities = await ner('My name is John and I live in New York.');

问答

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 generator = await pipeline('text-generation', 'onnx-community/gemma-3-270m-it-ONNX');
const text = await generator('Once upon a time', {
  max_new_tokens: 100,
  temperature: 0.7
});

流式输出和对话： 参见 文本生成指南 了解：

• 使用 TextStreamer 逐 token 流式输出
• 系统/用户/助手角色的对话格式
• 生成参数（temperature、top_k、top_p）
• 浏览器和 Node.js 示例
• React 组件和 API 端点

翻译

const translator = await pipeline('translation', 'Xenova/nllb-200-distilled-600M');
const result = await translator('Hello, how are you?', {
  src_lang: 'eng_Latn',
  tgt_lang: 'fra_Latn'
});