Skip to content

mixtral recipe#1674

Merged
pstjohn merged 9 commits into
NVIDIA-BioNeMo:mainfrom
pstjohn:pstjohn/moe-recipe
Jul 9, 2026
Merged

mixtral recipe#1674
pstjohn merged 9 commits into
NVIDIA-BioNeMo:mainfrom
pstjohn:pstjohn/moe-recipe

Conversation

@pstjohn

@pstjohn pstjohn commented Jul 2, 2026

Copy link
Copy Markdown
Collaborator

Adds recipes/mixtral_native_te, a demonstration of how to train Mixtral 8x7b with TE's GroupedLinear and GroupedMLP layers using expert parallelism, FSDP2, and MXFP8. Benchmarks training throughput on 8xB300 under different combinations of EP and DP (FSDP2). We modify the base mixtral model to ensure support for torch distributed checkpointing, using DTensor to help coordinate the discrete, rank-local expert weights needed by TransformerEngine.

@copy-pr-bot

copy-pr-bot Bot commented Jul 2, 2026

Copy link
Copy Markdown

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

@coderabbitai

coderabbitai Bot commented Jul 2, 2026

Copy link
Copy Markdown
Contributor

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 3cf5b3ed-5a34-4787-9314-97744b440894

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Comment @coderabbitai help to get the list of available commands.

@pstjohn pstjohn changed the title [wip] mixtra recipe [wip] mixtral recipe Jul 7, 2026
Comment thread recipes/mixtral_native_te/benchmarks/mixtral_8x7b_pflops.png
Comment thread recipes/eden_megatron/src/bionemo/common/checkpoint/__init__.py
Comment thread recipes/mixtral_native_te/train_fsdp2_ep.py
Comment thread recipes/mixtral_native_te/README.md Outdated
Comment thread recipes/mixtral_native_te/README.md Outdated
Comment thread recipes/mixtral_native_te/README.md Outdated
Comment thread recipes/mixtral_native_te/tests/test_checkpoint.py
@pstjohn pstjohn force-pushed the pstjohn/moe-recipe branch from 4fa03a9 to 25b3389 Compare July 7, 2026 14:17
@pstjohn pstjohn marked this pull request as ready for review July 7, 2026 20:36
Native PyTorch + Transformer Engine training recipe for Mixtral 8x7B that implements expert
parallelism (EP) "from scratch" — 2D (dp, ep) DeviceMesh, FSDP2 fully_shard over dp, hand-written
differentiable all-to-all token dispatch, explicit dense-gradient all-reduce over ep, and the fused
CuteDSL MXFP8 GroupedMLP kernel — without Megatron-LM.

Includes:
- models/mixtral: NVMixtral TE model (attention, MoE block, token dispatcher, expert weight
  handling), HF<->TE conversion (convert.py/export.py), consolidated/EP-reshardable expert
  checkpointing (grouped_dcp.py), and tests.
- recipes/mixtral_native_te: train_fsdp2_ep.py entrypoint, distributed_setup (mesh + FSDP2 wrapping
  + dense grad all-reduce), checkpoint save/load, THD dataloader, Hydra configs, requirements +
  Dockerfile (pinned CuteDSL trio), and tests (L0 sanity, EP stop/go checkpoint parity, EP=N->M
  reshard, 2D EP+FSDP2).
- Global MoE aux-loss reduction, decoupled FusedAdam fp32 master weights, and fused save_pretrained.
- Benchmarks: steady-state throughput for the four (dp, ep) layouts at MXFP8 and BF16 on 8xB300
  (DCLM-baseline, max_seq=8192, token_mb=16384) and 8xB200, with a dual-axis (PFLOP/s/GPU and
  tokens/s/GPU) chart in the recipe README and per-run result CSVs.
- perf_logger reports the true per-step peak GPU memory (max_memory_allocated) instead of the
  resting post-step allocation.
@pstjohn pstjohn force-pushed the pstjohn/moe-recipe branch from 04a225e to 4fab9a3 Compare July 7, 2026 20:39
@pstjohn pstjohn changed the title [wip] mixtral recipe mixtral recipe Jul 7, 2026
pstjohn added 3 commits July 7, 2026 15:13
…patcher

Replace the moe_permute + bespoke _pad_expert_groups (+ keep-mask) path with TE's fused
moe_permute_and_pad_with_probs: it groups tokens by expert, pads each group to the 256-row MXFP8
alignment (returning pad_offsets), and carries per-token routing probs so the destination-side
ScaledSwiGLU applies them — the layout the fused GroupedMLP kernel wants. combine() now uses
mask-type moe_unpermute with pad_offsets and merging_probs=None (weights already applied in the FFN).
The empty-rank dummy-group guard is retained (empty experts stay unpadded at 0 rows).

Numerically equivalent to the previous dispatcher (A/B: grouped_linear matches to ~5 sig figs, fused
to ~3-4 given MXFP8 fp-reordering) and throughput-neutral at 8x1B; simplifies the expert FFN and
matches TE's intended fused-MoE dispatch pattern.
Unwrap lines to the repo's 120-char ruff-format width and realign README
tables via mdformat so pre-commit passes cleanly.
@copy-pr-bot

copy-pr-bot Bot commented Jul 8, 2026

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.

@pstjohn

pstjohn commented Jul 8, 2026

Copy link
Copy Markdown
Collaborator Author

/ok to test 9b4858e

Comment thread .github/workflows/unit-tests-recipes.yml
Comment thread ci/scripts/recipes_local_test.py
@trvachov

trvachov commented Jul 8, 2026

Copy link
Copy Markdown
Collaborator

One comment from an agentic review, it seems to complain about FLOPS undercounting. I am not sure how FLOPS works with EP, and unfortunately do not have time to dig at the moment, so in the name of fast feedback, here's the agent output. I did have it check itself 😅 .

`Yes, after re-checking, the benchmark.py math is wrong for the metric it prints.

The evidence is:

  • benchmark.py creates a local batch on every rank: /tmp/bionemo-recipes-pr1674/recipes/mixtral_native_te/benchmark.py:161

  • The recipe/data path shards data over world_size, not only dp_size: /tmp/bionemo-recipes-pr1674/recipes/mixtral_native_te/dataset.py:62

  • The distributed setup comments explicitly say dense params are data-parallel over the full world and that data is sharded over dp x ep = world_size: /tmp/bionemo-recipes-pr1674/recipes/mixtral_native_te/
    distributed_setup.py:71, /tmp/bionemo-recipes-pr1674/recipes/mixtral_native_te/distributed_setup.py:117

  • The training logger’s per-GPU token metric uses the local batch token count divided by step time, which matches micro_batch * seq_len / step_time: /tmp/bionemo-recipes-pr1674/recipes/mixtral_native_te/
    perf_logger.py:171

So this line is under-counting by ep_size:

tokens_per_step = micro_batch * seq_len * args.dp_size

For benchmark FLOPs, it should be:

global_tokens_per_step = micro_batch * seq_len * dist_config.world_size
tokens_per_sec_per_gpu = micro_batch * seq_len / mean_step_time
flops_per_step = compute_flops_per_step(config, total_tokens=global_tokens_per_step, seq_len=seq_len)

One caveat: benchmark.py does not appear to write the checked-in CSVs directly, so I’d phrase the review as “benchmark.py reports wrong throughput/MFU for EP layouts,” not necessarily “the committed CSVs are
proven wrong” unless their provenance is known.`

Comment thread models/mixtral/tests/test_compat_matrix.py
Comment thread models/mixtral/tests/test_compat_matrix.py Outdated
Comment thread models/mixtral/tests/test_export.py Outdated
Comment thread models/mixtral/tests/test_te_capabilities.py Outdated
Comment thread models/mixtral/tests/test_te_capabilities.py
Comment thread recipes/mixtral_native_te/tests/conftest.py Outdated
Comment thread models/mixtral/tests/test_te_capabilities.py
Comment thread recipes/mixtral_native_te/tests/test_checkpoint.py

@jstjohn jstjohn left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

some questions about test tolerances.

pstjohn added 2 commits July 9, 2026 10:13
Add tolerance negative controls, keep compatibility test output in tmp dirs, and centralize Mixtral recipe test path setup.
@pstjohn

pstjohn commented Jul 9, 2026

Copy link
Copy Markdown
Collaborator Author

/ok to test d7122e7

@pstjohn pstjohn enabled auto-merge July 9, 2026 16:33
Propagate the recipe root through PYTHONPATH so direct torchrun worker scripts inherit the same import path as pytest collection.
@pstjohn

pstjohn commented Jul 9, 2026

Copy link
Copy Markdown
Collaborator Author

/ok to test 877bf85

@pstjohn pstjohn added this pull request to the merge queue Jul 9, 2026
Merged via the queue into NVIDIA-BioNeMo:main with commit 248e740 Jul 9, 2026
11 checks passed
@pstjohn pstjohn deleted the pstjohn/moe-recipe branch July 9, 2026 17:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants