llm-d 使用指南:在 Kubernetes 上部署智能路由的大模型推理服务

举报
jarin 发表于 2026/11/11 09:52:43 2026/11/11
【摘要】 llm-d 使用指南:在 Kubernetes 上部署智能路由的大模型推理服务把 vLLM 部署到 Kubernetes,并启动多个副本,并不意味着已经获得高效的分布式推理服务。大模型请求的输入长度、生成时间和缓存复用机会差异很大。简单轮询可能把请求送到繁忙实例,也可能让具有相同上下文的请求不断切换副本,重复计算已经处理过的内容。llm-d 要解决的,就是从“模型能够运行”到“推理集群能够...

llm-d 使用指南:在 Kubernetes 上部署智能路由的大模型推理服务

把 vLLM 部署到 Kubernetes,并启动多个副本,并不意味着已经获得高效的分布式推理服务。

大模型请求的输入长度、生成时间和缓存复用机会差异很大。简单轮询可能把请求送到繁忙实例,也可能让具有相同上下文的请求不断切换副本,重复计算已经处理过的内容。

llm-d 要解决的,就是从“模型能够运行”到“推理集群能够高效提供服务”之间的问题。

本文以官方 v1.0.0 发布资料及 release-1.0 部署指南为依据,使用 NVIDIA GPU 和 vLLM 跑通一套最小服务。

信息核验截至 2026 年 11 月 11 日(北京时间)。本文是入门部署指南,不是已经完成鉴权、容灾和容量规划的生产方案。

一、llm-d 是什么?

llm-d 是面向 Kubernetes 的开源大模型推理服务栈。它不是模型,也不是用于替代 vLLM 的另一套推理引擎。

可以把几者的职责理解为:

  • Kubernetes:管理工作负载、计算资源和服务生命周期。
  • vLLM、SGLang 等模型服务器:加载权重,执行实际推理。
  • llm-d:提供推理感知的请求路由,并组合缓存管理、分离式推理等能力。
  • Gateway API Inference Extension(GAIE):为 Kubernetes 网关体系提供推理服务相关扩展,例如 InferencePool。

尤其需要区分两种“调度”:Kubernetes 调度器决定 Pod 放在哪个节点;llm-d 的 Endpoint Picker 决定一次推理请求交给哪个模型服务端点。二者不在同一个层面。

如果只是单机验证模型,直接使用 vLLM 往往更简单。已经运行多个模型副本、存在重复长上下文,或者需要进一步探索分布式推理的平台,才更值得引入 llm-d。

二、先理解请求路径与核心概念

1. Router 与 Endpoint Picker

Router 的代理接收客户端请求,通过 External Processing 机制咨询 Endpoint Picker(EPP),再把请求转发给选中的模型服务器。

本文的请求路径可以概括为:

客户端 → Envoy 代理 → EPP 选择端点 → vLLM 模型服务器 → 返回结果

这里的箭头表示逻辑处理关系,并不意味着 EPP 自己执行模型推理。

官方提供两种主要部署模式:

  • Standalone Mode:代理与 EPP 位于同一个 Pod,默认使用 Envoy,适合快速入门。
  • Gateway Mode:与 Kubernetes Gateway API 集成,通过 HTTPRoute 连接 InferencePool,适合需要共享入口和复杂流量管理的平台。

本文选择 Standalone,不需要先安装完整的 Gateway 控制器,但仍按官方指南安装 GAIE CRD。

2. 前缀缓存感知与负载感知

Optimized Baseline 默认结合两种路由目标:

  • 前缀缓存亲和性:优先选择可能复用请求前缀缓存的实例。
  • 负载感知:根据模型服务器处理的 token 负载选择端点。

缓存亲和性不是无限制地把请求固定在一个副本上。当实例趋于饱和时,需要让负载分散,避免“缓存命中了,但排队更久”。

这里的 KV cache 是推理过程中保存的中间状态,不是完整回答缓存,也不是向量数据库。

3. Prefill/Decode 分离不是默认步骤

Prefill 处理输入上下文,Decode 逐步生成输出。llm-d 支持把两阶段部署到不同实例,并协调请求及 KV cache 传输。

但这会引入额外的网络、传输和运维要求。本文部署的 Optimized Baseline 没有启用 P/D 分离,也不应把相关能力理解为安装后自动生效。

三、部署前准备什么?

准备一个可以访问的 Kubernetes 集群,以及本地的 Git、Bash、kubectl、Helm。下面的命令还使用 realpath,应在具备该工具的环境中执行。

官方基础设施文档列出的 Kubernetes 测试起点为 1.29,并推荐 1.33.0 及以上以获得完整的 sidecar init container 支持。特定 DRA 部署可能要求更高版本,不能直接套用这一最低值。

本文默认配置为:

项目 配置
模型 Qwen/Qwen3-32B
推理引擎 vLLM
模型副本 2
每副本张量并行度 2
GPU 总数 4
官方参考硬件 H100 80 GB

每个模型 Pod 还请求 8 核 CPU、96 GiB 内存,应为 Router 和系统组件预留额外资源。

GPU 节点需要具备与实际推理镜像匹配的驱动及设备分配能力。本文清单请求 nvidia.com/gpu,集群必须能够提供该资源。

此外,需要确保节点能拉取镜像、下载模型,并按照官方要求准备有效的 Hugging Face token;如模型需要访问授权,也应提前完成。

这不是一套普通笔记本上的轻量示例。官方虽提供其他硬件配置,但模型、资源要求和验证状态并不完全相同。

四、部署最小推理服务

以下步骤均在同一个 Bash 会话中执行,工作目录保持在仓库根目录。

1. 获取发布分支并加载配置

export BRANCH=release-1.0
git clone https://github.com/llm-d/llm-d.git && cd llm-d && git checkout ${BRANCH}

