nemo-mbridge-perf-sequence-packing

シーケンスパッキングスキル

安定性の背景情報と推奨レベルについては、以下を参照してください。

• @docs/training/packed-sequences.md
• @skills/nemo-mbridge-perf-sequence-packing/card.yaml

有効化

LLM ファインチューニング向けのオフラインパック済み SFT：

from megatron.bridge.data.datasets.packed_sequence import PackedSequenceSpecs

cfg.train.micro_batch_size = 1
cfg.dataset.seq_length = 4096
cfg.model.seq_length = 4096
cfg.dataset.dataset_kwargs = {"pad_to_max_length": True}
cfg.dataset.packed_sequence_specs = PackedSequenceSpecs(
    packed_sequence_size=4096,
    pad_seq_to_mult=1,
)

CP が有効な場合：

cfg.model.context_parallel_size = 2
cfg.model.calculate_per_token_loss = True
cfg.ddp.average_in_collective = False
cfg.dataset.packed_sequence_specs.pad_seq_to_mult = cfg.model.context_parallel_size * 2

# If sequence_parallel is also enabled, use lcm(2*CP, CP*TP):
# import math
# cfg.dataset.packed_sequence_specs.pad_seq_to_mult = math.lcm(2 * CP, CP * TP)
# See src/megatron/bridge/training/vlm_step.py for reference logic.

このパック済みパスで CUDA グラフが有効な場合：

cfg.dataset.packed_sequence_specs.pad_cu_seqlens = True
cfg.dataset.dataset_kwargs["pad_to_max_length"] = True

注： pad_cu_seqlens = True の場合、パック済みデータセットと同じ場所にメタデータ JSON ファイルも必要です（src/megatron/bridge/data/datasets/sft.py でアサーションされます）。メタデータファイルのないカスタムのパック済みデータセットは、データセットの初期化時にアサーションに失敗します。

VLM ファインチューニング向けのバッチ内パッキング：

cfg.dataset.pack_sequences_in_batch = True
cfg.train.micro_batch_size = 2

長文脈のベースライン：

cfg.model.seq_length = 16384
cfg.dataset.seq_length = 16384
cfg.model.context_parallel_size = 2

コードの参照箇所

LLM パック済み SFT の設定項目：

if packed_sequence:
    dataset_kwargs = {"pad_to_max_length": True}
    packed_sequence_specs = PackedSequenceSpecs(packed_sequence_size=seq_length, pad_seq_to_mult=pad_seq_to_mult)
else:
    dataset_kwargs = {}
    packed_sequence_specs = None

Bridge の検証：

if self.model.context_parallel_size > 1:
    assert self.model.seq_length % (self.model.context_parallel_size * 2) == 0, ...
    if isinstance(self.dataset, FinetuningDatasetConfig):
        assert self.model.calculate_per_token_loss, ...
        assert not self.ddp.average_in_collective, ...
...
if ... packed_sequence_size > 0 and self.train.micro_batch_size > 1:
    raise ValueError(...)
...
if getattr(self.dataset, "pack_sequences_in_batch", False) and self.train.micro_batch_size == 1:
    raise ValueError(...)

VLM のバッチ内ランタイム：

if enable_packing:
    ...
    ) = pack_batch_sequences(
        ...
        pad_token_id=0,
        pad_to_multiple_of=cp_size * 2 if cp_size > 1 else 1,
    )

パック済み THD のランタイム制約：

if cu_seqlens.dim() > 1 and cu_seqlens.size(0) != 1:
    raise ValueError("Packed THD batches expect micro-batch size 1 for context-parallel slicing (THD layout)")

注意点

1. オフラインのパック済み SFT と VLM のバッチ内パッキングは別の機能であり、マイクロバッチのルールも逆です。
2. CP が有効な場合、パック済みシーケンス長は 2 * context_parallel_size で割り切れる必要があります。
3. CP を使用したファインチューニングでは、calculate_per_token_loss=True と ddp.average_in_collective=False が必要です。
4. pad_cu_seqlens=True の場合、pad_to_max_length=True も必要です。
5. パッキングのサポートはモデルファミリーごとに異なります。Qwen3-Next、GLM-4.5、Qwen3.5-VL には、それぞれ異なるパスで明示的な対象外設定があります。
6. MTP ファインチューニングは、パック済みシーケンスと互換性がないとドキュメントに記載されています。

検証

リポジトリに含まれるユニットテストを使用してください。

uv run python -m pytest tests/unit_tests/training/utils/test_packed_seq_utils.py -v && \
uv run python -m pytest tests/unit_tests/training/test_config.py -k "packed_sequence or pack_sequences_in_batch or context_parallel_seq_length_divisibility or context_parallel_finetuning_validations" -v && \
uv run python -m pytest tests/unit_tests/training/test_vlm_step.py -k "enable_packing" -v

成功条件：

• 最初のコマンドで 8 passed と表示される
• 2 番目のコマンドで 14 passed と表示される
• 3 番目のコマンドで 2 passed と表示される