Transformers documentation
패딩 없는 학습
패딩 없는 학습
Padding-free training(또는 packing이라고도 함)은 각 샘플을 고정된 길이로 padding하는 대신 여러 샘플을 하나의 시퀀스로 연결(concatenate)합니다. 모델은 각 샘플이 어디에서 끝나는지 알아야 (linear) attention이 샘플 간에 토큰을 섞지 않도록 할 수 있습니다.
이러한 경계를 제공하는 방법은 두 가지가 있습니다.
- data collator를 사용하여 미리 준비합니다.
position_ids에서 런타임에 추론합니다.
권장되는 방법은 데이터 콜레이터입니다. 이 가이드에서는 그 이유와 position_ids 경로의 주의 사항을 설명합니다.
position_ids에서 경계를 추론하는 것은 권장되지 않는 방식이며, 표준 attention 모델에서만 동작합니다. Qwen3-Next와 Qwen3.5 (Gated DeltaNet)와 같은 Linear-attention 모델 및 convolution 기반 모델은position_ids경계를 무시하며 data collator가 필요합니다. Linear attention 및 convolution 모델을 참조하세요.
데이터 콜레이터로 경계 준비
boundary kwargs를 미리 준비하면 위의 문제를 제거할 수 있으며, 컴파일을 하든 하지 않든 동일한 방식으로 동작합니다.
DataCollatorWithFlattening를 사용하여 각 배치(flattening)를 평탄화하고 경계 정보를 반환합니다. return_flash_attn_kwargs=True를 설정하여 런타임에서 position_ids를 통해 경계를 추론하는 대신 collator가 경계를 사전 계산하도록 합니다. Trainer에 전달하고, 평탄화된 배치에 이미 경계가 인코딩되어 있으며 마스크가 패킹된 레이아웃과 충돌하므로 attention_mask를 추가하지 마세요.
Padding-free는 표준 attention 모델의 경우 FlashAttention 구현에 의존합니다. 이는 플래트닝된 배치에 필요한 가변 길이 경로를 노출하는 것이 FlashAttention 커널뿐이기 때문입니다.
로컬 빌드 없이 사전 빌드된 FlashAttention 커널을 가져오는 kernels 라이브러리를 설치합니다. 또한 flash-attn이 로컬에 설치되지 않은 경우에도 폴백으로 작동합니다.
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()position_ids에서 경계를 추론
FlashAttention은 position_ids만으로 패딩이 없는 배치(padding-free batch)를 감지할 수 있으며, TRL과 같은 하위 프레임워크가 이를 의존하고 있기 때문에 하위 호환성을 유지하기 위해 남아 있습니다.
position_ids에 의존하는 방식에는 두 가지 문제가 있습니다.
position_ids에서 packed sequence를 감지하는 것은 동적이고 데이터에 의존하는 검사입니다. 컴파일 없이도 작동하지만,torch.compile환경에서는 graph break를 유발합니다. 실제 배치 크기는 보통 더 크므로, 이 검사가 실행되는 빈도를 제한하기 위해 현재batch_size == 1로만 제한되어 있습니다.- Compiled FlashAttention은 일부 kwargs가 순수 Python
int여야 합니다. 런타임에position_ids에서 이를 추론하면 디바이스-호스트 동기화가 발생하며, 구버전 PyTorch에서는 텐서에서 int로 변환하는 과정에서 추가적인 그래프 브레이크가 발생합니다.
Linear attention 및 convolution 모델
Gated DeltaNet(GDN), 기타 linear-attention 레이어, causal convolution은 설계상 position_ids만 사용하는 경로를 지원하지 않습니다. 이러한 모델의 경우 collator로 데이터를 준비하는 것이 유일한 지원되는 방법입니다.
GDN, linear-attention, 또는 causal convolution 모델의 경우
position_ids만으로는 충분하지 않습니다.seq_idx를 포함한 boundary kwargs를 data collator로 준비하세요.
이러한 모델의 경우 return_flash_attn_kwargs=True와 return_seq_idx=True를 모두 설정하세요.
from transformers import DataCollatorWithFlattening
data_collator = DataCollatorWithFlattening(
return_flash_attn_kwargs=True,
return_seq_idx=True,
)정확한 커널 패키지는 모델의 원래 구현에 따라 달라집니다. Qwen3-Next와 Qwen3.5와 같은 Gated DeltaNet 모델은 flash-linear-attention을, Bamba와 같은 Mamba 기반 모델은 mamba-ssm을 사용합니다. 두 패키지 모두 합성곱(convolution)을 위해 causal-conv1d에 의존합니다. 올바른 커널이 없으면 모델은 경계(boundary) kwargs를 무시하고 샘플 간에 토큰을 혼합하는 참조 구현으로 폴백됩니다.
이러한 커널의 상당수는 kernels 라이브러리를 통해서도 사용할 수 있으며, 이 라이브러리는 호환되는 빌드를 가져와 줍니다. flash-linear-attention은 여전히 직접 설치가 필요한 경우가 많습니다.
boundary kwargs가 누락된 경우, 커널은 전체 배치(whole batch)를 하나의 시퀀스로 조용히 처리합니다. 런타임 체크는 데이터에 의존하는 분기를 추가하여 torch.compile과 충돌하기 때문에, 오류나 경고가 발생하지 않습니다.
다음 단계
- 기타 collator에 대해서는 data collators 가이드를 참조하세요.
- 전체 인자 집합에 대한 DataCollatorWithFlattening API 참고 문서를 참조하세요.
- 벤치마크와 더 자세한 설명은 Flash Attention을 활용한 Packing으로 Hugging Face 학습 효율 개선하기를 참고하세요.