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/async_schedule.md

@@ -0,0 +1,33 @@
+# 异步调度
+
+## 背景
+大模型推理过程可划分为3个阶段，包括CPU执行调度准备模型输入阶段，device计算阶段，CPU处理输出阶段。
+由于解码操作的序列性，step-i+1 的输入需要依赖 step-i 的输出结果，
+上述3个阶段需要按顺序串行执行，导致在CPU执行阶段1和3的时候，device侧空闲等待出现空泡，资源利用不充分。
+
+
+
+## 功能介绍
+
+xLLM在框架层支持了异步调度功能，在device执行 step-i 计算的同时提前让CPU执行 step-i+1 的调度操作，device在完成 step-i 计算后可立即开始 step-i+1 的计算，从而消除空泡。
+具体地，CPU在发起 step-i 计算调用后，不等待device计算完成，为 step-i 的请求构造fake token，使用fake token执行 step-i+1 的调度操作，分配KV Cache等；device在启动 step-i+1 的计算时，用 step-i 计算出来的true token替换fake token，保证计算的正确性。CPU在另外的线程中同步处理 step-i 的结果返回给client。
+
+整体架构如图，实现中CPU侧执行阶段1和阶段3的操作分别采用了不同的线程池，rpc等函数调用采用C++ future和promise非阻塞调用，实现全异步runtime。![异步调度](../../assets/async_schedule_architecture.jpg)
+
+
+## 使用方式
+
+xLLM中提供了gflags参数`enable_schedule_overlap`，默认false，如需开启在xLLM的服务启动脚本中设置为true即可，示例如下：
+```shell
+--enable_schedule_overlap=true
+```
+
+
+## 性能效果
+- 异步调度开启后，两个step之间的device空闲时在200us左右，基本类似一个kernel launch的时间。
+- 在DeepSeek-R1-Distill-Qwen-1.5B模型上，限制TPOT 50ms，吞吐 **提升17%**。
+
+
+!!! warning "注意"
+    - 异步调度功能会在服务端额外计算一个step，当使用场景中输出token数量较少，或是类似embedding模型只一次性输出的场景，会影响服务端吞吐，所以强制关闭异步调度。
+    - VLM模型正在适配中，暂时会强制关闭异步调度。

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

@@ -0,0 +1,9 @@
+# 基础知识
+
+- xLLM使用一卡一进程模式，多卡之间使用rpc进行函数调用，模型计算过程中的数据通信使用device集合通信库。
+
+- HCCL/LCCL是高性能集合通信，提供单机多卡以及多机多卡间的数据并行、模型并行集合通信方案。
+
+
+
+

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

@@ -0,0 +1,17 @@
+# ChunkedPrefill调度器
+
+## 功能介绍
+xLLM支持chunked prefill调度策略。Chunked prefill是一种优化大语言模型推理的技术，将长prompt分割成多个较小的chunk进行分批处理，而不是一次性处理整个prompt。
+这种方法可以有效降低显存峰值使用量，提高Device利用率，并且能够更好地与decode阶段的请求进行调度和混合处理。
+
+## 使用方式
+上述策略已在xLLM实现，并向外暴露gflag参数，控制功能的开关。
+
+- 开启chunked prefill，并设置chunked_size，如果不手动设置chunked size，则默认等于max_tokens_per_batch。
+```bash
+--enable_chunked_prefill=true
+--max_tokens_per_chunk_for_prefill=20480 # optional
+```
+
+## 性能效果
+开启chunked_prefill之后，在Qwen3-8B模型上，限制TPOT 50ms，TTFT时延 **下降46%**。

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

@@ -0,0 +1,7 @@
+# Continuous调度器
+
+## 功能介绍
+xLLM实现了支持continuous batching的调度策略，continuous_batch是一种动态批处理策略，它不等待批次填满，而是在有请求时就开始处理，同时持续接收新请求并将其加入正在执行的批次中，从而在保持高吞吐量的同时显著降低延迟。
+
+## 使用方式
+xLLM提供了continuous batching调度策略。目前`enable_chunked_prefill`默认值为true，开箱即用时默认调度器是chunked prefill调度器。

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

