Skip to content

Commit 5224123

Browse files
committed
fix(perf): align HSDP recipe tests and verification docs
Remove the unused NCCL EP flag from the HybridEP HSDP recipe and test its current 256-GPU entry point. Correct token throughput from the recorded step time, sequence length, global batch size, and GPU count. The catalog renderer did not recognize the new pretrain_performance_hsdp workflow, hiding its commands from model guides. Register it as a separate benchmark option for all cards using this workflow, preserve existing benchmark rendering, cover both Sphinx and Fern output, and regenerate the catalog and guides. Validation: 120 targeted unit tests passed; model card validation, generated-doc freshness, and pre-commit --all-files passed. Signed-off-by: Chen Cui <chcui@nvidia.com>
1 parent ddab81f commit 5224123

10 files changed

Lines changed: 191 additions & 10 deletions

File tree

‎docs/_static/model-verification/catalog-v1.json‎

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -691,14 +691,47 @@
691691
"status": "verified",
692692
"variant": null,
693693
"workflow": "pretrain_performance"
694+
},
695+
{
696+
"bridge_commit": "797a3141d3ccc4ec20a45cc653a4b69f9af0cdbf",
697+
"command_topologies": [
698+
{
699+
"gpus_per_node": "4",
700+
"nodes": "64",
701+
"recipe": "deepseek_v3_pretrain_256gpu_gb300_fp8mx_hsdp_config",
702+
"sequence_length": "4096",
703+
"total_gpus": 256
704+
}
705+
],
706+
"commands": [
707+
"./scripts/training/train.sh --wait --nodes 64 --gpus-per-node 4 --recipe deepseek_v3_pretrain_256gpu_gb300_fp8mx_hsdp_config --mode pretrain --max_steps 50 --seq_length 4096 logger.save_config_filepath=work/model-verification/deepseek-v3/gb300-hsdp-performance/ConfigContainer.yaml"
708+
],
709+
"dimensions": {},
710+
"enabled_features": {},
711+
"entry_id": "deepseek-v3-pretrain-performance-hsdp-gb300",
712+
"expected_result": "On exactly 256 GB300 GPUs, the 50-step mock-data MXFP8 Megatron Hybrid FSDP recipe completed at TP1/PP1/VP1/CP1/EP64/ETP1 and GBS/MBS 1024/1. Dense parameters use ZeRO-2 optim_grads sharding while expert parameters use optim_grads_params across four distributed optimizer instances, with full-iteration CUDA graphs and MoE paged stashing enabled. All 50 keyed rows had finite loss and throughput with zero skipped or NaN iterations. Steps 41-50 averaged 3,197.040 ms and 1,332.420 model TFLOP/s/GPU. Do not compare this item against pretrain_performance.GB300: that recipe runs a different convergence contract at GBS 4096 with PP2/VP8/EP32, so step time and per-GPU throughput are not commensurable. Mock data, forced expert balancing, and reduced-precision optimizer moments make this benchmark-only evidence, not convergence evidence.\n",
713+
"hardware": "GB300",
714+
"last_verified": "2026-10-09",
715+
"metrics": {
716+
"final_loss": 5.146079,
717+
"initial_loss": 11.89824,
718+
"last_10_steps_model_tflops_per_gpu_avg": 1332.42,
719+
"last_10_steps_step_time_ms_avg": 3197.04,
720+
"last_10_steps_tokens_per_second_per_gpu_avg": 5124.74
721+
},
722+
"precision": "fp8_mx",
723+
"source_pointer": "items.pretrain_performance_hsdp.GB300",
724+
"status": "verified",
725+
"variant": null,
726+
"workflow": "pretrain_performance_hsdp"
694727
}
695728
],
696729
"hf_id": "deepseek-ai/DeepSeek-V3",
697730
"hf_revision": "e815299b0bcbac849fa540c768ef21845365c9eb",
698731
"min_transformers_version": "5.8.0",
699732
"slug": "deepseek-v3",
700733
"source_card": "examples/model_verification_cards/deepseek-v3/card.yaml",
701-
"summary": "Distributed H100 GPU import, BF16 export, and deterministic inference are verified against the pinned blockwise-FP8 checkpoint. The canonical pretrain_performance.H100 1024-GPU BF16, pretrain_performance.GB200 256-GPU MXFP8, and pretrain_performance.GB300 256-GPU MXFP8 recipes are also verified. A distributed CPU export of the same pinned checkpoint is also verified. Timing and throughput metrics from future functional training items remain sanity checks rather than optimized performance results. CPU import, forward correlation, functional training, fine-tuning, and checkpoint-resume verification remain deferred.\n",
734+
"summary": "Distributed H100 GPU import, BF16 export, and deterministic inference are verified against the pinned blockwise-FP8 checkpoint. The canonical pretrain_performance.H100 1024-GPU BF16, pretrain_performance.GB200 256-GPU MXFP8, and pretrain_performance.GB300 256-GPU MXFP8 recipes are also verified, as is the pretrain_performance_hsdp.GB300 256-GPU MXFP8 Hybrid FSDP recipe. A distributed CPU export of the same pinned checkpoint is also verified. Timing and throughput metrics from future functional training items remain sanity checks rather than optimized performance results. CPU import, forward correlation, functional training, fine-tuning, and checkpoint-resume verification remain deferred.\n",
702735
"title": "deepseek_v3"
703736
},
704737
{

‎docs/fern/versions/nightly/pages/models/README.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
Choose a model to open its interactive import/export and training configurations. Every option comes directly from an authoritative YAML verification card; independent fields are never combined into synthetic commands.
66

7-
Current inventory: **28 model cards** and **400 concrete configurations**.
7+
Current inventory: **28 model cards** and **401 concrete configurations**.
88

99
Each model page lets you select import/export, pretraining, benchmarking, SFT, LoRA, or long-context SFT and immediately see the exact command and expected result for the recorded precision and GPU.
1010

‎docs/fern/versions/nightly/pages/models/deepseek/deepseek-v3.mdx‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -121,6 +121,13 @@ Choose a workflow, precision, and exact recorded combination. The command and ex
121121
</span>
122122
<span class="verification-combination-meta">FP8 MX</span>
123123
</button>
124+
<button type="button" class="verification-combination" data-capability="benchmark" data-precision="fp8_mx" data-hardware="GB300" data-status="verified" data-entry="deepseek-v3-pretrain-performance-hsdp-gb300" aria-controls="deepseek-v3-pretrain-performance-hsdp-gb300" aria-pressed="false">
125+
<span class="verification-combination-heading">
126+
<strong>Benchmark · HSDP · GB300</strong>
127+
<span class="verification-status verification-status--verified" title="Verified">✓ Verified</span>
128+
</span>
129+
<span class="verification-combination-meta">FP8 MX</span>
130+
</button>
124131
</div>
125132
<div class="verification-model-details">
126133
<article id="deepseek-v3-hf-to-megatron-cpu" class="verification-model-detail" data-entry-detail="deepseek-v3-hf-to-megatron-cpu" tabindex="-1">
@@ -543,6 +550,56 @@ Choose a workflow, precision, and exact recorded combination. The command and ex
543550
<p>On exactly 256 GB300 GPUs, the canonical 50-step mock-data MXFP8 recipe completed at TP1/PP2/VP8/CP1/EP32/ETP1 and GBS/MBS 4096/1. All 50 keyed rows had finite loss and throughput with zero skipped or NaN iterations, and the resolved configuration was saved. Steps 41-50 averaged 10,667.300 ms and 1,597.310 model TFLOP/s/GPU, passing gates of at most 11,000 ms and at least 1,550 TFLOP/s/GPU. Mock data, forced expert balancing, and reduced-precision optimizer moments make this benchmark-only evidence, not convergence evidence.</p>
544551
</section>
545552
</article>
553+
<article id="deepseek-v3-pretrain-performance-hsdp-gb300" class="verification-model-detail" data-entry-detail="deepseek-v3-pretrain-performance-hsdp-gb300" tabindex="-1">
554+
<header class="verification-model-detail-heading">
555+
<h4>Benchmark · HSDP · GB300</h4>
556+
<span class="verification-status verification-status--verified" title="Verified">✓ Verified</span>
557+
</header>
558+
<dl class="verification-model-detail-meta">
559+
<div><dt>Hardware</dt><dd>GB300</dd></div>
560+
<div><dt>Precision</dt><dd>FP8 MX</dd></div>
561+
<div><dt>Last verified</dt><dd>2026-10-09</dd></div>
562+
</dl>
563+
<section class="verification-recorded-metrics">
564+
<h5>Recorded metrics</h5>
565+
<dl class="verification-metric-list">
566+
<div>
567+
<dt>Initial loss</dt>
568+
<dd>11.89824</dd>
569+
</div>
570+
<div>
571+
<dt>Final loss</dt>
572+
<dd>5.146079</dd>
573+
</div>
574+
<div>
575+
<dt>Step time · last 10 avg</dt>
576+
<dd>3,197.040 ms</dd>
577+
</div>
578+
<div>
579+
<dt>Model throughput · last 10 avg</dt>
580+
<dd>1,332.420 TFLOP/s/GPU</dd>
581+
</div>
582+
<div>
583+
<dt>Token throughput · last 10 avg</dt>
584+
<dd>5,124.740 tokens/s/GPU</dd>
585+
</div>
586+
</dl>
587+
</section>
588+
<section class="verification-command-section">
589+
<h5>Exact command</h5>
590+
<div class="verification-command">
591+
<div class="verification-command-heading">
592+
<span>Command</span>
593+
<button type="button" class="verification-copy-command">Copy</button>
594+
</div>
595+
<pre><code class="language-bash">./scripts/training/train.sh --wait --nodes 64 --gpus-per-node 4 --recipe deepseek_v3_pretrain_256gpu_gb300_fp8mx_hsdp_config --mode pretrain --max_steps 50 --seq_length 4096 logger.save_config_filepath=work/model-verification/deepseek-v3/gb300-hsdp-performance/ConfigContainer.yaml</code></pre>
596+
</div>
597+
</section>
598+
<section class="verification-expected-result">
599+
<h5>Expected result</h5>
600+
<p>On exactly 256 GB300 GPUs, the 50-step mock-data MXFP8 Megatron Hybrid FSDP recipe completed at TP1/PP1/VP1/CP1/EP64/ETP1 and GBS/MBS 1024/1. Dense parameters use ZeRO-2 optim_grads sharding while expert parameters use optim_grads_params across four distributed optimizer instances, with full-iteration CUDA graphs and MoE paged stashing enabled. All 50 keyed rows had finite loss and throughput with zero skipped or NaN iterations. Steps 41-50 averaged 3,197.040 ms and 1,332.420 model TFLOP/s/GPU. Do not compare this item against pretrain_performance.GB300: that recipe runs a different convergence contract at GBS 4096 with PP2/VP8/EP32, so step time and per-GPU throughput are not commensurable. Mock data, forced expert balancing, and reduced-precision optimizer moments make this benchmark-only evidence, not convergence evidence.</p>
601+
</section>
602+
</article>
546603
</div>
547604
</div>
548605

‎docs/models/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
Choose a model to open its interactive import/export and training configurations. Every option comes directly from an authoritative YAML verification card; independent fields are never combined into synthetic commands.
66

7-
Current inventory: **28 model cards** and **400 concrete configurations**.
7+
Current inventory: **28 model cards** and **401 concrete configurations**.
88

99
Each model page lets you select import/export, pretraining, benchmarking, SFT, LoRA, or long-context SFT and immediately see the exact command and expected result for the recorded precision and GPU.
1010

‎docs/models/deepseek/deepseek-v3.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -121,6 +121,13 @@ Choose a workflow, precision, and exact recorded combination. The command and ex
121121
</span>
122122
<span class="verification-combination-meta">FP8 MX</span>
123123
</button>
124+
<button type="button" class="verification-combination" data-capability="benchmark" data-precision="fp8_mx" data-hardware="GB300" data-status="verified" data-entry="deepseek-v3-pretrain-performance-hsdp-gb300" aria-controls="deepseek-v3-pretrain-performance-hsdp-gb300" aria-pressed="false">
125+
<span class="verification-combination-heading">
126+
<strong>Benchmark · HSDP · GB300</strong>
127+
<span class="verification-status verification-status--verified" title="Verified">✓ Verified</span>
128+
</span>
129+
<span class="verification-combination-meta">FP8 MX</span>
130+
</button>
124131
</div>
125132
<div class="verification-model-details">
126133
<article id="deepseek-v3-hf-to-megatron-cpu" class="verification-model-detail" data-entry-detail="deepseek-v3-hf-to-megatron-cpu" tabindex="-1">
@@ -551,6 +558,57 @@ Choose a workflow, precision, and exact recorded combination. The command and ex
551558
<section class="verification-expected-result">
552559
<h5>Expected result</h5>
553560
<p>On exactly 256 GB300 GPUs, the canonical 50-step mock-data MXFP8 recipe completed at TP1/PP2/VP8/CP1/EP32/ETP1 and GBS/MBS 4096/1. All 50 keyed rows had finite loss and throughput with zero skipped or NaN iterations, and the resolved configuration was saved. Steps 41-50 averaged 10,667.300 ms and 1,597.310 model TFLOP/s/GPU, passing gates of at most 11,000 ms and at least 1,550 TFLOP/s/GPU. Mock data, forced expert balancing, and reduced-precision optimizer moments make this benchmark-only evidence, not convergence evidence.
561+
</p>
562+
</section>
563+
</article>
564+
<article id="deepseek-v3-pretrain-performance-hsdp-gb300" class="verification-model-detail" data-entry-detail="deepseek-v3-pretrain-performance-hsdp-gb300" tabindex="-1">
565+
<header class="verification-model-detail-heading">
566+
<h4>Benchmark · HSDP · GB300</h4>
567+
<span class="verification-status verification-status--verified" title="Verified">✓ Verified</span>
568+
</header>
569+
<dl class="verification-model-detail-meta">
570+
<div><dt>Hardware</dt><dd>GB300</dd></div>
571+
<div><dt>Precision</dt><dd>FP8 MX</dd></div>
572+
<div><dt>Last verified</dt><dd>2026-10-09</dd></div>
573+
</dl>
574+
<section class="verification-recorded-metrics">
575+
<h5>Recorded metrics</h5>
576+
<dl class="verification-metric-list">
577+
<div>
578+
<dt>Initial loss</dt>
579+
<dd>11.89824</dd>
580+
</div>
581+
<div>
582+
<dt>Final loss</dt>
583+
<dd>5.146079</dd>
584+
</div>
585+
<div>
586+
<dt>Step time · last 10 avg</dt>
587+
<dd>3,197.040 ms</dd>
588+
</div>
589+
<div>
590+
<dt>Model throughput · last 10 avg</dt>
591+
<dd>1,332.420 TFLOP/s/GPU</dd>
592+
</div>
593+
<div>
594+
<dt>Token throughput · last 10 avg</dt>
595+
<dd>5,124.740 tokens/s/GPU</dd>
596+
</div>
597+
</dl>
598+
</section>
599+
<section class="verification-command-section">
600+
<h5>Exact command</h5>
601+
<div class="verification-command">
602+
<div class="verification-command-heading">
603+
<span>Command</span>
604+
<button type="button" class="verification-copy-command">Copy</button>
605+
</div>
606+
<pre><code class="language-bash">./scripts/training/train.sh --wait --nodes 64 --gpus-per-node 4 --recipe deepseek_v3_pretrain_256gpu_gb300_fp8mx_hsdp_config --mode pretrain --max_steps 50 --seq_length 4096 logger.save_config_filepath=work/model-verification/deepseek-v3/gb300-hsdp-performance/ConfigContainer.yaml</code></pre>
607+
</div>
608+
</section>
609+
<section class="verification-expected-result">
610+
<h5>Expected result</h5>
611+
<p>On exactly 256 GB300 GPUs, the 50-step mock-data MXFP8 Megatron Hybrid FSDP recipe completed at TP1/PP1/VP1/CP1/EP64/ETP1 and GBS/MBS 1024/1. Dense parameters use ZeRO-2 optim_grads sharding while expert parameters use optim_grads_params across four distributed optimizer instances, with full-iteration CUDA graphs and MoE paged stashing enabled. All 50 keyed rows had finite loss and throughput with zero skipped or NaN iterations. Steps 41-50 averaged 3,197.040 ms and 1,332.420 model TFLOP/s/GPU. Do not compare this item against pretrain_performance.GB300: that recipe runs a different convergence contract at GBS 4096 with PP2/VP8/EP32, so step time and per-GPU throughput are not commensurable. Mock data, forced expert balancing, and reduced-precision optimizer moments make this benchmark-only evidence, not convergence evidence.
554612
</p>
555613
</section>
556614
</article>

‎examples/model_verification_cards/deepseek-v3/card.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -359,7 +359,7 @@ items:
359359
final_loss: 5.146079
360360
last_10_steps_step_time_ms_avg: 3197.040
361361
last_10_steps_model_tflops_per_gpu_avg: 1332.420
362-
last_10_steps_tokens_per_second_per_gpu_avg: 5124.777
362+
last_10_steps_tokens_per_second_per_gpu_avg: 5124.740
363363
expected_result: >
364364
On exactly 256 GB300 GPUs, the 50-step mock-data MXFP8 Megatron Hybrid
365365
FSDP recipe completed at TP1/PP1/VP1/CP1/EP64/ETP1 and GBS/MBS 1024/1.

‎scripts/docs/generate_model_verification_catalog.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@
5959
"Pretrain",
6060
("pretrain", "pretrain_fsdp", "pretrain_weak_scaling"),
6161
),
62-
("benchmark", "Benchmark", ("pretrain_performance",)),
62+
("benchmark", "Benchmark", ("pretrain_performance", "pretrain_performance_hsdp")),
6363
("sft", "SFT", ("sft",)),
6464
("lora", "LoRA", ("peft",)),
6565
("long-context", "Long Context", ("sft_long_context",)),
@@ -588,6 +588,7 @@ def _entry_option_label(entry: dict[str, object]) -> str:
588588
"pretrain": "Pretrain",
589589
"pretrain_fsdp": "Pretrain · FSDP",
590590
"pretrain_performance": "Benchmark",
591+
"pretrain_performance_hsdp": "Benchmark · HSDP",
591592
"pretrain_weak_scaling": "Pretrain · Weak scaling",
592593
"sft": "SFT",
593594
"peft": "LoRA",

