千卡推理平台：SGLang + Mooncake PD/EPD 生产部署与运维

1. 目标：把推理拆成可独立扩缩和隔离的资源池

面向超大规模 MoE 文本推理、长上下文和多模态推理时，一个 SGLang 实例同时处理 Prefill 和 Decode，会让两个阶段互相拖累：并行度高的 Decode 被 Prefill 抢占，或者 Prefill 的突发把 Decode 的显存带宽挤掉。生产做法是把推理系统拆成可独立扩缩、升级、观测和故障隔离的资源池：

• Encoder Pool：多模态视觉 / 音频编码，仅 EPD 场景使用。
• Prefill Pool：处理 Prompt / Context，计算密集型。
• Decode Pool：持续生成 Token，显存带宽和 KV Cache 敏感。
• Mooncake Data Plane：负责跨 Prefill / Decode 的 KV Cache 传输。
• DeepEP：负责 MoE Expert Parallelism 内部的 All-to-All。
• SMG（SGLang Model Gateway）：统一入口、PD 路由、健康检查与熔断。
• LWS + Volcano：管理多 Pod inference group 生命周期与 Gang Scheduling。
• Prometheus / Grafana / DCGM：应用、GPU、RDMA、网络和缓存全链路观测。

2. 总体架构与三类通信

Client / API Gateway
        │
        ▼
SGLang Model Gateway (SMG)
   ┌─────┴──────┐
   │            │
   ▼            ▼
Prefill Pool   Decode Pool
(SGLang)       (SGLang)
   │  KV Cache RDMA   │
   └────────┬─────────┘
            ▼
Mooncake Transfer Engine / Store
            │
            ▼
Mooncake Master (HA: etcd)

通信必须按层级区分，不要混为一谈：

把它们当成同一层能力，会在一处故障时错把另一条链路当成修复对象。

3. Release Manifest：上线前必须冻结版本

生产环境禁止 latest、dev 和未固定 Git commit 的镜像。维护一份 manifest 记录运行时、GPU 栈、集群组件与模型的一致性：

release:
  name: inference-prod-2026-09-r1
runtime:
  sglang: "v0.5.19"
  sglang_image: "registry.example.com/ai/sglang:v0.5.19"
  sglang_image_digest: "sha256:<digest>"
  moonlight_image_digest: "sha256:<digest>"
gpu_stack:
  gpu: "H100-80GB"
  nvidia_driver: "<version>"
  cuda: "<match-sglang-image>"
  nccl: "<version>"
  ofed_or_doca: "<version>"
kubernetes:
  gpu_operator: "<version>"
  lws: "<version>"
  volcano: "<version>"
  rdma_shared_device_plugin: "<version>"
models:
  text:
    path: "/models/<text-model>"
    revision: "<commit>"
    config_sha256: "<sha256>"
    tokenizer_sha256: "<sha256>"
    weights_manifest_sha256: "<sha256>"

Prefill 和 Decode 必须保持 model config、tokenizer、checkpoint revision、量化格式、KV layout 相关参数、LoRA adapter、SGLang 版本与 Mooncake transfer ABI 一致，避免 decode corrupt 一类隐性错误：

sha256sum /models/<model>/config.json
sha256sum /models/<model>/tokenizer.json
find /models/<model> -type f -name '*.safetensors' \
  -exec sha256sum {} \; | sort > weights.sha256
sha256sum weights.sha256

结果写入 Release Manifest。

4. 集群 Pre-flight：未通过不允许部署 Worker

每个节点执行 nvidia-smi、nvidia-smi topo -m、nvidia-smi nvlink -s，确认 GPU 型号与显存一致、NVLink/NVSwitch 正常、GPU↔NIC PCIe/NUMA 拓扑符合设计。建议给节点打拓扑标签，让调度可以按拓扑放置资源。

RDMA 验证分两步：先做基础验证，再做 GPUDirect RDMA 验证，并分别在同机架和跨机架下执行，确认无 registration / peer-memory / GID 错误：

