AutoGineer
Generated banner for Nemo Mbridge Perf Megatron Fsdp
Generated logo for Nemo Mbridge Perf Megatron Fsdp

Nemo Mbridge Perf Megatron Fsdp

NVIDIAOfficialPublished by NVIDIA

  • Skill
  • Tool integration
  • Software development
  • Apache-2.0
  • Medium risk
Download ZIP

From the author

Operational guide for enabling Megatron FSDP in Megatron-Bridge, including config knobs, code anchors, pitfalls, and verification.
— the description by NVIDIA

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a comprehensive reference for enabling and troubleshooting Megatron FSDP (Fully Sharded Data Parallel) in Megatron-Bridge. It covers essential configuration parameters, code migration paths, common pitfalls, and verification procedures to ensure stable training performance.

What it does

  • Provides configuration snippets for enabling Megatron FSDP in training recipes.
  • Details necessary adjustments for checkpoint formats and sharding strategies.
  • Identifies code anchors for migrating legacy distributed configuration settings.
  • Highlights common pitfalls regarding mutual exclusivity and hardware-specific settings.
  • Outlines functional smoke testing procedures to verify successful implementation.

When to use it

  • When transitioning from DDP to FSDP-based data parallelism.
  • When debugging Out-of-Memory (OOM) errors related to data parallel configurations.
  • When investigating performance regressions linked to FSDP settings.
  • When setting up new training runs requiring specific sharding strategies.

Advantages

  • Centralizes configuration requirements for Megatron FSDP.
  • Reduces integration errors by highlighting mandatory checkpoint format changes.
  • Provides clear validation steps to confirm correct deployment.
  • Clarifies the relationship between different distributed training wrappers.

Usage examples

“How do I enable Megatron FSDP in my Megatron-Bridge training config?”
The agent provides the required configuration block, including setting use_megatron_fsdp to True, selecting the appropriate sharding strategy, and configuring the fsdp_dtensor checkpoint format.
“I am getting an error when using Megatron FSDP, how do I verify my setup?”
The agent directs you to run the functional smoke test using the provided pytest command and explains how to interpret the logs for finite loss and successful checkpointing.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/nvidia/nemo-mbridge-perf-megatron-fsdp/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip nemo-mbridge-perf-megatron-fsdp.zip -d .agents/skills

Documentation by NVIDIA

Megatron FSDP Skill

For stable background and recommendation level, see:

  • @docs/training/megatron-fsdp.md

  • @skills/nemo-mbridge-perf-megatron-fsdp/card.yaml

Enablement

Minimal Megatron FSDP override in Bridge:

cfg.ddp.use_megatron_fsdp = True
cfg.ddp.data_parallel_sharding_strategy = "optim_grads_params"
cfg.ddp.average_in_collective = False
cfg.checkpoint.ckpt_format = "fsdp_dtensor"

Example recipe fixup:

cfg = llama3_8b_pretrain_config()
cfg.ddp.use_megatron_fsdp = True
cfg.ddp.data_parallel_sharding_strategy = "optim_grads_params"
cfg.ddp.average_in_collective = False
cfg.checkpoint.ckpt_format = "fsdp_dtensor"
cfg.checkpoint.save = "/tmp/fsdp_ckpts"
cfg.checkpoint.load = None

Performance harness note:

python scripts/performance/launch.py --use_megatron_fsdp true

Code Anchors

Megatron-Core DDP configuration (exposed as cfg.ddp in Bridge):

from megatron.core.distributed import DistributedDataParallelConfig

ddp_config = DistributedDataParallelConfig(use_megatron_fsdp=True)

DistributedInitConfig no longer accepts use_megatron_fsdp. Migrate existing cfg.dist.use_megatron_fsdp overrides to cfg.ddp.use_megatron_fsdp.

Bridge validation:

if self.ddp.use_megatron_fsdp and self.dist.use_torch_fsdp2:
    raise ValueError(...)
