# Pipeline

O [Pipeline](/docs/transformers/main/pt/main_classes/pipelines#transformers.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](https://hf.co/models) do Hugging Face.

Adapte o [Pipeline](/docs/transformers/main/pt/main_classes/pipelines#transformers.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](/docs/transformers/main/pt/main_classes/pipelines#transformers.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](/docs/transformers/main/pt/main_classes/pipelines#transformers.Pipeline) genérico e vários pipelines específicos para tarefas, como o [TextGenerationPipeline](/docs/transformers/main/pt/main_classes/pipelines#transformers.TextGenerationPipeline). Carregue esses pipelines individuais definindo o identificador da tarefa no parâmetro `task` em [Pipeline](/docs/transformers/main/pt/main_classes/pipelines#transformers.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](/docs/transformers/main/pt/main_classes/pipelines#transformers.TextGenerationPipeline) com o [Gemma 2](./model_doc/gemma2), defina `task="text-generation"` e `model="google/gemma-2-2b"`.

```py
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.

```py
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](/docs/transformers/main/pt/main_classes/pipelines#transformers.Pipeline), demonstrará seus recursos e mostrará como configurar seus diversos parâmetros.

## Tarefas

[Pipeline](/docs/transformers/main/pt/main_classes/pipelines#transformers.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](/docs/transformers/main/pt/main_classes/pipelines#transformers.Pipeline) para diferentes tarefas e modalidades.

```py
from transformers import pipeline

pipeline = pipeline(task="automatic-speech-recognition", model="openai/whisper-large-v3")
pipeline("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.'}
```

```py
from transformers import pipeline

pipeline = pipeline(task="image-classification", model="google/vit-base-patch16-224")
pipeline(images="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg")
[{'label': 'lynx, catamount', 'score': 0.43350091576576233},
 {'label': 'cougar, puma, catamount, mountain lion, painter, panther, Felis concolor',
  'score': 0.034796204417943954},
 {'label': 'snow leopard, ounce, Panthera uncia',
  'score': 0.03240183740854263},
 {'label': 'Egyptian cat', 'score': 0.02394474856555462},
 {'label': 'tiger cat', 'score': 0.02288915030658245}]
```

```py
from transformers import pipeline

pipeline = pipeline(task="visual-question-answering", model="Salesforce/blip-vqa-base")
pipeline(
    image="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/tasks/idefics-few-shot.jpg",
    question="What is in the image?",
)
[{'answer': 'statue of liberty'}]
```

## Parâmetros

No mínimo, o [Pipeline](/docs/transformers/main/pt/main_classes/pipelines#transformers.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](/docs/transformers/main/pt/main_classes/pipelines#transformers.Pipeline) é compatível com muitos 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](/docs/transformers/main/pt/main_classes/pipelines#transformers.Pipeline) coloca automaticamente o modelo no primeiro acelerador disponível (GPU CUDA, Apple Silicon MPS, XPU, ...) e só recorre a uma CPU quando nenhum está disponível. Passe `device="cpu"` para forçar a execução em uma CPU.

Para executar o [Pipeline](/docs/transformers/main/pt/main_classes/pipelines#transformers.Pipeline) em uma GPU, defina `device` como o id do dispositivo CUDA correspondente. Por exemplo, `device=0` executa na primeira GPU.

```py
from transformers import pipeline

pipeline = pipeline(task="text-generation", model="google/gemma-2-2b", device=0)
pipeline("the secret to baking a really good cake is ")
```

Você também pode deixar que o [Accelerate](https://hf.co/docs/accelerate/index), uma biblioteca para treinamento distribuído, escolha automaticamente como carregar e armazenar os pesos do modelo no dispositivo apropriado. Isso é especialmente útil se você tiver vários dispositivos. O Accelerate carrega e armazena os pesos do modelo primeiro no dispositivo mais rápido e, em seguida, move os pesos para outros dispositivos (CPU, disco rígido) conforme necessário. Defina `device_map="auto"` para deixar que o Accelerate escolha o dispositivo.

> [!TIP]
> Verifique se o [Accelerate](https://hf.co/docs/accelerate/basic_tutorials/install) está instalado.
>
> ```py
> !pip install -U accelerate
> ```

```py
from transformers import pipeline

pipeline = pipeline(task="text-generation", model="google/gemma-2-2b", device_map="auto")
pipeline("the secret to baking a really good cake is ")
```

Para executar o [Pipeline](/docs/transformers/main/pt/main_classes/pipelines#transformers.Pipeline) em Apple silicon, defina `device="mps"`.

```py
from transformers import pipeline

pipeline = pipeline(task="text-generation", model="google/gemma-2-2b", device="mps")
pipeline("the secret to baking a really good cake is ")
```

### Inferência em lote

[Pipeline](/docs/transformers/main/pt/main_classes/pipelines#transformers.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](/docs/transformers/main/pt/main_classes/pipelines#transformers.Pipeline) passa um lote de 2 entradas para o modelo por vez.

```py
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](/docs/transformers/main/pt/main_classes/pipelines#transformers.Pipeline).

```py
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.

1. A única maneira de ter certeza é medir o desempenho no seu modelo, nos seus dados e no seu hardware.
2. Não faça inferência em lote se você estiver limitado por latência (por exemplo, um produto de inferência ao vivo).
3. Não faça inferência em lote se estiver usando uma CPU.
4. 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.
5. 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.
6. 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](/docs/transformers/main/pt/main_classes/pipelines#transformers.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](https://github.com/huggingface/transformers/issues/new?assignees=&labels=feature&template=feature-request.yml) no GitHub para solicitá-lo!

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

Passe o parâmetro `return_timestamps="word"` para [Pipeline](/docs/transformers/main/pt/main_classes/pipelines#transformers.Pipeline) para retornar quando cada palavra foi falada.

```py
from transformers import pipeline

pipeline = pipeline(task="automatic-speech-recognition", model="openai/whisper-large-v3")
pipeline(audio="https://huggingface.co/datasets/Narsil/asr_dummy/resolve/main/mlk.flac", return_timestamps="word")
{'text': ' I have a dream that one day this nation will rise up and live out the true meaning of its creed.',
 'chunks': [{'text': ' I', 'timestamp': (0.0, 1.1)},
  {'text': ' have', 'timestamp': (1.1, 1.44)},
  {'text': ' a', 'timestamp': (1.44, 1.62)},
  {'text': ' dream', 'timestamp': (1.62, 1.92)},
  {'text': ' that', 'timestamp': (1.92, 3.7)},
  {'text': ' one', 'timestamp': (3.7, 3.88)},
  {'text': ' day', 'timestamp': (3.88, 4.24)},
  {'text': ' this', 'timestamp': (4.24, 5.82)},
  {'text': ' nation', 'timestamp': (5.82, 6.78)},
  {'text': ' will', 'timestamp': (6.78, 7.36)},
  {'text': ' rise', 'timestamp': (7.36, 7.88)},
  {'text': ' up', 'timestamp': (7.88, 8.46)},
  {'text': ' and', 'timestamp': (8.46, 9.2)},
  {'text': ' live', 'timestamp': (9.2, 10.34)},
  {'text': ' out', 'timestamp': (10.34, 10.58)},
  {'text': ' the', 'timestamp': (10.58, 10.8)},
  {'text': ' true', 'timestamp': (10.8, 11.04)},
  {'text': ' meaning', 'timestamp': (11.04, 11.4)},
  {'text': ' of', 'timestamp': (11.4, 11.64)},
  {'text': ' its', 'timestamp': (11.64, 11.8)},
  {'text': ' creed.', 'timestamp': (11.8, 12.3)}]}
```

Passe `return_full_text=False` para [Pipeline](/docs/transformers/main/pt/main_classes/pipelines#transformers.Pipeline) para retornar apenas o texto gerado, em vez do texto completo (prompt e texto gerado).

[__call__()](/docs/transformers/main/pt/main_classes/pipelines#transformers.TextGenerationPipeline.__call__) também suporta argumentos de palavra-chave adicionais do método [generate()](/docs/transformers/main/pt/main_classes/text_generation#transformers.GenerationMixin.generate). Para retornar mais de uma sequência gerada, defina `num_return_sequences` com um valor maior que 1.

```py
from transformers import pipeline

pipeline = pipeline(task="text-generation", model="openai-community/gpt2")
pipeline("the secret to baking a good cake is", num_return_sequences=4, return_full_text=False)
[{'generated_text': ' how easy it is for me to do it with my hands. You must not go nuts, or the cake is going to fall out.'},
 {'generated_text': ' to prepare the cake before baking. The key is to find the right type of icing to use and that icing makes an amazing frosting cake.\n\nFor a good icing cake, we give you the basics'},
 {'generated_text': " to remember to soak it in enough water and don't worry about it sticking to the wall. In the meantime, you could remove the top of the cake and let it dry out with a paper towel.\n"},
 {'generated_text': ' the best time to turn off the oven and let it stand 30 minutes. After 30 minutes, stir and bake a cake in a pan until fully moist.\n\nRemove the cake from the heat for about 12'}]
```

## 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](https://github.com/huggingface/transformers/blob/99e0ab6ed888136ea4877c6d8ab03690a1478363/src/transformers/pipelines/base.py#L1387) foi projetada para lidar com esses casos de uso. Ambas as classes de pipeline são usadas da mesma forma, mas como o [ChunkPipeline](https://github.com/huggingface/transformers/blob/99e0ab6ed888136ea4877c6d8ab03690a1478363/src/transformers/pipelines/base.py#L1387) 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](/docs/transformers/main/pt/main_classes/pipelines#transformers.Pipeline).

```py
# 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 conjunto de dados. Isso evita a alocação imediata de memória para todo o conjunto de dados e você não precisa se preocupar em criar lotes por conta própria. Tente [Inferência em lote](#batch-inference) com o parâmetro `batch_size` para ver se isso melhora o desempenho.

```py
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](/docs/transformers/main/pt/main_classes/pipelines#transformers.Pipeline) incluem o uso de um iterador ou gerador.

```py
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](https://hf.co/docs/accelerate/index) habilita algumas otimizações para executar modelos grandes com [Pipeline](/docs/transformers/main/pt/main_classes/pipelines#transformers.Pipeline). Certifique-se de que o Accelerate está instalado primeiro.

```py
!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](/docs/transformers/main/pt/main_classes/pipelines#transformers.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.

> [!TIP]
> As entradas são convertidas internamente para torch.float16 e isso só funciona para modelos com backend PyTorch.

Por fim, o [Pipeline](/docs/transformers/main/pt/main_classes/pipelines#transformers.Pipeline) também aceita modelos quantizados para reduzir ainda mais o uso de memória. Certifique-se de que a biblioteca [bitsandbytes](https://hf.co/docs/bitsandbytes/installation) está instalada e, em seguida, adicione `quantization_config` a `model_kwargs` no pipeline.

```py
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'}]
```