# SGLang 2026 前沿大模型部署手册

> 版本基准：SGLang 0.5.23（2026-10-30）　·　文档核验：2026-11-06
> 所有参数释义与启动命令取自 docs.sglang.io 官方文档与官方 Cookbook，模型规模取自各模型 `config.json`。

---

## 目录

- [00 导读](#00-导读)
- [01 2026 的部署格局](#01-2026-的部署格局)
- [02 显存预算与 KV 计算](#02-显存预算与-kv-计算)
- [03 架构与参数作用点](#03-架构与参数作用点)
- [04 核心参数详解](#04-核心参数详解)
- [05 并行策略选型](#05-并行策略选型)
- [06 逐模型实战配置](#06-逐模型实战配置)
- [07 调优方法论](#07-调优方法论)
- [08 生产化与排错](#08-生产化与排错)
- [09 附录](#09-附录)

---

## 00 导读

### 这份文档讲什么

SGLang 在 2026 年的定位很清晰：**它是 MoE 大模型推理性能的标杆实现**。RadixAttention（基数树前缀缓存）、PD 分离、HiCache 分层缓存、DeepEP/MoRI 专家并行，这些能力让它成为 DeepSeek、Qwen、GLM、Kimi 这类稀疏模型的首选引擎之一。

本文只讲三件事：

1. **参数到底控制什么** —— 不是抄 `--help`，而是说明它作用在哪个阶段、调大调小分别牺牲什么。
2. **不同硬件怎么配** —— 官方 Cookbook 已验证的组合，附完整命令。
3. **出问题怎么定位** —— 日志里看哪几个数字。

### 数据基准

| 组件 | 基线 | 说明 |
| :-- | :-- | :-- |
| SGLang | 0.5.23 | 2026-10-30 发布 |
| Python | ≥ 3.11 | 官方 wheel 要求 |
| CUDA | 12.x / 13.x | Blackwell 需 CUDA 13 镜像 |
| ROCm | 7.0 / 7.2 / 10.0 | MI355X 新特性多在 ROCm 10 |
| 引擎 | SGLang Runtime (SRT) | 另有 `sglang-router` 做多实例路由 |

> **时效性声明**：SGLang 迭代极快，很多模型需要 `--prerelease=allow` 从 main 分支安装。凡涉及「默认值」的判断，请在目标机器上执行 `python -m sglang.launch_server --help` 确认。

### 三个必须先建立的心智模型

**① RadixAttention 是 SGLang 的核心差异点。**
vLLM 用块哈希做前缀缓存，SGLang 用基数树（radix tree）。基数树能表达「多个请求共享不同长度的公共前缀」这种树状结构，在 Agent、多轮对话、few-shot 场景下命中率更高。代价是调度器要维护树结构，CPU 开销略大。

**② `--mem-fraction-static` 是显存的总闸门。**
它一次性决定「权重 + KV 池」占多少显存，剩余部分留给激活和 CUDA Graph。这个参数设错，要么 OOM，要么 KV 池小得可怜。

**③ SGLang 的并行维度比 vLLM 多一维。**
除了 TP/PP/DP/EP，它还有 `--attn-dp-size`（TP 组内做注意力数据并行）和 `--dcp-size`（解码上下文并行）。DeepSeek 系的官方推荐配置几乎都会用到 `--attn-dp-size`。

---

## 01 2026 的部署格局

### 变化一：MoE 成为默认，通信成为主瓶颈

2026 年的旗舰模型清一色是细粒度专家混合：

| 模型 | 总参 | 激活 | 专家数 / 激活数 |
| :-- | --: | --: | :-- |
| DeepSeek-V4-Pro | 1.6T | 49B | 384 / 6 |
| Kimi-K3.1-Pro | 2.8T | — | 896 / 16 |
| Qwen3.5-397B-A17B | 397B | 17B | 512 / 10 |
| GLM-5.3 | 743B | 39B | 256 / 8 |
| MiniMax-M3 | 427B | 26B | 128 / 4 |

激活比例压到 3%–6% 后，**算力不再是瓶颈，跨卡 all-to-all 才是**。这就是 SGLang 把大量工程投入放在 `--moe-a2a-backend` 和 `--moe-runner-backend` 上的原因。

### 变化二：上下文进入百万级

DeepSeek-V4、Kimi-K3、MiniMax-M3、GLM-5.3 都标称 1,048,576 token。Qwen3.5 原生 262,144，可通过 YaRN 扩到约 101 万。

直接后果：

- **Prefill 成本爆炸。** 1M token 的 prefill 计算量相当于生成数万 token，必须靠 chunked prefill 切块。
- **PD 分离成为刚需。** 混合调度下，长 prefill 会打断 decode，导致 ITL 抖动。SGLang 官方文档明确指出这是 PD 分离要解决的两个核心问题之一。

### 变化三：注意力架构分道扬镳

| 架构族 | 代表 | SGLang 对应参数 |
| :-- | :-- | :-- |
| MLA | DeepSeek-V3/V4、GLM、Kimi | `--attention-backend flashmla` / `trtllm_mla` / `tokenspeed_mla` |
| 稀疏注意力 DSA | DeepSeek-V4、GLM-5.3 | `--attention-backend dsa`、`--dsa-topk-backend` |
| 线性注意力 GDN | Qwen3.5、Qwen3.8 | `--linear-attn-prefill-backend`、`--mamba-radix-cache-strategy` |
| 线性注意力 KDA | Kimi-K3 | 内置，需 `--page-size` 配合 |
| GQA + 滑窗 | gpt-oss、Llama | `--attention-backend flashinfer` / `fa3` / `fa4` |

### 2026 前沿模型一览

| 模型 | 总参 / 激活 | 上下文 | 注意力 | 精度 | 备注 |
| :-- | :-- | --: | :-- | :-- | :-- |
| **DeepSeek-V4-Pro** | 1.6T / 49B | 1,048,576 | CSA + HCA | FP4 / FP8 | 需多节点 |
| **DeepSeek-V4.1-Flash** | 552B / 8B·16B | 1,048,576 | SWA + CSA | FP8 | 视觉语言 |
| **Qwen3.5-397B-A17B** | 397B / 17B | 262,144 → 1.01M | GDN + 全注意力 | BF16 / FP8 / NVFP4 / MXFP4 | 官方 Cookbook 覆盖最全 |
| **Kimi-K3.1-Pro** | 2.8T / 16 of 896 | 1,048,576 | KDA + 稀疏 MLA | MXFP4 | 需 day-0 分支 |
| **Qwen3.8-Flash-Next** | 176B / 6B | 262,144 | Qwen4 预览，GDN + GQA | NVFP4 / FP8 / BF16 / MXFP4 | 51B N-gram embedding |
| **GLM-5.3** | 743B / 39B | 1,048,576 | MLA + DSA | FP8 / NVFP4 / W4A8 | 官方 Cookbook 有 Ascend 路径 |
| **MiniMax-M3** | 427B / 26B | 1,048,576 | MSA 块稀疏 | MXFP8 / BF16 / NVFP4 | 原生多模态 |
| **gpt-oss-120b** | 117B / 5.1B | 131,072 | 滑窗 + 全注意力 | MXFP4 | 入门基线 |

> **注意**：SGLang 对前沿模型的支持高度依赖镜像版本。Kimi-K3.1-Pro 需要 `kimi-k3.1-day-0` 分支，MiniMax-M3 需要 ≥ 0.5.22 的版本化镜像，Qwen3.5 需要 main 分支源码安装。**部署前先确认镜像 tag，不要用 `pip install sglang` 的默认版本**。

---

## 02 显存预算与 KV 计算

### 显存的四块开销

```
┌────────────────────────────────────────────────────────────┐
│   Weights   │  KV Cache Pool  │  CUDA Graph  │ Activations │
└────────────────────────────────────────────────────────────┘
 └──── mem_fraction_static ────┘
                                 └──────── 剩余部分 ────────┘
```

SGLang 的划分方式和 vLLM 不同：**`--mem-fraction-static` 同时覆盖权重和 KV 池**，公式为：

```
mem_fraction_static = (model weights + KV cache pool) / GPU memory capacity
```

剩余部分留给激活和 CUDA Graph buffer。官方经验值：**保留 5–8 GB 给激活**即可。

### 怎么判断设得对不对

启动日志会打印一行关键信息：

```
max_total_num_tokens=665690, chunked_prefill_size=8192, max_prefill_tokens=16384,
max_running_requests=4096, context_len=65536, available_gpu_mem=13.50 GB
```

看 `available_gpu_mem`：

| 值 | 判断 | 动作 |
| :-- | :-- | :-- |
| 5–8 GB | 合适 | 保持 |
| 10–20 GB | 太保守，KV 池浪费 | 提高 `--mem-fraction-static` |
| < 5 GB | 有 OOM 风险 | 降低 `--mem-fraction-static` |

官方给的调法很直接：**以 0.01 为步长往上加，直到压测出现 OOM，再退回来**。

### KV Cache 的两种算法

#### MHA / GQA / MQA（统一公式）

这三种架构用的是**同一个公式**，差别只在 `n_kv_heads` 取什么值：

```
KV_bytes_per_token = 2 × n_layers × n_kv_heads × head_dim × dtype_bytes
                     ↑                        ↑
                     K 和 V 各一份            这里是唯一的架构差异
```

| 架构 | `n_kv_heads` | 相对 MHA 的 KV 量 | 例 |
| :-- | :-- | :-- | :-- |
| **MHA** | `= n_heads` | 1× | Llama-1/2、GPT-3 |
| **GQA** | `= n_heads / g` | **1/g** | Llama-3（g=8）、Qwen3（g=8） |
| **MQA** | `= 1` | 1/n_heads | PaLM、Falcon |

所以 GQA 和 MHA 的差别就是**分组比 g 倍**——Llama-3-70B 是 64 个 query head 配 8 个 KV head（g=8），KV 只有 MHA 的 1/8。写公式时用 `n_kv_heads` 就把三者统一了，但**不要把 "GQA / MHA" 并列成一个类别**，读到的人容易误以为两者算法相同。

例：Llama-3.3-70B，BF16（64 q-heads / 8 kv-heads，g=8）

```
2 × 80 × 8 × 128 × 2 = 327,680 B ≈ 320 KiB / token
```

若换成 MHA（64 kv-heads），同样的模型会是 2.56 MiB/token —— 8 倍。

8K 上下文单请求就要 2.6 GB。这就是 GQA 模型的并发天花板。

#### MLA（DeepSeek / GLM / Kimi 系）

MLA 只缓存低秩潜向量 + RoPE 分量：

```
KV_bytes_per_token = n_layers × (kv_lora_rank + qk_rope_head_dim) × dtype_bytes
```

例：DeepSeek-V3，BF16

```
61 × (512 + 64) × 2 = 70,272 B ≈ 68.6 KiB / token
```

例：GLM-5，FP8

```
78 × (512 + 64) × 1 = 44,928 B ≈ 43.9 KiB / token
```

同样 FP8 下，GLM-5 每 token 只有 Llama-70B 的 **1/7**。这是 MLA 在长上下文场景的核心优势。

> **稀疏注意力的额外开销**：DSA / MSA / CSA 会额外维护索引器状态，且通常不跟随主 KV 量化。Kimi-K3 的 KDA 层还为每条序列保留常数大小的循环状态，这部分**不在分页 KV 池里**。真实占用 = 公式值 + 索引器 + 状态池，务必以启动日志的 `max_total_num_tokens` 为准。

### 读懂 SGLang 的运行日志

SGLang 每个 decode step 会打印一行：

```
Decode batch. #running-req: 233, #token: 370959, token usage: 0.82,
cuda graph: True, gen throughput (token/s): 4594.01, #queue-req: 317
```

| 字段 | 含义 | 健康值 |
| :-- | :-- | :-- |
| `#running-req` | 当前在跑的请求数 | 接近 `--max-running-requests` |
| `token usage` | KV 池使用率 | **> 0.9 说明利用充分** |
| `#queue-req` | 排队请求数 | **100–2000** |
| `gen throughput` | 生成吞吐 | 越高越好 |

官方给的两个诊断信号：

- **`token usage < 0.9` 且 `#queue-req > 0`** → 服务太保守，降低 `--schedule-conservativeness`（如 0.3）。
- **频繁出现 `KV cache pool is full. Retract requests.`** → 太激进，提高 `--schedule-conservativeness`（如 1.3）。偶尔（约每分钟一次）出现是正常的。

---

## 03 架构与参数作用点

### SGLang 的进程与组件

```
Client
  │  HTTP / SSE
  ▼
┌─────────────────────────────────────────────┐
│  HTTP Server (FastAPI + uvicorn)            │
│  · 分词 / chat template / 多模态预处理        │
│  · OpenAI 兼容接口                            │
└───────────────┬─────────────────────────────┘
                │ ZMQ / IPC
                ▼
┌─────────────────────────────────────────────┐
│  Scheduler × (TP × DP × attn-dp)            │
│  · RadixCache：基数树前缀复用                 │
│  · Token 预算分配 / chunked prefill           │
│  · Retract（KV 不足时回退请求）                │
└───────────────┬─────────────────────────────┘
                ▼
┌─────────────────────────────────────────────┐
│  Model Runner × N (每卡一个)                  │
│  · Attention backend（fa3/fa4/flashmla/dsa） │
│  · MoE runner（deep_gemm/triton/flashinfer） │
│  · All-to-all（deepep/mooncake/nixl/mori）   │
└─────────────────────────────────────────────┘
```

### 一次请求的路径

```
① 接入        HTTP → 鉴权 → SSE 建连
                 ↓
② 输入处理    分词 → chat template → 多模态解码
                 ↓  --tokenizer-worker-num 可并行
③ 前缀匹配    RadixCache 查找最长公共前缀
                 ↓  --schedule-policy lpm 可优化
④ 排队调度    token 预算分配 → chunked prefill 切块
                 ↓  --max-prefill-tokens / --chunked-prefill-size
⑤ KV 分配     从 KV 池取页 → 不足则 retract
                 ↓  --page-size / --mem-fraction-static
⑥ 前向        prefill / decode → 采样
                 ↓  --attention-backend / --moe-runner-backend
⑦ 输出        反分词 → 流式推送
                 ↓  --stream-interval
```

**延迟归属**：

- **TTFT** 主要由 ③④⑥（prefill）决定
- **ITL** 几乎完全由 ⑥（decode 单步）决定
- **吞吐** 由 ④ 的 batch 效率和 ⑥ 的 kernel 效率共同决定

---

## 04 核心参数详解

### 4.1 模型与显存

| 参数 | 默认 | 含义与取舍 |
| :-- | :-- | :-- |
| `--model-path` | 必填 | HF 仓库名或本地路径。生产用本地路径 |
| `--tp-size` / `--tp` | 1 | 张量并行度。要求 `num_key_value_heads` 能被 TP 整除，否则 KV 会被复制 |
| `--ep-size` / `--ep` | 1 | 专家并行度。DeepEP/Mooncake/NIXL/PPLX/MoRI **只支持 `ep_size = tp_size`** |
| `--dp-size` | 1 | 数据并行副本数。**官方建议用 Router 而非 `--dp-size` 做 DP** |
| `--pp-size` | 1 | 流水并行度 |
| `--attn-dp-size` | 1 | TP 组内的注意力数据并行组数，每个组一个 scheduler，FFN 仍走 TP |
| `--dcp-size` | 1 | 解码上下文并行，把 MLA 潜变量切到多卡 |
| `--mem-fraction-static` | 自动 | **最重要的显存参数**：权重 + KV 池占 GPU 的比例 |
| `--max-total-tokens` | 自动 | 直接指定 KV 池 token 数，覆盖自动计算 |
| `--context-length` | 从 config 读 | 模型最大上下文。OOM 时优先降这个 |
| `--quantization` | 自动 | 加载已量化 checkpoint 时无需指定；`--quantization fp8` 用于在线量化 |
| `--kv-cache-dtype` | 自动 | `fp8_e4m3` / `fp8_e5m2`。**FP8 KV 通常必开** |

### 4.2 调度与批处理

| 参数 | 默认 | 含义与取舍 |
| :-- | :-- | :-- |
| `--max-running-requests` | 自动 | 最大并发请求数。**decode OOM 时优先降它** |
| `--max-queued-requests` | 自动 | 最大排队数，PD 分离模式下忽略 |
| `--chunked-prefill-size` | 8192 | 单次 prefill 的最大 token 数。**prefill OOM 时降到 4096 或 2048** |
| `--max-prefill-tokens` | 16384 | 单批 prefill token 上限；实际取它与模型最大上下文的较大值 |
| `--schedule-policy` | `fcfs` | `lpm`（最长前缀优先，提升命中率）、`random`、`dfs-weight`、`lof`、`priority`、`routing-key` |
| `--schedule-conservativeness` | 1.0 | < 1 更激进（吃更多请求），> 1 更保守（减少 retract） |
| `--page-size` | 1 | KV 页大小。AITER 后端要求 16；Kimi-K3 的 mamba 策略要求 64 |
| `--cuda-graph-max-bs-decode` | 自动（<160/256） | decode CUDA Graph 的最大 batch。大 TP 时可提到 512–768，但会吃显存 |

### 4.3 缓存

| 参数 | 默认 | 含义 |
| :-- | :-- | :-- |
| `--disable-radix-cache` | 关闭（即默认启用） | RadixAttention 前缀缓存。**与 HiCache 互斥** |
| `--enable-hierarchical-cache` / `--enable-hicache` | 关闭 | 启用 host DRAM 二级 KV 缓存 |
| `--hicache-ratio` | 1.5 | host 层大小为 device KV 的倍数 |
| `--hicache-size` | — | 直接指定 host 层大小（GB/rank），覆盖 ratio |
| `--hicache-write-policy` | — | `write_through`（写时同步镜像）/ `write_back` |
| `--hicache-io-backend` | — | `kernel` / `direct` |
| `--hicache-mem-layout` | — | `page_first` 等 |
| `--enable-unified-cache-external-linker` | 关闭 | 直接对接外部 KV 存储（如 Mooncake） |
| `--mamba-radix-cache-strategy` | `no_buffer` | 混合 Mamba 模型的缓存策略：`no_buffer`（默认，省显存）/ `extra_buffer`（支持 overlap 调度，需 FLA 内核） |

### 4.4 后端选择

**Attention backend**（`--attention-backend`）：

| 值 | 适用 |
| :-- | :-- |
| `flashinfer` | 通用，Hopper/Blackwell 上表现均衡 |
| `fa3` / `fa4` | FlashAttention 3/4，H100/H200 用 fa3，B200/B300 用 fa4 |
| `flashmla` / `trtllm_mla` / `tokenspeed_mla` / `cutedsl_mla` | MLA 模型专用 |
| `dsa` | DeepSeek Sparse Attention |
| `aiter` | AMD，需 `--page-size 16` |
| `triton` | 兜底，兼容性最好 |

**MoE all-to-all backend**（`--moe-a2a-backend`）：

| 值 | 适用场景 |
| :-- | :-- |
| `none`（默认） | 混合 EP+TP 场景，用 AllReduce/AllGather 派发 |
| `deepep` | 大规模 EP，支持 normal / low_latency 两种模式 |
| `mooncake` | 弹性 EP，基于 RDMA |
| `nixl` | 弹性 EP，NVIDIA NIXL，支持容错与动态扩缩 |
| `mori` | AMD ROCm 原生 |
| `flashinfer` | 大规模 EP |
| `pplx` | Hopper 上的低延迟 decode EP，需 NVSHMEM |

**MoE runner backend**（`--moe-runner-backend`）：

| 值 | 适用 |
| :-- | :-- |
| `auto`（默认） | 按架构/硬件/量化自动选 |
| `deep_gemm` | FP8 block-wise 量化，prefill 用连续布局、decode 用 masked 布局 |
| `triton` | 通用，建议配合 tuned config |
| `flashinfer_trtllm` | Blackwell + TRT-LLM 内核 |
| `flashinfer_cutedsl` | Blackwell + NVFP4 |

### 4.5 解析器

| 参数 | 说明 |
| :-- | :-- |
| `--tool-call-parser` | 可设 `auto` 从 chat template 自动检测。可选值含 `deepseekv4`、`glm47`、`kimi_k3`、`qwen3_coder`、`minimax_m3`、`gpt-oss` 等 |
| `--reasoning-parser` | 同上。可选 `deepseek-v4`、`glm45`、`kimi_k3`、`qwen3`、`minimax_m3`、`step3p5` 等 |
| `--served-model-name` | 覆盖 `/v1/models` 返回的名字 |

> **实践建议**：2026 年的模型几乎都支持 `auto`，但**自动检测依赖 chat template 的元数据**。如果模型用的是自定义编码器（如 Kimi-K3 的 XTML、DeepSeek-V4 的 Python encoder），`auto` 可能失效，需要显式指定。

---

## 05 并行策略选型

<!-- engine-topologies:start -->
### 本引擎的推理拓扑与 KV 存放

> attention-DP 是 TP 组内的注意力数据分组，不等于完整模型副本。DeepEP 等后端的 EP/TP 约束需单独满足；共享专家融合会改变执行路径，不能只凭 ep-size 推断。

#### SGLang · A · Attention TP4 + routed TP4

配置要点：`--tp-size 4 --ep-size 1`（机制示例，须满足模型与硬件约束）。

![SGLang · A · Attention TP4 + routed TP4](assets/topologies/sglang/topology-1.svg)

KV 已明确按 GQA 示例标注：TP4 每卡 2 个 KV head；attention-DP4 每卡保存自己请求的 KV。共享专家布局是图示前提，不是该引擎所有后端的默认承诺。

#### SGLang · B · Attention TP4 + routed EP4

配置要点：`--tp-size 4 --ep-size 4`（机制示例，须满足模型与硬件约束）。

![SGLang · B · Attention TP4 + routed EP4](assets/topologies/sglang/topology-2.svg)

KV 已明确按 GQA 示例标注：TP4 每卡 2 个 KV head；attention-DP4 每卡保存自己请求的 KV。共享专家布局是图示前提，不是该引擎所有后端的默认承诺。

#### SGLang · C · attention-DP4 + routed TP4

配置要点：`--tp-size 4 --attn-dp-size 4 --ep-size 1`（机制示例，须满足模型与硬件约束）。

![SGLang · C · attention-DP4 + routed TP4](assets/topologies/sglang/topology-3.svg)

KV 已明确按 GQA 示例标注：TP4 每卡 2 个 KV head；attention-DP4 每卡保存自己请求的 KV。共享专家布局是图示前提，不是该引擎所有后端的默认承诺。

#### SGLang · D · attention-DP4 + routed EP4

配置要点：`--tp-size 4 --attn-dp-size 4 --ep-size 4`（机制示例，须满足模型与硬件约束）。

![SGLang · D · attention-DP4 + routed EP4](assets/topologies/sglang/topology-4.svg)

KV 已明确按 GQA 示例标注：TP4 每卡 2 个 KV head；attention-DP4 每卡保存自己请求的 KV。共享专家布局是图示前提，不是该引擎所有后端的默认承诺。

官方依据：[SGLang](https://docs.sglang.io/docs/advanced_features/expert_parallelism)。
<!-- engine-topologies:end -->


### 五种并行

```
TP（张量并行）        层内切权重，每层 all-reduce
PP（流水并行）        按层切，stage 间传激活
DP（数据并行）        整模型复制，各跑各的请求
EP（专家并行）        MoE 专家分散，all-to-all 派发
DCP（解码上下文并行）  MLA 潜变量与索引器 KV 切到多卡
```

### SGLang 特有的两个维度

**`--attn-dp-size`：TP 组内的注意力数据并行**

这是 DeepSeek 系模型的官方推荐配置。它把注意力层按 DP 拆成多个组，每组一个独立 scheduler，FFN 仍走 TP。好处是：

- 每个 DP 组有独立的 KV 池和调度队列，减少跨组同步
- 配合 `--enable-dp-lm-head` 可避免 DP 组间的 all-gather

官方 DeepSeek 多节点示例：

```bash
python -m sglang.launch_server \
  --model-path deepseek-ai/DeepSeek-V3-0324 \
  --tp-size 16 \
  --attn-dp-size 8 \
  --moe-a2a-backend deepep \
  --mem-fraction-static 0.8
```

**`--dcp-size`：解码上下文并行**

把 MLA 潜变量和索引器 KV 切片到多卡，直接放大 KV 容量。Kimi-K3 在 DCP8 下 KV 容量约为 TP8 的 7 倍，代价是 decode 慢 7–25%。**只在 KV 容量是瓶颈时用**。

### 选型决策

```
模型能装进单卡？
├─ 是 → 单卡，无需并行
└─ 否 → 是 MoE？
        ├─ 否（稠密）→ TP = 卡数（单机）；跨机加 PP
        └─ 是 → 瓶颈是延迟还是吞吐？
                ├─ 延迟 → TP 优先 + 小 max-running-requests
                └─ 吞吐 → DP（或 attn-dp）+ EP + 大 batch
                          · 单机：--tp 8 --ep 8 --moe-a2a-backend deepep
                          · 多机：--tp 16 --attn-dp-size 8
                └─ 长上下文 → 加 --dcp-size 或 HiCache
```

### EP 的关键约束

> **DeepEP / Mooncake / NIXL / PPLX / MoRI 只支持 `ep_size = tp_size`。**
>
> 混合 EP+TP（即 `ep_size < tp_size`）只能用 `none` 后端（AllReduce/AllGather 派发）。

这条约束经常被忽略，导致配置报错。如果确实需要 `ep < tp`，就得接受 `none` 后端的性能损失。

另外：

- `--deepep-mode auto` 会在运行时自动切换 normal / low_latency 模式
- `--deepep-mode normal` 适合 prefill（高吞吐）
- `--deepep-mode low_latency` 适合 decode（低延迟 + CUDA Graph 兼容）
- `pplx` 额外要求 `--attn-dp-size > 1`

### PD 分离

SGLang 的 PD 分离支持 Mooncake 和 NIXL 两种传输引擎。

```bash
# Prefill 实例
python -m sglang.launch_server \
  --model-path meta-llama/Llama-3.1-8B-Instruct \
  --disaggregation-mode prefill \
  --port 30000 \
  --disaggregation-ib-device mlx5_roce0

# Decode 实例
python -m sglang.launch_server \
  --model-path meta-llama/Llama-3.1-8B-Instruct \
  --disaggregation-mode decode \
  --port 30001 \
  --base-gpu-id 1 \
  --disaggregation-ib-device mlx5_roce0

# Router
python -m sglang_router.launch_router \
  --pd-disaggregation \
  --prefill http://127.0.0.1:30000 \
  --decode http://127.0.0.1:30001 \
  --host 0.0.0.0 --port 8000
```

**DeepSeek 多节点 PD 分离**（官方示例，2 节点 × TP16）：

```bash
# Prefill（每节点都执行，node-rank 0/1）
python -m sglang.launch_server \
  --model-path deepseek-ai/DeepSeek-V3-0324 \
  --disaggregation-ib-device ${device_name} \
  --disaggregation-mode prefill \
  --host ${local_ip} --port 30000 \
  --trust-remote-code \
  --dist-init-addr ${prefill_master_ip}:5000 \
  --nnodes 2 --node-rank 0 \
  --tp-size 16 --attn-dp-size 8 \
  --moe-a2a-backend deepep \
  --mem-fraction-static 0.8

# Decode（额外限制并发）
python -m sglang.launch_server \
  --model-path deepseek-ai/DeepSeek-V3-0324 \
  --disaggregation-mode decode \
  --host ${local_ip} --port 30001 \
  --dist-init-addr ${decode_master_ip}:5000 \
  --nnodes 2 --node-rank 0 \
  --tp-size 16 --attn-dp-size 8 \
  --moe-a2a-backend deepep \
  --mem-fraction-static 0.8 \
  --max-running-requests 128
```

> **关键提醒**：H200 上做 PD 分离可能需要 `--privileged --ulimit memlock=-1`（或 `--device /dev/infiniband:/dev/infiniband --cap-add IPC_LOCK`），否则 Mooncake 找不到 IB HCA，会**静默回退到 TCP**，导致大 checkpoint 的 KV 传输出现乱码。

---

## 06 逐模型实战配置

### 6.1 入门基线：gpt-oss-120b

```bash
# 单卡（H100/H200/B200，或 A100 80G）
python -m sglang.launch_server --model-path openai/gpt-oss-120b

# 多卡
python -m sglang.launch_server --model-path openai/gpt-oss-120b --tp 4

# 工具调用
python -m sglang.launch_server \
  --model-path openai/gpt-oss-120b \
  --tool-call-parser gpt-oss \
  --reasoning-parser gpt-oss
```

**验证**：

```python
from openai import OpenAI

client = OpenAI(base_url="http://localhost:30000/v1", api_key="EMPTY")
r = client.chat.completions.create(
    model="openai/gpt-oss-120b",
    messages=[{"role": "user", "content": "Explain eigenvalues briefly."}],
)
print(r.choices[0].message.content)
```

> SGLang 默认端口是 **30000**，不是 vLLM 的 8000。

### 6.2 主力中坚：Qwen3.5-397B-A17B

官方 Cookbook 覆盖最全的模型，NVIDIA / AMD / Intel / Ascend 都有验证配置。

**架构要点**：Gated Delta Networks（线性，O(n)）与全注意力交替，每 4 层一次全注意力；512 路由专家 top-10 + 共享专家；原生多模态（DeepStack ViT + Conv3d）。

#### NVIDIA 配置

```bash
# H200 × 8，FP8，吞吐优先（文本）
python -m sglang.launch_server \
  --model-path Qwen/Qwen3.5-397B-A17B-FP8 \
  --tp-size 8 \
  --mem-fraction-static 0.85 \
  --reasoning-parser qwen3 \
  --tool-call-parser qwen3_coder \
  --enable-symm-mem

# B200/B300，FP8，加 Blackwell 专用优化
python -m sglang.launch_server \
  --model-path Qwen/Qwen3.5-397B-A17B-FP8 \
  --tp-size 4 \
  --moe-runner-backend flashinfer_trtllm \
  --linear-attn-prefill-backend flashinfer \
  --enable-flashinfer-allreduce-fusion \
  --reasoning-parser qwen3
```

**硬件需求对照**（官方 Cookbook）：

| 精度 | 权重显存 | H100 80G | H200 141G | B200 183G | B300 275G | MI300X 192G | MI325X 256G | MI355X 288G |
| :-- | --: | :-- | :-- | :-- | :-- | :-- | :-- | :-- |
| BF16 | ~800 GB | tp16（2 节点） | tp8 | tp8 | tp4 | tp8 | tp4 | tp4 |
| FP8 | ~400 GB | tp8 | tp4 | tp4 | tp2 | tp4 | tp2 | tp2 |

#### AMD 配置

```bash
export SGLANG_USE_AITER=1
export SGLANG_USE_AITER_UNIFIED_ATTN=1
export AITER_FLYDSL_FORCE=1
export SGLANG_MAMBA_SSM_DTYPE=bfloat16

python -m sglang.launch_server \
  --model-path Qwen/Qwen3.5-397B-A17B-FP8 \
  --tp-size 4 \
  --attention-backend aiter \
  --page-size 16 \
  --enable-aiter-allreduce-fusion \
  --reasoning-parser qwen3
```

**MXFP4 单卡（MI350X/MI355X）**：

```bash
export VLLM_ROCM_USE_AITER=1   # 注意：SGLang 的 MXFP4 路径沿用此变量名
export ROCM_QUICK_REDUCE_QUANTIZATION=INT4

python -m sglang.launch_server \
  --model-path amd/Qwen3.5-397B-A17B-MXFP4 \
  --tp-size 1 \
  --attention-backend aiter \
  --page-size 16 \
  --max-running-requests 64 \
  --reasoning-parser qwen3
```

> **注意**：`--max-running-requests 64` 不是随便设的。单卡留下的 Mamba cache block 约 296 个，默认的 1024 会直接导致服务拒绝启动。

#### 长上下文

Qwen3.5 原生 262,144。要跑更长需要开 YaRN：

```bash
python -m sglang.launch_server \
  --model-path Qwen/Qwen3.5-397B-A17B-FP8 \
  --tp-size 8 \
  --context-length 1010000 \
  --json-model-override-args '{"text_config":{"rope_parameters":{"rope_type":"yarn","factor":4.0,"original_max_position_embeddings":262144,"rope_theta":10000000,"partial_rotary_factor":0.25,"mrope_interleaved":true,"mrope_section":[11,11,10]}}}'
```

> 静态 YaRN 会把缩放因子固定，**不服务长 prompt 时不要开**。只跑 ~524K 的话，把 `factor` 减半到 2.0。

#### 已知坑

| 现象 | 原因 | 处理 |
| :-- | :-- | :-- |
| `assert num_cache_lines >= batch` | CUDA graph 捕获尺寸 > Mamba cache | 降低 `--cuda-graph-max-bs-decode` |
| 服务拒绝启动 | `max_running_requests` 超过单卡 Mamba block 数 | 设 `--max-running-requests 64` |
| 多模态 TTFT 高 | 特征传输走 CPU | 设 `SGLANG_USE_CUDA_IPC_TRANSPORT=1`（会额外吃显存） |
| 加载极慢 | 397B 权重读取 | 加 `--model-loader-extra-config='{"enable_multithread_load":"true","num_threads":64}'` |

### 6.3 旗舰：DeepSeek-V4-Pro

1.6T 总参 / 49B 激活，CSA + HCA 混合注意力。**必须多节点**。

官方 Cookbook 给出的策略分三档：

| 策略 | 目标 | 典型配置 |
| :-- | :-- | :-- |
| Low-Latency | 单用户最快回复 | TP-only，小 batch |
| Balanced | 多用户常规服务 | TP + DP，中等并发 |
| High-Throughput | 批量任务 | TP + DP，大并发，`--attn-dp-size` |

**MI355X 多节点（官方 1P1D 部署）**：

```bash
# Prefill 节点
python -m sglang.launch_server \
  --model-path deepseek-ai/DeepSeek-V4-Pro \
  --tp-size 4 \
  --ep-size 4 \
  --moe-a2a-backend mori \
  --disaggregation-mode prefill \
  --disaggregation-ib-device mlx5_0 \
  --mem-fraction-static 0.85 \
  --reasoning-parser deepseek-v4 \
  --tool-call-parser deepseekv4

# Decode 节点
python -m sglang.launch_server \
  --model-path deepseek-ai/DeepSeek-V4-Pro \
  --tp-size 4 \
  --ep-size 4 \
  --moe-a2a-backend mori \
  --attn-dp-size 8 \
  --enable-dp-attention-local-control-broadcast \
  --tokenizer-worker-num 8 \
  --stream-interval 20 \
  --prefill-decode-interval 10 \
  --disaggregation-mode decode \
  --disaggregation-ib-device mlx5_0 \
  --mem-fraction-static 0.85 \
  --max-running-requests 128

# Router
python -m sglang_router.launch_router \
  --pd-disaggregation \
  --prefill http://<prefill-ip>:30000 \
  --decode http://<decode-ip>:30001 \
  --host 0.0.0.0 --port 8000
```

**投机解码**：

- 原始 Flash / Pro checkpoint 自带 MTP 头：
  ```bash
  --speculative-algorithm EAGLE \
  --speculative-num-steps 3 \
  --speculative-eagle-topk 1 \
  --speculative-num-draft-tokens 4
  ```
- Pro Official（0813）没有 MTP 头，只有 DSpark：
  ```bash
  --speculative-algorithm DSPARK
  ```

> **AMD 注意**：FP4 模型用原始 `deepseek-ai/DeepSeek-V4-{Flash,Pro}`，FP8 模型用 `sgl-project/DeepSeek-V4-{Flash,Pro}-FP8`。用错 checkpoint 精度会异常。

### 6.4 超大 MoE：Kimi-K3.1-Pro

2.8T 参数，896 专家激活 16 个，KDA 线性注意力 + 稀疏 MLA（24 层 MLA 加 DSA top-2048 索引器）。

**必须用 day-0 分支**：

```bash
git clone -b kimi-k3.1-day-0 https://github.com/sgl-project/sglang.git
cd sglang && pip install -e "python"
```

或用镜像：`lmsysorg/sglang:dev-kimi-k31-pro`

**三档策略**：

```bash
# Low-Latency（TP8）
python -m sglang.launch_server \
  --model-path moonshotai/Kimi-K3.1-Pro \
  --tp-size 8 \
  --mem-fraction-static 0.85

# High-Concurrency（DCP8，KV 切到 8 卡）
python -m sglang.launch_server \
  --model-path moonshotai/Kimi-K3.1-Pro \
  --tp-size 8 \
  --dcp-size 8 \
  --mem-fraction-static 0.85

# High-Throughput（PD 分离，prefill PP4×PCP2，decode DCP8·EP2）
```

> **Mamba ratio**：Kimi-K3 的 KDA 层有循环状态，SGLang 提供 mamba ratio 计算器来平衡「KV 池」与「状态池」的显存分配。这个值设错会表现为「KV 还有空间但请求跑不动」。

**完整的高并发配置（B300 / GB300）**：

```bash
python -m sglang.launch_server \
  --model-path moonshotai/Kimi-K3.1-Pro \
  --tp-size 8 \
  --dcp-size 8 \
  --attention-backend tokenspeed_mla \
  --kv-cache-dtype fp8_e4m3 \
  --mem-fraction-static 0.82 \
  --max-running-requests 128 \
  --speculative-algorithm EAGLE \
  --speculative-num-steps 3 \
  --reasoning-parser kimi_k3 \
  --tool-call-parser kimi_k3
```

| 布局 | 适用 | 关键参数 | 代价 |
| :-- | :-- | :-- | :-- |
| TP8 | 基线 | `--tp-size 8` | KV 容量最小 |
| TP8 + DCP8 | 超长上下文 / 多会话 | `--dcp-size 8` | decode 慢 7–25%，KV 容量约 7 倍 |
| PD 分离 | 长 prompt + 高并发 | prefill PP4×PCP2 / decode DCP8·EP2 | 需要 Router + 传输引擎 |
| MI355X | AMD 路径 | `--moe-a2a-backend mori` | 需 ROCm 10 镜像 |

### 6.5 Qwen3.8-Flash-Next

Qwen4 架构预览：125B 主模型 + 51B N-gram embedding，每 token 激活 6B，262K 上下文，原生多模态。

**精度与显存**：

| 精度 | checkpoint | 最小显存 | 推荐硬件 |
| :-- | :-- | --: | :-- |
| NVFP4 | `Inferact/Qwen3.8-Flash-Next-NVFP4` | 130 GB | 单 GB200 / GB300 |
| FP8 | `Qwen/Qwen3.8-Flash-Next-FP8` | 250 GB | B300 满 tray |
| MXFP4 | `amd/Qwen3.8-Flash-Next-Quark-MXFP4` | 219 GB | MI355X |
| BF16 | `Qwen/Qwen3.8-Flash-Next` | 423 GB | 8×H200 |

**B300 满 tray（TEP4）**：

```bash
python -m sglang.launch_server \
  --model-path Qwen/Qwen3.8-Flash-Next-FP8 \
  --tp-size 4 \
  --ep-size 4 \
  --moe-runner-backend flashinfer_trtllm \
  --linear-attn-prefill-backend flashinfer \
  --mem-fraction-static 0.85 \
  --enable-hierarchical-cache \
  --hicache-ratio 1.5 \
  --speculative-algorithm NEXTN \
  --speculative-num-draft-tokens 3 \
  --reasoning-parser qwen3 \
  --tool-call-parser qwen3_coder
```

**8×H200（TEP8 + Triton MoE）**：

```bash
python -m sglang.launch_server \
  --model-path Qwen/Qwen3.8-Flash-Next-FP8 \
  --tp-size 8 \
  --ep-size 8 \
  --moe-runner-backend triton \
  --mem-fraction-static 0.85 \
  --max-running-requests 256
```

> **三个约束**：① 纯 TP 与 FP8 checkpoint 不兼容（128 宽量化块切不开），必须开 EP；② `--max-running-requests 256` 不要降，低了会触发 Mamba cache 容量错误；③ 压测 MTP 用 `--dataset-name speed_bench`，随机数据集测不出真实接受率。

### 6.6 GLM-5.3

743B / 39B，MLA + DSA。官方 Cookbook 同时覆盖 NVIDIA、AMD、Ascend。

**NVIDIA**：

```bash
python -m sglang.launch_server \
  --model-path zai-org/GLM-5.3 \
  --tp-size 8 \
  --ep-size 8 \
  --moe-a2a-backend deepep \
  --dsa-topk-backend sgl-kernel \
  --tool-call-parser glm47 \
  --reasoning-parser glm45 \
  --mem-fraction-static 0.85
```

**AMD MI355X（MXFP4 + EAGLE MTP）**：

```bash
export SGLANG_OPT_USE_TOPK_V2=true
export SGLANG_TIMEOUT_KEEP_ALIVE=900

python -m sglang.launch_server \
  --model-path amd/GLM-5.3-Quark-MXFP4-AttnFP8 \
  --tp-size 4 \
  --ep-size 4 \
  --trust-remote-code \
  --kv-cache-dtype fp8_e4m3 \
  --dsa-prefill-backend triton \
  --dsa-decode-backend triton \
  --tool-call-parser glm47 \
  --reasoning-parser glm45 \
  --chunked-prefill-size 32768 \
  --mem-fraction-static 0.85 \
  --max-running-requests 20 \
  --cuda-graph-max-bs-decode 20
```

> **批量限制**：官方建议 `--max-running-requests` 和 `--cuda-graph-max-bs-decode` 都设为**目标并发的 2 倍**。

**HiCache（host DRAM 二级缓存）**：

```bash
--enable-hierarchical-cache \
--hicache-size 180        # GB per rank；4 rank 需要约 720 GB host 内存
--hicache-write-policy write_through \
--hicache-io-backend kernel \
--hicache-mem-layout page_first
```

> HiCache 扩展的是 RadixCache，**与 `--disable-radix-cache` 互斥**，同时开会启动失败。

### 6.7 MiniMax-M3

427B / 26B，MSA 块稀疏注意力，原生多模态（图 + 视频 + 计算机操作）。

```bash
# NVIDIA Blackwell，MXFP8
python -m sglang.launch_server \
  --model-path MiniMaxAI/MiniMax-M3-MXFP8 \
  --tp-size 8 \
  --reasoning-parser auto \
  --tool-call-parser auto \
  --mem-fraction-static 0.85

# Hopper（H200）用 BF16 全精度
python -m sglang.launch_server \
  --model-path MiniMaxAI/MiniMax-M3 \
  --tp-size 8 \
  --reasoning-parser auto
```

> **必须用 `--reasoning-parser auto`**：模型用 `<mm:think>...</mm:think>` 包裹思维链，auto 会从 chat template 检测正确解析器，然后把标签剥离、内容放到 `message.reasoning_content`。

> **镜像注意**：M3 从 0.5.22 起进入正式版本镜像。旧 dev 镜像（`dev-minimax-m3` 等）已废弃。正式镜像**不包含 MiniMax 的 MSA 稀疏注意力内核**（`fmha_sm100`），稀疏步走内置 Triton 路径。

### 6.8 配置速查表

| 模型 | 推荐 TP/EP | 关键参数 | 镜像 |
| :-- | :-- | :-- | :-- |
| gpt-oss-120b | tp1 / tp4 | `--tool-call-parser gpt-oss` | `lmsysorg/sglang:latest` |
| Qwen3.5-397B | tp4–8 | `--enable-symm-mem`、`--moe-runner-backend flashinfer_trtllm` | `lmsysorg/sglang:latest` |
| DeepSeek-V4-Pro | tp4 + ep4（多节点） | `--moe-a2a-backend mori/deepep` | ROCm 10 nightly / CUDA 13 |
| Kimi-K3.1-Pro | tp8 | `--dcp-size 8`（高并发） | `lmsysorg/sglang:dev-kimi-k31-pro` |
| **Qwen3.8-Flash-Next** | tp4 + ep4 / tp8 + ep8 | `--moe-runner-backend flashinfer_trtllm`（B300）、`triton`（H200） | `lmsysorg/sglang:latest` |
| GLM-5.3 | tp8 + ep8 | `--dsa-topk-backend sgl-kernel` | `lmsysorg/sglang:latest` |
| MiniMax-M3 | tp8 | `--reasoning-parser auto` | `lmsysorg/sglang:v0.5.23-cu130` |

---

## 07 调优方法论

### 先定义指标

| 指标 | 定义 | 主要决定因素 |
| :-- | :-- | :-- |
| **TTFT** | 请求到首 token | 排队 + prefill 计算 |
| **ITL / TPOT** | 相邻 token 间隔 | decode 单步耗时 |
| **Throughput** | 每秒总 token | GPU 利用率 × batch 效率 |
| **Goodput** | 满足 SLO 的有效吞吐 | 真正的业务指标 |

### 官方调优顺序

SGLang 官方文档给了一套很具体的调优流程，按顺序执行：

**第一步：提高 batch size（吞吐优先）**

看日志里的 `#queue-req`：

- 频繁 `#queue-req: 0` → 客户端提交太慢
- 健康区间：**100–2000**
- 太大 → 调度开销上升

**第二步：提高 token usage**

- `token usage > 0.9` 说明 KV 池利用充分
- `token usage < 0.9` 且 `#queue-req > 0` → 降 `--schedule-conservativeness` 到 0.3
- 频繁 `KV cache pool is full. Retract requests.` → 升到 1.3

**第三步：调 `--mem-fraction-static`**

- 看 `available_gpu_mem`，目标 5–8 GB
- 太高 → 加 `--mem-fraction-static`
- 太低 → 减，否则会 OOM
- 或者：以 0.01 步长往上加，直到 OOM 再退回

**第四步：调 `--cuda-graph-max-bs-decode`**

- 默认只对小 batch 开 graph（< 160 或 256）
- 大 TP 场景可以提到 512 或 768
- 注意 CUDA Graph 吃显存，可能要同时降 `--mem-fraction-static`

**第五步：其他手段**

- `--enable-torch-compile`：小模型 + 小 batch 有效
- `--quantization fp8`：换更低的权重精度
- `--attn-dp-size 8`：DeepSeek 系专用
- `--schedule-policy lpm`：共享前缀多的场景（会引入调度开销）

### 按场景的配方

| 场景 | 关键配置 | 理由 |
| :-- | :-- | :-- |
| **低延迟对话** | `--max-running-requests 8`<br>`--chunked-prefill-size 4096`<br>EAGLE/MTP | 小 batch 降 ITL；小 chunk 减少 prefill 干扰 |
| **高吞吐批处理** | `--max-running-requests 1024`<br>`--chunked-prefill-size 16384`<br>`--mem-fraction-static 0.9` | 大 batch 摊薄权重读取 |
| **长上下文 / RAG** | `--context-length 1000000`<br>`--kv-cache-dtype fp8_e4m3`<br>`--page-size 64` | KV 减半；大页减少元数据开销 |
| **多轮 Agent** | `--enable-hierarchical-cache`<br>`--hicache-ratio 1.5`<br>`--schedule-policy lpm` | host 层缓存长前缀；lpm 提升命中 |
| **在线混合负载** | `--schedule-policy priority`<br>`--enable-priority-scheduling` | 交互请求优先 |

### 压测

```bash
# 官方 benchmark 脚本
python -m sglang.bench_serving \
  --backend sglang \
  --host 127.0.0.1 --port 30000 \
  --model Qwen/Qwen3.5-397B-A17B-FP8 \
  --dataset-name random \
  --random-input 8000 \
  --random-output 1024 \
  --num-prompts 256 \
  --max-concurrency 64
```

### 启动时间优化

| 手段 | 说明 |
| :-- | :-- |
| `--model-loader-extra-config='{"enable_multithread_load":"true","num_threads":64}'` | 大模型多线程加载权重 |
| `--watchdog-timeout 1200` | 397B 级模型加载慢，默认超时不够 |
| `--load-format fastsafetensors` | 加速 safetensors 读取 |
| 预热 CUDA Graph | 首次请求会触发捕获，压测前先发几条 |

---

## 08 生产化与排错

### 8.1 容器化

```bash
docker run --gpus all \
  --shm-size 32g \
  --ipc=host \
  -p 30000:30000 \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  --env "HF_TOKEN=<your-token>" \
  lmsysorg/sglang:latest \
  python -m sglang.launch_server --model-path <model> --host 0.0.0.0 --port 30000
```

> **`--shm-size` 必给**：SGLang 用共享内存做进程间通信。官方示例用 32g。

### 8.2 监控

```bash
# 启用 Prometheus 指标
--enable-metrics

# 查看
curl http://localhost:30000/metrics
```

关键指标：

| 指标 | 说明 |
| :-- | :-- |
| `sglang:num_running_reqs` | 在跑请求数 |
| `sglang:num_queue_reqs` | 排队请求数 |
| `sglang:token_usage` | KV 池使用率 |
| `sglang:gen_throughput` | 生成吞吐 |
| `sglang:cache_hit_rate` | 前缀缓存命中率 |
| `sglang:e2e_request_latency_seconds` | 端到端延迟 |

### 8.3 故障排查

| 现象 | 最可能原因 | 处理 |
| :-- | :-- | :-- |
| 启动 OOM | `mem-fraction-static` 太高 | 降到 0.8 或 0.7 |
| prefill OOM | chunk 太大 | 降 `--chunked-prefill-size` 到 4096/2048 |
| decode OOM | 并发太高 | 降 `--max-running-requests` |
| 服务拒绝启动（Qwen3.5 单卡） | `max_running_requests` 超过 Mamba block 数 | 设 `--max-running-requests 64` |
| `assert num_cache_lines >= batch` | CUDA graph 尺寸 > Mamba cache | 降 `--cuda-graph-max-bs-decode` |
| KV 传输乱码（PD 分离） | Mooncake 回退到 TCP | 加 `--privileged --ulimit memlock=-1` |
| 推理内容为空 | reasoning parser 未配 | 加 `--reasoning-parser` |
| 工具调用变纯文本 | tool parser 不匹配 | 显式指定 `--tool-call-parser` |
| 吞吐上不去 | `token usage` 低 | 降 `--schedule-conservativeness` |
| 频繁 retract | KV 池太小 | 升 `--schedule-conservativeness` 或降并发 |
| 加载超时 | 大模型权重慢 | `--watchdog-timeout 1200` + 多线程加载 |

### 8.4 安全

- **默认无鉴权**：需 `--api-key` 或网关
- **多模态 URL 是 SSRF 入口**：用 `--allowed-media-domains` 限制域名
- **`--trust-remote-code`** 会执行模型仓库代码，只对可信来源开

---

## 09 附录

### A. 参数速查

| 参数 | 一句话 |
| :-- | :-- |
| `--model-path` | 模型路径 |
| `--tp-size` | 张量并行度 |
| `--ep-size` | 专家并行度（DeepEP 系要求 = tp） |
| `--dp-size` | 数据并行副本数 |
| `--attn-dp-size` | TP 组内注意力 DP 组数（DeepSeek 系关键） |
| `--dcp-size` | 解码上下文并行，放大 KV 容量 |
| `--mem-fraction-static` | 权重 + KV 池占 GPU 比例 |
| `--max-running-requests` | 最大并发 |
| `--chunked-prefill-size` | 单次 prefill 最大 token |
| `--max-prefill-tokens` | 单批 prefill token 上限 |
| `--schedule-policy` | `fcfs` / `lpm` / `priority` 等 |
| `--schedule-conservativeness` | 调度激进程度 |
| `--page-size` | KV 页大小 |
| `--kv-cache-dtype` | KV 精度 |
| `--attention-backend` | 注意力内核 |
| `--moe-a2a-backend` | EP 通信后端 |
| `--moe-runner-backend` | MoE 计算后端 |
| `--enable-hierarchical-cache` | host DRAM 二级 KV 缓存 |
| `--speculative-algorithm` | EAGLE / EAGLE3 / NEXTN / STANDALONE / NGRAM |
| `--disaggregation-mode` | `prefill` / `decode` |

### B. 环境变量

| 变量 | 作用 |
| :-- | :-- |
| `SGLANG_USE_AITER` | AMD 启用 AITER 内核 |
| `SGLANG_USE_AITER_UNIFIED_ATTN` | AMD 统一注意力 |
| `SGLANG_MAMBA_SSM_DTYPE` | Mamba 状态精度（`bfloat16` 省显存） |
| `SGLANG_USE_CUDA_IPC_TRANSPORT` | 多模态特征走 CUDA IPC，提升 TTFT |
| `SGLANG_OPT_USE_TOPK_V2` | GLM-5.3 的 top-k 优化 |
| `ROCM_QUICK_REDUCE_QUANTIZATION` | AMD 量化 all-reduce |
| `SGLANG_DISAGGREGATION_BOOTSTRAP_TIMEOUT` | PD 分离引导超时 |
| `SGLANG_DISAGGREGATION_WAITING_TIMEOUT` | decode 等待 prefill 完成的超时 |

### C. 来源

| 来源 | 用途 |
| :-- | :-- |
| docs.sglang.io/docs/advanced_features/server_arguments | 参数完整释义与默认值 |
| docs.sglang.io/docs/advanced_features/expert_parallelism | EP 后端选型 |
| docs.sglang.io/docs/advanced_features/pd_disaggregation | PD 分离配置 |
| docs.sglang.io/docs/advanced_features/hyperparameter_tuning | 官方调优流程 |
| docs.sglang.io/cookbook/autoregressive/* | 逐模型验证命令 |
| pypi.org/project/sglang | 版本核验 |

---

*本文档基于 2026-11-06 可获取的公开资料整理。SGLang 与各模型迭代迅速，涉及默认值与支持状态的内容请以目标版本的 `--help` 与实际启动日志为准。*