Transformers documentation

Обучение без дополнения

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Обучение без дополнения

Обучение без дополнения (также называемое упаковкой) заключается в конкатенации нескольких образцов в одну последовательность вместо дополнения каждого из них до фиксированной длины. Модели необходимо знать, где заканчивается каждый образец, чтобы (линейное) внимание не смешивало токены между образцами.

Существует два способа задать эти границы.

  • Заранее подготовьте их с помощью коллаборатора данных.
  • Определять их из position_ids во время выполнения.

Рекомендуемый подход — это data collator. В этом руководстве объясняется, почему это так, и рассматриваются нюансы, связанные с путём position_ids.

Вывод границ из position_ids не является предпочтительным подходом и работает только для стандартных моделей внимания. Линейные модели внимания, такие как Qwen3-Next и Qwen3.5 (Gated DeltaNet), а также модели на основе свёрток игнорируют границы position_ids и требуют использования data collator. См. Линейные модели внимания и модели на основе свёрток.

Подготовка границ с помощью коллаборатора данных

Предварительная подготовка аргументов boundary kwargs устраняет описанные выше проблемы и обеспечивает идентичное поведение независимо от того, компилируется код или нет.

Используйте DataCollatorWithFlattening для сжатия каждого батча и возврата информации о границах. Установите return_flash_attn_kwargs=True, чтобы коллактор заранее вычислял границы, а не оставлял их для определения из position_ids во время выполнения. Передайте его в Trainer и не добавляйте attention_mask, так как сжатый батч уже кодирует границы, а маска конфликтует с упакованной структурой.

Padding-free опирается на реализацию FlashAttention для стандартных моделей внимания, поскольку только ядра FlashAttention предоставляют путь переменной длины, необходимый для сглаженной (flattened) батча.

Установите библиотеку kernels, которая загружает предварительно собранный ядро FlashAttention без необходимости локальной сборки. Она также работает как резервный вариант, если 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 может определять батчи без padding по одному position_ids и сохраняется в целях обратной совместимости, поскольку от него зависят такие фреймворки, как TRL.

Опора на position_ids имеет две проблемы.

  • Обнаружение упакованных последовательностей по position_ids — это динамическая, зависящая от данных проверка. Она работает без компиляции, но при использовании torch.compile приводит к разрывам графа. В настоящее время проверка ограничена условием batch_size == 1, чтобы снизить частоту её выполнения, поскольку фактические размеры батчей обычно больше.
  • Compiled FlashAttention требует, чтобы некоторые kwargs были обычными Python-целыми числами int. Их вычисление из position_ids во время выполнения приводит к синхронизации между устройством и хостом, а в более старых версиях PyTorch — к дополнительному разрыву графа из-за преобразования тензора в целое число.

Модели линейного внимания и свёртки

Gated DeltaNet (GDN), другие слои линейного внимания и каузальные свёртки по замыслу не имеют пути, использующего только position_ids. Подготовка данных с помощью collator — единственный поддерживаемый вариант для этих моделей.

Не полагайтесь только на position_ids для моделей GDN, linear-attention или causal convolution. Готовьте граничные kwargs, включая seq_idx, с помощью 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,
)

Точный набор пакетов с ядрами зависит от исходной реализации модели. Модели Gated DeltaNet, такие как Qwen3-Next и Qwen3.5, используют flash-linear-attention, а модели на основе Mamba, такие как Bamba, используют mamba-ssm. Обе зависят от causal-conv1d для выполнения свёртки. При отсутствии нужных ядер модель переключается на эталонные реализации, которые игнорируют аргументы границ и смешивают токены между разными образцами.

Многие из этих ядер также доступны через библиотеку kernels, которая может подобрать для вас совместимую сборку. flash-linear-attention, как правило, по-прежнему требует прямой установки.

Если аргументы boundary kwargs отсутствуют, ядра молча рассматривают весь батч как одну последовательность. Ни одна ошибка или предупреждение не возникает, поскольку проверка во время выполнения добавила бы ветвление, зависящее от данных, что конфликтует с torch.compile.

Дальнейшие шаги

Update on GitHub