@@ -0,0 +1,74 @@
+# PD分离
+## 背景
+LLM在线推理服务通常需要满足TTFT和TPOT两项性能指标，而传统的Contiguous Batching调度策略将Prefill和Decode请求混合在一起调度，导致P和D会互相抢占计算资源，影响性能指标无法最大程度的利用计算资源。为解决上述矛盾，将Prefill和Decode两阶段拆分到独立的计算资源并行执行，从而同时降低TTFT和TPOT并提升吞吐量。
+## 功能介绍
+xLLM PD分离功能主要通过以下三个模块实现：
+
+- **etcd**: 存储实例信息等元数据
+- **xLLM Service**: 调度请求和管理所有计算实例
+- **xLLM**: 请求计算实例
+
+整体架构图如下：
+![xLLM PD分离架构图](../../assets/pd_architecture.jpg)
+## 功能使用示例
+### 使用准备
+#### 安装相关依赖
+- **xLLM**: 参见[安装编译](../getting_started/quick_start.md)
+- **xLLM Service**: 参见[PD分离部署](../getting_started/disagg_pd.md)
+
+### 启动PD分离服务
+1. 启动etcd
+```
+./etcd
+```
+2. 启动xLLM Service
+```bash
+ENABLE_DECODE_RESPONSE_TO_SERVICE=true ./xllm_master_serving --etcd_addr="127.0.0.1:12389" --http_server_port 28888 --rpc_server_port 28889 --tokenizer_path=/path/to/tokenizer_config_dir/
+```
+3. 启动xLLM
+
+4. 以Qwen2-7B为例
+    - 启动Prefill实例
+        ```bash
+        /path/to/xllm --model=Qwen2-7B-Instruct \
+               --port=8010 \
+               --devices="npu:0" \
+               --master_node_addr="127.0.0.1:18888" \
+               --enable_prefix_cache=false \
+               --enable_chunked_prefill=false \
+               --enable_disagg_pd=true \
+               --instance_role=PREFILL \
+               --etcd_addr=127.0.0.1:12389 \
+               --transfer_listen_port=26000 \
+               --disagg_pd_port=7777 \
+               --node_rank=0 \
+               --nnodes=1
+        ```
+    - 启动Decode实例
+        ```bash
+        /path/to/xllm --model=Qwen2-7B-Instruct \
+               --port=8020 \
+               --devices="npu:1" \
+               --master_node_addr="127.0.0.1:18898" \
+               --enable_prefix_cache=false \
+               --enable_chunked_prefill=false \
+               --enable_disagg_pd=true \
+               --instance_role=DECODE \
+               --etcd_addr=127.0.0.1:12389 \
+               --transfer_listen_port=26100 \
+               --disagg_pd_port=7787 \
+               --node_rank=0 \
+               --nnodes=1
+        ```
+    需要注意：
+    
+    - PD分离需要读取`/etc/hccn.conf`文件，确保将物理机上的该文件映射到了容器中
+  
+    - `etcd_addr`需与`xllm_service`的`etcd_addr`相同
+
+!!! warning "注意事项"
+    PD分离目前不支持开启prefix cache及chunked prefill功能，需要通过以下参数关闭
+    ``` shell
+    --enable_prefix_cache=false
+    --enable_chunked_prefill=false
+    ```

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的重组实现更好的负载均衡。

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

@@ -0,0 +1,34 @@
+# 全局多级KV Cache
+## 背景
+大型语言模型（LLM）解码阶段因自回归生成需频繁访问历史KV缓存，导致显存带宽成为瓶颈。随着模型规模与上下文窗口扩大（如128K Token消耗超40GB显存），单卡显存压力剧增。现有方案（如vLLM）在长上下文场景下存在明显局限：预填充耗时激增、解码阶段显存带宽争抢严重，为满足SLO（TTFT<2s, TBT<100ms）常需过量预留资源，致使GPU利用率不足40%，且难以利用跨服务器资源。为此，我们提出分布式全局多级KV缓存管理系统，采用存算一体架构以突破单机资源限制。
+
+## 功能介绍
+xLLM 全局KV Cache功能主要通过以下三个模块实现：
+- etcd: 集群服务注册、负载信息同步及全局缓存状态管理
+- xLLM Service: 调度请求和管理所有计算实例
+- xLLM: 请求计算实例
+
+整体架构图如下：
+![xLLM 全局多级KV Cache](../../assets/globalkvcache_architecture.png)
+## 功能使用示例
+### 使用准备
+#### 安装相关依赖
+- **xLLM**: 参见[快速开始](../getting_started/quick_start.md)
+- **xLLM Service**: 参见[PD分离部署](../getting_started/disagg_pd.md)
+
+### 使用方式
+1. etcd启动配置：
+```bash
+./etcd  --listen-peer-urls=http://0.0.0.0:10999 --listen-client-urls=http://0.0.0.0:10998
+```
+2. xLLM Service启动配置：
+```bash
+./xllm_master_serving  --etcd_addr="127.0.0.1:10998" --http_server_port 28888 --rpc_server_port 28889 --tokenizer_path=/path/to/tokenizer_config_dir/
+```
+3. xLLM启动添加上下面的 gflag 参数即可：
+```bash
+--enable_service_routing=true
+--enable_cache_upload=true
+# PD分离暂时不支持全局KVCache管理
+--enable_disagg_pd=false
+```

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

