ref(upstream): FULL TREE — Deep-Spark xllm (1470) + ds_vllm csrc/models (703)

Replaces cherry-picked upstream_ref with complete source trees.

xllm/ — Iluvatar official C++ inference engine (15MB, 1470 files)
  Complete: kernels → layers → models → runtime → scheduler → api
  Excluded: .git, binary images, third_party submodule checkouts

ds_vllm/ — Iluvatar official vllm fork (8MB, 703 files)
  Included: csrc/ (ALL CUDA kernels), fused_moe/, qwen3_5 model, _custom_ops
  Excluded: tests, benchmarks, docs, examples (not needed for reference)

Critical call chains now fully traceable:
  MoE: moe_topk_softmax_kernels.cuh → ixformer.h → fused_moe.cpp → layer
  GDN: qwen3_gated_delta_net_base.cpp → qwen3_5_gated_delta_net.cpp
  Attention: ixformer.h → xllm_paged_attention → attention.cpp

upstream_ref/xllm/docs/zh/features/eplb.md

@@ -0,0 +1,35 @@
+# MoE负载均衡（EPLB）
+
+## 背景介绍
+
+MoE模型依赖动态路由分配tokens给专家，但实际部署中因数据分布不均，导致专家负载失衡（部分过载、部分闲置）。专家冗余调整（如新增/删除副本）需要消耗额外显存，并可能因权重迁移影响推理延迟，如何高效、平滑地完成是一大挑战。为此，采用专家冗余策略（复制热点专家）结合分层和全局动态负载均衡实现了动态的MOE负载均衡。
+
+## 功能介绍
+xLLM MoE负载均衡（EPLB）功能主要通过以下三个模块实现：
+- eplb manager: 负责专家负载并收集并管理专家分布更新更新，采用逐层更新机制，根据专家负载变化情况判断是否更新该层。
+- eplb excutor: 实际专家分布更新执行器。
+- eplb policy: 新专家负载表生成策略。
+整体架构图如下：
+![xLLM eplb](../../assets/eplb_architecture.png)
+
+## 使用方式
+只需在启动 xLLM 时加上下面的 gflag 参数即可：
+替换为实际的Device个数 ep_size要与device个数保持一致
+
+- xLLM中提供了gflags参数`enable_eplb`，默认false，如需开启动态专家负载均衡，在xLLM的服务启动脚本中设置为true即可。
+- `expert_parallel_degree`与`ep_size`为moe相关参数，`expert_parallel_degree`需要设置为`2`，`ep_size`要与实际NPU/GPU卡个数保持一致。参考 [moe_params](./moe_params.md)
+- `eplb_update_interval`为专家分布更新时间间隔，单位为妙，默认值为1000.
+- 专家分布更新采用根据专家负载的逐层更新机制，当某一层专家的前后两次的负载相似度小于`eplb_update_interval`时选择更新该层，默认值为1，取之范围为(0,1)。
+
+```bash
+  --enable_eplb=true 
+  --expert_parallel_degree=2 
+  --ep_size=16  
+  --eplb_update_interval=2000
+  --eplb_update_threshold=0.9
+```
+
+## 未来工作
+  * 采用更加细粒度的专家更新机制。
+
+  * 与调度层结合，通过请求batch的重组实现更好的负载均衡。