使用 llm-d 跨节点部署 vLLM 服务

概述

当一个模型实例需要来自多个 Kubernetes 节点的 GPU 时,请使用此模式。此示例在两个节点上创建一个逻辑 vLLM 服务,每个节点配备四个 GPU:

LLMInferenceService replicas=1
└── LeaderWorkerSet group
    ├── leader: 4 GPUs, node rank 0, OpenAI-compatible API
    └── worker: 4 GPUs, node rank 1, headless

tensor parallel = 4
pipeline parallel = 2
total GPUs = 4 x 2 = 8

各组件承担不同的职责:

  • LLMInferenceService 描述逻辑服务以及其 leader 和 worker Pod 规范。
  • LeaderWorkerSet (LWS) 将 leader 和 worker 作为一个组创建和管理。
  • vLLM 多进程和 NCCL 在多个 GPU 之间执行张量并行和流水线并行。
  • llm-d 路由组件(包括推理调度器/EPP)将请求路由到可用的后端组。它们不会实现模型并行,也不会自行组合 GPU。
WARNING

不要将此拓扑替换为请求八个 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 是否已安装:

kubectl api-resources | grep -E 'LLMInferenceService|LeaderWorkerSet'

准备清单

下载或复制 双节点、每节点四 GPU 的模板。

应用之前,请替换以下值:

占位符替换为
your-namespace服务和模型 PVC 所在的命名空间
your-registry/vllm-openai:your-tag已针对模型和 GPU 架构验证的运行时镜像;生产环境中请使用不可变的摘要
pvc://your-model-pvc/path/to/model共享模型 URI,或集群使用的存储 URI
distributed-model通过 OpenAI 兼容 API 暴露的名称
--max-model-len 131072适合可用 KV 缓存和预期并发量的上下文限制
nvidia.com/gpu集群使用的 GPU 资源键

模板使用标准的 nvidia.com/gpu 资源。如果集群使用 HAMi,请将其替换为现有正常运行的 Pod 所用的 HAMi 资源约定, 例如 nvidia.com/gpualloc、nvidia.com/gpucores 和 nvidia.com/gpumem。HAMi 仍会在单个节点上独立评估每个 Pod。

只有在确认确切的运行时镜像后,才添加特定于模型的标志。示例 包括量化、Expert Parallel、工具调用解析器、推理解析器和 硬件专用的 attention 后端。首次启动时请禁用推测解码,避免将其与多节点故障排查混为一谈。

理解并行度字段

Kubernetes 和 vLLM 设置必须保持一致:

层级设置示例值
逻辑服务spec.replicas1
LLMInferenceServicespec.parallelism.tensor4
LLMInferenceServicespec.parallelism.pipeline2
Leader vLLM--tensor-parallel-size4
Leader vLLM--pipeline-parallel-size2
Worker vLLM--tensor-parallel-size4
Worker vLLM--pipeline-parallel-size2
两个 vLLM Pod--nnodes2

Leader 使用其 Pod IP 作为 --master-addr。LWS 会将 LWS_LEADER_ADDRESS 注入 Worker;Worker 使用该地址加入同一个 TCPStore 和 NCCL 进程组。Worker 使用 --headless 运行;只有 Leader 会暴露推理 API。

应用服务

应用清单:

kubectl apply -f llm-d-multi-node-vllm-2x4.yaml

在应用更新后的 Pod 模板前,无需删除现有的 LLMInferenceService。KServe 和 LWS 会协调生成的工作负载。

监视逻辑服务及其 Pod:

watch -n 5 'kubectl -n your-namespace get llminferenceservice vllm-multinode; kubectl -n your-namespace get pods -o wide | grep -E "NAME|vllm-multinode"'

预期结果是一个 leader Pod 和一个 worker Pod,且二者位于不同节点上。只有在两个节点都加入分布式引擎且 OpenAI 兼容 API 启动后,leader 才会变为 Ready。

使用真实推理请求进行验证

Ready=True 和 /health 是必要条件,但无法证明请求能够通过所有流水线阶段。将端口转发到 leader Pod:

kubectl -n your-namespace port-forward pod/vllm-multinode-kserve-mn-0 8000:8000

在另一个终端中,发送真实请求:

curl -sS http://127.0.0.1:8000/v1/chat/completions -H 'Content-Type: application/json' -d '{"model":"distributed-model","stream":false,"messages":[{"role":"user","content":"Reply with: multi-node inference succeeded"}],"temperature":0,"max_tokens":64}'

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 的调度或路由进行基准测试。

WARNING

截至 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 安装会查找预设配置。出现类似以下内容的调和事件,表示引用的预设不存在:

failed to get LLMInferenceServiceConfig
"kserve-config-llm-worker-pipeline-parallel" not found

请使用集群中已安装的确切名称和 API 版本创建预设。提供的模板包含一个空的命名空间级 overlay,因为它提供了完整的 leader 和 worker Pod 规范。不要猜测 API 版本;请先进行验证:

kubectl get crd llminferenceserviceconfigs.serving.kserve.io -o jsonpath='{.spec.versions[*].name}'

对于提供 v1alpha2 的 AML 版本,请使用 serving.kserve.io/v1alpha2。出现 no matches for kind 错误表示该清单使用了该集群未提供的 API 版本。

Worker Pod 处于 Pending 状态

请检查调度器事件,而不要仅依赖 nvidia-smi:

kubectl -n your-namespace describe pod <worker-pod> | tail -n 30

常见原因包括:

  • 根据 HAMi 判断,可分配的 GPU 数量或 GPU 内存不足;
  • CPU 或系统内存不足;
  • 节点选择器、污点、亲和性或拓扑规则导致无法调度;
  • 模型 PVC 无法挂载到选定的节点。

nvidia-smi 显示的物理可用内存不等同于调度器可见的容量。请检查资源请求、HAMi 分配注解,以及节点上已经占用 GPU 的所有 Pod。

Ranks 加入后报告 TCPStore 或 NCCL Broken Pipe

TCPStore Broken pipe、NCCL 心跳警告以及日志末尾的进程终止,通常是在某个 rank 已经退出后产生的次要错误。请在两个 Pod 中查找最早出现的引擎或 worker 异常:

kubectl -n your-namespace logs <pod> -p --all-containers --prefix | grep -m1 -A40 -E 'Traceback|ValueError|RuntimeError|ERROR'

典型的主要原因包括:不受支持的 attention backend、不支持该 GPU 架构的运行时镜像、模型加载失败,或模型默认最大序列长度所需的 KV cache 不足。

默认上下文长度超出可用容量

vLLM 会检查可用的 KV cache 是否至少能够容纳一个长度为 max_model_len 的请求。如果启动时报告了所需和可用的 KV cache 大小,请将 --max-model-len 设置为低于估算最大值的值,并为并发和内存变化保留运行余量。增大 --gpu-memory-utilization 仅在确实有额外 GPU 内存可用时才可能有所帮助;它无法修复不兼容的内核或运行时。

相关文档