...
assert not self.dist.use_tp_pp_dp_mapping, "use_tp_pp_dp_mapping is not supported with Megatron FSDP"
...
assert self.checkpoint.ckpt_format == "fsdp_dtensor", (
    "Megatron FSDP only supports fsdp_dtensor checkpoint format"
)

Runtime wrapper selection:

if use_megatron_fsdp:
    DP = FullyShardedDataParallel
elif use_torch_fsdp2:
    DP = TorchFullyShardedDataParallel
else:
    DP = DistributedDataParallel
...
DP(
    config=get_model_config(model_chunk),
    ddp_config=ddp_config,
    module=model_chunk,
    ...
    pg_collection=pg_collection,
)

Perf harness overrides:

recipe.ddp.use_megatron_fsdp = True
recipe.ddp.data_parallel_sharding_strategy = "optim_grads_params"
recipe.ddp.keep_fp8_transpose_cache = False
recipe.ddp.average_in_collective = False
...
recipe.checkpoint.load = None

Pitfalls

  1. Public recipes often expose use_megatron_fsdp but still default to ckpt_format="torch_dist". If save/load is enabled, switch to fsdp_dtensor.

  2. use_torch_fsdp2 exists, but on the validated branch Bridge still fails before training because _ddp_wrap passes pg_collection.

  3. CPU offloading is only valid when pipeline_model_parallel_size == 1 and activation recomputation is disabled.

  4. Upstream warns that FSDP and TP/CP can want different CUDA_DEVICE_MAX_CONNECTIONS settings on Hopper and earlier.

  5. Megatron FSDP and FSDP2 are mutually exclusive.

Verification

Use the existing 2-GPU functional smoke test:

CUDA_VISIBLE_DEVICES=0,1 uv run python -m torch.distributed.run --nproc_per_node=2 \
  -m pytest tests/functional_tests/training/test_megatron_fsdp.py::TestMegatronFSDP::test_fsdp_pretrain_basic -v -s

Success criteria:

  • Pytest reports 1 passed

  • The log shows finite loss at the last iteration

  • The run finishes without a checkpoint format assertion

Files

BENCHMARK.md

Skill Benchmark: nemo-mbridge-perf-megatron-fsdp

✅ Overall verdict: PASS — Recommended for publication

Publication Recommendation

Recommended for publication based on the completed evaluation evidence in this report.

Evaluation Metadata

  • Skill: nemo-mbridge-perf-megatron-fsdp

  • Validation status: passed

  • Evaluation date: 2026-11-04

  • Evaluator version: 1.6.6

  • Agents: Claude Code (aws/anthropic/bedrock-claude-opus-5-5), Codex (openai/openai/gpt-6.1-sol)

  • Tasks: 1 evaluation tasks (1 positive)

  • Dataset digest: sha256:16192a516f7c2ea6a26939adadefb7c586f47ca060c1f0a59c72721dc0f0e393 (skill-evaluator-dataset-snapshot/1)

  • Attempts per task: 1

  • Environment: k8s-sandbox

  • Tier 2 evidence: required for publication

  • Tier 3 evidence: required for publication

Each task attempt ran in its own isolated sandbox pod.

Tier 1 LLM Provenance

SkillSpector provider, model, analyzer revision, and determinism evidence retained for this scan.

SkillProviderAdapterAnalyzerModelRevisionDeterminism
nemo-mbridge-perf-megatron-fsdpnv_inferenceopenaimcp_tool_poisoningaws/anthropic/bedrock-claude-opus-5-52.13.3nondeterministic / provider_defaults
nemo-mbridge-perf-megatron-fsdpnv_inferenceopenaisemantic_developer_intentaws/anthropic/bedrock-claude-opus-5-52.13.3nondeterministic / provider_defaults
nemo-mbridge-perf-megatron-fsdpnv_inferenceopenaisemantic_quality_policyaws/anthropic/bedrock-claude-opus-5-52.13.3nondeterministic / provider_defaults
nemo-mbridge-perf-megatron-fsdpnv_inferenceopenaisemantic_security_discoveryaws/anthropic/bedrock-claude-opus-5-52.13.3nondeterministic / provider_defaults
nemo-mbridge-perf-megatron-fsdpnv_inferenceopenaimeta_analyzeraws/anthropic/bedrock-claude-opus-5-52.13.3nondeterministic / provider_defaults

  • Controls for nemo-mbridge-perf-megatron-fsdp: temperature=not set (source=provider_default, forwarded=no); seed=not set (source=unset, forwarded=no); reasoning_effort=not set (source=provider_default, forwarded=no)

