For the complete documentation index, see llms.txt. Markdown versions of all pages are available by appending .md to any URL (e.g. /get-started.md).

Python function

rebalance_experts

rebalance_experts()

max.pipelines.lib.eplb_rebalance.rebalance_experts(weight, num_replicas, num_groups, num_nodes, num_gpus)

source

Entry point for expert-parallelism load balancing.

Identical contract to the speed-of-light torch reference: same inputs, same outputs, byte-equivalent for any well-shaped input.

Parameters:

• weight (ndarray[tuple[Any, ...], dtype[int64]] | ndarray[tuple[Any, ...], dtype[float64]]) – [layers, num_logical_experts] int64 or float load statistics for each logical expert (typically the cumulative routing histogram from max.serve.pipelines.ep_stats.EpStatsSnapshot).
• num_replicas (int) – total number of physical slots after replication. Must be a multiple of num_gpus. For v1 set num_replicas == num_logical_experts (no redundancy).
• num_groups (int) – number of expert groups (DeepSeek-V3=8, Kimi-K2.5=1).
• num_nodes (int) – number of server nodes; intra-node network is assumed faster.
• num_gpus (int) – number of GPUs; must be a multiple of num_nodes.

Returns:

[layers, num_replicas] — logical expert id at each physical slot. logical_to_physical_map: [layers, num_logical_experts, X] — physical slots holding each logical expert. expert_count: [layers, num_logical_experts] — replica count per logical expert.

Return type:

physical_to_logical_map