Hugging Face 的 LOGO

Transformers.js 文档

pipeline API

您正在查看的是需要从源码安装。如果您想使用常规的 npm install，请查看最新的稳定版本 (v3.0.0)。
Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

pipeline API

就像 transformers Python 库一样，Transformers.js 为用户提供了一种利用 transformers 强大功能的简单方法。pipeline() 函数是使用预训练模型进行推理的最简单、最快捷的方式。

要查看可用任务/pipeline 的完整列表，请查看此表格。

基础知识

首先，创建一个 pipeline() 实例并指定要使用的任务。例如，要创建一个情感分析 pipeline，您可以这样做：

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

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

首次运行时，pipeline 将下载并缓存与该任务关联的默认预训练模型。这可能需要一些时间，但后续调用会快得多。

默认情况下，模型将从 Hugging Face Hub 下载并存储在浏览器缓存中，但也有方法可以指定自定义模型和缓存位置。有关更多信息，请参阅此处。

现在，您可以通过将分类器作为函数调用来对目标文本进行处理：

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

如果您有多个输入，可以将其作为数组传递：

const result = await classifier(['I love transformers!', 'I hate transformers!']);
// [{'label': 'POSITIVE', 'score': 0.9998}, {'label': 'NEGATIVE', 'score': 0.9982}]

您还可以通过将模型作为第二个参数传递给 pipeline() 函数来指定用于 pipeline 的不同模型。例如，要为情感分析使用不同的模型（比如一个被训练用来预测评论情感作为1到5星级评分的模型），您可以这样做：

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

const result = await reviewer('The Shawshank Redemption is a true masterpiece of cinema.');
// [{label: '5 stars', score: 0.8167929649353027}]

Transformers.js 支持加载 Hugging Face Hub 上托管的任何模型，只要它具有 ONNX 权重（位于名为 onnx 的子文件夹中）。有关如何将您的 PyTorch、TensorFlow 或 JAX 模型转换为 ONNX 的更多信息，请参阅转换部分。

pipeline() 函数是快速使用预训练模型进行推理的好方法，因为它为您处理了所有的预处理和后处理工作。例如，如果您想使用 OpenAI 的 Whisper 模型进行自动语音识别 (ASR)，您可以这样做：

// Create a pipeline for Automatic Speech Recognition
const transcriber = await pipeline('automatic-speech-recognition', 'Xenova/whisper-small.en');

// Transcribe an audio file, loaded from a URL.
const result = await transcriber('https://huggingface.co/datasets/Narsil/asr_dummy/resolve/main/mlk.flac');
// {text: ' I have a dream that one day this nation will rise up and live out the true meaning of its creed.'}

Pipeline 选项

加载

我们提供了多种选项来控制如何从 Hugging Face Hub（或本地）加载模型。默认情况下，在浏览器中运行时，会使用模型的*量化*版本，它更小更快，但通常精度较低。要覆盖此行为（即使用未量化的模型），您可以将自定义的 PretrainedOptions 对象作为第三个参数传递给 pipeline 函数：

// Create a pipeline for feature extraction, using the full-precision model (fp32)
const pipe = await pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2', {
    dtype: "fp32",
});

请查看关于量化的部分以了解更多信息。

您还可以通过传递 revision 参数来指定要使用的模型版本。由于 Hugging Face Hub 使用基于 git 的版本控制系统，您可以使用任何有效的 git 版本说明符（例如，分支名称或提交哈希）。

const transcriber = await pipeline('automatic-speech-recognition', 'Xenova/whisper-tiny.en', {
    revision: 'output_attentions',
});

有关选项的完整列表，请查看 PretrainedOptions 文档。

运行

许多 pipeline 都有可以指定的附加选项。例如，当使用支持多语言翻译的模型时，您可以像这样指定源语言和目标语言：

// Create a pipeline for translation
const translator = await pipeline('translation', 'Xenova/nllb-200-distilled-600M');

// Translate from English to Greek
const result = await translator('I like to walk my dog.', {
    src_lang: 'eng_Latn',
    tgt_lang: 'ell_Grek'
});
// [ { translation_text: 'Μου αρέσει να περπατάω το σκυλί μου.' } ]

// Translate back to English
const result2 = await translator(result[0].translation_text, {
    src_lang: 'ell_Grek',
    tgt_lang: 'eng_Latn'
});
// [ { translation_text: 'I like to walk my dog.' } ]

当使用支持自回归生成的模型时，您可以指定生成参数，如新词元数量、采样方法、温度、重复惩罚等等。有关可用参数的完整列表，请参阅 GenerationConfig 类。

例如，要使用 LaMini-Flan-T5-783M 生成一首诗，您可以这样做：

// Create a pipeline for text2text-generation
const poet = await pipeline('text2text-generation', 'Xenova/LaMini-Flan-T5-783M');
const result = await poet('Write me a love poem about cheese.', {
    max_new_tokens: 200,
    temperature: 0.9,
    repetition_penalty: 2.0,
    no_repeat_ngram_size: 3,
});

将 result[0].generated_text 打印到控制台，得到：

Cheese, oh cheese! You're the perfect comfort food.
Your texture so smooth and creamy you can never get old.
With every bite it melts in your mouth like buttery delights
that make me feel right at home with this sweet treat of mine. 

From classic to bold flavor combinations,
I love how versatile you are as an ingredient too?
Cheddar is my go-to for any occasion or mood; 
It adds depth and richness without being overpowering its taste buds alone

流式处理

一些 pipeline 如 text-generation 或 automatic-speech-recognition 支持流式输出。这是通过 TextStreamer 类实现的。例如，当使用像 Qwen2.5-Coder-0.5B-Instruct 这样的聊天模型时，您可以指定一个回调函数，该函数将针对每个生成的词元文本被调用（如果未设置，新词元将被打印到控制台）。

import { pipeline, TextStreamer } from "@huggingface/transformers";

// Create a text generation pipeline
const generator = await pipeline(
  "text-generation",
  "onnx-community/Qwen2.5-Coder-0.5B-Instruct",
  { dtype: "q4" },
);

// Define the list of messages
const messages = [
  { role: "system", content: "You are a helpful assistant." },
  { role: "user", content:  "Write a quick sort algorithm." },
];

// Create text streamer
const streamer = new TextStreamer(generator.tokenizer, {
  skip_prompt: true,
  // Optionally, do something with the text (e.g., write to a textbox)
  // callback_function: (text) => { /* Do something with text */ },
})

// Generate a response
const result = await generator(messages, { max_new_tokens: 512, do_sample: false, streamer });

将 result[0].generated_text 打印到控制台，得到：

点击查看控制台输出 
Here's a simple implementation of the quick sort algorithm in Python:
```python
def quick_sort(arr):
    if len(arr) <= 1:
        return arr
    pivot = arr[len(arr) // 2]
    left = [x for x in arr if x < pivot]
    middle = [x for x in arr if x == pivot]
    right = [x for x in arr if x > pivot]
    return quick_sort(left) + middle + quick_sort(right)
# Example usage:
arr = [3, 6, 8, 10, 1, 2]
sorted_arr = quick_sort(arr)
print(sorted_arr)
```
### Explanation:
- **Base Case**: If the array has less than or equal to one element (i.e., `len(arr)` is less than or equal to `1`), it is already sorted and can be returned as is.
- **Pivot Selection**: The pivot is chosen as the middle element of the array.
- **Partitioning**: The array is partitioned into three parts: elements less than the pivot (`left`), elements equal to the pivot (`middle`), and elements greater than the pivot (`right`). These partitions are then recursively sorted.
- **Recursive Sorting**: The subarrays are sorted recursively using `quick_sort`.
This approach ensures that each recursive call reduces the problem size by half until it reaches a base case.

这种流式功能允许您在生成输出时对其进行处理，而不是等待整个输出生成完毕后再进行处理。

有关每个 pipeline 可用选项的更多信息，请参阅 API 参考。如果您希望对推理过程有更多控制，可以使用 AutoModel、AutoTokenizer 或 AutoProcessor 类。

可用任务

任务

自然语言处理

