Skip to content

[DEV] Cherry-pick: M4 + Dist Checkpoint: Replace global parallel state with explicit group parameters - #2152

Merged
yanring merged 31 commits into
NVIDIA:devfrom
yaoyu-33:yuya/m4_dist_ckpt_dev
Nov 11, 2025
Merged

[DEV] Cherry-pick: M4 + Dist Checkpoint: Replace global parallel state with explicit group parameters#2152
yanring merged 31 commits into
NVIDIA:devfrom
yaoyu-33:yuya/m4_dist_ckpt_dev

Conversation

@yaoyu-33

@yaoyu-33 yaoyu-33 commented Nov 5, 2025

Copy link
Copy Markdown
Contributor

This PR refactors the parallel group management to eliminate dependencies on global parallel_state.xxx APIs and instead use explicit group parameters (tp_group, pp_group, dp_cp_group) with fallbacks to existing global state when not provided.

Key Changes

1. Explicit Group Parameters

  • Added tp_group, pp_group, dp_cp_group parameters to key functions in:
    • megatron/training/checkpointing.py
    • megatron/training/utils.py
    • megatron/core/utils.py
  • Functions now accept Optional[torch.distributed.ProcessGroup] parameters with None defaults
  • When groups are None, code falls back to existing mpu.get_xxx_group() APIs for backward compatibility

2. Enhanced Metadata Handling

  • Extended _build_sharded_state_dict_metadata() to include dp_cp_group in metadata
  • Updated sharded state dict generation to properly propagate group information
  • dp_cp_group now consistently sourced from metadata across checkpoint operations

3. Improved Group Sourcing Strategy

  • Tensor/Pipeline Groups: Sourced directly from module.tp_group and module.pp_group
  • Data Parallel + Context Parallel Group: Sourced from metadata to ensure consistency across save/load operations
  • Utilizes get_pg_size() and get_pg_rank() utilities for group introspection

4. Function Signature Updates

Key functions updated with explicit group parameters:

  • save_checkpoint()
  • load_checkpoint()
  • get_rng_state()
  • _build_sharded_state_dict_metadata()

@yaoyu-33
yaoyu-33 requested review from a team as code owners November 5, 2025 23:46
@copy-pr-bot

copy-pr-bot Bot commented Nov 5, 2025

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.

@skyw skyw left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like it is mainly apply the boilerplate to all necessary places. LGTM.

The reason as of why tp_group is passed outside metadata is not clear. would recommend to document it some where in the code for users to understand and also prevent further changes from breaking it unintentionally.

Comment thread megatron/core/transformer/moe/experts.py
self.num_local_experts = num_local_experts
self.local_experts = torch.nn.ModuleList()
self.ep_group = pg_collection.ep
self.tp_group = pg_collection.expt_tp

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Q: Any reason to not use expt_tp_group to be consistent? Are there any code depend on the naming?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we were trying to keep it consistent in sharded state dict. it sometimes goes to parent's sharded state dict or default sharded state dict. In these modules it will look for self.tp_group.

Comment thread megatron/core/transformer/module.py Outdated
Comment thread megatron/core/transformer/utils.py Outdated
Comment thread megatron/core/utils.py
Comment thread megatron/core/utils.py Outdated

clean_metadata = metadata.copy()
# Remove dp_cp_group as it's not serializable
clean_metadata.pop('dp_cp_group', None)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Q: Is it possible to have other process groups reach here?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think so. dp_cp_group should be the only thing.

dimapihtar and others added 13 commits November 6, 2025 10:19
Signed-off-by: dimapihtar <dpihtar@gmail.com>
Signed-off-by: dimapihtar <dpihtar@gmail.com>
Signed-off-by: dimapihtar <dpihtar@gmail.com>
Signed-off-by: dimapihtar <dpihtar@gmail.com>
Signed-off-by: dimapihtar <dpihtar@gmail.com>
Signed-off-by: dimapihtar <dpihtar@gmail.com>
Signed-off-by: dimapihtar <dpihtar@gmail.com>
Signed-off-by: dimapihtar <dpihtar@gmail.com>
Signed-off-by: dimapihtar <dpihtar@gmail.com>
Signed-off-by: dimapihtar <dpihtar@gmail.com>
@yaoyu-33

yaoyu-33 commented Nov 6, 2025

Copy link
Copy Markdown
Contributor Author

/ok to test ddd3fca

@yaoyu-33

yaoyu-33 commented Nov 6, 2025

Copy link
Copy Markdown
Contributor Author

/ok to test 7d92f3c

@copy-pr-bot

copy-pr-bot Bot commented Nov 6, 2025

Copy link
Copy Markdown

/ok to test 7d92f3c

@yaoyu-33, there was an error processing your request: E2

See the following link for more information: https://docs.gha-runners.nvidia.com/cpr/e/2/

dimapihtar and others added 5 commits November 7, 2025 09:50
Signed-off-by: dimapihtar <dpihtar@gmail.com>
Signed-off-by: dimapihtar <dpihtar@gmail.com>
Signed-off-by: dimapihtar <dpihtar@gmail.com>
Signed-off-by: dimapihtar <dpihtar@gmail.com>
@yaoyu-33

yaoyu-33 commented Nov 7, 2025

Copy link
Copy Markdown
Contributor Author

/ok to test fcb950a

@yanring

yanring commented Nov 10, 2025

Copy link
Copy Markdown
Contributor

Regarding this MR, have we passed the functional test on dev/MR?

@yaoyu-33

Copy link
Copy Markdown
Contributor Author

/ok to test c67d12e

@yaoyu-33

Copy link
Copy Markdown
Contributor Author

unit and functional test both passed on original pr to main: #2053

@yanring

yanring commented Nov 11, 2025

Copy link
Copy Markdown
Contributor

BTW, what is the corresponding main PR? Could you update it in the desc?

@yaoyu-33

Copy link
Copy Markdown
Contributor Author

/ok to test e1da770

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

dev branch Dev branch related issues and development Run tests

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants