NVIDIA-NeMo / NVIDIA-NeMo/Automodel
Adopt composable activation checkpointing once compile + DDP ready
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 963
- Forks
- 318
- Avg merge
- 3d 20h
- Merged PRs (30d)
- 143
Description
Summary
Track migration from module-replacing CheckpointWrapper activation checkpointing to PyTorch's type-preserving composable activation-checkpointing API:
from torch.distributed._composable import checkpoint
checkpoint(module)
The composable API installs checkpointing through forward hooks, preserving module identity, concrete type, model structure, and fully-qualified parameter names.
Motivation
PR #2955 fixes AM-370, where replacing block.mlp with CheckpointWrapper broke forward-time isinstance(self.mlp, MLP | MoE) dispatch in GPT-OSS and Qwen3-MoE.
Using the composable API centrally would avoid changing the apparent module type and eliminate this class of wrapper-aware model logic. PyTorch already exercises composable activation checkpointing together with FSDP2, but its compiled-FSDP parity test currently skips the composable variant.
Readiness gates
Adopt the composable API after all of the following are true:
- PyTorch exposes the API as stable/public, or AutoModel explicitly accepts depending on the private
torch.distributed._composablenamespace. - Composable activation checkpointing is supported and covered with
torch.compile+ FSDP2; the current upstream compile skip is removed. - The AutoModel DDP activation-checkpointing path is validated with the composable API.
- Full and selective activation checkpointing remain correct with
context_fn, RNG preservation, and per-layer compile. - Context-parallel attention hooks fire correctly during both forward and recomputation.
- KV-sharing fallback behavior remains correct.
- State-dict save/load, DCP, SafeTensors export, and FQN normalization remain compatible.
- Pipeline-parallel and expert-parallel configurations are covered.
Proposed migration
- Migrate the ordinary non-compiled submodule path in
apply_submodule_checkpointing(). - Migrate the DDP submodule-checkpointing path after parity coverage exists.
- Migrate compile/selective-AC paths only after upstream compile support is established.
- Remove model-specific
_checkpoint_wrapped_moduleinspection once no supported path replaces those submodules withCheckpointWrapper.
References
- PyTorch composable API: https://github.com/pytorch/pytorch/blob/23b1588b32ea2d46410793347d635017fdc49c75/torch/distributed/_composable/checkpoint_activation.py#L38-L46
- PyTorch FSDP2 parity coverage and current compiled-FSDP skip: https://github.com/pytorch/pytorch/blob/23b1588b32ea2d46410793347d635017fdc49c75/test/distributed/_composable/fsdp/test_fully_shard_training.py#L790-L855
- AutoModel PR #2955: https://github.com/NVIDIA-NeMo/Automodel/pull/2955
- Linear AM-370: https://linear.app/nvidia/issue/AM-370/nemo-bench-gpt-oss-qwen3-moe-pretrain-fsdp2-wrapped-selfmlp-fails
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with apply_submodule_checkpointing() and AutoModel PR #2955, then inspect the referenced PyTorch FSDP2 parity test and its compiled-FSDP skip. Trace the ordinary, DDP, compile, and selective-checkpointing paths against the listed readiness gates. Done means the supported paths use the composable API, compatibility coverage passes, and obsolete CheckpointWrapper inspection can be removed.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- distributed-systems, machine-learning
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100