Skip to content

[TRTLLM-17824][fix] Decline EPLB in modeling_v2 targets that do not implement it - #22277

Closed
ruocheng-nv wants to merge 3 commits into
NVIDIA:mainfrom
ruocheng-nv:fix/mv2-eplb-guard
Closed

ruocheng-nv wants to merge 3 commits into
NVIDIA:mainfrom
ruocheng-nv:fix/mv2-eplb-guard

Conversation

@ruocheng-nv

Copy link
Copy Markdown
Collaborator

Description

A deployment that sets modeling_v2 (auto or require) together with moe_config.load_balancer builds a Modeling V2 target whenever its route claims the layout, but no target registers its MoE layers with the load balancer. The loader still creates the balancer (maybe_create_moe_load_balancer), so static EPLB runs on the target's fixed expert windows and the replicas that num_slots / initial_global_assignments ask for are dropped without an error, and online EPLB finalizes a balancer with no layer, where MoeLoadBalancer::generateUpdatePlan reads front() of an empty plan. This affects the DeepSeek-R1 and gpt-oss default targets at their EP layouts when modeling_v2 is set explicitly, and the GLM-5.2 tep4 target, which is built by default.

This PR makes EPLB support an explicit property of a target and checks it once, for every target:

  • moe_load_balancer.py: moe_load_balancer_mode(model_config, mapping) returns the EPLB mode the engine runs (static for standard EPLB with layer_updates_per_iter == 0, online, or per_layer_dynamic), or None when no balancer is created (no config, an architecture outside moe_model_arch_list, one EP rank, smart routing). maybe_create_moe_load_balancer now creates a balancer exactly when it returns a mode; its behavior is unchanged.
  • _router_index.modeling_v2_resolve: after route returns a target, a deployment that runs EPLB in a mode the target class does not list in EPLB_MODES is NoTarget. auto keeps Modeling V1, which implements EPLB, and require raises with the reason. EPLB_MODES is empty unless a target sets it, so every current target declines EPLB until it implements it. A name in EPLB_MODES that is not an EPLB mode raises ValueError, because a misspelled mode would decline every EPLB deployment without a word.
  • modeling_v2/README.md: the rule is documented under Routing and in the steps for adding a target.

Deployments without EPLB resolve as before, and so do EPLB deployments that leave modeling_v2 at its default for the DeepSeek-R1 and gpt-oss targets, which are @disable_v2_by_default.

This is the first part of TRTLLM-17824. Follow-up PRs implement static and then online EPLB in the DeepSeek-R1 target and declare them in its EPLB_MODES.

Test Coverage

  • tests/unittest/_torch/moe/test_moe_load_balancer.py (CPU; unittest/_torch/moe is in l0_cpu): test_moe_load_balancer_mode covers static, online and per-layer dynamic EPLB, no config, one EP rank, and an architecture outside moe_model_arch_list. test_maybe_create_moe_load_balancer_follows_the_mode checks, with the runtime mocked, that the loader creates a balancer exactly for those modes.
  • tests/unittest/_torch/modeling_v2/test_modeling_v2_routing.py (CPU, l0_cpu): a target without EPLB_MODES is declined for each mode (auto returns the built-in model, require raises naming the mode); a target that lists static is built for static EPLB only; deployments where the engine creates no balancer are unaffected; an unknown mode name is an error; DeepSeek-R1 and gpt-oss at dep4 and GLM-5.2 at tep4 with EPLB keep the built-in model.

Local results in the CI image (pytorch-26.09-py3-x86_64-ubuntu24.04-skip-tritondevel-202611030656-21516) with a recent CI wheel and this PR's two modules copied over it:

  • Both test files: 392 passed, 75 skipped. With the resolver's check removed, the 21 cases that expect a decline fail.
  • The other l0_cpu modeling_v2 test files show the same failures with and without this PR's modules (the wheel predates some of those tests).

PR Checklist

Please review the following before submitting your PR:

  • PR description clearly explains what and why. If using CodeRabbit's summary, please make sure it makes sense.

  • PR Follows TRT-LLM CODING GUIDELINES to the best of your knowledge.

  • Test cases are provided for new code paths (see test instructions)

  • If PR introduces API changes, an appropriate PR label is added - either api-compatible or api-breaking. For api-breaking, include BREAKING in the PR title.

  • Any new dependencies have been scanned for license and vulnerabilities

  • CODEOWNERS updated if ownership changes

  • Documentation updated as needed

  • Update tava architecture diagram if there is a significant design change in PR.

  • The reviewers assigned automatically/manually are appropriate for the PR.

  • Please check this after reviewing the above items as appropriate for this PR.

GitHub Bot Help

To see a list of available CI bot commands, please comment /bot help.

…mplement it

The loader creates the MoE load balancer around whichever class it builds,
but a modeling_v2 target takes part only by registering its MoE layers with
it. No target does, so a deployment that sets modeling_v2 together with
EPLB ran on fixed expert windows: static EPLB lost its replicas silently,
and online EPLB gave the balancer no layer to update.

- moe_load_balancer.py: moe_load_balancer_mode() reports the EPLB mode the
  engine runs (static, online or per_layer_dynamic) or None, and
  maybe_create_moe_load_balancer creates a balancer exactly when it returns
  a mode.
- modeling_v2 resolver: after route returns a target, a deployment that runs
  EPLB in a mode the target does not list in EPLB_MODES is NoTarget, so auto
  keeps Modeling V1 and require says why. An unknown name in EPLB_MODES is
  an error.
- README: document EPLB_MODES.

Signed-off-by: Ruocheng Jia <ruochengj@nvidia.com>
@ruocheng-nv

Copy link
Copy Markdown
Collaborator Author

/bot run

Signed-off-by: Ruocheng Jia <ruochengj@nvidia.com>

# Conflicts:
#	tensorrt_llm/_torch/_experimental/modeling_v2/README.md
#	tensorrt_llm/_torch/_experimental/modeling_v2/_router_index.py
#	tests/unittest/_torch/modeling_v2/test_modeling_v2_routing.py
…ith main

Signed-off-by: Ruocheng Jia <ruochengj@nvidia.com>
@ruocheng-nv

Copy link
Copy Markdown
Collaborator Author

/bot run

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #84984 [ run ] triggered by Bot. Commit: 98ee560 Link to invocation

@ruocheng-nv

Copy link
Copy Markdown
Collaborator Author

Folded into #22282, whose branch already contains this commit; reviewing the resolver check there together with the first target that implements EPLB.

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #84984 [ run ] completed with state SUCCESS. Commit: 98ee560
/LLM/main/L0_MergeRequest_PR pipeline #70335 completed with status: 'UNSTABLE'

CI Report

⚠️ Multi-GPU Label Required:
Multi-GPU tests require the ci: full pre-merge approved label on this PR. Either:

  • Wait for the PR to be fully approved — the label is added automatically once approval is complete. Having unresolved open comments is fine, or
  • If needed, ask a member of NVIDIA/trt-llm-ci-approvers to add the label manually.
    Then re-trigger CI with the same bot command (no rebase needed).

⚠️ Action Required:

  • Please check the failed tests and fix your PR
  • If you cannot view the failures, ask the CI triggerer to share details
  • Once fixed, request an NVIDIA team member to trigger CI again

Link to invocation

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.

2 participants