Transformers 文档

流水线

Transformers

加入 Hugging Face 社区

并获得增强的文档体验

协作开发模型、数据集和空间

通过加速推理获得更快的示例

在文档主题之间切换

开始使用

流水线

流水线是使用模型进行推理的一种出色且简单的方法。这些流水线是抽象了库中大部分复杂代码的对象，提供了一个简单的 API，专用于多个任务，包括命名实体识别、掩码语言建模、情感分析、特征提取和问答。有关使用示例，请参阅任务摘要。

需要注意两类流水线抽象

pipeline()是最强大的对象，封装了所有其他流水线。
特定于任务的流水线可用于音频、计算机视觉、自然语言处理和多模态任务。

流水线抽象

流水线抽象是所有其他可用流水线的包装器。它像任何其他流水线一样实例化，但可以提供额外的生活质量。

对一项进行简单调用

>>> pipe = pipeline("text-classification")
>>> pipe("This restaurant is awesome")
[{'label': 'POSITIVE', 'score': 0.9998743534088135}]

如果要使用中心中的特定模型，如果中心上的模型已经定义了任务，则可以忽略该任务

>>> pipe = pipeline(model="FacebookAI/roberta-large-mnli")
>>> pipe("This restaurant is awesome")
[{'label': 'NEUTRAL', 'score': 0.7313136458396912}]

要对多个项目调用流水线，可以使用列表调用它。

>>> pipe = pipeline("text-classification")
>>> pipe(["This restaurant is awesome", "This restaurant is awful"])
[{'label': 'POSITIVE', 'score': 0.9998743534088135},
 {'label': 'NEGATIVE', 'score': 0.9996669292449951}]

要迭代完整的数据集，建议直接使用 dataset。这意味着您不需要一次性分配整个数据集，也不需要自己进行批处理。这应该与 GPU 上的自定义循环一样快。如果没有，请随时创建问题。

import datasets
from transformers import pipeline
from transformers.pipelines.pt_utils import KeyDataset
from tqdm.auto import tqdm

pipe = pipeline("automatic-speech-recognition", model="facebook/wav2vec2-base-960h", device=0)
dataset = datasets.load_dataset("superb", name="asr", split="test")

# KeyDataset (only *pt*) will simply return the item in the dict returned by the dataset item
# as we're not interested in the *target* part of the dataset. For sentence pair use KeyPairDataset
for out in tqdm(pipe(KeyDataset(dataset, "file"))):
    print(out)
    # {"text": "NUMBER TEN FRESH NELLY IS WAITING ON YOU GOOD NIGHT HUSBAND"}
    # {"text": ....}
    # ....

为了便于使用，也可以使用生成器

from transformers import pipeline

pipe = pipeline("text-classification")


def data():
    while True:
        # This could come from a dataset, a database, a queue or HTTP request
        # in a server
        # Caveat: because this is iterative, you cannot use `num_workers > 1` variable
        # to use multiple threads to preprocess data. You can still have 1 thread that
        # does the preprocessing while the main runs the big inference
        yield "This is a test"


for out in pipe(data()):
    print(out)
    # {"text": "NUMBER TEN FRESH NELLY IS WAITING ON YOU GOOD NIGHT HUSBAND"}
    # {"text": ....}
    # ....

transformers.pipeline

< 源代码 >

( task: str = None model: Union = None config: Union = None tokenizer: Union = None feature_extractor: Union = None image_processor: Union = None framework: Optional = None revision: Optional = None use_fast: bool = True token: Union = None device: Union = None device_map = None torch_dtype = None trust_remote_code: Optional = None model_kwargs: Dict = None pipeline_class: Optional = None **kwargs ) → 流水线

参数

