使用 llm-d 跨节点部署 vLLM 服务
目录
概述先决条件准备清单理解并行度字段应用服务使用真实推理请求进行验证已验证示例:A100 上的 GLM-5.2故障排除缺少 LLMInferenceServiceConfigWorker Pod 处于 Pending 状态Ranks 加入后报告 TCPStore 或 NCCL Broken Pipe默认上下文长度超出可用容量相关文档概述
当一个模型实例需要来自多个 Kubernetes 节点的 GPU 时,请使用此模式。此示例在两个节点上创建一个逻辑 vLLM 服务,每个节点配备四个 GPU:
各组件承担不同的职责:
LLMInferenceService描述逻辑服务以及其 leader 和 worker Pod 规范。- LeaderWorkerSet (LWS) 将 leader 和 worker 作为一个组创建和管理。
- vLLM 多进程和 NCCL 在多个 GPU 之间执行张量并行和流水线并行。
- llm-d 路由组件(包括推理调度器/EPP)将请求路由到可用的后端组。它们不会实现模型并行,也不会自行组合 GPU。
不要将此拓扑替换为请求八个 GPU 的单个 Pod。Kubernetes 和 GPU 调度器会将 Pod 分配到一个节点上;不同节点上的空闲 GPU 无法组合到一个 Pod 中。此外,replicas: 2 会创建两个独立的 leader/worker 组。它不会将两个四 GPU 副本转换为一个八 GPU 模型实例。
先决条件
部署之前,请确认以下所有条件:
- 已安装 Alauda AI Platform Inference Management 和 Alauda Build of LeaderWorkerSet。
- 集群具有两个可调度的 GPU 节点,且每个节点至少有四个可分配的 GPU。
- 两个节点运行兼容的 GPU 驱动程序、CUDA、NCCL 和 RDMA 软件。
- 运行时镜像支持此处使用的模型、GPU 架构、量化格式、attention 后端和 vLLM 多节点命令行参数。
- 两个 Pod 都可以读取完全相同的模型文件。可以使用 RWX PVC、两个节点都能拉取的 OCI ModelCar,或内容完全相同的独立节点本地副本。
- 网络策略和主机网络允许在端口
29501上进行 TCPStore rendezvous,并允许使用 NCCL 动态选择的端口。低性能以太网可能使服务能够运行,但不适合生产环境。 - CPU 和内存请求能够在两个 GPU 节点上满足。仅有 GPU 容量不足以完成调度。
检查所需的 API 是否已安装:
准备清单
下载或复制 双节点、每节点四 GPU 的模板。
应用之前,请替换以下值:
模板使用标准的 nvidia.com/gpu 资源。如果集群使用
HAMi,请将其替换为现有正常运行的 Pod 所用的 HAMi 资源约定,
例如 nvidia.com/gpualloc、nvidia.com/gpucores 和
nvidia.com/gpumem。HAMi 仍会在单个节点上独立评估每个 Pod。
只有在确认确切的运行时镜像后,才添加特定于模型的标志。示例 包括量化、Expert Parallel、工具调用解析器、推理解析器和 硬件专用的 attention 后端。首次启动时请禁用推测解码,避免将其与多节点故障排查混为一谈。
理解并行度字段
Kubernetes 和 vLLM 设置必须保持一致:
Leader 使用其 Pod IP 作为 --master-addr。LWS 会将
LWS_LEADER_ADDRESS 注入 Worker;Worker 使用该地址加入同一个
TCPStore 和 NCCL 进程组。Worker 使用 --headless 运行;只有
Leader 会暴露推理 API。
应用服务
应用清单:
在应用更新后的 Pod 模板前,无需删除现有的 LLMInferenceService。KServe 和 LWS 会协调生成的工作负载。
监视逻辑服务及其 Pod:
预期结果是一个 leader Pod 和一个 worker Pod,且二者位于不同节点上。只有在两个节点都加入分布式引擎且 OpenAI 兼容 API 启动后,leader 才会变为 Ready。
使用真实推理请求进行验证
Ready=True 和 /health 是必要条件,但无法证明请求能够通过所有流水线阶段。将端口转发到 leader Pod:
在另一个终端中,发送真实请求:
HTTP 200 响应并包含生成内容,即可确认基本的端到端请求。在投入生产前,还应验证具有代表性的长上下文、并发请求、多轮对话、工具调用、Pod 重启,以及延迟和吞吐量。
已验证示例:A100 上的 GLM-5.2
此部署模式已在 AML 2.7 上使用 QuantTrio/GLM-5.2-Int4-Int8Mix 完成验证:
- 两个节点,每个节点配备四块 NVIDIA A100 80 GB GPU;
- 张量并行度为 4,流水线并行度为 2;
- 启用 Expert Parallel,禁用推测解码;
- 一个真实的
/v1/chat/completions请求成功完成,并返回 HTTP 200。
该部署使用了客户内部的 vLLM 镜像,该镜像基于 vLLM PR #47629 提出的 SM80 稀疏 MLA 实现构建。在使用一个后端组的情况下,此结果验证了 LLMInferenceService、LWS、vLLM 和 NCCL 的多节点执行能力,但未对 llm-d 的调度或路由进行基准测试。
截至 2026 年 8 月 10 日,PR #47629 尚未合并到官方 vLLM 版本中。公开的 vLLM 镜像不提供 GLM-5.2 在 A100 上所需的 SM80 稀疏 MLA 后端。对模型进行量化可以减少权重内存占用,但无法消除这项运行时要求。模型卡中公布的 vLLM 验证使用的是八块 H200 GPU,而非 A100 GPU。
该客户镜像未公开提供。其他 A100 部署必须基于固定的 PR 提交自行构建并验证镜像。此结果仅验证了基本的多节点推理能力,不代表已验证长上下文、并发、性能、工具调用或生产稳定性。
故障排除
缺少 LLMInferenceServiceConfig
当 spec.worker 和
spec.parallelism.pipeline 同时存在时,某些 KServe 安装会查找预设配置。出现类似以下内容的调和事件,表示引用的预设不存在:
请使用集群中已安装的确切名称和 API 版本创建预设。提供的模板包含一个空的命名空间级 overlay,因为它提供了完整的 leader 和 worker Pod 规范。不要猜测 API 版本;请先进行验证:
对于提供 v1alpha2 的 AML 版本,请使用
serving.kserve.io/v1alpha2。出现 no matches for kind 错误表示该清单使用了该集群未提供的 API 版本。
Worker Pod 处于 Pending 状态
请检查调度器事件,而不要仅依赖 nvidia-smi:
常见原因包括:
- 根据 HAMi 判断,可分配的 GPU 数量或 GPU 内存不足;
- CPU 或系统内存不足;
- 节点选择器、污点、亲和性或拓扑规则导致无法调度;
- 模型 PVC 无法挂载到选定的节点。
nvidia-smi 显示的物理可用内存不等同于调度器可见的容量。请检查资源请求、HAMi 分配注解,以及节点上已经占用 GPU 的所有 Pod。
Ranks 加入后报告 TCPStore 或 NCCL Broken Pipe
TCPStore Broken pipe、NCCL 心跳警告以及日志末尾的进程终止,通常是在某个 rank 已经退出后产生的次要错误。请在两个 Pod 中查找最早出现的引擎或 worker 异常:
典型的主要原因包括:不受支持的 attention backend、不支持该 GPU 架构的运行时镜像、模型加载失败,或模型默认最大序列长度所需的 KV cache 不足。
默认上下文长度超出可用容量
vLLM 会检查可用的 KV cache 是否至少能够容纳一个长度为 max_model_len 的请求。如果启动时报告了所需和可用的 KV cache 大小,请将 --max-model-len 设置为低于估算最大值的值,并为并发和内存变化保留运行余量。增大 --gpu-memory-utilization 仅在确实有额外 GPU 内存可用时才可能有所帮助;它无法修复不兼容的内核或运行时。