# 节点 A
ib_write_bw -d mlx5_0 -R
# 节点 B（-x gdr 为 GPUDirect 版本）
ib_write_bw -d mlx5_0 -R -x gdr <NODE_A_IP>

RoCE 无损网络由网络团队确认 PFC 只对指定 lossless priority 生效、ECN/WRED 已配置、MTU 端到端一致，并对 ingress/egress drop、PFC pause、ECN marking、buffer occupancy、port utilization 建立告警。

5. RDMA Device Plugin 与 Gang Scheduling

按 NIC / fabric 分资源，不把所有 HCA 混成一个不可控资源池：

data:
  config.json: |
    {
      "configList": [{
        "resourceName": "hca_shared_devices",
        "rdmaHcaMax": 1000,
        "selectors": { "vendors": ["15b3"], "drivers": ["mlx5_core"] }
      }]
    }

LWS 只负责 inference group 生命周期，Gang Scheduling 要独立配置——显式开启 Volcano provider：

helm install lws oci://ghcr.io/kubernetes-sigs/lws-charts/lws \
  -n lws-system --create-namespace \
  --set gangSchedulingManagement.schedulerProvider=volcano

原则：LWS = inference group lifecycle，Volcano = gang scheduling policy。

6. 模型存储与预热

统一挂载 /models，包含模型、VLM 与 LoRA。不要让几十个模型 Pod 同时从对象存储冷启动：Object Storage → Alluxio → Node-local warm cache → SGLang Pod。上线前在目标节点预热权重文件。

7. Mooncake 部署：先从单 Master 联调，再上 HA

POC 阶段允许单 Master + 内嵌 HTTP metadata：

mooncake_master \
  --rpc_address=0.0.0.0 --rpc_port=50051 \
  --enable_http_metadata_server=true \
  --http_metadata_server_host=0.0.0.0 --http_metadata_server_port=8080 \
  --enable_metric_reporting=true --metrics_port=9003

export MOONCAKE_MASTER="mooncake-master.ai-inference.svc:50051"
export MOONCAKE_TE_META_DATA_SERVER="http://mooncake-master.ai-inference.svc:8080/metadata"

注意 50051 是 Master RPC，8080 是 HTTP metadata，不要把 http://...:50051 写进 MOONCAKE_TE_META_DATA_SERVER。

生产环境改为 --enable_ha=true + etcd backend + oplog + Master metrics，并在上线前专门演练 leader kill、etcd 单节点故障、Master 滚动升级、stale metadata 清理与 Worker 重连。

SGLang 侧公共环境变量放进 ConfigMap：

data:
  MOONCAKE_MASTER: "mooncake-master.ai-inference.svc:50051"
  MOONCAKE_TE_META_DATA_SERVER: "http://mooncake-master.ai-inference.svc:8080/metadata"
  MOONCAKE_PROTOCOL: "rdma"
  SGLANG_MOONCAKE_CUSTOM_MEM_POOL: "INTRA_NODE_NVLINK"
  MC_INTRANODE_NVLINK: "true"

8. MoE PD 部署：Prefill 与 Decode 各用各的参数

Prefill 计算密集，默认 --deepep-mode normal，chunked prefill 从 8K / 16K 起逐级压测到 64K，观察 TTFT、prompt tok/s、KV transfer 与 Prefill queue，不追求盲目的最大并发：

sglang serve \
  --model-path "${TEXT_MODEL_PATH}" --port 30000 \
  --disaggregation-mode prefill \
  --disaggregation-transfer-backend mooncake --disaggregation-ib-device mlx5_0 \
  --disaggregation-bootstrap-port 8998 \
  --tp 8 --dp 8 --enable-dp-attention \
  --moe-a2a-backend deepep --deepep-mode normal \
  --chunked-prefill-size 16384 --mem-fraction-static 0.80 --enable-metrics

Decode 显存带宽敏感，默认 --deepep-mode low_latency，用 --max-running-requests 控制并发：