‎src/megatron/bridge/perf_recipes/deepseek/gb300/deepseek_v3.py‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -420,8 +420,6 @@ def deepseek_v3_pretrain_256gpu_gb300_fp8mx_hsdp_config() -> ConfigContainer:
420420
"NUM_OF_TOKENS_PER_CHUNK_COMBINE_API": 128,
421421
"NVLINK_DOMAIN_SIZE": 72,
422422
"USE_MNNVL": 1,
423-
# NCCL EP dispatcher mode and one GPU per rank.
424-
"NCCL_EP_HT_EM_PULL_PUSH": 1,
425423
# Transformer Engine overlap settings for this model.
426424
"NVTE_BWD_LAYERNORM_SM_MARGIN": 20,
427425
"NVTE_CPU_OFFLOAD_V1": 1,

‎tests/unit_tests/doc_consistency/test_model_verification_catalog.py‎

Lines changed: 26 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,9 @@
2727
GENERATOR_PATH = REPO_ROOT / "scripts/docs/generate_model_verification_catalog.py"
2828
RECIPE_METADATA_PATH = REPO_ROOT / "scripts/training/recipe_metadata.py"
2929
# Items whose commands intentionally launch benchmark recipes.
30-
BENCHMARK_ITEMS = frozenset({"pretrain_performance", "pretrain_fsdp", "pretrain_weak_scaling"})
30+
BENCHMARK_ITEMS = frozenset(
31+
{"pretrain_performance", "pretrain_performance_hsdp", "pretrain_fsdp", "pretrain_weak_scaling"}
32+
)
3133

3234

3335
def _load_generator() -> ModuleType:
@@ -199,7 +201,7 @@ def test_sphinx_model_page_renders_focused_combinations(generator: ModuleType, c
199201
"megatron_to_hf_gpu",
200202
},
201203
"pretrain": {"pretrain", "pretrain_fsdp", "pretrain_weak_scaling"},
202-
"benchmark": {"pretrain_performance"},
204+
"benchmark": {"pretrain_performance", "pretrain_performance_hsdp"},
203205
"sft": {"sft"},
204206
"lora": {"peft"},
205207
"long-context": {"sft_long_context"},
@@ -240,6 +242,28 @@ def test_sphinx_model_page_renders_focused_combinations(generator: ModuleType, c
240242
assert html.escape(entry["expected_result"]) in page
241243

242244

245+
@pytest.mark.parametrize("fern", [False, True])
246+
def test_hsdp_performance_renders_as_a_separate_benchmark(
247+
generator: ModuleType, catalog: dict[str, object], fern: bool
248+
) -> None:
249+
model = _models(catalog)["deepseek-v3"]
250+
page = generator.render_model_section([model], fern=fern)
251+
benchmark_entries = [
252+
entry
253+
for entry in model["entries"]
254+
if entry["workflow"] in {"pretrain_performance", "pretrain_performance_hsdp"}
255+
]
256+
257+
assert {entry["workflow"] for entry in benchmark_entries} == {"pretrain_performance", "pretrain_performance_hsdp"}
258+
assert "Benchmark · HSDP · GB300" in page
259+
for entry in benchmark_entries:
260+
assert page.count(f'id="{entry["entry_id"]}"') == 1
261+
button = next(line for line in page.splitlines() if f'data-entry="{entry["entry_id"]}"' in line)
262+
assert 'data-capability="benchmark"' in button
263+
for command in entry["commands"]:
264+
assert html.escape(command) in page
265+
266+
243267
def test_full_verification_records_are_removed_from_every_model_page(
244268
generator: ModuleType, catalog: dict[str, object]
245269
) -> None:

0 commit comments

Comments
 (0)