手把手实战教程：用 LeaderWorkerSet 在 Kubernetes 上部署 vLLM 多节点推理服务

手把手实战教程用 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 装不下必须把模型切分到多台机器上本教程将带你用LeaderWorkerSetLWS在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 为例最快安装方法一条命令装好 LeaderWorkerSetLeaderWorkerSet 的安装非常简单使用 kubectl 安装最新发布版本即可VERSIONv0.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 --forconditionavailable --timeout5m如果你偏好 Helm也可以使用官方 chart 安装详见 charts/lws/Chart.yaml。安装完成后你就可以使用LeaderWorkerSet这个 CRD 了。理解 LeaderWorkerSet 核心概念leader、worker 与环境变量动手写 YAML 之前先记住 3 个关键概念双模板leaderTemplate定义 leader Pod跑 Ray head vLLM API ServerworkerTemplate定义 worker Pod跑 Ray worker组Groupreplicas表示组数size表示每组 Pod 总数注入的环境变量LWS 会自动注入LWS_LEADER_ADDRESSleader 地址、LWS_GROUP_SIZE组大小、LWS_WORKER_INDEX组内序号这些正是 vLLM 多节点脚本所需的关键信息参考 labels-annotations-and-environment-variables.md一键部署 vLLM 多节点推理服务的完整步骤第一步配置 HuggingFace TokenvLLM 需要从 HuggingFace 拉取模型权重先导出你的 tokenexport HF_TOKENyour-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 个 Podpipeline_parallel_size2每个 Pod 占用 8 张 GPUtensor_parallel_size8即总共 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-size16的配置。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），仅供参考