[feat] Generalized Tensor Parallelism (GTP) by fanshiqing · Pull Request #4967 · NVIDIA/Megatron-LM

fanshiqing · 2026-05-25T07:25:19Z

I, the PR author, have personally reviewed every line of this PR.

What does this PR do ?

Generalized Tensor Parallelism (GTP) is a light-weight, high-performance and memory-efficient distributed training strategy implemented in Megatron-LM and TransformerEngine. It shards weight tensors across an GTP process group and reconstructs them on-demand via async all-gather, enabling training of larger models without sacrificing throughput by overlapping communication with computation.

GTP_README.md

Outline:

Features
1.1 Fine-grained, per-weight materialization & gradient reduction
1.2 CUDA graph compatibility
1.3 Low-precision gather (native FP8 / NVFP4 param)
1.4 Composability with TP / SP / EP / DDP
1.5 Opt-in, minimally invasive integration
1.6 Optimizer-agnostic (Adam + Muon)
1.7 Scaling
1.8 Native distributed checkpointing (DCP)
Usage
2.1 Required flags
2.2 High-priority streams (Blackwell and later)
2.3 Minimal end-to-end example
2.4 Tuning knobs
Implementation details
3.1 GTP_remat architecture (Mcore ↔ TE integration)
Class hierarchy: which linears shard
3.2 DDP buckets with (E)GTP_remat
3.3 Distributed checkpointing (DCP)
3.4 Prefetch-chain construction and its design assumptions
Testing
TE related MR: TE-3005 (Merged)

GTP's Architecture (Mcore + TE)

• TE ships self-contained: Protocol + dispatcher no-op.
• GTP lives 100% in Mcore as one protocol implementer.

Changes Summary

Convergence Test (07/25)

Config: 1/4 of NT3 Ultra,27Layers512Experts, 32xGB200, GTP16_EP8EGTP2_m1g32_mxfp8_CG, Adam Optimizer, forceBalance, vs. 3D parallel baseline with parallelism=TP8_EP16DP2_m1g32, ~10k steps, dataset=blend_files/1T-phase1var-moresft.json

GTP matches well with the 3d baseline in lm loss curve:

Issue tracking

For PRs from open-source community contributors:

New features: a linked issue is required. Please open a feature request and reference it here before submitting the PR.
Small updates (bug fixes, minor improvements): a linked issue is recommended and will accelerate the PR review process.

Linked issue:

Contribution process

Pre-checks

I have added relevant unit tests
I have added relevant functional tests
I have added proper typing to my code Typing guidelines
I have added relevant documentation
I have run the autoformatter.sh on my PR

Code review

Feel free to message or comment @NVIDIA/mcore-oncall to help accelerate your merge into main. The less complex your PR is, the faster it will be approved and merged!

All PRs start as draft. If you open a non-draft PR, it will be automatically converted to draft.

Step 1: Mark PR as "Ready for Review"

When your PR is ready, click Ready for Review.
An oncall reviewer is auto-assigned and expert reviewers are notified based on your changes.
- Some PRs may jump straight to step 2. This is determined by .github/CODEOWNERS.

⚠️ Only mark as ready once merge-conflicts are resolved and the CI is passing.
Final Review might get declined if these requirements are not fulfilled.

Step 2: Final Review

For PRs that change megatron/core, once all expert reviewers have approved, the Final Review label is applied automatically and final reviewers are assigned.

For PRs outside megatron/core, this step is skipped.

Step 3: Approved

Once all required reviewers have approved, the Approved label is applied automatically.

Merge

Any member of mcore-engineers will be able to merge your PR.

Co-authored-by: Jieming Zhang <jiemingz@nvidia.com> Signed-off-by: Shiqing Fan <shiqingf@nvidia.com>

copy-pr-bot · 2026-05-25T07:25:23Z

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.

github-actions · 2026-05-25T07:25:29Z

This PR has been automatically converted to draft because all PRs must start as drafts.

When you are ready for review, click Ready for Review to begin the review process. This will:

Add the oncall reviewer (optional reviewer)
Add required review teams based on your changes

See the contribution guide for more details.

Signed-off-by: Shiqing Fan <shiqingf@nvidia.com>

fanshiqing · 2026-05-25T08:49:48Z

/claude review

fanshiqing · 2026-07-23T23:54:58Z

/ok to test 34d420c

Signed-off-by: Shiqing Fan <shiqingf@nvidia.com>

fanshiqing · 2026-07-24T13:44:20Z

/ok to test 9870010

Signed-off-by: Shiqing Fan <shiqingf@nvidia.com>

fanshiqing · 2026-07-24T13:52:01Z

/ok to test 10fa249

mkhona-nvidia

Please leave TODOs in the 2 places where a comment has been added

Signed-off-by: Shiqing Fan <shiqingf@nvidia.com>

fanshiqing · 2026-07-24T23:09:39Z

/ok to test dea1206

fanshiqing · 2026-07-25T05:11:44Z

/ok to test 269949e

svcnvidia-nemo-ci · 2026-07-25T12:22:46Z

🔄 Merge queue validation started!

You can track the progress here: https://github.com/NVIDIA/Megatron-LM/actions/runs/30157876620

svcnvidia-nemo-ci · 2026-07-25T13:26:44Z

🔄 Merge queue validation started!

You can track the progress here: https://github.com/NVIDIA/Megatron-LM/actions/runs/30159727680

Signed-off-by: Shiqing Fan <shiqingf@nvidia.com>

Buckets were split by the layout's num_optimizer_shards (full DP world) while the collective runs over the intra-instance data_parallel_group, leaving half the params with no owning rank. Take the count from the group again. Signed-off-by: Shiqing Fan <shiqingf@nvidia.com>

