vLLM on Kubernetes with KubeRay: Declarative Ray Cluster Deployment for Large-Scale Model Serving【免费下载链接】vllmA high-throughput and memory-efficient inference and serving engine for LLMs项目地址: https://gitcode.com/GitHub_Trending/vl/vllm本文围绕 vLLM 官方文档 KubeRay 集成说明 展开介绍如何用 KubeRay 以 Kubernetes 原生的声明式方式在 Ray 集群上运行 vLLM 工作负载并结合仓库中的 Ray 集成源码、多节点部署文档与示例脚本说明 vLLM 底层如何感知 Ray 集群、环境变量如何在 driver 与 worker 间传播以及集群验证与排障的实操路径。读完后你将掌握KubeRay 相对手工脚本的运维优势、Ray 集群 vLLM 的启动参数组合以及 vLLM 侧 Ray 执行器与配置传播的源码级原理。1. KubeRay 是什么在 vLLM 部署中扮演什么角色KubeRay 提供了一条 Kubernetes 原生的路径用于在 Ray 集群上运行 vLLM 工作负载。其核心思路是Ray 集群本身可以用一段 YAML 声明式地描述出来由 KubeRay Operator 负责后续的 Pod 调度、网络配置、故障重启和蓝绿部署同时保留熟悉的 Kubernetes 使用体验。放到 vLLM 的多节点推理场景里这一层的价值在于vLLM 的多机部署依赖 Ray 作为分布式执行后端详见 docs/serving/parallelism_scaling.md 中 Multi-node deployment 一节。传统做法是逐节点 SSH 进容器、手工拉起ray start而 KubeRay 把「建集群」这件事收敛为一次kubectl apply -f cluster.yaml让 Ray 集群的供给成为 Kubernetes 工作流CI/CD、Secrets、StorageClass 等的一部分。2. 为什么用 KubeRay 而不是手工脚本官方文档 docs/deployment/integrations/kuberay.md 给出了一张核心对比表完整继承如下特性手工脚本KubeRay集群启动Bootstrap手动 SSH 到每台节点执行脚本一条命令创建或更新整个集群kubectl apply -f cluster.yaml自动扩缩容手工操作自动 patch CRD 来调整集群规模升级手工拆掉重建支持蓝/绿部署方式更新声明式配置Bash 参数与环境变量Git-ops 友好的 YAML CRDRayCluster / RayService文档结论是使用 KubeRay 能显著降低运维负担并简化 Ray vLLM 与既有 Kubernetes 工作流CI/CD、secrets、storage classes 等的集成。对照理解仓库中的手工方式为了体会这张对比表的含义可以直接看仓库提供的手工建集群脚本 examples/ray_serving/run_cluster.sh。该脚本的典型用法是# 在一台节点上作为 head 节点启动 bash run_cluster.sh \ vllm/vllm-openai \ HEAD_NODE_IP \ --head \ /path/to/the/huggingface/home/in/this/node \ -e VLLM_HOST_IPHEAD_NODE_IP # 在每台 worker 节点上启动 bash run_cluster.sh \ vllm/vllm-openai \ HEAD_NODE_IP \ --worker \ /path/to/the/huggingface/home/in/this/node \ -e VLLM_HOST_IPWORKER_NODE_IP从脚本实现可以看出「手工方式」的运维特征每台节点需要一个保持打开的 shell 会话来维持容器存活脚本用trap cleanup EXIT在退出时docker stop/rm容器VLLM_HOST_IP必须逐节点手工指定且互不相同集群的扩缩容、重启、升级都依赖人工在这些终端上操作。KubeRay 的 RayCluster CRD 正是把这一套状态收敛为版本化的 YAML由 Operator 持续调和reconcile到期望状态。docs/serving/parallelism_scaling.md 在介绍完上述手工流程后也明确提示可以「Alternatively, set up the Ray cluster using KubeRay」作为替代方案。3. Ray 集群就绪后vLLM 的启动参数组合无论集群由run_cluster.sh还是 KubeRay 拉起一旦 Ray 集群在运行vLLM 的用法与单机完全一致——Ray 集群上的所有 GPU 资源对 vLLM 可见在任一节点执行一条vllm命令即可。按 docs/serving/parallelism_scaling.md 的通用实践# 2 节点 x 8 GPUTP8每节点 GPU 数PP2节点数 vllm serve /path/to/the/model/in/the/container \ --tensor-parallel-size 8 \ --pipeline-parallel-size 2 \ --distributed-executor-backend ray参数选择规则--tensor-parallel-size设为每节点 GPU 数--pipeline-parallel-size设为节点数也可以直接把--tensor-parallel-size设为集群总 GPU 数如 16。--distributed-executor-backend ray显式指定 Ray 执行后端单节点默认是multiprocessing跨节点多机推理默认走 Ray。线上服务化的示例Ray Serve vLLM仓库提供了更完整的在线服务示例examples/ray_serving/ray_serve_deepseek.py使用 Ray Serve 部署 DeepSeek 模型的参考实现展示如何把 vLLM 作为引擎接入 Ray Serve 的高层 API获得生产级容错、自动扩缩与分布式可观测性。examples/ray_serving/elastic_ep/弹性 Expert Parallel 场景的完整示例包含 serve_deepseek_v2.sh 启动脚本、scale.py 扩缩容脚本与 bench.sh 压测脚本与 KubeRay「自动 patch CRD 调整集群规模」的能力形成互补——集群弹性由 KubeRay 负责引擎侧 EP 弹性由 vLLM 支持。4. 源码视角vLLM 如何与 Ray 集群协同4.1 Ray 执行后端的两种实现从 vllm/envs.py 中的环境变量定义可以看到vLLM 在distributed_executor_backendray时存在两条执行路径由VLLM_USE_RAY_V2_EXECUTOR_BACKEND默认1控制为1时走RayExecutorV2基于消息队列 MQ 的执行器为0时走RayDistributedExecutor基于 Ray Compiled Graph 的后端。另有VLLM_USE_RAY_COMPILED_DAG_OVERLAP_COMMvllm/envs.py 附近控制是否利用 Ray Compiled DAG 做通信重叠VLLM_USE_RAY_WRAPPED_PP_COMM控制 PP 通信器是走 vLLM 自有的 pipeline 通信包装还是 Ray 的 NCCL 通信器。这些开关在 KubeRay 场景中通常在 Ray 工作节点容器内生效调优多节点 PP/TP 通信行为时可参考。4.2 环境变量从 driver 到 Ray worker 的传播多节点部署中最常见的「配置不生效」问题根源在于 driver 进程的环境变量没有传播到各节点的 Ray actor。vLLM 用 vllm/ray/ray_env.py 集中解决这一问题默认按前缀传播VLLM_、FLASH_ATTENTION_、LMCACHE_、NCCL_、UCX_、HF_、HUGGING_FACE_vllm/ray/ray_env.py加上PYTHONHASHSEED这类单点变量用户可通过VLLM_RAY_EXTRA_ENV_VAR_PREFIXES_TO_COPY前缀和VLLM_RAY_EXTRA_ENV_VARS_TO_COPY单个变量名均为逗号分隔做增量补充而不是替换默认集可通过配置文件ray_non_carry_over_env_vars.json位于VLLM_CONFIG_ROOT下显式拉黑某些变量防止其被复制到 workervllm/ray/ray_env.py。这一点在 KubeRay 场景尤其重要YAML CRD 中为 head 容器设置的VLLM_*、NCCL_*等环境变量只有经过这套机制传播才会在 worker 节点的推理进程里生效。4.3 Ray 运行态探测vllm/ray/lazy_utils.py 提供is_ray_initialized()与is_in_ray_actor()两个轻量探测函数前者判断 Ray 是否已初始化后者进一步检查当前进程是否运行在 Ray actor 内部。vLLM 通过这类判断在 driver 进程与 worker actor 进程之间走不同的初始化分支——这解释了为什么「在 head 节点容器里执行一条vllm serve」就能透明地驱动整个 KubeRay 集群上的多机推理。5. 集群验证与排障5.1 验证集群规模建好集群后无论手工脚本还是 KubeRay在任一节点进入容器执行ray status ray list nodes确认节点数与 GPU 数符合预期后再启动 vLLM。docs/serving/parallelism_scaling.md 同时给出性能验证手段启动后观察日志中的GPU KV cache size与Maximum concurrency两行判断 KV cache 容量是否满足吞吐目标不足则加 GPU/节点。5.2 常见排障入口多节点 GPU 排障docs/serving/distributed_troubleshooting.md 覆盖了多节点 GPU 部署的常见故障定位思路并建议对照官方 KubeRay 多节点 GPU troubleshooting 指南在 Ray 官方文档中查阅。网络路径验证用NCCL_DEBUGTRACE vllm serve ...启动确认跨节点通信走NET/IB/GDRDMA而非NET/Socket避免 tensor parallel 退化为 TCP 通信详见 docs/serving/parallelism_scaling.md 中 Optimizing network communication for tensor parallelism 与 Enabling GPUDirect RDMA 两节。Kubernetes 层配置vLLM 的 Kubernetes 部署总入口见 docs/deployment/k8s.md其中将 KubeRay 列为集成方案之一对外暴露服务时的 Nginx 网关配置可参考 docs/deployment/nginx.md。5.3 安全与运行前提沿用 docs/serving/parallelism_scaling.md 中的通用安全提示VLLM_HOST_IP一类节点间地址应落在私有网段因为节点间流量未加密不可信方不应能触达该网络。另外注意 Ray 是 vLLM 的可选依赖使用 Ray 后端前需显式安装如pip install ray[cgraph]官方容器镜像vllm/vllm-openai已内置。6. 小结定位KubeRay 是 vLLM 多节点部署中「Ray 集群供给层」的声明式方案用 YAML CRDRayCluster/RayService取代逐节点 SSH 手工脚本获得自动扩缩容与蓝绿升级能力docs/deployment/integrations/kuberay.md。协同关系KubeRay 负责集群生命周期vLLM 负责集群内的分布式推理——vllm serve --distributed-executor-backend ray --tensor-parallel-size 每节点GPU数 --pipeline-parallel-size 节点数即可透明利用全部节点资源docs/serving/parallelism_scaling.md。源码支撑执行器版本切换VLLM_USE_RAY_V2_EXECUTOR_BACKENDvllm/envs.py、driver→worker 的环境变量传播vllm/ray/ray_env.py、Ray actor 运行态探测vllm/ray/lazy_utils.py是理解 vLLM 与 Ray 协同的三个关键入口。延伸实践在线服务化参考 examples/ray_serving/ray_serve_deepseek.py弹性 EP 场景参考 examples/ray_serving/elastic_ep/排障参考 docs/serving/distributed_troubleshooting.md。【免费下载链接】vllmA high-throughput and memory-efficient inference and serving engine for LLMs项目地址: https://gitcode.com/GitHub_Trending/vl/vllm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考