sglang serve \
  --model-path "${TEXT_MODEL_PATH}" --port 30001 \
  --disaggregation-mode decode \
  --disaggregation-transfer-backend mooncake --disaggregation-ib-device mlx5_0 \
  --tp 8 --dp 8 --enable-dp-attention \
  --moe-a2a-backend deepep --deepep-mode low_latency \
  --max-running-requests 128 --mem-fraction-static 0.80 --enable-metrics

HiSparse 只在模型满足当前 SGLang 稀疏注意力支持条件并跑完 correctness + A/B 后才允许启用，不能因为“是 Decode 就默认打开”。

P:D 比例禁止拍脑袋固定为 1:4。正确算法是按线上 Token 分布算容量：P capacity = prompt_tokens/s，D capacity = generation_tokens/s。至少按 Chat（2K in / 1K out）、Code（8K / 2K）、RAG（32K / 1K）、Long Context（128K / 512）四组 workload 建 benchmark，得出每个业务池自己的比例。

9. EPD 多模态部署

EPD = Encoder → Prefill → Decode。Encoder 输出 multimodal embedding，Prefill → Decode 仍走 Mooncake KV transfer。Encoder 用 --encoder-only（按业务做 --enable-mm-global-cache，重复图片比例低时未必有收益），Prefill 用 --language-only --encoder-urls <encoder>，Decode 同 PD 配置。

当前 EPD 应理解为 Encoder Disaggregation + PD Disaggregation。SMG 仍负责 Prefill / Decode 路由，Encoder URL / discovery 由 Prefill language-only 侧维护，不要把它简化成一个未经验证的 --epd-disaggregation 开关。

10. SMG：统一网关

固定版本安装 sglang-router（或固定 digest 的镜像），PD 模式同时注册 prefill 与 decode worker：

smg \
  --pd-disaggregation \
  --prefill http://prefill.ai-inference.svc:30000 8998 \
  --decode http://decode.ai-inference.svc:30001 \
  --prefill-policy cache_aware \
  --decode-policy power_of_two \
  --host 0.0.0.0 --port 8000

多 Worker 时重复 --prefill / --decode 参数即可。SMG 负责对异常 worker 摘流、熔断与负载均衡。

11. LWS 模板与启动 Wrapper

LWS 把多节点推理模型当一个 group 管理：单 Pod crash → 整个 group 视为不健康 → LWS 按 group 策略重建。下面模板展示结构，LWS_WORKER_INDEX、leader DNS 和多节点 rank 注入方式必须按所用 LWS 版本的实际字段验证：

apiVersion: leaderworkerset.x-k8s.io/v1
kind: LeaderWorkerSet
metadata:
  name: text-prefill
  namespace: ai-inference
  annotations:
    scheduling.volcano.sh/queue-name: inference
spec:
  replicas: 1
  leaderWorkerTemplate:
    size: 2
    restartPolicy: RecreateGroupOnPodRestart
    leaderTemplate:
      spec:
        containers:
        - name: sglang
          image: registry.example.com/ai/sglang:v0.5.19
          envFrom:
          - configMapRef:
              name: sglang-mooncake-env
          resources:
            limits:
              nvidia.com/gpu: 8
              rdma/hca_shared_devices: 1
          volumeMounts:
          - name: models
            mountPath: /models
          - name: shm
            mountPath: /dev/shm
          command: ["/bin/bash","-lc"]
          args:
          - |
            exec launch-worker --role prefill --nnodes 2 \
              --node-rank "${LWS_WORKER_INDEX}" \
              --dist-init-addr text-prefill-0:5000 \
              --tp 16 --dp 8
        volumes:
        - name: models
          persistentVolumeClaim:
            claimName: model-pvc
        - name: shm
          emptyDir:
            medium: Memory
            sizeLimit: 64Gi

