# Pipeline

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

Adaptez le [Pipeline](/docs/transformers/main/fr/main_classes/pipelines#transformers.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](/docs/transformers/main/fr/main_classes/pipelines#transformers.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](/docs/transformers/main/fr/main_classes/pipelines#transformers.Pipeline) et de nombreux pipelines spécifiques à une tâche, comme [TextGenerationPipeline](/docs/transformers/main/fr/main_classes/pipelines#transformers.TextGenerationPipeline). Pour charger ces pipelines individuels, il suffit de définir l'identifiant de tâche dans le paramètre `task` de [Pipeline](/docs/transformers/main/fr/main_classes/pipelines#transformers.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](/docs/transformers/main/fr/main_classes/pipelines#transformers.TextGenerationPipeline) avec [Gemma 2](./model_doc/gemma2), définissez `task="text-generation"` et `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'}]
```

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

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

Ce guide vous présente le [Pipeline](/docs/transformers/main/fr/main_classes/pipelines#transformers.Pipeline), illustre ses fonctionnalités et montre comment configurer ses différents paramètres.

## Tâches

[Pipeline](/docs/transformers/main/fr/main_classes/pipelines#transformers.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](/docs/transformers/main/fr/main_classes/pipelines#transformers.Pipeline) pour différentes tâches et modalités.

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

## Paramètres

À minima, [Pipeline](/docs/transformers/main/fr/main_classes/pipelines#transformers.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](/docs/transformers/main/fr/main_classes/pipelines#transformers.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](/docs/transformers/main/fr/main_classes/pipelines#transformers.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.

Pour exécuter [Pipeline](/docs/transformers/main/fr/main_classes/pipelines#transformers.Pipeline) sur un GPU, définissez `device` sur l'identifiant de périphérique CUDA associé. Par exemple, `device=0` s'exécute sur le premier 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 ")
```

Vous pouvez également laisser [Accelerate](https://hf.co/docs/accelerate/index), une bibliothèque pour l’entraînement distribué, choisir automatiquement comment charger et stocker les poids du modèle sur l’appareil approprié. C’est particulièrement utile si vous disposez de plusieurs appareils. Accelerate charge et stocke les poids du modèle d’abord sur l’appareil le plus rapide, puis déplace les poids vers d’autres appareils (CPU, disque dur) au besoin. Définissez `device_map="auto"` pour laisser Accelerate choisir l’appareil.

> [!TIP]
> Vérifiez que [Accelerate](https://hf.co/docs/accelerate/basic_tutorials/install) est installé.
>
> ```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 ")
```

Pour exécuter [Pipeline](/docs/transformers/main/fr/main_classes/pipelines#transformers.Pipeline) sur Apple silicon, définissez `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 ")
```

### Inférence par lots

[Pipeline](/docs/transformers/main/fr/main_classes/pipelines#transformers.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 un 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 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](/docs/transformers/main/fr/main_classes/pipelines#transformers.Pipeline) transmet au modèle un lot de 2 entrées à la fois.

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

Un autre bon cas d’usage de l’inférence par lots est le streaming de données dans [Pipeline](/docs/transformers/main/fr/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)
```

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.

1. La seule façon d’être certain est de mesurer les performances sur votre modèle, vos données et votre matériel.
2. Ne regroupez pas les inférences par lots si vous êtes contraint par la latence (par exemple, un produit d’inférence en direct).
3. N'utilisez pas le batch d'inférence si vous utilisez un CPU.
4. 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.
5. 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.
6. 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](/docs/transformers/main/fr/main_classes/pipelines#transformers.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'utilisation, n'hésitez pas à ouvrir un [issue](https://github.com/huggingface/transformers/issues/new?assignees=&labels=feature&template=feature-request.yml) sur GitHub pour le demander !

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

Transmettez le paramètre `return_timestamps="word"` à [Pipeline](/docs/transformers/main/fr/main_classes/pipelines#transformers.Pipeline) pour obtenir le moment où chaque mot a été prononcé.

```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)}]}
```

Passez `return_full_text=False` à [Pipeline](/docs/transformers/main/fr/main_classes/pipelines#transformers.Pipeline) pour ne renvoyer que le texte généré, au lieu du texte complet (invite et texte généré).

[__call__()](/docs/transformers/main/fr/main_classes/pipelines#transformers.TextGenerationPipeline.__call__) prend également en charge des arguments nommés supplémentaires issus de la méthode [generate()](/docs/transformers/main/fr/main_classes/text_generation#transformers.GenerationMixin.generate). Pour renvoyer plus d'une séquence générée, définissez `num_return_sequences` sur une valeur supérieure à 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'}]
```

## 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](https://github.com/huggingface/transformers/blob/99e0ab6ed888136ea4877c6d8ab03690a1478363/src/transformers/pipelines/base.py#L1387) 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](https://github.com/huggingface/transformers/blob/99e0ab6ed888136ea4877c6d8ab03690a1478363/src/transformers/pipelines/base.py#L1387) 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](/docs/transformers/main/fr/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)
```

## 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](#batch-inference) avec le paramètre `batch_size` pour voir si cela améliore les performances.

```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)
```

D'autres façons d'exécuter l'inférence sur de grands jeux de données avec [Pipeline](/docs/transformers/main/fr/main_classes/pipelines#transformers.Pipeline) consistent à utiliser un itérateur ou un générateur.

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

## Grands modèles

[Accelerate](https://hf.co/docs/accelerate/index) permet d'appliquer plusieurs optimisations pour l'exécution de grands modèles avec [Pipeline](/docs/transformers/main/fr/main_classes/pipelines#transformers.Pipeline). Assurez-vous d'abord que Accelerate est installé.

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

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

Enfin, [Pipeline](/docs/transformers/main/fr/main_classes/pipelines#transformers.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](https://hf.co/docs/bitsandbytes/installation), puis ajoutez `quantization_config` à `model_kwargs` dans le 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'}]
```