export REPO_ROOT=$(realpath $(git rev-parse --show-toplevel))
export GUIDE_NAME=optimized-baseline
export NAMESPACE=llm-d-optimized-baseline
export MODEL=Qwen/Qwen3-32B

source ${REPO_ROOT}/guides/env.sh

env.sh 定义了配套 CRD、Router Chart 和测试镜像等变量,避免手工拼接不兼容的组件版本。本次核验时,Router Chart 为 v1.0.0,GAIE 为 v1.6.2。

2. 安装 CRD,创建命名空间和 Secret

CRD 属于集群级资源,应由具备相应权限的管理员确认后安装;共享集群尤其需要先核对现有版本。

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api-inference-extension/${GAIE_URL}/v1-manifests.yaml

kubectl create namespace ${NAMESPACE} --dry-run=client -o yaml | kubectl apply -f -

在当前会话通过安全方式设置好 HF_TOKEN 环境变量后,创建官方清单使用的 Secret:

kubectl create secret generic llm-d-hf-token \
  --from-literal="HF_TOKEN=${HF_TOKEN}" \
  --namespace "${NAMESPACE}" \
  --dry-run=client -o yaml | kubectl apply -f -

不要把真实 token 写进博客、Git 仓库或共享终端记录。生产环境应结合平台的凭据管理机制处理。

3. 安装 Standalone Router

helm install ${GUIDE_NAME} \
  ${ROUTER_STANDALONE_CHART} \
  -f guides/recipes/router/base.values.yaml \
  -f guides/optimized-baseline/router/optimized-baseline.values.yaml \
  -n ${NAMESPACE} --version ${ROUTER_CHART_VERSION}

基础 values 提供通用配置,第二个文件叠加前缀缓存亲和性、token 负载评分及模型端点选择条件。

4. 部署 vLLM 模型服务器

kubectl apply -n ${NAMESPACE} \
  -k guides/optimized-baseline/modelserver/gpu/vllm/base/

bash ${REPO_ROOT}/guides/scripts/wait-for-pods-ready.sh \
  -l llm-d.ai/guide=optimized-baseline \
  -n ${NAMESPACE}

首次启动需要下载权重并完成引擎初始化,不能仅凭 Pod 已经创建就认为服务可用。

注意,清单中的 Deployment 即使名为 decode,也不代表本例已经启用了 P/D 分离;判断部署方式应看完整配置。

五、发送第一条请求

先获取 Router Service 的 ClusterIP:

export IP=$(kubectl get service ${GUIDE_NAME}-epp \
  -n ${NAMESPACE} \
  -o jsonpath='{.spec.clusterIP}')

ClusterIP 通常只能在集群网络内访问,因此使用官方示例中的临时 Pod 发起请求:

kubectl run curl-test --rm -i --restart=Never \
  --image=${CURL_TEST_IMAGE} \
  --namespace="${NAMESPACE}" \
  --env="IP=${IP}" \
  --env="MODEL=${MODEL}" \
  -- /bin/sh -c 'curl -sS -X POST "http://${IP}/v1/completions" -H "Content-Type: application/json" -d "{\"model\": \"${MODEL}\", \"prompt\": \"How are you today?\"}"'

这里调用的是 OpenAI 兼容的 /v1/completions 接口。请求中的模型名必须与实际部署保持一致;使用其他硬件配置时,不能只修改请求而不检查模型清单。

收到生成结果,说明基本请求链路已经打通。但一次成功调用并不能证明缓存亲和性有效,更不能证明性能已经优化。

进一步验证时,应发送具有较长公共前缀的多条请求,并结合各副本的请求计数和前缀缓存命中指标观察。

六、实践建议与常见问题

Pod 一直 Pending

先检查可分配 GPU、CPU 和内存,以及节点污点、亲和性与配额。

默认每个模型 Pod 需要两张 GPU。即使集群 GPU 总数足够,也必须存在能满足单个 Pod 资源要求的节点。

模型启动失败

检查镜像拉取、模型下载、访问权限、磁盘空间,以及驱动与镜像兼容性。不要一看到启动缓慢就反复重建 Pod,否则可能重复下载或初始化。

请求失败,但 Pod 看起来正常

检查模型服务器是否真正 Ready,以及 Router 的标签选择条件是否匹配模型 Pod。当前 Router values 使用 llm-d.ai/guide: optimized-baseline 选择后端,修改标签时要同步检查。

如果从集群外直接访问 ClusterIP 失败,应先排查访问路径,而不是立即怀疑模型服务。

换硬件后负载分配不理想

默认路由参数参考 Qwen3-32B、H100 80 GB、TP=2 环境。

其中 peakPrefillThroughput 与模型和硬件有关。更换组合后,应按照官方 calibration recipe 测量,而不是直接沿用参考参数。

不要只看吞吐量

建议同时观察:

  • 首 token 延迟(TTFT);
  • token 间延迟(ITL);
  • 各副本排队与活跃请求;
  • KV cache 使用情况及前缀缓存命中;
  • Router 调度延迟。

缓存命中率高不代表用户体验一定好;过度集中请求也可能让排队成为瓶颈。

进入生产前,还应补齐鉴权、TLS、限流、监控告警和升级验证。v1.0 提供多租户流控等能力,但官方默认行为仍接近先到先服务,业务优先级策略需要显式配置。

总结

llm-d 的价值,不在于替代 vLLM,而在于让多个模型实例组成更懂推理负载的服务系统。

合理的落地顺序是:先跑通 Optimized Baseline,再验证缓存与负载路由,随后用真实业务压测,最后决定是否引入 P/D 分离、缓存卸载或更复杂的扩缩容。

先确认瓶颈,再增加组件,通常比一次启用全部能力更可靠

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。