推荐把启动逻辑收敛到 wrapper，而不是把复杂参数散落在 YAML。wrapper 只接收 MODEL_PATH / ROLE / NODE_RANK / NNODES / DIST_INIT_ADDR / RDMA_DEVICE 等变量，按 role 拼接差异参数后 exec sglang serve ...。这样 YAML 只描述 Desired State，参数按 ConfigMap / Helm values 版本化，Prefill 与 Decode 的差异一目了然。

12. 健康检查

• SGLang：curl -fsS http://<worker>:30000/health
• SMG：curl -fsS http://<smg>:8000/health
• Mooncake Master：nc -vz mooncake-master 50051、curl -fsS http://mooncake-master:9003/metrics/summary
• Metadata：curl -fsS http://mooncake-master:8080/metadata（按当前版本支持的健康方式为准）

13. 上线验收：先对，再快

顺序不能颠倒：

1. Correctness：先跑单体 SGLang baseline，再跑 PD、EPD，对比 deterministic prompt、tokenizer、reasoning / tool call parser、stop token、LoRA、多模态结果和长上下文。性能好但输出错误，一律不上线。
2. KV Transfer：观测 kv_transfer_speed_gb_s、kv_transfer_latency_ms、num_transfer_failed_reqs_total 等指标，按 8K / 32K / 128K 上下文、同机架 / 跨机架分别记录。验收以整体 TTFT / TPOT 对比为准，不把互联宣传数据当 SLO。
3. 服务指标：TTFT / TPOT / E2E 的 P50 / P95 / P99，prompt 与 generation tokens per second、requests per second、queue、cache 命中率。
4. GPU：SM 利用率、HBM 用量与带宽、NVLink / PCIe、XID、ECC。
5. RDMA / Switch：带宽、延迟、retry / RNR / error、PFC pause、ECN / CNP、switch drop 与 buffer occupancy。

阈值全部用 benchmark 校准，不存在跨模型通用的 “单卡 105–130 tok/s” 验收线。

14. 观测与告警

告警结构示例（阈值为占位，必须用 benchmark 校准）：

- alert: SGLangKVTransferFailure
  expr: increase(sglang_num_transfer_failed_reqs_total[5m]) > 0
  for: 2m
  labels: { severity: critical }

- alert: SGLangDecodeQueueHigh
  expr: <decode_queue_metric> > <BENCHMARK_THRESHOLD>
  for: 5m
  labels: { severity: warning }

- alert: MooncakeMasterDown
  expr: up{job="mooncake-master"} == 0
  for: 1m
  labels: { severity: critical }

注意 Prometheus exposition 中指标名含 : 时通常会被改写，上线前以 /metrics 实际名称为准。至少建 6 块 Dashboard：Request SLO、Prefill、Decode、Mooncake、Fabric、GPU。

15. 扩缩容与滚动升级

• Encoder：看 encoder queue、图片 / 视频 QPS、encoder 延迟、cache 命中率。
• Prefill：看 prefill queue、TTFT、prompt tokens/s。
• Decode：看 decode queue、TPOT、generation tokens/s、KV occupancy。

禁止只用 GPU Utilization > 80% 作为扩缩唯一指标；对 LWS 应扩 replica group，而不是随机扩一个 worker Pod。

Worker 升级流程：Gateway 摘流 → Drain → 等待 running request 降为 0 → 删除 inference group → 新镜像启动 → 权重预热 → 健康检查 → 合成请求 → KV transfer 测试 → 加回流量。不要对大 group 无脑使用 Deployment rolling update。

模型升级禁止 P、D 两边不同版本混跑，使用 Blue / Green 整组切换：新版本整组 Ready → Shadow → Canary → 切 Gateway → Drain 旧组。EPD 把 E / P / D 作为兼容版本集合一起管理。

16. 故障 Runbook

RDMA 异常（KV transfer 延迟飙升、TTFT 上升）：检查 ibv_devices、rdma link、ethtool -S、dmesg；随后标记 Worker unhealthy → SMG 熔断 → Drain → 转移流量。RDMA 断开后不会自动、无感地切到 TCP，TCP fallback 要提前维护独立的部署 profile。

