FIX: Use decoupled gradients for precision-aware M-FSDP grad norm by XueSongTap · Pull Request #3746 · NVIDIA/Megatron-LM

XueSongTap · 2026-03-09T02:32:07Z

What does this PR do ?

When Megatron FSDP is used with the precision-aware optimizer, update_main_grads() stores gradients on param.decoupled_grad instead of param.grad. https://github.com/NVIDIA/Megatron-LM/blob/main/megatron/core/optimizer/optimizer.py#L149

get_main_grads_for_grad_norm() previously prioritized the FSDP param.grad._local_tensor path, which could miss the actual gradient used by the optimizer and produce an incorrect grad norm for clipping. https://github.com/NVIDIA/Megatron-LM/blob/main/megatron/core/distributed/fsdp/src/megatron_fsdp/param_and_grad_buffer.py#L2873

Prioritize the precision-aware decoupled_grad path so grad norm and clip grad are computed from the correct gradient source.

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 the @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.

For MRs into `dev` branch

The proposed review process for `dev` branch is under active discussion.

MRs are mergable after one approval by either eharper@nvidia.com or zijiey@nvidia.com.

…e M-FSDP Signed-off-by: yexiaochuan <yexiaochuan@baidu.com>

copy-pr-bot · 2026-03-09T02:32:10Z

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-03-09T02:32:17Z

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.

…rad norm Signed-off-by: yexiaochuan <yexiaochuan@baidu.com>

shjwudp

Nice spot! Appreciate you fixing the bug!

shjwudp · 2026-03-09T06:55:35Z

/ok to test cb189e4

cspades · 2026-04-01T15:03:06Z

/ok to test 462443c

svcnvidia-nemo-ci · 2026-04-02T04:09:30Z

🔄 Merge queue validation started!

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

…IDIA#3746) Signed-off-by: yexiaochuan <yexiaochuan@baidu.com> Co-authored-by: yexiaochuan <yexiaochuan@baidu.com> Co-authored-by: Cory Ye <44509866+cspades@users.noreply.github.com>

…IDIA#3746) Signed-off-by: yexiaochuan <yexiaochuan@baidu.com> Co-authored-by: yexiaochuan <yexiaochuan@baidu.com> Co-authored-by: Cory Ye <44509866+cspades@users.noreply.github.com> Signed-off-by: yhgalaxy <yhgalaxy@outlook.com>

…IDIA#3746) Signed-off-by: yexiaochuan <yexiaochuan@baidu.com> Co-authored-by: yexiaochuan <yexiaochuan@baidu.com> Co-authored-by: Cory Ye <44509866+cspades@users.noreply.github.com> Signed-off-by: Jon Barker <jbarker@aws-cmh-slurm-1-vscode-02.cm.cluster>

# Description NVIDIA#4024 NVIDIA#3746 NVIDIA#2799 NVIDIA#3676 NVIDIA#4133 NVIDIA#3295 NVIDIA#3831 NVIDIA#3754 ## Type of change - [ ] New feature (non-breaking change which adds functionality) - [ ] Infra/Build change (changes to CI/CD workflows or build scripts) - [ ] Code refactoring - [ ] Documentation change - [x] Bug fix - [ ] Breaking change ## Changes - Content 1 - Content 2 - Content 3 - Content 4 ## Checklist - [ ] I have read and followed the contributing guidelines - [ ] The functionality is complete - [ ] I have commented my code, particularly in coverage report uploading steps - [ ] I have made corresponding changes to the documentation - [ ] My changes generate no new warnings - [ ] I have added/updated tests that prove my feature works - [ ] New and existing unit tests pass locally --------- Signed-off-by: Cory Ye <cye@nvidia.com> Signed-off-by: yexiaochuan <yexiaochuan@baidu.com> Signed-off-by: Akshat Kumar <akshat230405@gmail.com> Signed-off-by: Youngeun Kwon <youngeunk@nvidia.com> Signed-off-by: jinliangl <jinliangl@nvidia.com> Co-authored-by: Ritesh Patel <ripatel@nvidia.com> Co-authored-by: Cory Ye <cye@nvidia.com> Co-authored-by: Cory Ye <44509866+cspades@users.noreply.github.com> Co-authored-by: Xiaochuan Ye <tap91624@gmail.com> Co-authored-by: yexiaochuan <yexiaochuan@baidu.com> Co-authored-by: Akshat8510 <akshat230405@gmail.com> Co-authored-by: Kunlun Li <94586211+kunlunl@users.noreply.github.com> Co-authored-by: eternally-z <zzywzj@gmail.com> Co-authored-by: Philip Petrakian <ppetrakian@nvidia.com> Co-authored-by: Youngeun Kwon <youngeunk@nvidia.com> Co-authored-by: xuwchen <xuwenc@nvidia.com> Co-authored-by: Li Jinliang <jinliangl@nvidia.com>

