Pipeline

O Pipeline é uma API de inferência simples, porém poderosa, prontamente disponível para uma variedade de tarefas de aprendizado de máquina com qualquer modelo do Hub do Hugging Face.

Adapte o Pipeline à sua tarefa com parâmetros específicos, como adicionar timestamps a um pipeline de reconhecimento automático de fala (ASR) para transcrever anotações de reuniões. O Pipeline suporta GPUs, Apple Silicon e pesos em meia precisão para acelerar a inferência e economizar memória.

O Transformers possui duas classes de pipeline: o Pipeline genérico e vários pipelines específicos para tarefas, como o TextGenerationPipeline. Carregue esses pipelines individuais definindo o identificador da tarefa no parâmetro task em Pipeline. Você pode encontrar o identificador da tarefa de cada pipeline na documentação da API.

Cada tarefa é configurada para usar um modelo e um pré-processador pré-treinados por padrão, mas isso pode ser substituído com o parâmetro model caso você queira usar um modelo diferente.

Por exemplo, para usar o TextGenerationPipeline com o Gemma 2, defina task="text-generation" e model="google/gemma-2-2b".

from transformers import pipeline

pipeline = pipeline(task="text-generation", model="google/gemma-2-2b")
pipeline("the secret to baking a really good cake is ")
[{'generated_text': 'the secret to baking a really good cake is 1. the right ingredients 2. the'}]

Quando você tem mais de uma entrada, passe-as como uma lista.

from transformers import pipeline
from accelerate import Accelerator

device = Accelerator().device

pipeline = pipeline(task="text-generation", model="google/gemma-2-2b", device=device)
pipeline(["the secret to baking a really good cake is ", "a baguette is "])
[[{'generated_text': 'the secret to baking a really good cake is 1. the right ingredients 2. the'}],
 [{'generated_text': 'a baguette is 100% bread.\n\na baguette is 100%'}]]

Este guia apresentará o Pipeline, demonstrará seus recursos e mostrará como configurar seus diversos parâmetros.

Tarefas

Pipeline é compatível com diversas tarefas de aprendizado de máquina em diferentes modalidades. Passe uma entrada adequada para o pipeline e ele cuidará do restante.

Aqui estão alguns exemplos de como usar o Pipeline para diferentes tarefas e modalidades.

reconhecimento automático de fala

classificação de imagens

resposta a perguntas visuais

Parâmetros

No mínimo, o Pipeline requer apenas um identificador de tarefa, um modelo e a entrada apropriada. No entanto, há muitos parâmetros disponíveis para configurar o pipeline, desde parâmetros específicos da tarefa até a otimização do desempenho.

Esta seção apresenta alguns dos parâmetros mais importantes.

Dispositivo

Pipeline é compatível com vários tipos de hardware, incluindo GPUs, CPUs, Apple Silicon e outros. Configure o tipo de hardware com o parâmetro device. Por padrão, quando device não é definido, o Pipeline posiciona automaticamente o modelo no primeiro acelerador disponível (GPU CUDA, Apple Silicon MPS, XPU, …) e só recorre a uma CPU quando nenhum acelerador está disponível. Passe device="cpu" para forçar a execução em uma CPU.

GPU

Apple silicon

Inferência em lote

Pipeline também pode processar lotes de entradas com o parâmetro batch_size. A inferência em lote pode melhorar a velocidade, especialmente em uma GPU, mas isso não é garantido. Outras variáveis, como o hardware, os dados e o próprio modelo, podem afetar se a inferência em lote melhora a velocidade. Por esse motivo, a inferência em lote é desativada por padrão.

No exemplo abaixo, quando há 4 entradas e batch_size é definido como 2, o Pipeline passa um lote de 2 entradas para o modelo por vez.

from transformers import pipeline
from accelerate import Accelerator

device = Accelerator().device

pipeline = pipeline(task="text-generation", model="google/gemma-2-2b", device=device, batch_size=2)
pipeline(["the secret to baking a really good cake is", "a baguette is", "paris is the", "hotdogs are"])
[[{'generated_text': 'the secret to baking a really good cake is to use a good cake mix.\n\ni’'}],
 [{'generated_text': 'a baguette is'}],
 [{'generated_text': 'paris is the most beautiful city in the world.\n\ni’ve been to paris 3'}],
 [{'generated_text': 'hotdogs are a staple of the american diet. they are a great source of protein and can'}]]

Outro bom caso de uso para inferência em lote é para dados em streaming no Pipeline.

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

device = Accelerator().device

# KeyDataset is a utility that returns the item in the dict returned by the dataset
dataset = load_dataset("stanfordnlp/imdb", name="plain_text", split="unsupervised")
pipeline = pipeline(task="text-classification", model="distilbert/distilbert-base-uncased-finetuned-sst-2-english", device=device)
for out in pipeline(KeyDataset(dataset, "text"), batch_size=8, truncation="only_first"):
    print(out)

Mantenha em mente as seguintes diretrizes gerais para determinar se a inferência em lote pode ajudar a melhorar o desempenho.

