1. 项目概述为什么要在 DOKS 上跑 llm-d 做分布式大模型推理最近两周我连续帮三个客户在 DigitalOcean 的 Kubernetes 集群也就是 DOKS上部署了llm-d这个工具目标很明确不是为了跑通一个 demo而是要支撑真实业务场景下的分布式大模型推理服务——比如给 SaaS 产品的客服模块提供低延迟、高并发的对话补全能力或者为内部知识库构建可横向扩展的语义检索后端。这里说的“分布式”不是指把一个模型切片扔到多台 GPU 上训而是指把推理请求按策略分发到多个独立的推理实例每个实例可能运行不同模型或同一模型的不同副本由统一网关做负载均衡、熔断降级和缓存路由。这和传统单点部署动辄卡死、扩容靠重启、日志无追踪的模式完全是两个世界。核心关键词里“Deploy”不是点击几下控制台就能完事的动词它背后是镜像构建策略、资源配额计算、节点亲和性调度、GPU 设备插件配置、服务网格集成、TLS 终止位置选择等一系列必须亲手过一遍的硬核操作。“llm-d”这个项目名看起来像缩写实测下来它本质是一个轻量级但高度可定制的推理编排层底层封装了 vLLM 或 Text Generation InferenceTGI作为执行引擎对外暴露标准 OpenAI 兼容 API同时内置了 Prometheus 指标埋点、OpenTelemetry 追踪注入和基于 Redis 的请求队列缓冲。而“Distributed LLM Inference”这个短语很多人第一反应是“得用 Ray 或 Celery”但实际在 DOKS 环境里最稳的方案反而是用 Kubernetes 原生的 Service HorizontalPodAutoscaler ClusterIP ExternalIP 组合来实现——既不用引入新框架增加运维复杂度又能利用 DO 自带的 Load Balancer 实现跨区域流量分发。你可能会问为什么非选 DOKSAWS EKS 和 GCP GKE 不是更成熟吗实测下来在中小团队5–20 人技术栈场景中DOKS 的优势非常具体一是控制台响应快创建一个带 A10 GPU 的节点池从提交到 Ready 状态平均只要 92 秒我们用doctl脚本压测过 37 次二是它的 Kubernetes Dashboard 内置了实时 GPU 利用率热力图不需要自己搭 Grafana三是它的 Load Balancer 默认支持 PROXY protocol v2这对需要透传客户端真实 IP 做风控或地域限流的推理服务来说省掉了 Nginx Ingress Controller 的额外配置。当然它也有明显短板不支持自动伸缩 GPU 节点DO 官方明确说明暂未开放该 API所以 llm-d 的 HPA 必须基于 CPU内存自定义指标如 pending request count来做不能只看 GPU 显存占用——这点我在第三节会手把手拆解怎么写那个 Custom Metrics Adapter 的 YAML。适合谁参考这篇如果你正在评估将线上推理服务从裸机迁移到云原生环境或者已经买了 DO 的 GPU Droplet 但发现单机性能瓶颈明显、想快速切到集群模式又或者你被“linux deploy 操作环境更新错误”这类报错卡住过比如apt update卡在http://mirrors.digitalocean.com、kubectl apply报no matches for kind Ingress因为没装 ingress-nginx、甚至只是想搞懂“为什么别人部署 llm-d 要建 4 个 Namespace 而不是 1 个”那这篇就是为你写的。它不讲 Kubernetes 基础概念但会告诉你每一个 YAML 文件里字段的真实含义以及删掉哪一行会导致整个推理链路超时翻倍。2. 整体架构设计与关键决策逻辑2.1 为什么放弃 Helm Chart 直接部署而选择纯 YAML Kustomizellm-d 官方 GitHub 仓库里确实提供了 Helm Chart但我在第一次部署时就放弃了它。原因很实在Helm 的 values.yaml 里把所有组件API Server、Model Loader、Redis Queue、Prometheus Exporter默认绑在一个 namespace 下且默认启用hostNetwork: true——这在 DOKS 上直接导致节点间 Pod 无法通信因为 DO 的 CNI 插件Cilium对 hostNetwork 模式有特殊限制。更麻烦的是它的 readiness probe 路径写的是/healthz但 llm-d 实际健康检查端口监听在8080/ready这个路径不匹配会导致 Deployment 卡在ContainerCreating状态长达 5 分钟直到 liveness probe 失败触发重启循环。所以我改用 Kustomize 管理整套部署好处是显而易见的所有资源对象Deployment、Service、ConfigMap、Secret、HPA、CustomResourceDefinition全部解耦可以按需启用或禁用kustomization.yaml里用patchesStrategicMerge精准覆盖特定字段比如把spec.template.spec.containers[0].readinessProbe.httpGet.path改成/ready而不是全局替换最关键的是能用basesoverlays实现环境隔离dev/ staging / prod 三套环境共用同一套 base只在 overlay 里改镜像 tag、资源 limit、Load Balancer 类型staging 用 Basic LBprod 用 Standard LB和 TLS 证书 Secret 名称。提示Kustomize 不是必须学的新工具它本质就是一套“YAML 模板增强器”。你可以把它理解成用sed命令批量改配置的升级版但语法更安全、可复用性更高。如果你团队还在用 Ansible 或 Terraform 管理 K8s完全可以把 kustomize build 的输出结果当做一个中间产物交给它们调用。2.2 GPU 资源调度策略为什么必须用 nodeSelector tolerations而不是默认调度DOKS 的 GPU 节点池比如g-4vcpu-16gb-a10-1x默认不会被普通 Pod 调度到因为 Kubernetes 要求显式声明对nvidia.com/gpu这个污点taint的容忍toleration同时指定节点标签label让调度器知道“这台机器有 GPU”。很多新手直接照抄网上教程加一句resources.limits.nvidia.com/gpu: 1就以为完事了结果 Pod 一直 Pendingkubectl describe pod显示0/3 nodes are available: 3 node(s) had taint {node-role.kubernetes.io/master: }, that the pod didnt tolerate.—— 这其实是误读真正的问题是节点有nvidia.com/gpu: none这个污点而你的 Pod 没声明容忍。正确的做法分三步先确认 GPU 节点标签kubectl get nodes -l doks.digitalocean.com/node-poolgpu-pool --show-labels你会看到类似beta.kubernetes.io/archamd64,beta.kubernetes.io/oslinux,doks.digitalocean.com/node-poolgpu-pool,nvidia.com/gpu.presenttrue的输出在 llm-d 的 Deployment YAML 里spec.template.spec下添加nodeSelector: doks.digitalocean.com/node-pool: gpu-pool tolerations: - key: nvidia.com/gpu operator: Exists effect: NoSchedule同时确保容器镜像里已预装 NVIDIA Container Toolkit官方 llm-d 镜像已包含但如果你自己 build必须在 Dockerfile 里加RUN apt-get install -y nvidia-container-toolkit并配置/etc/nvidia-container-runtime/config.toml。注意不要用affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution替代nodeSelector虽然功能相似但在 DOKS 的 Cilium 网络环境下前者偶尔会触发调度器 bug导致 Pod 分配到非 GPU 节点后因找不到设备而 CrashLoopBackOff。2.3 网络拓扑设计为什么 API Gateway 和 Model Worker 必须分 namespace且 Service 类型必须是 ClusterIP这是最容易被忽略但影响最大的设计点。llm-d 架构里API Gateway接收 OpenAI 兼容请求和 Model Worker实际加载模型并执行推理是两个独立进程它们之间通过 Redis 队列通信而非直接 HTTP 调用。如果把它们放在同一个 namespace 下用默认的ClusterIPService看似简单实则埋雷当 Model Worker 数量扩到 10 时Gateway 会尝试连接所有 Worker 的 ClusterIP而 Kubernetes 的 kube-proxy 在 iptables 模式下对大规模 Service 的规则同步有延迟导致部分 Worker 的连接被丢弃表现就是503 Service Unavailable错误率突然飙升。我的解决方案是创建llm-d-gateway和llm-d-workers两个独立 namespaceGateway 的 Service 类型保持ClusterIP但只暴露给 IngressWorker 的 Service 类型也设为ClusterIP但不暴露任何端口只用于内部 DNS 解析比如llm-d-worker.llm-d-workers.svc.cluster.local所有 Worker 的 Pod 都挂载一个 ConfigMap里面写死 Redis 地址redis.llm-d-shared.svc.cluster.local:6379避免通过 Service 发现带来额外网络跳转。这样做的好处是网络路径极简Client → DO Load Balancer → Ingress Controller → Gateway Pod → Redis → Worker Pod故障域隔离Worker 崩溃不会影响 Gateway 的健康检查Gateway 日志里看不到 Worker 的 5xx扩容无感新增 Worker Pod 只需加入 Redis 队列监听无需修改任何 Service 或 Endpoint 配置。3. 核心组件部署与实操细节解析3.1 基础环境准备DOKS 集群初始化与 GPU 节点池配置部署 llm-d 前DOKS 集群本身必须满足几个硬性条件否则后续所有步骤都会失败。这不是“建议”而是 DO 官方文档里白纸黑字写的限制Kubernetes 版本必须 ≥ 1.26因为 llm-d 使用了server-side apply和status subresource这两个特性在 1.25 以下版本不完全支持。验证命令kubectl version --short如果显示Server Version: v1.25.11必须先升级doctl kubernetes cluster upgrade cluster-id --version 1.26.11-do.0注意升级过程约 8 分钟期间集群不可用务必选业务低峰期。GPU 节点池必须启用 NVIDIA Device PluginDO 控制台创建节点池时默认不勾选“Install NVIDIA device plugin”这个选项藏在“Advanced Options”折叠菜单里。如果漏选即使节点有 A10 卡kubectl describe node里也看不到nvidia.com/gpu: 1这个 Capacity 字段。补救方法很麻烦必须手动 SSH 到每个 GPU 节点运行curl -fsSL https://raw.githubusercontent.com/NVIDIA/k8s-device-plugin/v0.14.5/nvidia-device-plugin.yml | kubectl apply -f -然后重启 kubelet。所以强烈建议——第一次创建就勾上。必须预先配置好专用的 StorageClassllm-d 的 Model Loader 组件需要挂载模型权重文件通常 5–20GB如果直接用默认的do-block-storageIO 性能不够加载一个 Llama-3-8B 模型要 4 分钟以上。正确做法是创建一个基于 NVMe 的 StorageClass# nvme-storageclass.yaml apiVersion: storage.k8s.io/v1 kind: StorageClass metadata: name: do-nvme provisioner: dobs.csi.digitalocean.com parameters: type: nvme fsType: xfs reclaimPolicy: Retain volumeBindingMode: Immediate应用后再在 Model Loader 的 StatefulSet 里引用storageClassName: do-nvme。实操心得我踩过一次坑——在创建节点池时选了g-8vcpu-32gb-a10-1x规格但没注意 DO 的 A10 实例最低要求是 16GB 内存结果节点创建成功但kubectl get nodes里状态一直是NotReady。查日志发现kubelet报错cgroup memory limit exceeded。解决办法只能删掉整个节点池重建选g-8vcpu-32gb-a10-1x或更高规格。所以记住DOKS 的 GPU 实例规格不是“越大越好”而是必须严格匹配 DO 官方文档里写的最小内存要求。3.2 llm-d 核心组件 YAML 编写与参数详解llm-d 的部署不是“一键 apply 一个 giant YAML”而是由 7 个核心 YAML 文件组成每个文件负责一个明确职责。我把它们按依赖顺序排列并标注每个关键字段的取值逻辑文件名职责关键字段及说明01-namespace.yaml创建llm-d-shared放 Redis、Prometheus、llm-d-gateway、llm-d-workers三个命名空间labels: istio-injection: disabled—— 必须关闭 Istio 注入否则 Envoy Sidecar 会劫持 llm-d 的 gRPC 流量导致超时02-redis.yaml部署 Redis 作为任务队列resources.requests.memory: 2Gi—— 小于 2Gi 会导致 LLM 请求积压时 OOM Killenv.REDIS_PASSWORD必须用 Secret 引用不能明文写在 ConfigMap 里03-gateway-deployment.yamlAPI Gateway 主程序env.LLM_D_MODEL_LOADER_URL: http://llm-d-loader.llm-d-workers.svc.cluster.local:8000—— 这是内部 DNS 地址不是 ClusterIPlivenessProbe.initialDelaySeconds: 120—— 因为 Gateway 启动要加载 OpenAPI Schema首次启动慢必须设长04-worker-deployment.yamlModel Worker实际执行推理env.MODEL_NAME: meta-llama/Meta-Llama-3-8B-Instruct—— 必须和 Hugging Face 模型 ID 完全一致resources.limits.nvidia.com/gpu: 1—— 这里写 1不是 1 字符串否则调度失败05-ingress.yaml配置 DO Load Balancer 入口kubernetes.io/do-loadbalancer-enable-proxy-protocol: true—— 开启 PROXY protocol否则获取不到客户端真实 IPkubernetes.io/do-loadbalancer-certificate-id: xxx—— 必须提前在 DO 控制台上传证书并复制 ID06-hpa-worker.yamlWorker 的水平扩缩容策略metrics[0].type: Podsmetrics[0].pods.metric.name: queue_length—— 基于 Redis 队列长度扩缩比 CPU 更精准minReplicas: 2—— 至少 2 个副本避免单点故障07-prometheus-rules.yaml自定义告警规则alert: LLMWorkerHighErrorRateexpr: rate(llm_d_worker_errors_total[5m]) 0.05—— 错误率超 5% 触发告警其中最易出错的是04-worker-deployment.yaml里的volumeMounts配置。llm-d 要求模型文件必须放在/models目录下且权限为755。如果你用 PVC 挂载必须在 Pod 启动前执行chmod -R 755 /models否则 vLLM 加载时报Permission denied。解决方案是在initContainers里加一个busybox镜像initContainers: - name: fix-permissions image: busybox:1.35 command: [sh, -c, chmod -R 755 /models] volumeMounts: - name: model-storage mountPath: /models实操心得05-ingress.yaml里的kubernetes.io/do-loadbalancer-health-check-path默认是/但 llm-d Gateway 的健康检查端点是/ready。如果不改Load Balancer 会认为所有 Gateway Pod 都不健康永远不转发流量。这个字段必须显式设置为/ready而且要等 Gateway Pod Running 状态稳定 30 秒后再应用 Ingress否则 DO LB 会缓存错误的健康状态长达 2 分钟。3.3 镜像构建与推送如何避免 “linux deploy 操作环境更新错误”标题里提到的“linux deploy 操作环境更新错误”在实际部署中高频出现在两个环节一是构建 llm-d Worker 镜像时apt update卡住二是 Worker Pod 启动时pip install报ReadTimeoutError。根本原因是 DO 的镜像仓库和 PyPI 源在国内访问不稳定而很多教程教大家直接FROM python:3.11-slim这就踩坑了。我的解决方案是全部使用国内可信镜像源 多阶段构建。具体 Dockerfile 如下# 第一阶段构建环境用清华源加速 FROM registry.cn-hangzhou.aliyuncs.com/pytorch/pytorch:2.2.0-cuda12.1-devel AS builder RUN pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple/ RUN pip install --no-cache-dir torch2.2.0cu121 torchvision0.17.0cu121 --extra-index-url https://download.pytorch.org/whl/cu121 RUN pip install --no-cache-dir vllm0.4.2 transformers4.41.2 # 第二阶段运行环境用更小的基础镜像 FROM nvidia/cuda:12.1.1-runtime-ubuntu22.04 COPY --frombuilder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages COPY --frombuilder /usr/local/bin/python* /usr/local/bin/ # 手动复制 CUDA 库避免 runtime 镜像缺失 RUN cp /usr/lib/x86_64-linux-gnu/libcuda.so* /usr/lib/ \ cp /usr/lib/x86_64-linux-gnu/libnvidia-ml.so* /usr/lib/ # 最终镜像只保留必要文件 WORKDIR /app COPY requirements.txt . RUN pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple/ \ pip install --no-cache-dir -r requirements.txt COPY . . CMD [python, worker.py]构建完成后推送到 DO 的 Container Registryregistry.digitalocean.com/your-registry而不是 Docker Hub。DO Registry 和 DOKS 集群在同一内网拉取速度稳定在 120MB/s而 Docker Hub 国内经常降到 200KB/s 以下。注意requirements.txt里不要写--index-url因为构建阶段已经设了全局源。另外vllm必须用0.4.2锁死版本0.4.3 有内存泄漏 bug实测 Worker 运行 4 小时后显存占用从 12GB 涨到 18GB最终 OOM。4. 分布式推理链路验证与性能调优4.1 端到端链路测试从 curl 到 Prometheus 指标全通部署完所有 YAML别急着庆祝。必须按顺序验证 5 层链路缺一不可DNS 层kubectl exec -it gateway-pod -- nslookup llm-d-worker.llm-d-workers.svc.cluster.local必须返回10.244.x.x这类 ClusterIP不能是NXDOMAINRedis 层kubectl exec -it gateway-pod -- redis-cli -h redis.llm-d-shared.svc.cluster.local -p 6379 -a $REDIS_PASSWORD ping返回PONGHTTP 层内部kubectl exec -it gateway-pod -- curl -v http://llm-d-worker.llm-d-workers.svc.cluster.local:8000/healthz返回{status:ok}HTTP 层外部curl -v https://your-domain/v1/chat/completions -H Authorization: Bearer token -d {model:llama3,messages:[{role:user,content:Hello}]}必须返回200 OK和 JSON 响应Metrics 层打开 Prometheus UIkubectl port-forward svc/prometheus 9090:9090输入rate(llm_d_gateway_requests_total[1m])应该看到每秒请求数实时上涨。最容易卡在第 3 步。常见原因是Worker 的 Service 没写selector或者selector的 label 和 Pod 的 label 对不上。比如你在 Worker Deployment 里写了labels: app: llm-d-worker但 Service 的selector.app写成了llm-d-worker-app就会导致curl超时。验证命令kubectl get endpoints llm-d-worker -n llm-d-workers如果ENDPOINTS列为空就是 selector 错了。实操心得第 4 步的curl测试一定要加-v参数看详细响应头。如果返回502 Bad Gateway大概率是 Ingress Controller 没正确转发到 Gateway Service如果返回504 Gateway Timeout则是 Gateway Pod 本身处理慢需要查kubectl logs gateway-pod里是否有Redis connection timeout或Model loader not ready日志。4.2 性能基准测试用 hey 工具实测 QPS 与 P99 延迟验证通了不代表性能达标。我用heyGo 写的压测工具做了三组对比测试硬件环境是DOKS 集群 3 个节点1 个 CPU 节点跑 Gateway Redis2 个 GPU 节点各跑 2 个 Worker模型为 Llama-3-8B-Instruct输入 prompt 长度固定为 128 token输出 max_tokens256。测试场景并发数QPSP99 延迟关键观察单 Worker无 Redis103.21.8s所有请求串行GPU 利用率仅 35%2 Worker Redis 队列5018.72.1sQPS 翻倍但 P99 上升因 Redis 成为瓶颈4 Worker Redis Cluster3 节点10036.41.9sQPS 接近线性增长P99 稳定结论很清晰Worker 数量不是越多越好必须和 Redis 容量匹配。单节点 Redis 在 50 并发下INFO stats显示instantaneous_ops_per_sec峰值达 12000接近极限。所以生产环境必须上 Redis Cluster至少 3 个分片。调优关键参数在 llm-d Gateway 的 ConfigMap 里把redis.queue_timeout_ms从默认 5000 改成 2000避免请求在队列里等待过久Worker 的vllm.engine_args.max_num_seqs设为 256默认 256不用改但max_model_len必须根据模型实际长度设Llama-3 是 8192设小了会截断kubectl edit hpa llm-d-worker把targetAverageValue从100改成50让扩缩容更灵敏。注意hey命令必须加-m POST和-H Content-Type: application/json否则 Gateway 会返回415 Unsupported Media Type。完整命令hey -n 1000 -c 100 -m POST -H Content-Type: application/json -H Authorization: Bearer sk-xxx -d {model:llama3,messages:[{role:user,content:Explain quantum computing in simple terms}]} https://api.example.com/v1/chat/completions4.3 故障排查实战5 个高频问题与根因定位法问题 1kubectl get pods显示 Worker Pod 状态为Pendingkubectl describe pod提示0/3 nodes are available: 3 node(s) didnt match Pods node affinity/selector.根因nodeSelector的 label 值写错了。比如你创建节点池时指定的 label 是doks.digitalocean.com/node-pool: gpu-pool-2024但 YAML 里写的是gpu-pool。定位法kubectl get nodes --show-labels | grep gpu-pool复制真实的 label 值再kubectl edit deployment llm-d-worker修改。问题 2Worker Pod 状态为Running但kubectl logs pod显示OSError: [Errno 13] Permission denied: /models根因PVC 挂载的存储卷权限是root:root而 Worker 容器以非 root 用户uid1001运行。解决法在 PVC 的spec里加fsGroup: 1001或者用initContainer修复权限见 3.2 节。问题 3curl调用返回503 Service Unavailable但 Gateway Pod 日志里没有错误根因Ingress 的service.name指向了错误的 Service或者 Service 的selector没匹配到任何 Pod。定位法kubectl get endpoints gateway-service-name如果ENDPOINTS为空立刻检查 Service 的selector和 Pod 的labels是否一致。问题 4Prometheus 里llm_d_worker_gpu_utilization指标始终为 0根因Worker 镜像里没装nvidia-ml-py3包或者容器没挂载/proc/driver/nvidia。解决法在 Dockerfile 里加RUN pip install nvidia-ml-py3并在 Deployment 的volumeMounts里加- name: nvidia-driver mountPath: /proc/driver/nvidia readOnly: true volumes: - name: nvidia-driver hostPath: path: /proc/driver/nvidia问题 5kubectl top pods显示 Worker Pod 的 CPU 使用率 95%但nvidia-smi显示 GPU 利用率只有 10%根因模型加载阶段 CPU 密集解析 safetensors、构建 KV Cache但推理阶段 GPU 才忙。这是正常现象不代表性能差。验证法用watch -n 1 kubectl exec worker-pod -- nvidia-smi --query-gpuutilization.gpu --formatcsv,noheader,nounits等 30 秒看是否跳变如果一直 10%再查kubectl logs worker-pod | grep loaded model确认模型是否真加载成功。最后分享一个小技巧所有 YAML 文件都加上annotations: timestamp: 2024-06-15T14:30:00Z这样kubectl get -f dir -o yaml输出时能看到每次 apply 的时间戳回滚时能精准定位到哪次变更引入了问题。这个习惯让我在过去三个月里平均故障恢复时间MTTR从 47 分钟降到 8 分钟。