Skip to content

feat(draft): support sequence packing with online eagle3 draft training - #3463

Open
yuekaizhang wants to merge 1 commit into
NVIDIA-NeMo:mainfrom
yuekaizhang:seq_pack
Open

feat(draft): support sequence packing with online eagle3 draft training#3463
yuekaizhang wants to merge 1 commit into
NVIDIA-NeMo:mainfrom
yuekaizhang:seq_pack

Conversation

@yuekaizhang

@yuekaizhang yuekaizhang commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

What does this PR do?

Adds sequence packing support to online EAGLE-3 draft training (previously the
two features were mutually exclusive). With packing enabled, policy training
time is cut roughly in half (~2100 vs ~1040 tok/s/GPU on a Qwen3-30B-A3B 8K
GRPO run), so draft co-training no longer pays the unpacked-training penalty.

Key changes:

  • Per-segment teacher-logit/embedding shifts in the packed [1, T] layout
    (boundary-safe rolls; no leakage across packing boundaries)
  • Packed draft-loss path in DraftLossWrapper with a packed token mask
  • THD attention support in the eagle module forward (padding_causal
    mask-type override for TE kernels)
  • Guard relaxed from draft ⊥ sequence-packing to draft ⊥ CP>1

Unit tests prove packed/unpacked numerical equivalence (full-vocab and
d2t-mapped drafts); verified end-to-end on 1n8g (8B) and 4n8g (30B-A3B) GRPO
runs with no acceptance regression.

Blue curve: without the PR
Orange curve: with the PR

image

@yuekaizhang
yuekaizhang requested review from a team as code owners August 3, 2026 05:16
@copy-pr-bot

copy-pr-bot Bot commented Aug 3, 2026

Copy link
Copy Markdown

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

@yuekaizhang

Copy link
Copy Markdown
Contributor Author

/ok to test 114598c

@github-actions github-actions Bot added the Documentation Improvements or additions to documentation label Aug 3, 2026
Online draft co-training previously forced sequence_packing off, which
roughly halves training/logprob throughput on MoE policies (forfeits
permute fusion) and made the eagle3 run slower end-to-end than a packed
baseline despite the spec-decode generation speedup.

- loss/utils: add roll_packed_seq_dim (per-segment left shift via one
  global roll + zeroed segment boundaries) and
  pack_rolled_draft_token_mask; factor the d2t teacher-vocab mapping out
  of prepare_loss_input into map_teacher_logits_to_draft_vocab.
- DraftLossWrapper: packed mode computes the draft soft-CE once over the
  packed layout (teacher shifted within segments, mask packed with the
  same shift); numerically identical to the unpacked path.
- train.py: in packed mode, build the draft's shifted input embeddings by
  re-embedding per-sequence-shifted token ids (_pack_input_ids
  roll_shift=-1) instead of rolling captured embeddings across packing
  boundaries; attach DraftLossWrapper on top of the packing loss wrappers
  (fused and non-fused) and pass packed_seq_params to the draft forward.
- EagleModel: forward packed_seq_params into the modelopt EagleModule and
  temporarily override the eagle layers' AttnMaskType.arbitrary with
  padding_causal for THD (TE's THD kernels reject arbitrary; mcore only
  auto-converts causal/no_mask).
- lm_policy: replace the draft-vs-packing guard with an explicit
  draft-vs-context-parallelism guard (CP was previously blocked only
  transitively through packing).

Validated by unit tests asserting packed == unpacked draft loss (with and
without d2t) and a 2-step 8B GPU run per packing loss wrapper; step-1
losses match bit-for-bit between the fused and non-fused wrappers.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: Yuekai Zhang <zhangyuekai@foxmail.com>
@yuekaizhang

Copy link
Copy Markdown
Contributor Author

/ok to test 01699bc

@yuekaizhang yuekaizhang added CI:L0 Run doctests and unit tests CI:Lfast Runs a fast test suite and re-use nightly `main` container (but sync dependencies to PRs version) and removed Documentation Improvements or additions to documentation CI:L0 Run doctests and unit tests labels Aug 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CI:Lfast Runs a fast test suite and re-use nightly `main` container (but sync dependencies to PRs version)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant