Pipeline

Le Pipeline est une API d’inférence simple mais puissante, immédiatement disponible pour une grande variété de tâches d’apprentissage automatique avec n’importe quel modèle du Hub Hugging Face.

Adaptez le Pipeline à votre tâche à l'aide de paramètres spécifiques, par exemple en ajoutant des horodatages à un pipeline de reconnaissance automatique de la parole (ASR) pour transcrire des notes de réunion. Pipeline prend en charge les GPU, Apple Silicon et les poids en demi-précision afin d'accélérer l'inférence et d'économiser de la mémoire.

Transformers dispose de deux classes de pipeline : le pipeline générique Pipeline et de nombreux pipelines spécifiques à une tâche, comme TextGenerationPipeline. Pour charger ces pipelines individuels, il suffit de définir l'identifiant de tâche dans le paramètre task de Pipeline. Vous trouverez l'identifiant de tâche de chaque pipeline dans sa documentation API.

Chaque tâche est configurée pour utiliser un modèle pré-entraîné et un préprocesseur par défaut, mais cela peut être remplacé au moyen du paramètre model si vous souhaitez utiliser un autre modèle.

Par exemple, pour utiliser TextGenerationPipeline avec Gemma 2, définissez task="text-generation" et 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'}]

Lorsque vous avez plus d'une entrée, passez-les sous forme de liste.

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%'}]]

Ce guide vous présente le Pipeline, illustre ses fonctionnalités et montre comment configurer ses différents paramètres.

Tâches

Pipeline est compatible avec de nombreuses tâches d'apprentissage automatique couvrant différentes modalités. Fournissez une entrée appropriée au pipeline et il s'occupera du reste.

Voici quelques exemples d'utilisation de Pipeline pour différentes tâches et modalités.

reconnaissance automatique de la parole

classification d'images

réponse à des questions visuelles

Paramètres

À minima, Pipeline ne requiert qu’un identifiant de tâche, un modèle et l’entrée appropriée. Toutefois, de nombreux paramètres sont disponibles pour configurer le pipeline, des paramètres spécifiques à la tâche à l’optimisation des performances.

Cette section vous présente certains des paramètres les plus importants.

Appareil

Pipeline est compatible avec de nombreux types de matériel, notamment les GPU, les CPU, Apple Silicon et d'autres encore. Configurez le type de matériel à l'aide du paramètre device. Par défaut, lorsque device n'est pas défini, Pipeline place automatiquement le modèle sur le premier accélérateur disponible (GPU CUDA, Apple Silicon MPS, XPU, …) et ne recourt à un CPU que si aucun accélérateur n'est disponible. Passez device="cpu" pour forcer l'exécution sur un CPU.

GPU

Apple silicon

Inférence par lots

Pipeline peut également traiter des lots d’entrées à l’aide du paramètre batch_size. L’inférence par lots peut améliorer la vitesse, en particulier sur GPU, mais ce n’est pas garanti. D’autres variables, telles que le matériel, les données et le modèle lui-même, peuvent influencer l’amélioration de la vitesse obtenue par l’inférence par lots. Pour cette raison, l’inférence par lots est désactivée par défaut.

Dans l’exemple ci-dessous, lorsqu’il y a 4 entrées et que batch_size est défini sur 2, Pipeline transmet au modèle un lot de 2 entrées à la fois.

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

Un autre bon cas d’usage de l’inférence par lots est le streaming de données dans 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)

Gardez à l'esprit les règles générales suivantes pour déterminer si l'inférence par lots peut contribuer à améliorer les performances.

La seule façon d’être certain est de mesurer les performances sur votre modèle, vos données et votre matériel.
Ne regroupez pas les inférences par lots si vous êtes contraint par la latence (par exemple, un produit d’inférence en direct).
N’effectuez pas d’inférence par lots si vous utilisez un CPU.
Ne regroupez pas l’inférence par lots si vous ne connaissez pas la sequence_length de vos données. Mesurez les performances, augmentez itérativement sequence_length et incluez des vérifications de dépassement de mémoire (OOM) pour récupérer en cas d’échec.
Effectuez une inférence par lots si votre sequence_length est régulière, et augmentez la taille du lot jusqu’à ce que vous obteniez une erreur OOM. Plus la GPU est grande, plus l’inférence par lots est utile.
Assurez-vous de pouvoir gérer les erreurs OOM si vous décidez d’effectuer une inférence par lots.

Paramètres spécifiques à la tâche

Pipeline accepte tous les paramètres pris en charge par chaque pipeline de tâche individuel. Pensez à consulter chaque pipeline de tâche pour découvrir les types de paramètres disponibles. Si vous ne trouvez pas un paramètre utile pour votre cas d’usage, n’hésitez pas à ouvrir un issue sur GitHub pour le demander !

Les exemples ci-dessous illustrent certains des paramètres spécifiques à la tâche disponibles.

reconnaissance automatique de la parole

génération de texte

Batching de chunks

Il existe certains cas où vous devez traiter les données par lots.

pour certains types de données, une seule entrée (par exemple, un fichier audio très long) peut devoir être découpée en plusieurs parties avant de pouvoir être traitée
pour certaines tâches, comme la classification en zéro tir ou la réponse à des questions, une seule entrée peut nécessiter plusieurs passes avant, ce qui peut poser des problèmes avec le paramètre batch_size

La classe ChunkPipeline est conçue pour gérer ces cas d’utilisation. Les deux classes de pipeline s’utilisent de la même manière, mais comme ChunkPipeline peut gérer automatiquement le groupement par lots, vous n’avez pas à vous soucier du nombre de passes avant que vos entrées déclenchent. Vous pouvez donc optimiser batch_size indépendamment des entrées.

L'exemple ci-dessous montre en quoi il diffère 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)

Jeux de données volumineux

Pour l’inférence sur de grands jeux de données, vous pouvez itérer directement sur le jeu de données lui-même. Cela évite d’allouer immédiatement la mémoire pour l’ensemble du jeu de données, et vous n’avez pas à vous soucier de créer les lots vous-même. Essayez l’inférence par lots avec le paramètre batch_size pour voir si cela améliore les performances.

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)

D'autres façons d'exécuter l'inférence sur de grands jeux de données avec Pipeline consistent à utiliser un itérateur ou un générateur.

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"])

Grands modèles

Accelerate permet d'appliquer plusieurs optimisations pour l'exécution de grands modèles avec Pipeline. Assurez-vous d'abord que Accelerate est installé.

!pip install -U accelerate

Le paramètre device_map="auto" est utile pour distribuer automatiquement le modèle sur les dispositifs les plus rapides (GPU) en priorité, avant de le répartir sur d'autres dispositifs plus lents s'ils sont disponibles (CPU, disque dur).

Pipeline prend en charge les poids en demi-précision (torch.float16), ce qui peut être nettement plus rapide et économiser de la mémoire. La perte de performances est négligeable pour la plupart des modèles, en particulier pour les plus grands. Si votre matériel le permet, vous pouvez activer torch.bfloat16 à la place pour bénéficier d'une plage dynamique plus large.

Les entrées sont converties en interne en torch.float16 et ne fonctionne que pour les modèles avec un backend PyTorch.

Enfin, Pipeline accepte également les modèles quantifiés afin de réduire encore davantage l’utilisation de la mémoire. Assurez-vous d’abord d’avoir installé la bibliothèque bitsandbytes, puis ajoutez quantization_config à model_kwargs dans le 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