Prefill overload（TTFT ↑、queue ↑）：先看是否突发长上下文化，再查 chunked prefill，扩 Prefill group；必要时 Gateway 对超长上下文做 admission control。不要先扩 Decode。

Decode overload（TPOT ↑、KV usage ↑、HBM 接近瓶颈）：扩 Decode pool，检查 max-running-requests、输出长度变化、speculative decode 与 CUDA Graph 覆盖。

Mooncake Master 故障：确认 leader election → etcd health → oplog → Worker 重连。禁止在不确定 metadata 一致性时直接清空状态。

Model hash mismatch（可能表现为输出异常、KV transfer 错误、decode corruption）：sha256sum 核验 config / tokenizer / weight manifest，一旦不一致，把整个异常 P/D group 从 Gateway 下线，不要只重启单个 Pod。

单 Worker Pod 宕机：LWS 管理的是 group——单 Pod crash → group 视为不健康 → Gateway drain / 熔断 → LWS 按 group 重建 → 整体验收 → 重新加流量。不能把多节点模型当普通无状态服务对待。

17. 故障演练与 Benchmark

上线前至少演练：Prefill Pod kill、Decode Pod kill、Mooncake Master kill、RDMA 接口 down、受控拥塞注入、错误权重 revision、128K 长 Prompt 突发、大输出突发、图片突发、GPU 节点重启。

每个版本保存完整证据：image digest、model revision、driver / CUDA / NCCL / Mooncake 版本、NIC 与 switch profile、SGLang / SMG 参数、workload 与结果。Benchmark 矩阵对比 Unified vs PD vs EPD，输入 2K / 8K / 32K / 128K，输出 128 / 512 / 2K / 8K，并发 1 / 8 / 32 / 128 / 512 / saturation，评价 TTFT、TPOT、E2E、Prompt / Generation TPS、SLO 下 goodput、GPU 效率、KV transfer 开销与 Cost/request。

只有 PD / EPD 在真实 workload 下提升 SLO goodput / GPU efficiency / capacity isolation 才值得生产启用。

18. Release Gate 与运维心智模型

上线必须全部通过：镜像 digest 固定、模型 hash 固定、P/D/E 版本一致、GDR benchmark 通过、Mooncake health 通过、DeepEP A2A 通过、correctness eval 通过、8K / 32K / 128K benchmark 完成、TTFT / TPOT SLO 通过、RDMA 与 GPU dashboard 正常、Gateway circuit breaker 验证、LWS group restart 验证、Mooncake failure drill 验证、rollback 演练完成。任意一项失败，不进入生产流量。

不要把这套系统理解成“启动几个 SGLang Pod”，而是要同时看五条链路：

Request Plane → SMG → Encoder / Prefill / Decode
Prefill ── KVCache ──► Decode      （Mooncake）
Worker ── DeepEP ── Expert Parallelism
LWS + Volcano ── 拓扑感知的 GPU / RDMA 放置
Object Storage → Alluxio → Model Cache

生产平台真正要保证五件事：

1. Correctness：分离后结果仍正确。
2. Isolation：Prefill / Decode / Encoder 独立扩缩与故障隔离。
3. Transport：KV / Embedding 在 RDMA fabric 上稳定传输。
4. Scheduling：大模型 inference group 被当作整体正确放置和恢复。
5. Evidence：每次性能下降和故障都能通过 metric、log、trace、benchmark 还原。

相关阅读

• 模型推理服务怎样运行在 Kubernetes：版本、KServe、灰度与回滚
• 机器人训练数据怎样送到 GPU：Kubernetes、JuiceFS 与 Lance 的分工
• AI 数据平台部署前，先看懂一台 Kubernetes 节点
• 从 Docker Compose 到 Kubernetes：AI 数据平台为什么需要统一运行底座

参考资料

• SGLang：PD Disaggregation
• SGLang：EPD Disaggregation
• SGLang：Model Gateway
• Mooncake：KV Cache 为中心的解耦架构
• LeaderWorkerSet：文档与安装