零基础手把手教你在K8s部署SGLang推理服务-开发者社区

零基础手把手教你在K8s部署SGLang推理服务

1. 引言

随着大语言模型（LLM）在各类业务场景中的广泛应用，如何高效、稳定地部署推理服务成为工程落地的关键挑战。传统单体式部署方式在面对高并发、长上下文和多轮对话等复杂场景时，往往面临显存瓶颈、吞吐量低、延迟高等问题。

SGLang（Structured Generation Language）作为一个专为LLM推理优化的高性能框架，通过RadixAttention、结构化输出和前后端分离设计，在提升推理效率方面表现出色。结合RoleBasedGroup（RBG）与Mooncake，可以构建一个具备分布式KVCache管理能力的生产级推理系统。

本文将从零开始，手把手教你如何在Kubernetes环境中部署基于SGLang的PD分离架构推理服务，并集成Mooncake作为外置缓存层，实现高吞吐、低延迟的稳定服务。

2. SGLang核心特性解析

2.1 SGLang是什么？

SGLang全称Structured Generation Language（结构化生成语言），是一个专注于大模型推理优化的开源框架。其主要目标是解决以下痛点：

提升GPU/CPU资源利用率
减少重复计算，提高缓存命中率
支持复杂LLM程序逻辑（如任务规划、API调用、JSON格式生成）
简化开发流程，降低使用门槛

2.2 核心技术亮点

RadixAttention（基数注意力）

SGLang采用Radix Tree（基数树）来组织KV缓存，允许多个请求共享已计算的部分。尤其在多轮对话场景中，用户历史上下文可被高效复用，显著提升缓存命中率（实测可达3~5倍），从而降低首Token延迟（TTFT）。

结构化输出支持

通过正则表达式约束解码过程，SGLang可以直接生成指定格式的输出（如JSON、XML、YAML），无需后处理校验，极大提升了API接口的可靠性与性能。

前后端分离架构

SGLang采用DSL（领域特定语言）作为前端编程接口，简化复杂逻辑编写；后端运行时专注于调度优化与多GPU协同，实现“写得简单，跑得快”的设计理念。

3. 整体部署架构设计

3.1 架构组成

本方案基于RBG（RoleBasedGroup）实现多角色协同编排，整体包含以下核心组件：

SGLang Router：统一入口，负责请求路由与负载均衡
Prefill Backend：处理Prompt前向传播，生成初始KVCache
Decode Backend：执行自回归生成，依赖KVCache进行高效推理
Mooncake Master/Store：分布式KVCache存储引擎，提供L3级缓存能力

这些角色通过RBG统一管理，形成一个拓扑感知、状态一致的有机整体。

3.2 为什么需要RBG？

传统的Kubernetes原生Workload（如Deployment）难以满足大模型推理对以下特性的需求：

挑战	RBG解决方案
多角色强依赖	定义角色间比例关系与启动顺序
升级导致缓存丢失	支持原地升级（Inplace Update），保留本地状态
拓扑敏感性	拓扑感知调度，避免NVLink/RDMA跨节点通信
扩缩容不一致	成组伸缩，保持Prefill:Decode比例

RBG将“角色”作为调度单元，提供了Stable、Coordination、Orchestration、Performance、Extensible五大核心能力，真正实现了面向LLM推理的云原生编排。

4. 环境准备与镜像配置

4.1 前置条件

确保你已具备以下环境：

Kubernetes集群（v1.25+）
kubectl命令行工具
集群内可用GPU节点（用于Prefill/Decode）
共享内存或NVMe磁盘（用于Mooncake持久化）
Helm（可选，用于RBG安装）

4.2 镜像准备

本文使用的镜像信息如下：

镜像名称: lmsysorg/sglang:v0.5.6 描述: 包含SGLang v0.5.6及Mooncake transfer-engine >= 0.3.7 用途: Prefill、Decode、Router角色共用

该镜像已预装SGLang及其依赖库，包括Mooncake客户端组件，可直接用于部署。

注意：若需定制化构建，请参考官方Dockerfile： https://github.com/sgl-project/rbg/blob/main/examples/mooncake/Dockerfile.mooncake

5. 部署RBG控制器

5.1 安装RBG CRD与控制器

RBG以Custom Resource Definition（CRD）形式提供，需先部署到集群中：

