手把手实战教程：用 LeaderWorkerSet 在 Kubernetes 上部署 vLLM 多节点推理服务
【免费下载链接】lwsLeaderWorkerSet: An API for deploying a group of pods as a unit of replication项目地址: https://gitcode.com/gh_mirrors/lws2/lws
你是否遇到过这样的难题：想在 Kubernetes 上跑一个大模型推理服务，模型太大、单张 GPU 装不下，必须把模型切分到多台机器上？本教程将带你用LeaderWorkerSet（LWS）在Kubernetes上快速部署vLLM 多节点推理服务。LeaderWorkerSet 是 Kubernetes 社区专门为 AI/ML 推理负载设计的 API，它把一组 Pod 作为一个整体单元来调度和管理，完美契合 vLLM 的张量并行（Tensor Parallel）与流水线并行（Pipeline Parallel）需求。跟着本教程一步步操作，你也能轻松搞定多节点大模型推理部署。
为什么多节点推理需要 LeaderWorkerSet
大模型的规模远超单卡显存。以 Llama-3.1-405B 为例，即使采用 8 卡张量并行，单节点依然无法承载。vLLM 的分布式推理依赖 Ray 集群：需要一个leader 节点充当 Ray head，多个worker 节点作为 Ray worker。问题在于，原生 Kubernetes 很难保证"这一组 Pod 要么全部调度成功、要么全部不调度"。
LeaderWorkerSet 正是为此而生。它的核心理念是"超级 Pod"：一个 LeaderWorkerSet 由 1 个 leader Pod 和 N 个 worker Pod 组成，它们拥有相同的生命周期，可以并行创建、整体滚动更新，甚至按组整体重启。这是 Kubernetes 上多节点推理部署的最简方案。
环境准备：安装 LeaderWorkerSet 前的必要条件
在开始部署 vLLM 推理服务之前，先确认你的集群满足以下条件：
- Kubernetes 版本 ≥ 1.26，否则会出现不可预期的行为
- 至少 1 个节点拥有 1+ CPU 和 1G 内存，用于运行 LWS 控制器（controller manager）
- 安装好 kubectl 并已连接集群
- 准备好 GPU 节点（本教程以 NVIDIA GPU 为例）
最快安装方法：一条命令装好 LeaderWorkerSet
LeaderWorkerSet 的安装非常简单，使用 kubectl 安装最新发布版本即可：
VERSION=v0.10.0 kubectl apply --server-side -f https://github.com/kubernetes-sigs/lws/releases/download/$VERSION/manifests.yaml等待控制器就绪：
kubectl wait deploy/lws-controller-manager -n lws-system --for=condition=available --timeout=5m如果你偏好 Helm，也可以使用官方 chart 安装（详见 charts/lws/Chart.yaml）。安装完成后，你就可以使用LeaderWorkerSet这个 CRD 了。
理解 LeaderWorkerSet 核心概念：leader、worker 与环境变量
动手写 YAML 之前，先记住 3 个关键概念：
- 双模板：
leaderTemplate定义 leader Pod（跑 Ray head + vLLM API Server），workerTemplate定义 worker Pod（跑 Ray worker） - 组（Group）：
replicas表示组数，size表示每组 Pod 总数 - 注入的环境变量：LWS 会自动注入
LWS_LEADER_ADDRESS（leader 地址）、LWS_GROUP_SIZE（组大小）、LWS_WORKER_INDEX（组内序号），这些正是 vLLM 多节点脚本所需的关键信息（参考 labels-annotations-and-environment-variables.md）
一键部署 vLLM 多节点推理服务的完整步骤
第一步：配置 HuggingFace Token
vLLM 需要从 HuggingFace 拉取模型权重，先导出你的 token：
export HF_TOKEN=<your-hf-token>第二步：部署 LeaderWorkerSet
官方示例文件位于 docs/examples/vllm/GPU/lws.yaml，直接应用即可：
curl https://raw.githubusercontent.com/kubernetes-sigs/lws/refs/heads/main/docs/examples/vllm/GPU/lws.yaml -s | envsubst | kubectl apply -f -这个配置会创建2 组副本，每组包含 2 个 Pod（pipeline_parallel_size=2），每个 Pod 占用 8 张 GPU（tensor_parallel_size=8），即总共 2×16 张 GPU 来运行 Llama-3.1-405B。核心 YAML 逻辑如下（已精简）：
apiVersion: leaderworkerset.x-k8s.io/v1 kind: LeaderWorkerSet metadata: name: vllm spec: replicas: 2 # 2 组副本 leaderWorkerTemplate: size: 2 # 每组 1 个 leader + 1 个 worker restartPolicy: RecreateGroupOnPodRestart leaderTemplate: spec: containers: - name: vllm-leader image: vllm/vllm-openai:v0.8.5 command: - sh - -c - "bash /vllm-workspace/examples/online_serving/multi-node-serving.sh leader --ray_cluster_size=$(LWS_GROUP_SIZE); python3 -m vllm.entrypoints.openai.api_server --port 8080 --model meta-llama/Llama-3.1-405B-Instruct --tensor-parallel-size 8 --pipeline_parallel_size 2" resources: limits: nvidia.com/gpu: "8" workerTemplate: spec: containers: - name: vllm-worker image: vllm/vllm-openai:v0.8.5 command: - sh - -c - "bash /vllm-workspace/examples/online_serving/multi-node-serving.sh worker --ray_address=$(LWS_LEADER_ADDRESS)" resources: limits: nvidia.com/gpu: "8" --- apiVersion: v1 kind: Service metadata: name: vllm-leader spec: ports: - name: http port: 8080 targetPort: 8080 selector: leaderworkerset.sigs.k8s.io/name: vllm role: leader第三步：验证 vLLM Pod 启动状态
查看 Pod 运行情况：
kubectl get pods输出类似如下，说明 leader 和 worker 都已正常运行：
NAME READY STATUS RESTARTS AGE vllm-0 1/1 Running 0 2s vllm-0-1 1/1 Running 0 2s vllm-1 1/1 Running 0 2s vllm-1-1 1/1 Running 0 2s再确认多节点推理是否真正生效，检查模型权重加载日志：
kubectl logs vllm-0 |grep -i "Loading model weights took"如果看到来自不同 Ray worker（不同 IP）的加载日志，说明分布式推理已成功工作。
最快验证方法：用 port-forward 本地测试推理
转发服务端口
kubectl port-forward svc/vllm-leader 8080:8080发送推理请求
打开另一个终端，调用 OpenAI 兼容接口：
curl http://localhost:8080/v1/completions \ -H "Content-Type: application/json" \ -d '{ "model": "meta-llama/Meta-Llama-3.1-405B-Instruct", "prompt": "San Francisco is a", "max_tokens": 7, "temperature": 0 }'返回结果即证明vLLM 多节点推理服务部署成功：
{ "id": "cmpl-1bb34faba88b43f9862cfbfb2200949d", "model": "meta-llama/Meta-Llama-3.1-405B-Instruct", "choices": [ { "index": 0, "text": " top destination for foodies, with", "finish_reason": "length" } ] }进阶玩法：TPU 部署、Gang 调度与滚动更新
TPU 上的 vLLM 部署
如果使用 Google TPU，官方也提供了完整示例 docs/examples/vllm/TPU/lws.yaml，通过nodeSelector选择 TPU v5e 切片，并使用tensor-parallel-size=16的配置。LWS 还会自动注入TPU_WORKER_HOSTNAMES等 TPU 专用环境变量。
Gang 调度：保证同组 Pod 整体调度
对于推理服务，最怕"部分 Pod 调度成功、部分失败"，导致资源碎片和任务卡死。LWS 支持 Gang 调度（all-or-nothing），保证一组 Pod 要么全部调度，要么全部等待：
如上图所示，Pod Webhook 会为 leader 和 worker Pod 绑定同一个 PodGroup，调度器将整个组视为一个整体进行资源分配，避免碎片化调度。
滚动更新与失败恢复
LWS 支持组级滚动更新，升级时整组 Pod 一起替换，而非逐个替换，确保推理服务在更新期间始终可用。同时，restartPolicy: RecreateGroupOnPodRestart意味着组内任意一个 Pod 失败，整组都会被重建，保证分布式状态的一致性。
总结
通过本教程，你已经学会了：
- 使用一条命令安装 LeaderWorkerSet 到 Kubernetes 集群
- 理解 leader/worker 分组调度模型与自动注入的环境变量
- 部署 vLLM 多节点推理服务并验证分布式加载
- 通过 port-forward 测试 OpenAI 兼容推理接口
- 了解 Gang 调度、TPU 部署等进阶能力
LeaderWorkerSet 让"以组为单位"的部署模式从繁琐的手工编排变成了一等公民的 Kubernetes API。无论你是部署 Llama、vLLM 还是其他多节点推理框架，这套方法论都同样适用。感兴趣的话，可以继续阅读仓库中的 leaderworkerset_types.go 源码和 官方文档 深入探索更多高级特性。
【免费下载链接】lwsLeaderWorkerSet: An API for deploying a group of pods as a unit of replication项目地址: https://gitcode.com/gh_mirrors/lws2/lws
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
