Transformers documentation
Entraînement sans bourrage
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’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.
Inférer les limites à partir de
position_idsn'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 deposition_idset nécessitent le data collator. Voir Modèles d'attention linéaire et de convolution.
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 pour aplatir chaque lot et renvoyer les informations de limites. Définissez return_flash_attn_kwargs=True afin que le collateur précalcule les limites au lieu de les laisser être déduites de position_ids à l'exécution. Transmettez-le à 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.
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, 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 n’est pas installé localement. Chargez le modèle avec
attn_implementation="kernels-community/flash-attn2".
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_idsest une vérification dynamique, dépendante des données. Elle fonctionne sans compilation, mais soustorch.compile, elle provoque des ruptures de graphe. La vérification est actuellement limitée àbatch_size == 1afin 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
intPython purs. Les inférer à partir deposition_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.
Ne vous fiez pas uniquement à
position_idspour les modèles GDN, linear-attention ou convolution causale. Préparez les kwargs de frontière, y comprisseq_idx, avec le data collator.
Pour ces modèles, définissez à la fois return_flash_attn_kwargs=True et return_seq_idx=True.
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, et les modèles basés sur Mamba tels que Bamba utilisent mamba-ssm. Les deux reposent sur 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.
La plupart de ces noyaux sont également disponibles via la bibliothèque 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 pour découvrir d'autres collators.
- Consultez la référence de l’API 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 pour consulter les benchmarks et un guide plus détaillé.