kubectl apply -f https://raw.githubusercontent.com/sgl-project/rbg/main/config/crd/bases/workloads.x-k8s.io_rolebasedgroups.yaml kubectl apply -f https://raw.githubusercontent.com/sgl-project/rbg/main/config/crd/bases/workloads.x-k8s.io_rbgcontrollers.yaml

然后部署控制器：

kubectl create ns rbg-system helm repo add rbg https://sgl-project.github.io/rbg helm install rbg-controller rbg/rbg-controller -n rbg-system

验证安装结果：

kubectl get pods -n rbg-system # 输出应包含 rbg-controller-manager-* 实例

6. 部署SGLang + Mooncake服务

6.1 编写RBG部署YAML

创建文件sglang-pd-with-mooncake.yaml，内容如下：

apiVersion: workloads.x-k8s.io/v1alpha1 kind: RoleBasedGroup metadata: name: sglang-pd-with-mooncake-demo spec: roles: - name: router replicas: 1 template: spec: containers: - name: router image: lmsysorg/sglang:v0.5.6 command: ["python3", "-m", "sglang.launch_server"] args: - --model-path - /models/Qwen3-235B - --host - 0.0.0.0 - --port - "30000" - --enable-hierarchical-cache - --hicache-storage-backend - mooncake ports: - containerPort: 30000 env: - name: MOONCAKE_METADATA_ENDPOINT value: "sglang-pd-with-mooncake-demo-mooncake-master-0:9080" - name: prefill replicas: 2 template: spec: containers: - name: prefill image: lmsysorg/sglang:v0.5.6 command: ["python3", "-m", "sglang.launch_server"] args: - --model-path - /models/Qwen3-235B - --host - 0.0.0.0 - --port - "30000" - --chunked-prefill-size - "4096" - --enable-hierarchical-cache - --hicache-storage-backend - mooncake ports: - containerPort: 30000 resources: limits: nvidia.com/gpu: 1 env: - name: MOONCAKE_METADATA_ENDPOINT value: "sglang-pd-with-mooncake-demo-mooncake-master-0:9080" - name: decode replicas: 1 template: spec: containers: - name: decode image: lmsysorg/sglang:v0.5.6 command: ["python3", "-m", "sglang.launch_server"] args: - --model-path - /models/Qwen3-235B - --host - 0.0.0.0 - --port - "30000" - --enable-hierarchical-cache - --hicache-storage-backend - mooncake ports: - containerPort: 30000 resources: limits: nvidia.com/gpu: 1 env: - name: MOONCAKE_METADATA_ENDPOINT value: "sglang-pd-with-mooncake-demo-mooncake-master-0:9080" - name: mooncake-master replicas: 1 template: spec: containers: - name: master image: lmsysorg/sglang:v0.5.6 command: ["mooncake_master"] args: - "--http_metadata_server_port=9080" ports: - containerPort: 9080 - name: mooncake-store replicas: 3 template: spec: containers: - name: store image: lmsysorg/sglang:v0.5.6 command: ["python3", "-m", "mooncake.mooncake_store_service"] args: - "--config=/etc/mooncake/config.json" volumeMounts: - name: config-volume mountPath: /etc/mooncake env: - name: MOONCAKE_MASTER_ENDPOINT value: "sglang-pd-with-mooncake-demo-mooncake-master-0:9080" volumes: - name: config-volume configMap: name: mooncake-store-config

同时创建ConfigMap用于Mooncake Store配置：

apiVersion: v1 kind: ConfigMap metadata: name: mooncake-store-config data: config.json: | { "memory_pool_size_mb": 8192, "rdma_device_name": "", "use_shared_memory": true, "sharding_strategy": "round_robin" }

应用配置：

kubectl apply -f mooncake-store-config.yaml kubectl apply -f sglang-pd-with-mooncake.yaml

7. 验证部署状态

7.1 查看Pod状态

kubectl get pods -l rolebasedgroup.workloads.x-k8s.io/name=sglang-pd-with-mooncake-demo

预期输出：