@@ -0,0 +1,77 @@
+# Graph Mode
+
+## 概述
+
+xLLM 支持 Graph Mode，通过预捕获计算图并在后续执行中重放，减少 CPU 开销并提高推理性能。Graph Mode 在不同硬件平台上均有对应实现。
+
+## 功能介绍
+
+为了优化 Host 侧调度性能，图模式通过在 CPU 一次提交大任务后，设备内部流式执行小 kernel，显著降低启动时间和设备气泡。
+
+在 xLLM 引擎中，Graph Mode 实现了以下特性：
+
+### 动态维度参数化
+  - 将除 num_tokens 以外的关键动态维度作为整图输入参数，包括 batch_size、kv_seq_lens、q_seq_lens、block_table_size 等，从而提高灵活性。在进行图的内存分配和内核配置时，利用这些动态参数计算实际所需值。在图启动阶段，将上述实际参数传入，以确保 kernel 能够使用正确的 stride 访问数据。
+
+### Piecewise Graph
+  - 当部分算子不支持 graph 导致整图无法捕获（break graph）时，对 break 之后的各段（piece）分别捕获 graph。这样在无法整图捕获的情况下，仍能尽可能获得 graph mode 的收益，常用于 prefill、chunked_prefill 等场景。
+
+### 多 shape 复用的显存池
+  - 为了避免不同 shape 的 graph capture 分别占用独立显存，我们让不同 capture 使用不同虚拟地址空间，并共享同一组底层物理内存；同时，输入 tensor 通过持久化 buffer 与 slice 方式复用。
+ 
+## 使用方式
+
+上述功能已在 xLLM 引擎内部实现，通常通过 gflags 参数控制。
+
+最小配置只需要开启 `enable_graph`，用于打开 decode 阶段的 Graph Mode：
+
+```shell
+--enable_graph=true
+```
+
+常见的配套开关包括：
+
+- `enable_graph`：开启 decode 阶段的 Graph Mode 基础能力
+- `enable_prefill_piecewise_graph`：开启 prefill 阶段的 Piecewise Graph
+- `enable_graph_mode_decode_no_padding`：decode 阶段按实际 `num_tokens` 建图，而不是按 padding 后的 shape 建图
+- `max_tokens_for_graph_mode`：限制 Graph Mode 覆盖的最大 token 数；`0` 表示不限制
+
+如果希望同时开启 decode Graph 和 prefill Piecewise Graph，示例如下：
+
+```shell
+--enable_graph=true \
+--enable_prefill_piecewise_graph=true \
+--max_tokens_for_graph_mode=2048
+```
+
+如果需要在 decode 阶段启用无 padding 建图，可额外开启：
+
+```shell
+--enable_graph=true \
+--enable_graph_mode_decode_no_padding=true
+```
+
+更完整的参数说明可参考 [CLI 参数说明](../cli_reference.md)。
+
+## 性能效果
+
+- 开启 Graph Mode 后，在 Qwen3-0.6B 和 Qwen3-1.7B 等模型上，decode 阶段吞吐 **提升约 8%–10%**。
+
+## 模型支持
+
+下表列出目前各模型在 ACLGraph、CudaGraph、MLUGraph 上的支持情况。
+
+| 模型 | ACLGraph | CudaGraph | MLUGraph |
+|------|----------|-----------|----------|
+| Qwen3/Qwen3-MoE | ✅ | ✅ | ✅ |
+| DeepseekV3.2 | ✅ | | ✅ |
+| GLM4.5/4.6/4.7 | ✅ | | |
+| Qwen2.5-VL | | | ✅ |
+| Qwen3-VL/Qwen3-VL-MoE | ✅ | | |
+| GLM4V | ✅ | | |
+| GLM4V-MoE | ✅ | | |
+
+
+
+## 相关文档
+- 更详细的 Graph Mode 设计与实现说明（含 ACL Graph / CUDA Graph 基本原理、动态维度参数化、Piecewise Graph 与多 shape 复用内存方案）见：[Graph Mode 设计文档](../design/graph_mode_design.md)

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

@@ -0,0 +1,41 @@
+# GroupGEMM算子优化
+
+# 背景
+混合专家(Mixture of Experts, MoE)架构已成为扩展大规模语言模型的重要范式，其核心思想是将输入token动态路由至不同的专家子网络进行处理。在推理过程中，GroupGEMM算子是MoE架构的关键计算单元，负责高效执行多个专家矩阵乘法的并行计算，且在整个推理耗时中占据主导地位。
+
+## 功能介绍
+结合当前GroupGEMM的性能瓶颈为I/O受限，提出了一种优化方案，通过索引重排替代数据拷贝，取消了对token向量的多次复制，改为维护专家分配的索引表。通过该行号索引，直接将token映射到相应的专家计算单元，并将token的分配调度与矩阵乘法融合为一个单一的kernel。
+
+
+## 用户接口
+
+### 算子直调API
+```c++
+aclnnStatus aclnnIndexGroupMatmulGetWorkspaceSize(
+    const aclTensorList *x,
+    const aclTensorList *weight,
+    const aclTensorList *scale,
+    const aclTensorList *perTokenScale,
+    const aclTensor *groupList,
+    const aclTensorList *out,
+    uint64_t *workspaceSize,
+    aclOpExecutor **executor);
+
+aclnnStatus aclnnIndexGroupMatmul(
+    void *workspace,
+    uint64_t workspaceSize,
+    aclOpExecutor *executor,
+    aclrtStream stream);
+```
+
+- `x`: 输入的张量列表，包含待处理的数据。
+- `weight`: 权重张量，包含模型的参数。
+- `scale`: 缩放因子，用于调整输入张量的值。
+- `perTokenScale`:每个token的缩放因子，用于动态调整。
+- `groupList`: 专家组列表，指示哪些专家参与计算。
+- `out`: 输出张量列表，存储计算结果。
+
+## 性能效果
+![groupmatmul](../../assets/groupmatmul_performance.png)
+
+* 优化后的GroupMatmul算子在计算时间上表现出明显的优势，尤其是在k为128，m为64情况下，如图所示，优化后算子计算延时 **减少50%**。

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