任务 ID 描述 支持？
填充掩码 fill-mask 掩盖句子中的某些词，并预测应该用哪些词来替换这些掩码。 ✅ （文档）
（模型）
问答 问题回答 从给定文本中检索问题的答案。 ✅ （文档）
（模型）
句子相似度 sentence-similarity 判断两个文本的相似程度。 ✅ （文档）
（模型）
摘要 摘要 在保留重要信息的同时，生成文档的较短版本。 ✅ （文档）
（模型）
表格问答 table-question-answering 回答关于给定表格信息的问题。 ❌
文本分类 text-classification 或 sentiment-analysis 为给定的文本分配一个标签或类别。 ✅ （文档）
（模型）
文本生成 文本生成 通过预测序列中的下一个词来生成新文本。 ✅ （文档）
（模型）
文本到文本生成 text2text-generation 将一个文本序列转换为另一个文本序列。 ✅ （文档）
（模型）
Token 分类 token-classification 或 ner 为文本中的每个词元分配一个标签。 ✅ （文档）
（模型）
翻译 翻译 将文本从一种语言翻译成另一种语言。 ✅ （文档）
（模型）
零样本分类 zero-shot-classification 将文本分类到训练期间未见过的类别中。 ✅ （文档）
（模型）
特征提取 feature-extraction 将原始数据转换为可以处理的数值特征，同时保留原始数据集中的信息。 ✅ （文档）
（模型）

视觉

任务 ID 描述 支持？
背景移除 background-removal 通过移除或使背景透明来分离图像的主体。 ✅ （文档）
（模型）
深度估计 depth-estimation 预测图像中物体的深度。 ✅ （文档）
（模型）
图像分类 image-classification 为整个图像分配一个标签或类别。 ✅ （文档）
（模型）
图像分割 image-segmentation 将图像分割成多个片段，其中每个像素都映射到一个对象。此任务有多种变体，如实例分割、全景分割和语义分割。 ✅ （文档）
（模型）
图像到图像 image-to-image 将源图像转换为匹配目标图像或目标图像域的特征。 ✅ （文档）
（模型）
掩码生成 mask-generation 为图像中的对象生成掩码。 ❌
物体检测 object-detection 在图像中识别特定定义类别的对象。 ✅ （文档）
（模型）
视频分类 不适用 为整个视频分配一个标签或类别。 ❌
无条件图像生成 不适用 在没有任何上下文条件（如提示文本或其他图像）的情况下生成图像。 ❌
图像特征提取 image-feature-extraction 将原始数据转换为可以处理的数值特征，同时保留原始图像中的信息。 ✅ （文档）
（模型）

音频

任务 ID 描述 支持？
音频分类 音频分类 为给定的音频分配一个标签或类别。 ✅ （文档）
（模型）
音频到音频 不适用 从输入音频源生成音频。 ❌
自动语音识别 自动语音识别 将给定的音频转录成文本。 ✅ （文档）
（模型）
文本到语音 text-to-speech 或 text-to-audio 根据文本输入生成听起来自然的语音。 ✅ （文档）
（模型）

表格

任务 ID 描述 支持？
表格分类 不适用 根据一组属性对目标类别（一个组）进行分类。 ❌
表格回归 不适用 根据一组属性预测一个数值。 ❌

多模态

任务 ID 描述 支持？
文档问答 document-question-answering 回答文档图像上的问题。 ✅ （文档）
（模型）
图像到文本 image-to-text 从给定图像中输出文本。 ✅ （文档）
（模型）
文本到图像 text-to-image 从输入文本生成图像。 ❌
视觉问答 视觉问答 基于图像回答开放式问题。 ❌
零样本音频分类 zero-shot-audio-classification 将音频分类到训练期间未见过的类别中。 ✅ （文档）
（模型）
零样本图像分类 zero-shot-image-classification 将图像分类到训练期间未见过的类别中。 ✅ （文档）
（模型）
零样本对象检测 zero-shot-object-detection 识别训练期间未见过的类别的对象。 ✅ （文档）
（模型）

强化学习

任务 ID 描述 支持？
强化学习 不适用 通过与环境互动、试错以及接收奖励（正面或负面）作为反馈来从行动中学习。 ✅
< > 在 GitHub 上更新

←安装 自定义用法→