NAME READY STATUS RESTARTS AGE sglang-pd-with-mooncake-demo-router-0 1/1 Running 0 2m sglang-pd-with-mooncake-demo-prefill-0 1/1 Running 0 2m sglang-pd-with-mooncake-demo-decode-0 1/1 Running 0 2m sglang-pd-with-mooncake-demo-mooncake-master-0 1/1 Running 0 2m sglang-pd-with-mooncake-demo-mooncake-store-bh9xs 1/1 Running 0 2m ...

所有Pod应处于Running状态且READY为1/1。

7.2 检查网络与拓扑信息

查看某个Store实例的位置：

kubectl get pod sglang-pd-with-mooncake-demo-mooncake-store-bh9xs -o jsonpath='{.spec.nodeName}' kubectl get pod sglang-pd-with-mooncake-demo-mooncake-store-bh9xs -o jsonpath='{.status.podIP}'

确认其调度到具备本地存储能力的节点上。

8. 性能测试与效果验证

8.1 测试方法说明

使用SGLang自带的多轮对话压测工具进行Benchmark：

python3 benchmark/hicache/bench_multiturn.py \ --model-path /models/Qwen3-235B \ --dataset-path ShareGPT_V3_unfiltered_cleaned_split.json \ --output-length 1 \ --request-length 2048 \ --num-clients 150 \ --request-rate 16 \ --enable-round-barrier

对比三种模式下的性能表现：

缓存层级	平均TTFT(s)	P90延迟(s)	Input Token吞吐(token/s)
GPU Only	5.91	12.16	6576.85
L2 DRAM	3.77	10.88	10054.21
L3 Mooncake	2.58	6.97	15022.80

可见，引入Mooncake后TTFT下降56.3%，吞吐提升128%。

9. 实现平滑升级：原地更新Mooncake版本

9.1 升级背景

当SGLang主镜像升级至v0.5.6时，需同步更新Mooncake组件以保证transfer-engine协议兼容。

传统滚动升级会导致Pod重建，缓存丢失，引发Prefill重算，造成P99延迟毛刺。

9.2 使用RBG实现原地升级

执行patch操作，仅替换镜像而不重建Pod：

kubectl patch rolebasedgroup sglang-pd-with-mooncake-demo \ --type='json' \ -p='[{"op": "replace", "path": "/spec/roles/4/template/spec/containers/0/image", "value": "lmsysorg/sglang:v0.5.6"}]'

观察Pod状态变化：

kubectl get pods -l rolebasedgroup.workloads.x-k8s.io/name=sglang-pd-with-mooncake-demo

你会发现mooncake-store-*Pod的RESTARTS增加1次，但IP和Node未改变，说明实现了原地重启。

通过kubectl describe可确认事件日志中出现：

Container store definition changed, will be restarted

这正是RBG触发的原地更新机制。

10. 最佳实践与避坑指南

10.1 关键配置建议

Prefill:Decode比例：根据业务负载调整，一般设置为2:1~4:1
Mooncake内存池大小：建议不低于8GB per Store实例
启用共享内存：use_shared_memory: true可加速本地恢复
拓扑亲和性：Prefill与Decode尽量同节点部署，减少通信开销

10.2 常见问题排查

问题现象	可能原因	解决方案
Router无法连接Master	网络策略阻断	开放9080端口，检查Service暴露
Decode阶段延迟高	KVCache未命中	检查RadixAttention是否启用
升级后服务中断	transfer-engine版本不匹配	统一镜像版本，确保协议一致
Store启动失败	配置文件路径错误	确认ConfigMap挂载路径正确

11. 总结

本文详细介绍了如何从零开始在Kubernetes环境中部署SGLang推理服务，并集成Mooncake作为分布式KVCache层。我们完成了以下关键步骤：

理解SGLang的核心优势与适用场景
设计基于RBG的多角色协同架构
准备镜像并部署完整服务栈
验证服务状态与网络连通性
进行性能压测，验证分级缓存收益
利用RBG原地升级能力实现无感版本迭代

通过RBG + SGLang + Mooncake的组合，不仅可以突破单机显存限制，还能实现高达5倍的缓存命中率提升和超过50%的TTFT降低，真正构建出稳定、高效、可运维的生产级大模型推理平台。

未来，随着更多角色（如LoRA Manager、Tokenizer Pool）的加入，RBG将进一步扩展其编排能力，推动大模型服务向更智能、更弹性的方向演进。

获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。

零基础手把手教你在K8s部署SGLang推理服务