# Entraînement sans bourrage

L'entraînement sans padding (également appelé packing) concatène plusieurs échantillons en une seule séquence au lieu de compléter chacun d'entre eux jusqu'à une longueur fixe. Le modèle doit savoir où se termine chaque échantillon afin que l'attention (linéaire) ne mélange pas les jetons entre les échantillons.

Il existe deux façons de fournir ces limites.

- Préparez-les à l'avance à l'aide d'un data collator.
- Les inférer à partir de `position_ids` à l'exécution.

L’approche recommandée est le data collator. Ce guide explique pourquoi et aborde les précautions à prendre avec le chemin `position_ids`.

> [!WARNING]
> Inférer les limites à partir de `position_ids` n'est pas l'approche recommandée et ne fonctionne que pour les modèles d'attention standard. Les modèles d'attention linéaire tels que Qwen3-Next et Qwen3.5 (Gated DeltaNet) ainsi que les modèles basés sur des convolutions ignorent les limites de `position_ids` et nécessitent le data collator. Voir [Modèles d'attention linéaire et de convolution](#linear-attention-and-convolution-models).

## Préparer les limites avec un collateur de données

Préparer les kwargs de frontière à l’avance élimine les problèmes mentionnés ci-dessus et se comporte de manière identique, que vous compiliez ou non.

Utilisez [DataCollatorWithFlattening](/docs/transformers/v5.23.0/fr/main_classes/data_collator#transformers.DataCollatorWithFlattening) pour aplatir chaque lot et renvoyer les informations de limites. Définissez `return_flash_attn_kwargs=True` afin que le collator précalcule les limites, plutôt que de les laisser être déduites de `position_ids` à l'exécution. Transmettez-le à [Trainer](/docs/transformers/v5.23.0/fr/main_classes/trainer#transformers.Trainer) et n'ajoutez pas de `attention_mask`, car le lot aplati encode déjà les limites et un masque entre en conflit avec la disposition compactée.

> [!TIP]
> Padding-free s'appuie sur une implémentation de FlashAttention pour les modèles d'attention standard, car seules les noyaux FlashAttention exposent le chemin de longueur variable dont un lot aplati a besoin.
>
> Installez la bibliothèque [kernels](./kernels), qui récupère un noyau FlashAttention précompilé sans nécessiter de compilation locale. Elle fonctionne également en solution de repli lorsque [flash-attn](https://github.com/Dao-AILab/flash-attention) n'est pas installé localement. Chargez le modèle avec `attn_implementation="kernels-community/flash-attn2"`.

```python
import torch
from datasets import load_dataset
from transformers import AutoModelForCausalLM, AutoTokenizer, DataCollatorWithFlattening, Trainer, TrainingArguments

model_id = "meta-llama/Llama-3.2-1B"
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    attn_implementation="flash_attention_2",
    device_map="auto",
)

dataset = load_dataset("Salesforce/wikitext", "wikitext-2-raw-v1", split="train")
dataset = dataset.map(
    lambda example: tokenizer(example["text"], truncation=True, max_length=512),
    remove_columns=dataset.column_names,
)

# return_flash_attn_kwargs=True precomputes the sequence boundaries
data_collator = DataCollatorWithFlattening(return_flash_attn_kwargs=True)

trainer = Trainer(
    model=model,
    args=TrainingArguments(output_dir="padding-free-llama"),
    train_dataset=dataset,
    data_collator=data_collator,
)
trainer.train()
```

## Inférer les limites à partir de position_ids

FlashAttention peut détecter les lots sans bourrage à partir de `position_ids` uniquement et est conservé pour des raisons de rétrocompatibilité, car des frameworks en aval tels que TRL en dépendent.

S'appuyer sur `position_ids` pose deux problèmes.

- La détection des séquences empilées à partir de `position_ids` est une vérification dynamique, dépendante des données. Elle fonctionne sans compilation, mais sous `torch.compile`, elle provoque des ruptures de graphe. La vérification est actuellement limitée à `batch_size == 1` afin de limiter sa fréquence d’exécution, les tailles de lot réelles étant généralement plus grandes.
- Compiled FlashAttention impose que certains kwargs soient des `int` Python purs. Les inférer à partir de `position_ids` à l'exécution force des synchronisations device-versi-host, et sur les versions plus anciennes de PyTorch, une rupture de graphe supplémentaire due à la conversion tensor-vers-int.

## Modèles d'attention linéaire et de convolution

Gated DeltaNet (GDN), les autres couches d'attention linéaire et les convolutions causales ne disposent pas de chemin basé uniquement sur `position_ids`, par conception. La préparation des données à l'aide du collateur est la seule option prise en charge pour ces modèles.

> [!WARNING]
> Ne vous fiez pas uniquement à `position_ids` pour les modèles GDN, linear-attention ou convolution causale. Préparez les kwargs de frontière, y compris `seq_idx`, avec le data collator.

Pour ces modèles, définissez à la fois `return_flash_attn_kwargs=True` et `return_seq_idx=True`.

```python
from transformers import DataCollatorWithFlattening

data_collator = DataCollatorWithFlattening(
    return_flash_attn_kwargs=True,
    return_seq_idx=True,
)
```

Les paquets de noyaux exacts dépendent de l'implémentation d'origine du modèle. Les modèles Gated DeltaNet tels que Qwen3-Next et Qwen3.5 utilisent [flash-linear-attention](https://github.com/fla-org/flash-linear-attention), et les modèles basés sur Mamba tels que Bamba utilisent [mamba-ssm](https://github.com/state-spaces/mamba). Les deux reposent sur [causal-conv1d](https://github.com/Dao-AILab/causal-conv1d) pour la convolution. Sans les noyaux appropriés, le modèle bascule sur des implémentations de référence qui ignorent les arguments de bordure et mélangent les jetons entre les échantillons.

> [!TIP]
> La plupart de ces noyaux sont également disponibles via la bibliothèque [kernels](./kernels), qui peut récupérer une version compatible pour vous. flash-linear-attention nécessite généralement toujours une installation directe.

Lorsque les kwargs de bordure sont absents, les noyaux traitent silencieusement le lot entier comme une seule séquence. Aucune erreur ni aucun avertissement n’est levé, car une vérification à l’exécution ajouterait une branche dépendante des données, ce qui entre en conflit avec `torch.compile`.

## Étapes suivantes

- Consultez le guide sur les [data collators](./data_collators) pour découvrir d'autres collators.
- Consultez la référence de l’API [DataCollatorWithFlattening](/docs/transformers/v5.23.0/fr/main_classes/data_collator#transformers.DataCollatorWithFlattening) pour l’ensemble complet des arguments.
- Lisez [Améliorer l’efficacité de l’entraînement Hugging Face grâce au packing avec Flash Attention](https://huggingface.co/blog/packing-with-FA2) pour consulter les benchmarks et un guide plus détaillé.