task (str) — 定义将返回哪个管道的任务。当前接受的任务有：
- "audio-classification"：将返回一个 AudioClassificationPipeline。
- "automatic-speech-recognition"：将返回一个 AutomaticSpeechRecognitionPipeline。
- "depth-estimation"：将返回一个 DepthEstimationPipeline。
- "document-question-answering"：将返回一个 DocumentQuestionAnsweringPipeline。
- "feature-extraction"：将返回一个 FeatureExtractionPipeline。
- "fill-mask"：将返回一个 FillMaskPipeline。
- "image-classification"：将返回一个 ImageClassificationPipeline。
- "image-feature-extraction"：将返回一个 ImageFeatureExtractionPipeline。
- "image-segmentation"：将返回一个 ImageSegmentationPipeline。
- "image-to-image"：将返回一个 ImageToImagePipeline。
- "image-to-text"：将返回一个 ImageToTextPipeline。
- "mask-generation"：将返回一个 MaskGenerationPipeline。
- "object-detection"：将返回一个 ObjectDetectionPipeline。
- "question-answering"：将返回一个 QuestionAnsweringPipeline。
- "summarization"：将返回一个 SummarizationPipeline。
- "table-question-answering"：将返回一个 TableQuestionAnsweringPipeline。
- "text2text-generation"：将返回一个 Text2TextGenerationPipeline。
- "text-classification" （可用别名 "sentiment-analysis"）：将返回一个 TextClassificationPipeline。
- "text-generation"：将返回一个 TextGenerationPipeline。
- "text-to-audio" （可用别名 "text-to-speech"）：将返回一个 TextToAudioPipeline。
- "token-classification" （可用别名 "ner"）：将返回一个 TokenClassificationPipeline。
- "translation"：将返回一个 TranslationPipeline。
- "translation_xx_to_yy"：将返回一个 TranslationPipeline。
- "video-classification"：将返回一个 VideoClassificationPipeline。
- "visual-question-answering"：将返回一个 VisualQuestionAnsweringPipeline。
- "zero-shot-classification"：将返回一个 ZeroShotClassificationPipeline。
- "zero-shot-image-classification"：将返回一个 ZeroShotImageClassificationPipeline。
- "zero-shot-audio-classification": 将返回一个 ZeroShotAudioClassificationPipeline。
- "zero-shot-object-detection": 将返回一个 ZeroShotObjectDetectionPipeline。
model (str 或 PreTrainedModel 或 TFPreTrainedModel, 可选) — 管道将用于进行预测的模型。这可以是模型标识符，也可以是继承自 PreTrainedModel（对于 PyTorch）或 TFPreTrainedModel（对于 TensorFlow）的预训练模型的实际实例。

如果未提供，将加载 task 的默认值。
config (str 或 PretrainedConfig, 可选) — 管道将用于实例化模型的配置。这可以是模型标识符，也可以是继承自 PretrainedConfig 的实际预训练模型配置。

如果未提供，将使用请求模型的默认配置文件。这意味着如果给定了 model，将使用其默认配置。但是，如果未提供 model，则将使用此 task 的默认模型的配置。
tokenizer (str 或 PreTrainedTokenizer，可选) — 流水线将用于为模型编码数据的分词器。这可以是模型标识符或继承自 PreTrainedTokenizer 的实际预训练分词器。

如果未提供，将加载给定 model 的默认分词器（如果它是字符串）。如果未指定 model 或不是字符串，则加载 config 的默认分词器（如果它是字符串）。但是，如果也未给出 config 或不是字符串，则将加载给定 task 的默认分词器。
feature_extractor (str 或 PreTrainedFeatureExtractor，可选) — 流水线将用于为模型编码数据的特征提取器。这可以是模型标识符或继承自 PreTrainedFeatureExtractor 的实际预训练特征提取器。

特征提取器用于非 NLP 模型，例如语音或视觉模型以及多模态模型。多模态模型还需要传递分词器。

如果未提供，将加载给定 model 的默认特征提取器（如果它是字符串）。如果未指定 model 或不是字符串，则加载 config 的默认特征提取器（如果它是字符串）。但是，如果也未给出 config 或不是字符串，则将加载给定 task 的默认特征提取器。
framework (str，可选) — 要使用的框架，"pt" 代表 PyTorch，"tf" 代表 TensorFlow。必须安装指定的框架。

