# パディングなしの学習

Padding-free training（packingとも呼ばれる）では、各サンプルを固定長にパディングする代わりに、複数のサンプルを1つのシーケンスに連結します。モデルは各サンプルの終了位置を知る必要があり、これにより（線形）attentionがサンプル間でトークンを混在させないようにします。

これらの境界を指定するには、2つの方法があります。

- データコラテーターを使って、事前にそれらを準備してください。
- 実行時に`position_ids`から推論します。

推奨されるアプローチは、データコラテーターです。本ガイドでは、その理由と`position_ids`パスに関する注意点について説明します。

> [!WARNING]
> `position_ids` から境界を推論することは推奨される方法ではなく、標準的な attention モデルでのみ機能します。Qwen3-Next や Qwen3.5 (Gated DeltaNet) などの Linear-attention モデル、および convolution ベースのモデルは `position_ids` の境界を無視するため、data collator が必要です。[Linear attention と convolution モデル](#linear-attention-and-convolution-models)を参照してください。

## データコラクターで境界を準備する

境界の kwargs を事前に準備しておくと、上記の問題が解消され、compile を使用する場合としない場合とで同じ挙動になります。

[DataCollatorWithFlattening](/docs/transformers/main/ja/main_classes/data_collator#transformers.DataCollatorWithFlattening) を使用して、各バッチをフラット化し、境界情報を返します。`return_flash_attn_kwargs=True` を設定することで、ランタイムで `position_ids` から推論されるのではなく、コラクターが境界を事前計算します。[Trainer](/docs/transformers/main/ja/main_classes/trainer#transformers.Trainer) にこれを渡し、フラット化されたバッチはすでに境界をエンコードしているため、マスクがパックされたレイアウトと競合する点に注意して、`attention_mask` を追加しないでください。

> [!TIP]
> Padding-free は、標準的なアテンションモデルに対して FlashAttention の実装に依存しています。フラット化されたバッチに必要な可変長パスを公開しているのは、FlashAttention カーネルのみだからです。
>
> ローカルでのビルドを必要とせず、事前ビルド済みの FlashAttention カーネルを取得する [kernels](./kernels) ライブラリをインストールします。また、[flash-attn](https://github.com/Dao-AILab/flash-attention) がローカルにインストールされていない場合のフォールバックとしても機能します。モデルは `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()
```

## position_ids から境界を推論する

FlashAttention は `position_ids` のみからパディングなしのバッチを検出でき、TRL などの下流フレームワークがこれに依存しているため、後方互換性を保つ目的で残されています。

`position_ids` に依存することには、2つの問題があります。

- `position_ids`からのパックシーケンスの検出は、動的かつデータ依存のチェックです。コンパイルなしでも動作しますが、`torch.compile`下ではグラフの分断を引き起こします。実際のバッチサイズは通常より大きいため、このチェックの実行頻度を抑制するために、現在は`batch_size == 1`に限定されています。
- Compiled FlashAttention は、一部の kwargs がプレーンな Python の `int` であることを強制します。実行時に `position_ids` からこれらを推論すると、デバイスとホスト間の同期が発生し、古い PyTorch バージョンでは、テンソルから int への変換により追加のグラフブレイクが発生します。

## 線形アテンションと畳み込みモデル

Gated DeltaNet (GDN)、その他の linear-attention レイヤー、および causal convolution は、設計上、`position_ids` のみのパスを持ちません。これらのモデルでは、collator を用いてデータを準備することが唯一サポートされている方法です。

> [!WARNING]
> GDN、linear-attention、またはcausal convolutionモデルでは、`position_ids`だけに依存しないでください。データコラテーターで、`seq_idx`を含む境界のkwargsを準備してください。

これらのモデルでは、`return_flash_attn_kwargs=True` と `return_seq_idx=True` の両方を設定してください。

```python
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](https://github.com/fla-org/flash-linear-attention) を使用し、Bamba などの Mamba ベースのモデルは [mamba-ssm](https://github.com/state-spaces/mamba) を使用します。どちらも畳み込みには [causal-conv1d](https://github.com/Dao-AILab/causal-conv1d) に依存しています。適切なカーネルがない場合、モデルは境界の kwargs を無視し、サンプル間でトークンを混在させる参照実装にフォールバックします。

> [!TIP]
> これらのカーネルの多くは、[kernels](./kernels)ライブラリを通じて利用可能であり、互換性のあるビルドを取得できます。flash-linear-attentionは、通常、直接インストールする必要があります。

境界の kwargs が欠落している場合、カーネルはバッチ全体を単一のシーケンスとして静かに扱います。ランタイムチェックはデータ依存の分岐を追加するため `torch.compile` と競合するため、エラーや警告は発生しません。

## 次のステップ

- その他のコラレーターについては、[データコラレーター](./data_collators)のガイドを参照してください。
- [DataCollatorWithFlattening](/docs/transformers/main/ja/main_classes/data_collator#transformers.DataCollatorWithFlattening) の API リファレンスをご覧ください。すべての引数が記載されています。
- ベンチマークとより詳細な解説については、[Flash Attention を用いたパッキングによる Hugging Face の学習効率の向上](https://huggingface.co/blog/packing-with-FA2)をお読みください。