@@ -0,0 +1,17 @@
+# EP并行
+## 背景介绍
+在部署DeepSeek-R1 671B参数规模模型时传统分布式部署面临、显存利用率低、通信开销大、硬件成本高昂等核心瓶颈，因此需要引入ep并行。
++ 在同等资源下，单张卡上的Expert越少，可用于KV Cache的显存越多，可Cache的token个数越多。
++ 因MLA的特性，同等资源下TP Size越小，冗余的KV Cache就越少，可Cache的token个数越多。
++ 采用大规模ep并行部署，可以将同一个expert的token计算集中到同一设备上，提高硬件利用率
+## 参数设置
++ dp_size：设置Attention部分的dp规模大小，默认值为1，可设置为2的指数倍，当dp_size不等于卡数时，dp组内为tp并行.
++ ep_size：设置MoE部分的ep规模大小，默认值为1，可设置为2的指数倍，当ep_size不等于卡数时，dp组内为tp并行.
++ expert_parallel_degree ：ep并行相关参数，不开启ep时默认设置为0，开启ep时默认为1，此时为ep level1，当ep_size等于卡数时可以设置为2开启ep level2.
+
+支持 MLA 的模型会自动开启 MLA，不再需要手动配置。
+## 方案设计
++ 当开启ep时，默认为ep level1，此时attn与moe部分计算完成后，通过All Gather全卡通讯将数据发送到下一阶段，以64卡attn部分dp32tp2 moe部分ep32tp2为例，执行流程如下：
+![Alt text](../../assets/moe_eplevel1.jpg)
++ 当ep_size设置为卡数时，可以开启ep level2，此时attn部分与moe部分之间通讯变为ALL2ALL，只向需要的卡发送数据，降低通讯量与通讯开销，以64卡部署为例，执行流程如下：
+![Alt text](../../assets/moe_eplevel2.jpg)

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