…IDIA#3746) Signed-off-by: yexiaochuan <yexiaochuan@baidu.com> Co-authored-by: yexiaochuan <yexiaochuan@baidu.com> Co-authored-by: Cory Ye <44509866+cspades@users.noreply.github.com>

fix(optimizer): use decoupled grads for grad norm with precision-awar…

b387173

…e M-FSDP Signed-off-by: yexiaochuan <yexiaochuan@baidu.com>

XueSongTap requested review from a team as code owners March 9, 2026 02:32

svcnvidia-nemo-ci marked this pull request as draft March 9, 2026 02:32

github-actions Bot added the community-request label Mar 9, 2026

Merge branch 'main' into main

4342497

XueSongTap marked this pull request as ready for review March 9, 2026 02:35

svcnvidia-nemo-ci requested a review from a team March 9, 2026 02:35

svcnvidia-nemo-ci added the Final Review PR is in the "final review" stage label Mar 9, 2026

shjwudp assigned XueSongTap Mar 9, 2026

shjwudp requested a review from a team March 9, 2026 03:38

shjwudp added Expert Review [deprecated] Apply this label to indicate that your PR is ready for expert review. and removed Final Review PR is in the "final review" stage labels Mar 9, 2026

fix(optimizer): only read _local_tensor for FSDP decoupled grads in g…

cb189e4

…rad norm Signed-off-by: yexiaochuan <yexiaochuan@baidu.com>

shjwudp approved these changes Mar 9, 2026

View reviewed changes

svcnvidia-nemo-ci added this to the Core 0.16 milestone Mar 9, 2026

copy-pr-bot Bot temporarily deployed to test March 9, 2026 06:56 Inactive

chtruong814 added the needs-follow-up Issue needs follow-up label Mar 11, 2026

Merge branch 'main' into main

462443c

svcnvidia-nemo-ci added the Final Review PR is in the "final review" stage label Apr 1, 2026

copy-pr-bot Bot temporarily deployed to test April 1, 2026 15:04 Inactive

deepakn94 approved these changes Apr 1, 2026

View reviewed changes

chtruong814 removed the needs-follow-up Issue needs follow-up label Apr 1, 2026

ericharper approved these changes Apr 1, 2026

View reviewed changes

cspades enabled auto-merge April 1, 2026 23:48

cspades added this pull request to the merge queue Apr 1, 2026

Merged via the queue into NVIDIA:main with commit a52ceeb Apr 2, 2026
62 of 64 checks passed

zhaoyinglia mentioned this pull request Jul 16, 2026

cherry-pick fix pr for megatron_fsdp flagos-ai/Megatron-LM-FL#79

Merged

13 tasks

Navigation Menu

Uh oh!

FIX: Use decoupled gradients for precision-aware M-FSDP grad norm - #3746

FIX: Use decoupled gradients for precision-aware M-FSDP grad norm#3746
cspades merged 4 commits into
NVIDIA:mainfrom
XueSongTap:main

XueSongTap commented Mar 9, 2026 •

edited

Loading

Uh oh!

copy-pr-bot Bot commented Mar 9, 2026

Uh oh!

github-actions Bot commented Mar 9, 2026

Uh oh!

shjwudp left a comment

Uh oh!

shjwudp commented Mar 9, 2026

Uh oh!

cspades commented Apr 1, 2026

Uh oh!

svcnvidia-nemo-ci commented Apr 2, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

Uh oh!

Conversation

XueSongTap commented Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do ?

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 Mar 9, 2026

Uh oh!

github-actions Bot commented Mar 9, 2026

Uh oh!

shjwudp left a comment

Choose a reason for hiding this comment

Uh oh!

shjwudp commented Mar 9, 2026

Uh oh!

cspades commented Apr 1, 2026

Uh oh!

svcnvidia-nemo-ci commented Apr 2, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

XueSongTap commented Mar 9, 2026 •

edited

Loading