如果未指定框架，将默认使用当前安装的框架。如果未指定框架且安装了两个框架，将默认使用 model 的框架，如果未提供模型，则默认使用 PyTorch。
revision (str，可选，默认为 "main") — 传递任务名称或字符串模型标识符时：要使用的特定模型版本。它可以是分支名称、标签名称或提交 ID，因为我们使用基于 git 的系统在 huggingface.co 上存储模型和其他工件，因此 revision 可以是 git 允许的任何标识符。
use_fast (bool，可选，默认为 True) — 是否尽可能使用快速分词器（PreTrainedTokenizerFast）。
use_auth_token (str 或 bool，可选) — 用作远程文件 HTTP 持有者授权的令牌。如果为 True，将使用运行 huggingface-cli login 生成的令牌（存储在 ~/.huggingface 中）。
device (int 或 str 或 torch.device) — 定义将在其上分配此流水线的设备（*例如*，"cpu"、"cuda:1"、"mps" 或 GPU 序号等级，如 1）。
device_map (str 或 Dict[str, Union[int, str, torch.device]，*可选*) — 直接作为 model_kwargs 发送（只是一个更简单的快捷方式）。当存在 accelerate 库时，设置 device_map="auto" 以自动计算最优化的 device_map（有关详细信息，请参见此处）。

不要同时使用 device_map 和 device，因为它们会冲突
torch_dtype (str 或 torch.dtype，*可选*) — 直接作为 model_kwargs 发送（只是一个更简单的快捷方式），以使用此模型的可用精度（torch.float16、torch.bfloat16、… 或 "auto"）。
trust_remote_code (bool，*可选*，默认为 False) — 是否允许在其自己的建模、配置、标记化甚至流水线文件中使用 Hub 上定义的自定义代码。此选项仅应为你信任的并且你已阅读过代码的存储库设置为 True，因为它将在你的本地机器上执行 Hub 上存在的代码。
model_kwargs (Dict[str, Any]，*可选*) — 传递给模型的 from_pretrained(..., **model_kwargs) 函数的附加关键字参数字典。
kwargs (Dict[str, Any]，*可选*) — 传递给特定流水线初始化的附加关键字参数（有关可能的值，请参阅相应流水线类的文档）。

返回值

流水线

适合该任务的流水线。

用于构建流水线的实用工厂方法。

流水线由以下部分组成

负责将原始文本输入映射到标记的标记器。
根据输入进行预测的模型。
一些（可选的）后处理，用于增强模型的输出。

示例

>>> from transformers import pipeline, AutoModelForTokenClassification, AutoTokenizer

>>> # Sentiment analysis pipeline
>>> analyzer = pipeline("sentiment-analysis")

>>> # Question answering pipeline, specifying the checkpoint identifier
>>> oracle = pipeline(
...     "question-answering", model="distilbert/distilbert-base-cased-distilled-squad", tokenizer="google-bert/bert-base-cased"
... )

>>> # Named entity recognition pipeline, passing in a specific model and tokenizer
>>> model = AutoModelForTokenClassification.from_pretrained("dbmdz/bert-large-cased-finetuned-conll03-english")
>>> tokenizer = AutoTokenizer.from_pretrained("google-bert/bert-base-cased")
>>> recognizer = pipeline("ner", model=model, tokenizer=tokenizer)

流水线批处理

所有流水线都可以使用批处理。只要流水线使用其流式传输功能（因此在传递列表或 Dataset 或 generator 时），这就会起作用）。

from transformers import pipeline
from transformers.pipelines.pt_utils import KeyDataset
import datasets

dataset = datasets.load_dataset("imdb", name="plain_text", split="unsupervised")
pipe = pipeline("text-classification", device=0)
for out in pipe(KeyDataset(dataset, "text"), batch_size=8, truncation="only_first"):
    print(out)
    # [{'label': 'POSITIVE', 'score': 0.9998743534088135}]
    # Exactly the same output as before, but the content are passed
    # as batches to the model

然而，这并不一定意味着性能的提升。根据硬件、数据和实际使用的模型，它可能是 10 倍的加速或 5 倍的减速。

主要加速的例子

from transformers import pipeline
from torch.utils.data import Dataset
from tqdm.auto import tqdm

pipe = pipeline("text-classification", device=0)


class MyDataset(Dataset):
    def __len__(self):
        return 5000

    def __getitem__(self, i):
        return "This is a test"


dataset = MyDataset()

for batch_size in [1, 8, 64, 256]:
    print("-" * 30)
    print(f"Streaming batch_size={batch_size}")
    for out in tqdm(pipe(dataset, batch_size=batch_size), total=len(dataset)):
        pass

# On GTX 970
------------------------------
Streaming no batching
100%|██████████████████████████████████████████████████████████████████████| 5000/5000 [00:26<00:00, 187.52it/s]
------------------------------
Streaming batch_size=8
100%|█████████████████████████████████████████████████████████████████████| 5000/5000 [00:04<00:00, 1205.95it/s]
------------------------------
Streaming batch_size=64
100%|█████████████████████████████████████████████████████████████████████| 5000/5000 [00:02<00:00, 2478.24it/s]
------------------------------
Streaming batch_size=256
100%|█████████████████████████████████████████████████████████████████████| 5000/5000 [00:01<00:00, 2554.43it/s]
(diminishing returns, saturated the GPU)

主要减速的例子

class MyDataset(Dataset):
    def __len__(self):
        return 5000

    def __getitem__(self, i):
        if i % 64 == 0:
            n = 100
        else:
            n = 1
        return "This is a test" * n

与其他句子相比，这是一个偶尔出现的非常长的句子。在这种情况下，整个批次需要有 400 个标记的长度，因此整个批次将是 [64, 400] 而不是 [64, 4]，从而导致严重的减速。更糟糕的是，在更大的批次上，程序会直接崩溃。

------------------------------
Streaming no batching
100%|█████████████████████████████████████████████████████████████████████| 1000/1000 [00:05<00:00, 183.69it/s]
------------------------------
Streaming batch_size=8
100%|█████████████████████████████████████████████████████████████████████| 1000/1000 [00:03<00:00, 265.74it/s]
------------------------------
Streaming batch_size=64
100%|██████████████████████████████████████████████████████████████████████| 1000/1000 [00:26<00:00, 37.80it/s]
------------------------------
Streaming batch_size=256
  0%|                                                                                 | 0/1000 [00:00<?, ?it/s]
Traceback (most recent call last):
  File "/home/nicolas/src/transformers/test.py", line 42, in <module>
    for out in tqdm(pipe(dataset, batch_size=256), total=len(dataset)):
....
    q = q / math.sqrt(dim_per_head)  # (bs, n_heads, q_length, dim_per_head)
RuntimeError: CUDA out of memory. Tried to allocate 376.00 MiB (GPU 0; 3.95 GiB total capacity; 1.72 GiB already allocated; 354.88 MiB free; 2.46 GiB reserved in total by PyTorch)

这个问题没有好的（通用的）解决方案，您的结果可能会因您的用例而异。经验法则

对于用户来说，经验法则是

使用您的硬件，在您的负载上测量性能。测量，测量，不断测量。真实的数字是唯一的方法。
如果您受限于延迟（实时产品进行推理），请不要进行批处理。
如果您使用的是 CPU，请不要进行批处理。
如果您使用的是吞吐量（您想在一堆静态数据上运行您的模型），在 GPU 上，那么
- 如果您对序列长度（“自然”数据）的大小一无所知，默认情况下不要进行批处理，测量并尝试暂时添加它，添加 OOM 检查以在失败时恢复（如果您不控制序列长度，它最终会在某个时候失败。）
- 如果您的序列长度非常规则，那么批处理更有可能非常有用，请进行测量并推动它，直到您遇到 OOM。
- GPU 越大，批处理就越有可能更有用
一旦您启用了批处理，请确保您可以很好地处理 OOM。

流水线块批处理

从某种意义上说，zero-shot-classification 和 question-answering 略微特殊，因为单个输入可能会产生模型的多次前向传递。在正常情况下，这会导致 batch_size 参数出现问题。

为了解决这个问题，这两个流水线都有些特殊，它们是 ChunkPipeline 而不是常规的 Pipeline。简而言之

preprocessed = pipe.preprocess(inputs)
model_outputs = pipe.forward(preprocessed)
outputs = pipe.postprocess(model_outputs)

现在变成

all_model_outputs = []
for preprocessed in pipe.preprocess(inputs):
    model_outputs = pipe.forward(preprocessed)
    all_model_outputs.append(model_outputs)
outputs = pipe.postprocess(all_model_outputs)

这对您的代码来说应该是非常透明的，因为流水线的使用方式是相同的。

这是一个简化的视图，因为流水线可以自动处理到！这意味着您不必关心您的输入实际上会触发多少次前向传递，您可以独立于输入优化 batch_size。上一节的注意事项仍然适用。

流水线 FP16 推理

模型可以使用 FP16 运行，这在 GPU 上可以显著提高速度并节省内存。大多数模型都不会因此遭受明显的性能损失。模型越大，性能损失的可能性就越小。

要启用 FP16 推理，您只需将 torch_dtype=torch.float16 或 torch_dtype='float16' 传递给流水线构造函数。请注意，这只适用于具有 PyTorch 后端的模型。您的输入将在内部转换为 FP16。

流水线自定义代码

如果您想覆盖特定的流水线。

请随时为您的任务创建一个问题，流水线的目标是易于使用并支持大多数情况，因此 transformers 或许可以支持您的用例。

如果您想简单地尝试，您可以

将您选择的流水线子类化

class MyPipeline(TextClassificationPipeline):
    def postprocess():
        # Your code goes here
        scores = scores * 100
        # And here


my_pipeline = MyPipeline(model=model, tokenizer=tokenizer, ...)
# or if you use *pipeline* function, then:
my_pipeline = pipeline(model="xxxx", pipeline_class=MyPipeline)

这应该可以让您执行所有您想要的自定义代码。

实现流水线

实现新的流水线

音频

可用于音频任务的流水线包括以下内容。

AudioClassificationPipeline

类 transformers.AudioClassificationPipeline

< 源代码 >

( *args **kwargs )

参数

model (PreTrainedModel 或 TFPreTrainedModel) — 管道将用于进行预测的模型。这需要是一个继承自 PreTrainedModel（对于 PyTorch）和 TFPreTrainedModel（对于 TensorFlow）的模型。
feature_extractor (SequenceFeatureExtractor) — 管道将用于为模型编码数据的特征提取器。此对象继承自 SequenceFeatureExtractor。
modelcard (str 或 ModelCard, 可选) — 归属于此管道模型的模型卡片。
framework (str, 可选) — 要使用的框架，"pt" 表示 PyTorch，"tf" 表示 TensorFlow。必须安装指定的框架。

如果未指定框架，则默认使用当前安装的框架。如果未指定框架并且安装了两个框架，则默认使用 model 的框架，如果未提供模型，则默认使用 PyTorch。
task (str, 默认值 "") — 管道的任务标识符。
num_workers (int，可选，默认为 8) — 当管道将使用 DataLoader 时（传递数据集时，在 GPU 上为 Pytorch 模型），要使用的 worker 数量。
batch_size (int，可选，默认为 1) — 当管道将使用 DataLoader 时（传递数据集时，在 GPU 上为 Pytorch 模型），要使用的批次大小，对于推理，这并不总是有益的，请阅读使用管道进行批处理。
args_parser (ArgumentHandler，可选) — 对负责解析提供的管道参数的对象的引用。
device (int，可选，默认为 -1) — CPU/GPU 支持的设备序号。将此设置为 -1 将利用 CPU，正数将在关联的 CUDA 设备 ID 上运行模型。你也可以传递原生 torch.device 或 str
torch_dtype (str 或 torch.dtype，可选) — 直接作为 model_kwargs（只是一个简单的快捷方式）发送，以使用此模型的可用精度（torch.float16、torch.bfloat16…或 "auto"）
binary_output (bool，可选，默认为 False) — 指示管道输出是否应以序列化格式（即 pickle）或原始输出数据（例如文本）发生的标志。

使用任何 AutoModelForAudioClassification 的音频分类管道。此管道预测原始波形或音频文件的类别。对于音频文件，应安装 ffmpeg 以支持多种音频格式。

示例

>>> from transformers import pipeline

>>> classifier = pipeline(model="superb/wav2vec2-base-superb-ks")
>>> classifier("https://huggingface.co/datasets/Narsil/asr_dummy/resolve/main/1.flac")
[{'score': 0.997, 'label': '_unknown_'}, {'score': 0.002, 'label': 'left'}, {'score': 0.0, 'label': 'yes'}, {'score': 0.0, 'label': 'down'}, {'score': 0.0, 'label': 'stop'}]

在管道教程中了解有关使用管道的基础知识的更多信息

此管道当前可以使用以下任务标识符从 pipeline() 加载："audio-classification"。

在huggingface.co/models 上查看可用模型列表。

Transformers

流水线

流水线抽象

transformers.pipeline

流水线批处理

流水线块批处理

流水线 FP16 推理

流水线自定义代码

实现流水线

音频

AudioClassificationPipeline

类 transformers.AudioClassificationPipeline

__call__

AutomaticSpeechRecognitionPipeline

类 transformers.AutomaticSpeechRecognitionPipeline

__call__

TextToAudioPipeline

类 transformers.TextToAudioPipeline

__call__

ZeroShotAudioClassificationPipeline

class transformers.ZeroShotAudioClassificationPipeline

__call__

计算机视觉

DepthEstimationPipeline

类 transformers.DepthEstimationPipeline

__call__

ImageClassificationPipeline

class transformers.ImageClassificationPipeline

__call__

ImageSegmentationPipeline

类 transformers.ImageSegmentationPipeline

__call__

ImageToImagePipeline

类 transformers.ImageToImagePipeline

__call__

ObjectDetectionPipeline

class transformers.ObjectDetectionPipeline

__call__

VideoClassificationPipeline

类 transformers.VideoClassificationPipeline

__call__

ZeroShotImageClassificationPipeline

类 transformers.ZeroShotImageClassificationPipeline

__call__

ZeroShotObjectDetectionPipeline

类 transformers.ZeroShotObjectDetectionPipeline

__call__

自然语言处理

FillMaskPipeline

类 transformers.FillMaskPipeline

__call__

QuestionAnsweringPipeline

类 transformers.QuestionAnsweringPipeline

__call__

create_sample

span_to_answer

SummarizationPipeline

类 transformers.SummarizationPipeline

__call__

TableQuestionAnsweringPipeline

class transformers.TableQuestionAnsweringPipeline

__call__

TextClassificationPipeline

类 transformers.TextClassificationPipeline

__call__

TextGenerationPipeline

类 transformers.TextGenerationPipeline

__call__

Text2TextGenerationPipeline

class transformers.Text2TextGenerationPipeline

__call__

check_inputs

TokenClassificationPipeline

类 transformers.TokenClassificationPipeline

__call__

aggregate_words

gather_pre_entities

group_entities

group_sub_entities

TranslationPipeline

call

call

call

call

call

call

call

call

call

call

call

call

call

call

call

call

call

call

call

call

call

call

call

call

call

call

call

call