A única maneira de ter certeza é medir o desempenho no seu modelo, nos seus dados e no seu hardware.
Não agrupe a inferência se você estiver limitado pela latência (por exemplo, um produto de inferência ao vivo).
Não faça inferência em lote se estiver usando uma CPU.
Não faça inferência em lote se você não souber o sequence_length dos seus dados. Meça o desempenho, adicione iterativamente ao sequence_length e inclua verificações de estouro de memória (OOM) para se recuperar de falhas.
Use inferência em lote se o seu sequence_length for regular e continue aumentando o lote até atingir um erro de OOM. Quanto maior a GPU, mais útil é a inferência em lote.
Lembre-se de garantir que você consiga lidar com erros de OOM caso decida fazer inferência em lote.

Parâmetros específicos da tarefa

Pipeline aceita quaisquer parâmetros suportados por cada pipeline de tarefa individual. Verifique cada pipeline de tarefa individual para ver que tipo de parâmetros estão disponíveis. Se você não encontrar um parâmetro útil para seu caso de uso, sinta-se à vontade para abrir uma issue no GitHub para solicitá-lo!

Os exemplos abaixo demonstram alguns dos parâmetros específicos de tarefa disponíveis.

reconhecimento automático de fala

geração de texto

Lote de blocos

Existem alguns casos em que é necessário processar dados em blocos.

para alguns tipos de dados, uma única entrada (por exemplo, um arquivo de áudio muito longo) pode precisar ser dividida em várias partes antes de poder ser processada
para algumas tarefas, como classificação zero-shot ou resposta a perguntas, uma única entrada pode exigir múltiplas passadas de frente, o que pode causar problemas com o parâmetro batch_size

A classe ChunkPipeline foi projetada para lidar com esses casos de uso. Ambas as classes de pipeline são usadas da mesma forma, mas, como o ChunkPipeline pode lidar automaticamente com o loteamento, você não precisa se preocupar com o número de passes de propagação para frente que suas entradas acionam. Em vez disso, você pode otimizar o batch_size de forma independente das entradas.

O exemplo abaixo mostra como ele difere de Pipeline.

# ChunkPipeline
all_model_outputs = []
for preprocessed in pipeline.preprocess(inputs):
    model_outputs = pipeline.model_forward(preprocessed)
    all_model_outputs.append(model_outputs)
outputs =pipeline.postprocess(all_model_outputs)

# Pipeline
preprocessed = pipeline.preprocess(inputs)
model_outputs = pipeline.forward(preprocessed)
outputs = pipeline.postprocess(model_outputs)

Conjuntos de dados grandes

Para inferência com grandes conjuntos de dados, você pode iterar diretamente sobre o próprio dataset. Isso evita a alocação imediata de memória para o dataset inteiro, e você não precisa se preocupar em criar os batches manualmente. Experimente a inferência em lote com o parâmetro batch_size para verificar se isso melhora o desempenho.

from transformers.pipelines.pt_utils import KeyDataset
from transformers import pipeline
from accelerate import Accelerator
from datasets import load_dataset

device = Accelerator().device

dataset = load_dataset("stanfordnlp/imdb", name="plain_text", split="unsupervised")
pipeline = pipeline(task="text-classification", model="distilbert/distilbert-base-uncased-finetuned-sst-2-english", device=device)
for out in pipeline(KeyDataset(dataset, "text"), batch_size=8, truncation="only_first"):
    print(out)

Outras formas de executar inferência em grandes conjuntos de dados com Pipeline incluem o uso de um iterador ou gerador.

def data():
    for i in range(1000):
        yield f"My example {i}"

pipeline = pipeline(model="openai-community/gpt2", device=0)
generated_characters = 0
for out in pipeline(data()):
    generated_characters += len(out[0]["generated_text"])

Modelos grandes

Accelerate habilita algumas otimizações para executar modelos grandes com Pipeline. Certifique-se de que o Accelerate está instalado primeiro.

!pip install -U accelerate

A configuração device_map="auto" é útil para distribuir automaticamente o modelo primeiro nos dispositivos mais rápidos (GPUs) e, em seguida, nos dispositivos mais lentos disponíveis (CPU, disco rígido).

O Pipeline suporta pesos em meia precisão (torch.float16), o que pode ser significativamente mais rápido e economizar memória. A perda de desempenho é insignificante para a maioria dos modelos, especialmente para os maiores. Se o seu hardware suportar, você pode habilitar o torch.bfloat16 em vez disso para obter uma faixa maior.

As entradas são convertidas internamente para torch.float16 e isso só funciona para modelos com backend PyTorch.

Por fim, o Pipeline também aceita modelos quantizados para reduzir ainda mais o uso de memória. Certifique-se de que a biblioteca bitsandbytes está instalada e, em seguida, adicione quantization_config a model_kwargs no pipeline.

import torch
from transformers import pipeline, BitsAndBytesConfig

pipeline = pipeline(model="google/gemma-7b", dtype=torch.bfloat16, device_map="auto", model_kwargs={"quantization_config": BitsAndBytesConfig(load_in_8bit=True)})
pipeline("the secret to baking a good cake is ")
[{'generated_text': 'the secret to baking a good cake is 1. the right ingredients 2. the right'}]

Update on GitHub