Transformers documentation

Pelatihan tanpa padding

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Pelatihan tanpa padding

Pelatihan tanpa padding (juga disebut packing) menggabungkan beberapa sampel menjadi satu urutan alih-alih melakukan padding pada masing-masing sampel hingga panjang tetap. Model perlu mengetahui di mana setiap sampel berakhir agar perhatian (linear) tidak mencampur token antar sampel.

Ada dua cara untuk menyediakan batas-batas tersebut.

  • Siapkan mereka sebelumnya dengan data collator.
  • Infer them dari position_ids saat runtime.

Pendekatan yang direkomendasikan adalah data collator. Panduan ini menjelaskan alasannya dan membahas hal-hal yang perlu diperhatikan pada jalur position_ids.

Menyimpulkan batas dari position_ids bukan pendekatan yang disarankan, dan hanya berfungsi untuk model attention standar. Model linear-attention seperti Qwen3-Next dan Qwen3.5 (Gated DeltaNet) serta model berbasis konvolusi mengabaikan batas position_ids dan memerlukan data collator. Lihat Model linear attention dan konvolusi.

Siapkan batas dengan data collator

Menyiapkan boundary kwargs di awal menghilangkan masalah-masalah di atas dan berperilaku identik terlepas dari apakah Anda melakukan kompilasi atau tidak.

Gunakan DataCollatorWithFlattening untuk meratakan setiap batch dan mengembalikan informasi batas. Atur return_flash_attn_kwargs=True agar collator menghitung batas terlebih dahulu, bukan membiarkannya disimpulkan dari position_ids saat runtime. Sampaikan ke Trainer dan jangan tambahkan attention_mask, karena batch yang telah diratakan sudah mengodekan batas dan mask akan bertentangan dengan layout yang dikemas.

Padding-free bergantung pada implementasi FlashAttention untuk model attention standar, karena hanya kernel FlashAttention yang mengekspos jalur panjang variabel yang dibutuhkan oleh batch yang diratakan.

Instal pustaka kernels, yang mengambil kernel FlashAttention yang sudah dibangun sebelumnya tanpa memerlukan build lokal. Pustaka ini juga berfungsi sebagai cadangan ketika flash-attn tidak diinstal secara lokal. Muat model dengan 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()

Infer batas dari position_ids

FlashAttention dapat mendeteksi batch tanpa padding hanya dari position_ids dan tetap dipertahankan demi kompatibilitas mundur, karena framework turunan seperti TRL bergantung padanya.

Bergantung pada position_ids memiliki dua masalah.

  • Deteksi sekuens yang dikemas dari position_ids adalah pemeriksaan dinamis yang bergantung pada data. Pemeriksaan ini berjalan tanpa kompilasi, tetapi di bawah torch.compile menyebabkan graph breaks. Saat ini, pemeriksaan dibatasi pada batch_size == 1 untuk membatasi seberapa sering pemeriksaan dijalankan, karena ukuran batch yang sebenarnya biasanya lebih besar.
  • Compiled FlashAttention memaksa beberapa kwargs menjadi int Python biasa. Menurunkan nilai-nilai tersebut dari position_ids pada saat runtime memaksa sinkronisasi perangkat-ke-host, dan pada versi PyTorch yang lebih lama, menyebabkan graph break tambahan akibat konversi tensor-ke-int.

Model atensi linear dan konvolusi

Gated DeltaNet (GDN), lapisan linear-attention lainnya, dan konvolusi kausal tidak memiliki jalur yang hanya menggunakan position_ids, sesuai dengan desainnya. Menyiapkan data dengan collator adalah satu-satunya opsi yang didukung untuk model-model ini.

Jangan hanya mengandalkan position_ids untuk model GDN, linear-attention, atau causal convolution. Siapkan boundary kwargs, termasuk seq_idx, dengan data collator.

Untuk model-model ini, atur return_flash_attn_kwargs=True dan return_seq_idx=True.

from transformers import DataCollatorWithFlattening

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

Paket kernel yang tepat bergantung pada implementasi asli model. Model Gated DeltaNet seperti Qwen3-Next dan Qwen3.5 menggunakan flash-linear-attention, sedangkan model berbasis Mamba seperti Bamba menggunakan mamba-ssm. Keduanya bergantung pada causal-conv1d untuk konvolusi. Tanpa kernel yang benar, model akan kembali ke implementasi referensi yang mengabaikan kwargs boundary dan mencampur token antar sampel.

Banyak kernel ini juga tersedia melalui pustaka kernels, yang dapat mengambil build yang kompatibel untuk Anda. flash-linear-attention biasanya masih memerlukan instalasi langsung.

Ketika kwargs batas tidak ada, kernel secara diam-diam memperlakukan seluruh batch sebagai satu urutan. Tidak ada error atau peringatan yang muncul, karena pemeriksaan runtime akan menambahkan cabang yang bergantung pada data, yang bertentangan dengan torch.compile.

Langkah selanjutnya

Update on GitHub