fanshiqing · 2026-07-25T17:41:25Z

/ok to test 19f8482

svcnvidia-nemo-ci · 2026-07-25T19:17:54Z

🔄 Merge queue validation started!

You can track the progress here: https://github.com/NVIDIA/Megatron-LM/actions/runs/30171324705

Generalized Tensor Parallelism (GTP) init commit

162217c

Co-authored-by: Jieming Zhang <jiemingz@nvidia.com> Signed-off-by: Shiqing Fan <shiqingf@nvidia.com>

fanshiqing requested review from a team as code owners May 25, 2026 07:25

svcnvidia-nemo-ci marked this pull request as draft May 25, 2026 07:25

fanshiqing self-assigned this May 25, 2026

fanshiqing requested review from deepakn94, jaredcasper, jiemingz and kvareddy May 25, 2026 07:26

fix conflicts

1cab66a

Signed-off-by: Shiqing Fan <shiqingf@nvidia.com>

fanshiqing marked this pull request as ready for review May 25, 2026 08:11

svcnvidia-nemo-ci requested a review from a team May 25, 2026 08:12

svcnvidia-nemo-ci added the complexity: high label May 25, 2026

code clean

ccfee04

Signed-off-by: Shiqing Fan <shiqingf@nvidia.com>

fanshiqing changed the title ~~Generalized Tensor Parallelism (GTP)~~ [feat] Generalized Tensor Parallelism (GTP) May 25, 2026

claude Bot reviewed May 25, 2026

View reviewed changes

Comment thread megatron/core/extensions/transformer_engine.py Outdated

fanshiqing added 2 commits July 24, 2026 01:32

Test: assert GTP shard-group resolution is a safe read when GTP is off

a414d1b

Signed-off-by: Shiqing Fan <shiqingf@nvidia.com>

Rename tensor_parallel.gtp to gtp_api for clarity

9870010

Signed-off-by: Shiqing Fan <shiqingf@nvidia.com>

asolergi-nv approved these changes Jul 24, 2026

View reviewed changes

fix linting format

10fa249

Signed-off-by: Shiqing Fan <shiqingf@nvidia.com>

mkhona-nvidia reviewed Jul 24, 2026

View reviewed changes

Comment thread megatron/core/optimizer/emerging_optimizers.py

mkhona-nvidia reviewed Jul 24, 2026

View reviewed changes

Comment thread megatron/core/optimizer/emerging_optimizers.py

mkhona-nvidia requested changes Jul 24, 2026

View reviewed changes

yashaswikarnati approved these changes Jul 24, 2026

View reviewed changes

ericharper approved these changes Jul 24, 2026

View reviewed changes

fix comments: add necessary todo marker in emerging_optimizer.

dea1206

Signed-off-by: Shiqing Fan <shiqingf@nvidia.com>

mkhona-nvidia approved these changes Jul 25, 2026

View reviewed changes

fanshiqing added 2 commits July 25, 2026 10:33

Merge branch 'main' into gtp_release

d6af075

Signed-off-by: Shiqing Fan <shiqingf@nvidia.com>

MrAnayDongre mentioned this pull request Jul 27, 2026

Fix AG groups for custom parallel order #5754

Open

7 tasks

fanshiqing mentioned this pull request Aug 1, 2026

Fix layer-wise (Muon) distributed optimizer + fp8-param #5707

Closed

1 task

deepakn94 mentioned this pull request Aug 1, 2026

[DO NOT MERGE] GTP+Muon rebased onto main for testing #6194

Draft

fanshiqing mentioned this pull request Aug 4, 2026

[fix] Cleanup usage of pg_collection in gtp #6234

Merged

6 tasks

yaoyu-33 mentioned this pull request Aug 7, 2026

[feature] Integrate Megatron-Core Generalized Tensor Parallelism (GTP) NVIDIA-NeMo/Megatron-Bridge#5434

Open

8 tasks

fanshiqing mentioned this pull request Aug 13, 2026

[feat] GTP+DCP #6501

Closed

This was referenced Aug 17, 2026

2026年7月 Megatron-LM 工作汇总 lhb8125/Megatron-LM#56

Open

Megatron-LM Monthly Activity Report — July 2026 #6607

Open

Uh oh!

Conversation

fanshiqing commented May 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do ?

GTP's Architecture (Mcore + TE)

Changes Summary

Convergence Test (07/25)

Issue tracking

Contribution process

Pre-checks

Code review

Step 1: Mark PR as "Ready for Review"

Step 2: Final Review

Step 3: Approved

Merge

Uh oh!

copy-pr-bot Bot commented May 25, 2026

Uh oh!

github-actions Bot commented May 25, 2026

Uh oh!

fanshiqing commented May 25, 2026

Uh oh!

Uh oh!

fanshiqing commented Jul 23, 2026

Uh oh!

fanshiqing commented Jul 24, 2026

Uh oh!

fanshiqing commented Jul 24, 2026

Uh oh!

Uh oh!

Uh oh!

mkhona-nvidia left a comment

Choose a reason for hiding this comment

Uh oh!

fanshiqing commented Jul 24, 2026

Uh oh!

fanshiqing commented Jul 25, 2026

Uh oh!

svcnvidia-nemo-ci commented Jul 25, 2026

Uh oh!

svcnvidia-nemo-ci commented Jul 25, 2026

Uh oh!

fanshiqing commented Jul 25, 2026

Uh oh!

svcnvidia-nemo-ci commented Jul 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

14 participants

fanshiqing commented May 25, 2026 •

edited

Loading