[EPLB][Doc] Update EPLB document (vllm-project#10832)

### What this PR does / why we need it?
1. Update the EPLB documentation vllm-project#10718 
2. Updating the default values of EPLB parameters

### Does this PR introduce _any_ user-facing change?

### How was this patch tested?


- vLLM version: v0.22.1
- vLLM main:
vllm-project/vllm@967c5c3

Signed-off-by: shenchuxiaofugui <1311027364@qq.com>

Author: shenchuxiaofugui

docs/source/developer_guide/Design_Documents/eplb_swift_balancer.md

@@ -10,7 +10,7 @@ To facilitate reproduction and deployment, vLLM Ascend supports the deployed EP
 
 ## How to Use EPLB?
 
-Please refer to the EPLB section of the user guide for detailed information: [How to Use EPLB](../../user_guide/feature_guide/eplb_swift_balancer.md)
+Please refer to the EPLB section of the user guide for detailed information: [How to Use EPLB](../../user_guide/feature_guide/expert_parallelism_load_balancer.md)
 
 ## How It Works?
 

…ide/feature_guide/eplb_swift_balancer.md …uide/expert_parallelism_load_balancer.mddocs/source/user_guide/feature_guide/eplb_swift_balancer.md renamed to docs/source/user_guide/feature_guide/expert_parallelism_load_balancer.md docs/source/user_guide/feature_guide/eplb_swift_balancer.md renamed to docs/source/user_guide/feature_guide/expert_parallelism_load_balancer.md

@@ -1,29 +1,27 @@
-# Expert Load Balance (EPLB)
+# Expert Parallelism Load Balancer (EPLB)
 
 ## Overview
 
-Expert balancing for MoE (Mixture of Experts) models in LLM (Large Language) serving is essential for optimal performance. Dynamically changing experts during inference can negatively impact TTFT (Time To First Token) and TPOT (Time Per Output Token) due to stop-the-world operations. SwiftBalancer enables asynchronous expert load balancing with zero-overhead expert movement, ensuring seamless service continuity.
+Expert balancing for MoE (Mixture of Experts) models in LLM (Large Language) serving is essential for optimal performance. Dynamically changing experts during inference can negatively impact TTFT (Time To First Token) and TPOT (Time Per Output Token) due to stop-the-world operations. Our solution aims to minimize the negative impacts caused by the operation.
 
 ## EPLB Effects
 
 - Reduced Latency: Dynamically balances expert loads to minimize TTFT and TPOT by distributing workloads evenly across experts.
-- Enhanced Throughput: Optimizes NPU utilization, increasing token generation speed under high-concurrency scenarios.
-- Zero-Overhead Movement: Expert redistribution occurs asynchronously without interrupting ongoing inference requests.
 - Adaptive Scaling: Automatically adjusts to workload fluctuations while maintaining stable performance.
-- Fault Tolerance: Redundant expert placement ensures system resilience during hardware failures.
 
 ## Support Scenarios
 
 ### Models
 
-DeepSeekV3/V3.1/R1, Qwen3-MoE
+All MOE models supported by vLLM-Ascend.
+But we have only verified the performance on deepseek-v3.1/r1 models.
 
 ### MOE QuantType
 
 | QuantType                       | Supported Hardware          |
 | ------------------------------- | --------------------------- |
-| W8A8 / W8A8-Dynamic             | A2, A3, Ascend 950 Products |
-| W4A8 (with fused MC2 enabled)   | A2, A3, Ascend 950 Products |
+| W8A8 / W8A8-Dynamic             | A2, A3 |
+| W4A8 (with fused MC2 enabled)   | A2, A3 |
 | MXFP4                           | Ascend 950 Products         |
 | MXFP8                           | Ascend 950 Products         |
 
@@ -42,9 +40,27 @@ EPLB has three usage modes:
 
 ### Dynamic EPLB
 
-We need to add environment variable `export DYNAMIC_EPLB="true"` to enable vLLM EPLB. Enable dynamic balancing with auto-tuned parameters. Adjust expert_heat_collection_interval and algorithm_execution_interval based on workload patterns. In the current version, we recommend using the following: policy of swift balancer(2).
+We need to add environment variable `export DYNAMIC_EPLB="true"` to enable vLLM-Ascend EPLB. Enable dynamic balancing with auto-tuned parameters. Adjust expert_heat_collection_interval and algorithm_execution_interval based on workload patterns. In the current version, we recommend using the following: policy of swift balancer(2).
+
+| Parameter | Description | Default |
+| --- | --- | --- |
+| dynamic_eplb | Enable dynamic EPLB. | False |
+| expert_heat_collection_interval | Interval for collecting expert heat. | 600 |
+| algorithm_execution_interval | Interval for executing the balancing algorithm. | 50 |
+| eplb_policy_type | EPLB policy type. | 2 |
+| num_redundant_experts | Number of redundant experts. | 0 |
+
+```shell
+graph TB
+   A[start] --> B(collect_heat)
+   B --> C(execute_algorithm)
+   C --> D(update_layer one by one)
+   D --> B
+   D --> F[termination upon service termination]
+```
 
 ```shell
+# D node or colocation
 vllm serve Qwen/Qwen3-235B-A22 \
   --tensor-parallel-size 16 \
   --enable-expert-parallel \
@@ -55,6 +71,18 @@ vllm serve Qwen/Qwen3-235B-A22 \
     "eplb_policy_type": 2,
     "num_redundant_experts": 16
     }}'
+
+# P node
+vllm serve Qwen/Qwen3-235B-A22 \
+  --tensor-parallel-size 16 \
+  --enable-expert-parallel \
+  --additional-config '{ "eplb_config": {
+    "dynamic_eplb": true,
+    "expert_heat_collection_interval": 50,
+    "algorithm_execution_interval": 5,
+    "eplb_policy_type": 2,
+    "num_redundant_experts": {ep_size},
+    }}'
 ```
 
 #### EPLB Policy Types
@@ -102,28 +130,15 @@ vllm serve Qwen/Qwen3-235B-A22 \
 ## Critical Considerations
 
 1. Parameter Tuning:
-   - expert_heat_collection_interval: Higher values (e.g., 400+) for stable workloads; lower values (e.g., 100-200) for fluctuating traffic.
-   - algorithm_execution_interval: Should be ≥ 30 to avoid premature balancing during startup.
-   - num_redundant_experts: Must match tensor-parallel size (e.g., 16 for 16 NPUs) to ensure sufficient redundancy.
+   - expert_heat_collection_interval: Higher values (e.g., 600+) for stable workloads; lower values (e.g., 50-100) for fluctuating traffic.
+   - algorithm_execution_interval: Should be ≥ 50 to avoid premature balancing during startup.
+   - num_redundant_experts: Must match (num_experts + num_redundant_experts) is divisible by expert-parallel size.
 
 2. Hardware Requirements:
    - Ensure that all NPUs have identical memory capacity and compute capabilities.
    - Network bandwidth must support expert redistribution traffic (≥ 10 Gbps recommended).
 
-3. Model Compatibility:
-   - Only MoE models with explicit expert parallelism support (e.g., Qwen3 MoE models) are compatible.
-   - Verify model architecture supports dynamic expert routing through `--enable-expert-parallel`.
-
-4. Monitoring & Validation:
-   - Track metrics: expert_load_balance_ratio, ttft_p99, tpot_avg, and npu_utilization.
+3. Monitoring & Validation:
+   - Track metrics: Search for [Expert Hotness] in log, we will calculate the peak-to-average ratio of the load for each layer at different ranks, and then find their mean and maximum values. Current means actual peak-to-average ratio, update means estimated peak-to-average ratio after algorithm adjustment.
    - Use vLLM monitor to detect imbalances during runtime.
    - Always verify expert map JSON structure before loading (validate with jq or similar tools).
-
-5. Startup Behavior:
-   - Initial requests may experience higher latency during the first balancing cycle (typically 1-2 minutes).
-   - Avoid sudden traffic spikes during the warm-up phase.
-
-6. Common Pitfalls:
-   - Incorrect tensor-parallel-size vs. actual NPU count → causes resource underutilization.
-   - Using expert_map_path without generating the map first → runtime errors.
-   - Setting num_redundant_experts > available NPUs → system failure.

docs/source/user_guide/feature_guide/index.md

@@ -12,7 +12,7 @@ quantization
 sleep_mode
 structured_output
 lora
-eplb_swift_balancer
+expert_parallelism_load_balancer
 netloader
 rfork
 dynamic_batch

vllm_ascend/ascend_config.py

@@ -723,11 +723,11 @@ class EplbConfig:
     _defaults = {
         "dynamic_eplb": False,
         "expert_map_path": None,
-        "expert_heat_collection_interval": 400,
-        "algorithm_execution_interval": 30,
+        "expert_heat_collection_interval": 600,
+        "algorithm_execution_interval": 50,
         "expert_map_record_path": None,
         "num_redundant_experts": 0,
-        "eplb_policy_type": 1,
+        "eplb_policy_type": 2,
         "eplb_heat_collection_stage": "all",
     }