What This Report Answers

The three-tier evaluation checks whether the skill:

  • is safe to use;

  • produces correct answers;

  • is discovered and activated when needed;

  • helps the agent complete the user's goal and expected workflow; and

  • avoids wasted skill and tool usage.

Results at a Glance

MeasureClaude Code (Baseline → Skill Uplift)Codex (Baseline → Skill Uplift)
Overall98.1% — baseline ran, but no comparable score was available; uplift unavailable89.8% — baseline ran, but no comparable score was available; uplift unavailable
Security100.0% → 100.0% (±0.0 points)100.0% → 100.0% (±0.0 points)
Correctness60.0% → 100.0% (+40.0 points)100.0% → 100.0% (±0.0 points)
Discoverability100.0% — baseline ran, but no comparable score was available; uplift unavailable95.0% — baseline ran, but no comparable score was available; uplift unavailable
Effectiveness16.7% → 91.7% (+75.0 points)66.7% → 83.3% (+16.6 points)
Efficiency98.6% — baseline ran, but no comparable score was available; uplift unavailable70.6% — baseline ran, but no comparable score was available; uplift unavailable

How to read this table: baseline is the same task attempted without the target skill. Scores are rounded to one decimal; threshold-adjacent values use additional precision so their displayed band matches the verdict. Uplift is derived from those displayed scores and shown in percentage points.

Example: 47.0% → 92.0% (+45.0 points) means the skill-assisted run scored 92.0%, 45.0 percentage points above its 47.0% no-skill baseline.

Comparison details

Shared-source comparisons use the same signals and weights on both conditions. They do not replace the full dimension scores above or change the publication verdict.

AgentDimensionBasisBaseline → With skill (uplift)Explanation
claude-codeDiscoverabilityDimension comparisonN/ADiscoverability is not applicable to the no-skill baseline; there is no installed skill to discover.
claude-codeEfficiencyToken-only comparison84.0% → 97.2% (+13.2 points)Only Token Efficiency is comparable; the full dimension scores use different evaluator sources.
codexDiscoverabilityDimension comparisonN/ADiscoverability is not applicable to the no-skill baseline; there is no installed skill to discover.
codexEfficiencyToken-only comparison86.3% → 91.2% (+4.9 points)Only Token Efficiency is comparable; the full dimension scores use different evaluator sources.

Token Usage

Actual Tier 3 execution usage is reported for every observed agent/case pair and both conditions.

AgentDataset caseWith skillWithout skillDeltaChangeCoverage
claude-codeAll cases74,52173,128+1,393+1.90%skill 1/1; base 1/1
claude-codemegatron-fsdp-positive-enable-smoke74,52173,128+1,393+1.90%skill 1/1; base 1/1
codexAll cases32,60058,473-25,873-44.25%skill 1/1; base 1/1
codexmegatron-fsdp-positive-enable-smoke32,60058,473-25,873-44.25%skill 1/1; base 1/1
ALL AGENTSDataset aggregate107,121131,601-24,480-18.60%skill 2/2; base 2/2

Prompt tokens include cached reads, so total tokens are prompt + completion (cached is not added twice). The Efficiency score uses (prompt - cached) + completion. Change is 100 * (with - without) / without; negative means fewer tokens. N/A comparisons include their reason in the coverage column; coverage is never estimated.

Tier Status

TierPurposeStatusEvidence
Tier 1Static validationPASSED WITH OBSERVATIONS11 validator(s); 10 finding(s)
Tier 2Semantic deduplicationPASSED2 validator(s); 0 finding(s)
Tier 3Live agent evaluationPASS2 agent(s); 1 task(s)

Findings and Observations

<details> <summary>Show detailed findings and successful checks</summary>

  • MEDIUM QUALITY/quality_correctness: SKILL_SPEC recommended field missing: 'metadata.author' (skills/nemo-mbridge-perf-megatron-fsdp/SKILL.md)

  • MEDIUM QUALITY/quality_correctness: SKILL_SPEC recommended field missing: 'metadata.tags' (skills/nemo-mbridge-perf-megatron-fsdp/SKILL.md)

  • MEDIUM SCHEMA/body_recommended_section: Missing recommended section: '## Instructions' (skills/nemo-mbridge-perf-megatron-fsdp/SKILL.md)

  • MEDIUM SCHEMA/body_recommended_section: Missing recommended section: '## Examples' (skills/nemo-mbridge-perf-megatron-fsdp/SKILL.md)

  • MEDIUM SCHEMA/author_missing: Author not specified in metadata (skills/nemo-mbridge-perf-megatron-fsdp/SKILL.md)

  • 5 additional finding(s) are available in the full evaluation artifacts.

</details>

Scoring Methodology

<details> <summary>Show dimension definitions, source signals, and thresholds</summary>

DimensionQuestionScored signals
SecurityIs it safe to use?security (100%)
CorrectnessIs the answer correct?accuracy (100%)
DiscoverabilityWas the right skill loaded when needed?skill_execution (100%)
EffectivenessDid the skill help complete the task?goal_accuracy (50%) + behavior_check (50%)
EfficiencyDid it avoid wasted tool calls and token usage?skill_efficiency (50%) + token_efficiency (50%)

  • Dimension bands: PASS at 50% or above; NEUTRAL from 40% to below 50%; FAIL below 40%.

  • Overall Tier 3 lift: PASS at +5 points or more; FAIL at -10 points or less; values between those bands are NEUTRAL.

  • Overall verdict: PASS only when every configured dimension passes for at least one supported agent. Lift is reported as diagnostic evidence and does not override this gate.

  • The 50% attempt pass threshold is a separate per-task gate; it is not the dimension pass threshold.

  • Effectiveness is the equal-weight mean of goal completion (goal_accuracy) and expected workflow adherence (behavior_check).

  • Efficiency is 50% tool-call productivity (the backward-compatible skill_efficiency wire id) and 50% token_efficiency. Positive-case skill routing is scored under Discoverability, not Efficiency; a negative case without a routing target is N/A. N/A sources are omitted, remaining weights are renormalized, and the dimension is marked partial.

Signals present in this run:

  • security (Security): unsafe operations, secret leakage, and unauthorized access.

  • skill_execution (Skill Execution): whether the expected skill was selected, decoys were avoided, and the workflow executed.

  • skill_efficiency (Tool Productivity): tool-call productivity (legacy wire id; routing is scored under Discoverability).

  • accuracy (Accuracy): final-answer correctness against the reference answer.

  • goal_accuracy (Goal Accuracy): whether the user's goal was achieved.

  • behavior_check (Behavior Check): whether the expected workflow behavior was followed.

  • token_efficiency (Token Efficiency): actual uncached prompt plus completion usage (50% of Efficiency).

</details>

Freshness

Regenerate this benchmark when the skill, evaluation dataset, target agent/model, evaluator version, environment, or scoring policy changes.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Python

Security

What our scanner noticed· Medium risk

  • Large base64-encoded blobs

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
NVIDIA
Publisher
NVIDIA (Official)
Source
NVIDIA/skills · skills/nemo-mbridge-perf-megatron-fsdp · commit fce3cca
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE-APACHE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by NVIDIA.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download nemo-mbridge-perf-megatron-fsdp.zip