@@ -0,0 +1,149 @@
+# MTP投机推理
+
+## 背景
+MTP是一种创新的推理阶段加速技术，专注于解决大语言模型生成过程中的效率瓶颈。MTP的本质是通过预训练阶段的特殊设计，为推理阶段提供高效的草稿token预测能力，从而显著提升模型的生成速度。其核心价值在于平衡推理效率与输出质量，为大语言模型的长序列生成问题提供了一种高效的解决方案，最终实现推理性能的优化。
+
+## 功能介绍
+MTP在推理加速方面具有以下核心功能：
+
+- **高效草稿生成**：使用低成本的MTP结构快速生成草稿token，这些草稿token作为主模型验证的基础，大幅减少了传统自回归生成的计算开销。
+
+- **批量验证机制**：主模型能够同时批量验证多个MTP生成的草稿token，而不必逐个生成和验证，显著提升了推理速度。
+
+- **高采样准确率**：MTP解决了Eagle、Medusa等现有推理加速方法中的关键痛点——训练后生成的draft模块token采样率低的问题。由于MTP在预训练阶段就优化了草稿生成能力，其生成的token具有更高的准确率，减少了主模型的验证负担。
+
+- **推理延迟降低**：通过预先生成多个可能的后续token，MTP有效降低了模型生成长文本时的累积延迟，使用户体验更加流畅。
+
+- **资源消耗优化**：相比其他推理加速技术，MTP在保持加速效果的同时，对计算资源的额外需求更少，适合在资源受限环境下部署。
+
+MTP技术为大语言模型的推理阶段提供了一种全新的效率优化方案，特别适合需要快速响应的实时应用场景，代表了语言模型推理优化的重要发展方向。
+
+!!! note "模型支持"
+    目前支持以下模型的MTP结构导出：
+    - DeepSeek-V3 (输入 model_type: deepseek_v3, 导出 MTP model_type: deepseek_v3_mtp)
+    - DeepSeek-V3.2 (输入 model_type: deepseek_v3, 导出 MTP model_type: deepseek_v32_mtp)
+    - DeepSeek-R1 (输入 model_type: deepseek_v3, 导出 MTP model_type: deepseek_v3_mtp)
+    - GLM4 MoE (如 GLM-4.5-Air, 导出 MTP model_type: glm4_moe_mtp)
+    
+    注意：
+    - DeepSeek V3 和 R1 的输入 model_type 都是 "deepseek_v3"，导出的 MTP 模型 model_type 为 "deepseek_v3_mtp"
+    - DeepSeek V3.2 的输入 model_type 是 "deepseek_v3"（但可通过 index_head_dim 等字段自动识别），导出的 MTP 模型 model_type 为 "deepseek_v32_mtp"
+
+## 使用示例
+
+### 导出模型
+
+脚本会自动检测模型类型，也可以手动指定。
+
+#### DeepSeek-V3
+```bash
+python3 tools/export_mtp.py \
+    --input-dir /path/to/DeepSeek-V3 \
+    --output-dir /path/to/DeepSeek-V3-mtp
+```
+
+#### DeepSeek-V3.2
+```bash
+python3 tools/export_mtp.py \
+    --input-dir /path/to/DeepSeek-V3.2 \
+    --output-dir /path/to/DeepSeek-V3.2-mtp
+```
+
+#### DeepSeek-R1
+```bash
+python3 tools/export_mtp.py \
+    --input-dir /path/to/DeepSeek-R1 \
+    --output-dir /path/to/DeepSeek-R1-mtp
+```
+
+#### GLM4 MoE
+```bash
+python3 tools/export_mtp.py \
+    --input-dir /path/to/GLM-4.5-Air \
+    --output-dir /path/to/GLM-4.5-Air-mtp
+```
+
+#### 手动指定模型类型
+如果自动检测失败，可以手动指定模型类型：
+```bash
+python3 tools/export_mtp.py \
+    --input-dir /path/to/model \
+    --output-dir /path/to/model-mtp \
+    --model-type deepseek_v3  # 可选: deepseek_v3 (用于V3/R1), deepseek_v32 (用于V3.2), glm4_moe
+```
+
+输入模型参考:
+- [DeepSeek-V3](https://huggingface.co/deepseek-ai/DeepSeek-V3)
+- [DeepSeek-V3.2](https://huggingface.co/deepseek-ai/DeepSeek-V3.2)
+- [DeepSeek-R1](https://huggingface.co/deepseek-ai/DeepSeek-R1)
+- [GLM-4.5-Air](https://huggingface.co/zai-org/GLM-4.5-Air)
+
+### 启动脚本
+
+使用MTP进行推理时，需要同时指定主模型和草稿模型（MTP模型）。
+
+#### DeepSeek-V3/V3.2/R1 启动示例
+```bash
+MODEL_PATH="/models/DeepSeek-V3"
+DRAFT_MODEL_PATH="/models/DeepSeek-V3-mtp"
+MASTER_NODE_ADDR="127.0.0.1:42123"
+START_PORT=13222
+START_DEVICE=0
+LOG_DIR="log"
+NNODES=16
+
+for (( i=0; i<$NNODES; i++ ))
+do
+  PORT=$((START_PORT + i))
+  DEVICE=$((START_DEVICE + i))
+  LOG_FILE="$LOG_DIR/node_$i.log"
+  nohup ./xllm \
+    --model $MODEL_PATH \
+    --devices="npu:$DEVICE" \
+    --port $PORT \
+    --master_node_addr=$MASTER_NODE_ADDR \
+    --nnodes=$NNODES \
+    --draft_model $DRAFT_MODEL_PATH \
+    --draft_devices="npu:$DEVICE" \
+    --num_speculative_tokens 1 \
+    --max_memory_utilization=0.90 \
+    --max_tokens_per_batch=10000 \
+    --max_seqs_per_batch=256 \
+    --block_size=128 \
+    --ep_size=1 \
+    --dp_size=1 \
+    --enable_prefix_cache=false \
+    --enable_chunked_prefill=false \
+    --node_rank=$i > $LOG_FILE 2>&1 &
+  sleep 0.5
+done
+```
+
+#### GLM4 MoE 启动示例
+```bash
+MODEL_PATH="/models/GLM-4.5-Air"
+DRAFT_MODEL_PATH="/models/GLM-4.5-Air-mtp"
+# ... 其他配置相同
+```
+
+# 性能数据
+基于sharegpt数据集，输入长度2500，输出长度1500，请求总数80。
+
+| method    | Concurrency | Mean TPOT(ms) | Mean TTFT(ms) | Output Tokens/s | Total Tokens/s |
+|:---------:|:-----------:|:-------------:|:-------------:|:---------------:|:--------------:|
+| baseline  |      1      |     40.61     |    141.80     |      24.20      |     65.77      |
+| mtp       |      1      |     28.33     |    142.35     |      35.19      |     95.52      |
+| baseline  |      2      |     42.69     |    178.59     |      45.16      |    122.74      |
+| mtp       |      2      |     29.81     |    187.97     |      64.75      |    175.78      |
+| baseline  |      4      |     46.18     |    172.34     |      79.83      |    216.96      |
+| mtp       |      4      |     33.54     |    194.22     |     111.18      |    301.81      |
+| baseline  |      8      |     53.16     |    181.49     |     110.68      |    300.81      |
+| mtp       |      8      |     40.99     |    203.37     |     154.46      |    419.34      |
+| baseline  |     16      |     68.50     |    213.89     |     143.81      |    390.84      |
+| mtp       |     16      |     57.04     |    254.99     |     201.89      |    548.04      |
+| baseline  |     20      |     74.72     |    228.80     |     154.77      |    420.65      |
+| mtp       |     20      |     61.73     |    264.34     |     206.24      |    559.84      |
+| baseline  |     40      |    119.68     |    559.32     |     180.22      |    489.80      |
+| mtp       |     40      |    105.70     |    544.54     |     252.91      |    686.74      |
+| baseline  |     80      |    180.89     |   2996.21     |     192.09      |    522.06      |
+| mtp       |     80      |    152.19     |   2163.72     |     278.07      |    755.12      |

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

@@ -0,0 +1,29 @@
+# 多流并行
+
+## 背景
+大模型分布式推理场景中需要引入额外的通信操作，将不同设备上的计算结果聚合在一起。以Deepseek这类大规模的MoE模型为例，分布式规模通常较大，通信开销也会随之变大。计算和通信都采用同一个stream的话，在通信的同时，device计算资源会出现浪费，一直等待通信完成才能开始后面的计算。
+
+
+## 功能介绍
+xLLM在模型图层支持了多流并行功能，将输入的batch拆分成2个micro batches，一个流执行一个micro batch的计算操作，另一个流执行另一个micro batch的通信操作，计算和通信同时执行，从而掩盖通信开销。
+![异步调度](../../assets/multi_streams_architecture.jpg)
+
+
+## 使用方式
+
+xLLM中提供了gflags参数`enable_multi_stream_parallel`，默认false，如需开启在xLLM的服务启动脚本中设置为true即可，示例如下：
+```shell
+--enable_multi_stream_parallel=true
+```
+
+
+## 性能效果
+prefill双流并行开启后，基本可掩盖75以上的通信开销，在DeepSeek-R1模型上，只输出1个token的情况下
+
+- TTFT下降 **7%**
+- 吞吐 **提升7%**
+
+
+!!! warning "注意"
+    双流并行目前只支持prefill阶段，请求输入越长，收益越大。
+    目前仅支持DeepSeek、Qwen3 dense（非MoE）模型。

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

@@ -0,0 +1,19 @@
+# 多模态支持
+本文档主要介绍xLLM推理引擎中多模态的支持进展，包括支持模型及模态类型，以及离在线接口等。
+
+## 支持模型
+- Qwen2.5-VL: 包括7B/32B/72B。
+- Qwen3-VL: 包括2B/4B/8B/32B。
+- Qwen3-VL-MoE: 包括A3B/A22B。
+- MiniCPM-V-2_6: 7B。
+
+## 模态类型
+- 图片: 支持单图、多图的输入，以及图片+Prompt组合、纯文本Promot等输入方式。
+
+
+!!! warning "注意事项"
+    - 目前多模态后端不支持prefix cache以及chunk prefill，正在支持中。
+    - 目前，xLLM统一基于JinJa渲染ChatTemplate，部署MiniCPM-V-2_6，模型目录需提供ChatTemplate文件。
+    - 图片支持Base64输入以及图片Url。
+    - 目前多模态模型主要支持了图片模态，视频、音频等模态正在推进中。
+    

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

@@ -0,0 +1,57 @@
+# 整体架构
+
+## 背景
+
+近年来，随着百亿至万亿参数规模的大语言模型（如GPT、Claude、DeepSeek、LLaMA等）在自然语言处理和多模态交互领域取得突破性进展，产业界对高效推理引擎与服务体系的构建提出了迫切需求。如何降低集群推理成本、提升推理效率已成为实现规模化商业落地的关键挑战。
+
+尽管当前已涌现出一批面向大模型推理的优化引擎，但在实际部署过程中仍面临诸多技术瓶颈：
+
+- 硬件适配性挑战：现有推理引擎对国产芯片等专用加速器的架构特性支持不足，难以充分发挥异构计算硬件的性能潜力，导致计算资源利用率低下；
+- MoE架构优化难题：专家并行机制中的令牌分发过程产生显著的All-to-All通信开销，同时动态路由策略引发的专家负载不均衡问题严重制约了系统的可扩展性；
+- 长上下文管理瓶颈：随着模型上下文窗口持续扩展，KV缓存在内存碎片化处理、跨节点同步等方面的优化效率直接影响整体推理吞吐性能；
+- 混合部署效能局限：现有推理集群在同时处理在线服务和离线任务时，难以兼顾服务质量（SLO）保障与资源利用率优化。
+- 动态PD适配不足：当输入/输出序列长度出现剧烈波动时，静态PD资源划分缺乏实时调整PD资源配置的能力，既可能导致GPU资源闲置，又存在SLO违约风险。
+
+为此，我们提出了xLLM——高效且易用的开源智能推理框架，为模型在国产芯片上的推理提供企业级服务保障与高性能引擎计算能力。
+## 功能介绍
+
+xLLM提供智能计算能力，我们实现了多种计算系统层和算法驱动层的联合推理加速：
+
+### 计算系统层
+
+#### 多层流水线执行编排
+在框架层异步化CPU调度，使其与芯片推理计算形成流水线，减少计算空泡；在模型图层，切分单个batch，形成两个micro-batches之间的流水线，重叠计算通信；在算子内核层，不同计算单元间流水，重叠计算访存。
+#### 动态shape的图执行优化
+针对大语言模型处理动态输入（如可变序列长度和批大小）时面临的静态图适配问题，xLLM通过参数化设计捕获输入维度实现动态适配，并结合多图缓存方案减小编译开销，使用受管控的显存池替代绝对地址保障安全复用，最终在保持高灵活性的同时获得较高的执行效率。
+#### 算子优化
+xLLM实现了LLM中的关键算子在国产硬件芯片上的特定优化，包括GroupMatmul、Chunked Prefill等。
+#### xTensor显存管理
+xTensor 显存管理框架采用 物理内存页池预分配 + 虚拟地址连续性映射 的方法，通过动态按需映射物理页、复用可重用内存页（Reusable）及异步预映射优化调度，结合 NPU 算子适配（如虚拟地址化 FlashMLA），实现了高效动态内存管理，取得了内存利用率提升以及延迟降低。
+
+### 算法驱动层
+
+#### PD分离
+xLLM全面支持PD分离场景，实现了高效的PD实例的管理以及PD实例之间的通信以及kv cache传输。
+
+#### 全局调度
+xLLM对请求和实例做全周期的资源调度智能管理。
+##### 实例调度
+我们实现了多种实例调度策略来选择如何将实例分配到更适合的实例。包括简单的Round Robin策略，基于请求在各实例上的 prefix cache 命中率来选择的 prefix cache-aware 策略，基于实例上的显存空闲程度的 KV Cache-aware 策略。另外，针对PD分离场景，由于静态的PD比例往往无法很好应对流量以及请求输入输出长度突变的场景，我们实现了一种自适应的PD动态调度器，负责在线请求的全局实例分配与运行时PD动态调整。
+##### 请求调度
+我们实现了多种请求调度策略，支持continuous batching，包括chunked prefill，prefill优先和decode优先等batch策略，同时全面支持PD分离场景。
+#### 全局kv cache管理
+在全局层面采用ETCD作为元数据服务中间件，实现集群服务注册、负载信息同步及全局缓存状态管理。每个计算实例维护本地多级缓存池。在调度策略方面，系统采用基于 KV Cache 的动态决策机制：首先进行前缀匹配检测，计算各候选节点的 KV Cache 复用率，最终选择综合性能最优的节点进行处理，实现 KV Cache 的动态卸载与迁移。
+
+#### 投机推理
+xLLM内置优化后的投机推理算法，一次生成多个tokens提升吞吐。xLLM通过投机模块下沉减少通信成本，并使用调度和计算时序重叠优化、减少投机场景算子数据搬运等方式优化投机推理计算。
+####  MOE负载均衡
+xLLM针对MoE模型实现了基于历史专家负载统计的专家权重更新，在推理时通过高效专家负责统计和双缓冲无感知的专家权重更新实现有效的动态负载均衡。
+
+### 多模态支持
+
+xLLM对包括Qwen2-VL，MiniCPMV在内的多种多模态模型提供全面的支持。
+
+### 相关设计文档
+
+- [Graph Mode 设计文档](../design/graph_mode_design.md)
+- [生成式推荐设计文档](../design/generative_recommendation_design.md)

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

@@ -0,0 +1,36 @@
+# PpMatmul 算子优化
+
+## 背景
+
+针对大模型推理中矩阵乘法占比高、耗时长的问题，优化了矩阵乘法算子的实现。
+
+## 功能介绍
+
+PpMatmul 算子使用 Tiling 切分策略，将矩阵乘法分解为多个小的矩阵乘法任务。然而当 tile 数量较小时任务无法被均匀分配到所有 npu 核心上，导致 tail effect 问题，影响计算效率。我们通过预取内存或重新划分任务的方式，优化 PpMatmul 算子的性能。
+
+## 用户接口
+
+### 算子直调 API
+
+```cpp
+aclnnStatus aclnnPpMatmulOptGetWorkspaceSize(
+    const aclTensor *a,
+    const aclTensor *b,
+    const aclTensor *out,
+    uint64_t *workspaceSize,
+    aclOpExecutor **executor);
+
+aclnnStatus aclnnPpMatmulOpt(
+    void *workspace,
+    uint64_t workspaceSize,
+    aclOpExecutor *executor,
+    aclrtStream stream);
+```
+
+- `a`: 输入矩阵 A。
+- `b`: 输入矩阵 B。
+- `out`: 输出矩阵，存储计算结果。
+
+## 性能效果
+
+对于 tile 数量较小的情况（例如 M 较小，对应于 batch size 较小的情况），在（TP=4）时，算子较优化前有 **18%** 的性能提升。

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

@@ -0,0 +1,20 @@
+# Prefix Cache 优化
+
+## 功能介绍
+xLLM支持prefix_cache匹配。prefix_cache基于mermer_hash，使用lru淘汰策略，提供更极致的匹配效率，同时提高prefix_cache命中率。
+同时对prefix_cache进行了优化，支持continuous_scheduler、chunked_scheduler和zero_evict_scheduler，在prefill之后即更新
+prefix_cache，提高匹配时效性，同时对于chunked_scheduler，支持多阶段chunked_prefill匹配，减少计算量并尽可能减少kv_cache占用。
+
+## 使用方式
+prefix_cache已在xLLM实现，并向外暴露gflag参数，控制功能的开关。
+
+- 开启zero_evict策略，并设置max_decode_token_per_sequence。
+```
+--enable_prefix_cache=true
+```
+
+## 性能效果
+开启prefix_cache之后，在Qwen3-8B模型上，限制TPOT50ms，E2E时延 **下降10%**。
+
+!!! warning "注意"
+    暂不支持PD分离调度器

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

@@ -0,0 +1,27 @@
+# Topk&Topp算子优化
+
+## 背景
+在自然语言生成任务中，topK和topP采样策略被广泛应用于控制生成文本的多样性和质量。然而，在小模型中，这两种策略的计算耗时相对较长。这主要是由于小模型的参数较少，导致在处理概率分布时，排序和筛选的效率降低，从而影响了生成速度。因此，优化小模型中topK和topP的实现，可以提升其采样效率。
+
+
+## 功能介绍
+
+topKtopP算子的实现将排序、topK、softmax和topP等多个小算子融合为一个大算子，从而提高了计算效率和性能。
+
+
+## 用户接口
+### 算子调用API
+```c++
+void top_k_top_p(torch::Tensor& logits,
+                 const torch::Tensor& topK,
+                 const torch::Tensor& topP);
+```
+
+- `logits`: 输入的logits张量，包含模型的输出分数。
+- `topK`: 用于选择的前K个概率的阈值张量。
+- `topP`: 用于选择的累积概率的阈值张量。
+
+
+## 性能效果
+
+* 使用topKtopP融合算子后，在qwen2-0.5B模型中，TTOT **下降37%**,TTFT **提升10%**。

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

@@ -0,0 +1,48 @@
+
+
+# xLLM Service
+[:simple-github: xLLM Service](https://github.com/jd-opensource/xllm-service)
+
+## 简介
+
+**xLLM-service** 是一个基于 xLLM 推理引擎开发的服务层框架，为集群化部署提供高效率、高容错、高灵活性的大模型推理服务。
+
+xLLM-service 旨在解决企业级服务场景中的关键挑战：
+
+- 如何于在离线混合部署环境中，保障在线服务的SLA，提升离线任务的资源利用率。
+- 如何适应实际业务中动态变化的请求负载，如输入/输出长度出现剧烈波动。
+- 解决多模态模型请求的性能瓶颈。
+- 保障集群计算实例的高可靠性。
+
+#### 背景
+当前，百亿至万亿参数规模的大语言模型正快速部署于智能客服、实时推荐、内容生成等核心业务场景，对国产计算硬件的高效支持已成为低成本推理部署的核心需求。现有推理引擎难以有效适配国产芯片等专用加速器的架构特性，硬件计算单元利用率低、MoE 架构下的负载不均衡与通信开销瓶颈、kv 缓存管理困难等问题，制约了请求的高效推理与系统的可扩展性。xLLM-service + xLLM推理引擎提升了全链路效率，为大语言模型在实际业务中的规模化落地提供了关键技术支撑。
+
+--- 
+
+## 整体架构
+xLLM-service 整体架构如图所示:
+
+![1](../../assets/service_arch.png)
+
+## 核心组件
+
+### ETCD Cluster
+用于元信息管理，包括模型，xllm实例，请求等元信息的存储与管理。同时提供xllm节点注册与发现服务。
+
+### Fault Tolerance
+xLLM-service 提供容错管理，保障服务质量以及稳定性。
+
+### Global Scheduler
+实现全局感知调度，根据当前系统状态，将请求精准调度至最优实例执行，有效提升整体服务响应效率与资源利用率。
+
+### Global KV Cache Manager
+负责全局 KV Cache 管理，核心能力包括分布式 KV 缓存感知、Prefix 前缀匹配、KV Cache 动态迁移等，优化缓存资源使用效率。
+
+### Instance Manager
+聚焦实例全生命周期管理，所有 xllm 实例启动后需向本模块注册，模块基于预设策略，为实例提供调度适配、容错处理等支持。
+
+### Event Plane
+作为指标与事件中枢，接收各实例上报的 Metrics 数据，对统计指标进行统一收集与整理，为服务调度、容错、扩缩容等决策提供数据支撑。
+
+### Planner
+承担策略分析与决策职能，基于 Event Plane 上报的 Metrics 数据（含实例运行时指标、机器负载指标等），分析服务扩缩容需求、热点实例扩展必要性，输出资源调整与实例优化策略。

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

@@ -0,0 +1,17 @@
+# Zero Evict调度器
+
+## 功能介绍
+xLLM支持zero_evict调度策略。zero_evict调度策略是一种尽可能减少请求淘汰率的调度算法，可以减少淘汰请求的prefill计算，减少TPOT。
+这种调度算法通过模拟轮次，检测请求是否调度可以被调度且不导致其它请求被淘汰。
+
+## 使用方式
+上述策略已在xLLM实现，并向外暴露gflag参数，控制功能的开关。
+
+- 开启zero_evict策略，并设置max_decode_token_per_sequence。
+```
+--use_zero_evict=true
+--max_decode_token_per_sequence=256
+```
+
+## 性能效果
+开启zero_evict之后，在Qwen3-8B模型上，限制E2E时延，TPOT时延 **下降27%**。