llm-d/llm-d · 上手攻略

• 仓库：llm-d/llm-d
• 链接：https://github.com/llm-d/llm-d
• 分类：llm-infra（分布式推理服务平台）
• 作者：spark
• 更新：2026-07-30

是什么

llm-d 是一个 CNCF Sandbox 级的开源项目，定位是在 Kubernetes 上跑"生产级"大模型分布式推理。它本身不是一个模型服务器（model server），而是架在 vLLM / SGLang](https://github.com/sgl-project/sglang) 之上的编排与优化层——把推理服务拆成 prefill（首 token 阶段）/ decode（增量 token 阶段）、分层 KV cache、wide expert-parallel（MoE 跨节点专家并行）、prefix-cache 路由、batch gateway 等组件，把所有"上层调度工程"做成可复用的 Helm chart 和 Operator。

发起方是 Red Hat、Google Cloud、IBM Research、CoreWeave、NVIDIA 五家，2026-03-24 进 CNCF Sandbox 项目。背后也有 AMD、Cisco、Hugging Face、Intel、Lambda、Mistral AI、UC Berkeley、U Chicago 等支持者——你想在混合硬件 + 混合云上做"同一套 manifest 多处跑"，它的策略天然是 bias 到这条线。最新发布 v0.8（2026-05），节奏大约每两个月一个 minor。

仓库本身大部分是 Shell + Makefile + Kustomize + Helm chart 外加一组 well-lit-path Markdown 教程。核心编排逻辑都写在 Helm chart 里，跑起来拼的是上游 vLLM / SGLang worker pod，外面罩一层 Inference Gateway（基于 Kubernetes Gateway API 的 Inference Extension），通过 InferencePool / InferenceModel 把请求路由到合适的 worker。

解决什么问题

直接用裸 vLLM 跑生产推理时容易撞到几件事：

1. 多轮对话的 prefix-cache 命中率不高：用户每次重发会话前缀，命中率被 round-robin 打散。
2. Decode 长尾延迟拉垮 TTFT：decoding 节点常常排队 prefill 长请求，单 worker 既跑 prefill 又跑 decode。
3. MoE 大模型（GPT-OSS、DeepSeek-V3）跨节点专家：NVLink 域不够大，需要 wide-EP 把专家切到多机。
4. 多租户混部：SLA 不一致，热门租户挤掉冷租户；HPA 抖动。
5. 离线批处理 + 在线推理争资源：batch job 直接打爆在线流量。

llm-d 把上面五件事一起治：

• Intelligent Routing：prefix-cache / load-aware 路由，附带实验性 predicted-latency 调度。
• Tiered KV-Cache：用分层存储（GPU HBM → CPU RAM → NVMe）把"工作集"扩展到 GPU 之外。
• Serving Large Models：prefill / decode 拆开 + wide expert-parallelism 跨节点。
• Operational Excellence：multi-tenant flow control + SLO-aware autoscaling + 实时推理信号。
• Batch Processing：OpenAI 兼容 Batch API、异步离线推理。

快速安装

警告：llm-d 是 K8s-only，至少需要 1 个 GPU 节点 + 能装 NVIDIA Network Operator / device plugin。裸机 or 单卡开发机跑不动。

最小可行环境：

• Kubernetes ≥ 1.30（tested 1.30–1.32）
• Helm v3 + kubectl ≥ 1.30
• GPU 节点：NVIDIA H100 / A100 / B200 或 AMD MI300X（都已 GA 验证）
• 网络：节点间 RDMA / RoCE / 高速 IB 推荐；没有也能跑，但 wide-EP 受益打折
• 储存：如果是 batch gateway + KV 分层场景，建议给节点挂 NVMe；纯 in-GPU 体验也可以，但吞吐会被 GPU HBM 容量卡死

一键 quickstart（来自官方 quickstart 思路）：

# 1. 安装 GPU Operator 与 Network Operator（按云厂商文档）
# 2. 克隆仓库并安装 llm-d 基础组件
git clone https://github.com/llm-d/llm-d.git
cd llm-d

# 推荐先走"optimized baseline" 这条 well-lit path
helm install llm-d guides/optimized-baseline/helm/ \
    -n llm-d --create-namespace

# 3. 部署一个 vLLM 镜像支持的模型服务（用 Helm values 调整 model name / GPU 数）
cat > my-values.yaml <<EOF
model:
  name: "meta-llama/Llama-3.1-8B-Instruct"
  uri: "hf://meta-llama/Llama-3.1-8B-Instruct"
vllm:
  replicas: 2
  gpu: "1"
EOF
helm upgrade llm-d guides/optimized-baseline/helm/ -n llm-d -f my-values.yaml

# 4. 把一条流量转发到本地端口，curl 测试
kubectl -n llm-d port-forward svc/llm-d-inference 8000:8000 &
curl -s http://localhost:8000/v1/chat/completions \
     -H 'Content-Type: application/json' \
     -d '{"model":"Llama-3.1-8B-Instruct","messages":[{"role":"user","content":"hi"}]}' | jq .

⚠️ 上面命令路径与 chart 名字以官方 Quickstart 为准；版本升级到 v0.8 后部分 Helm value key 可能微调。

核心用法

1) Intelligent Routing（prefix-cache 感知）

# 部分 Helm values
inferencePool:
  router:
    type: prefix-cache-aware   # 默认 round-robin
    schedulingThresholdMs: 5
    enablePredictedLatency: true   # 实验性

配完部署一次后，连续两次带相同 system prompt 的请求会命中第二个请求 worker 的 KV cache，TTFT 与首 token 时延都能看到明显降低。官方 benchmark：在 4×AMD MI300X 跑 Llama-3.1-70B，prefix-cache 路由 vs round-robin 给出 3× 吞吐 / 2× TTFT。

2) Prefill / Decode 拆开

vllm:
  prefill:
    replicas: 4
    gpu: "1"
  decode:
    replicas: 8
    gpu: "1"
  disaggregation:
    enabled: true
    transport: uccl   # v0.5 引入的 UCCL 传输层

这条在 AWS p6-b200 跑 GPT-OSS 上给出"比标准 vLLM +70% tokens/sec"的对外数据。Wide-Expert-Parallelism 在 16×16 B200 集群上跑到 ~3.1k tok/s per GPU、整集群 ~50k output tok/s。

3) Tiered KV-Cache（hierarchical offload）

vllm:
  kvCache:
    tiered:
      cpuMemoryGB: 256
      nvmePath: /mnt/kv-tier
      offloadPolicy: lru

4×H100 + NVMe 在 250 并发下，相对纯 GPU 模式可拿到 最高 13.9× 吞吐。

4) 批处理 Gateway

curl -X POST http://gateway.llm-d.svc/openai/v1/batches \
     -H "Authorization: Bearer $TOKEN" \
     -d '{"input_file_id":"file-...","completion_window":"24h"}'

兼容 OpenAI Batch API 协议，把离线打分/合成数据请求从在线路径隔开。

5) 看 Prism 看 SOTA 基准

官方把可复现 benchmark 摆在 https://prism.llm-d.ai 上。挑你计划的硬件/模型组合拉一份 JSON 出来对账，是写容量规划最直接的材料。

典型适用场景

• 大规模多租户在线推理 SaaS：需要 SLO 区分、SLA-aware 调度，硬件又是混合 GPU（NVIDIA + AMD / H100 + H200 + B200），llm-d 的统一编排层正好；过去要自己写的负载隔离 / 公平调度 / token-bucket 现在都有 chart 默认值。
• MoE / 超大模型自托管：DeepSeek-V3、GPT-OSS、Qwen3-MoE 这类 200B+ MoE 一定要走 wide-EP + prefill/decode 拆，llm-d 把这条路径做成可复用 Helm chart，你只需关心"专家切多大、prefill 多深、decode 多宽"这三组超参。
• 对话产品的多轮 KV 复用：客服、代码助手、agent 类系统绝大部分 token 预算花在 system prompt + 历史轮次上，prefix-cache 路由直接是 ROI 提升——同样 QPS 下 TTFT 和 token/s 大幅上涨，硬件预算持平。
• 离线 batch + 在线混部：白天在线、晚间跑 evals / 合成数据 / 数据标注 / 司法长文档总结；batch gateway 单独打队列，不打 online，autoscaler 把副本往在线倾斜。
• 跨厂商 GPU 池化：在 CoreWeave / OCI / GCP / 自建集群上跑同一套 manifest，llm-d 的 well-lit-path 刻意做成跨云可复现；换云时不是 patch 一堆 CRD，而是同一组 Helm values 改 endpoint。
• 学术研究的可复现基线：CVPR/ICLR 类工作在自家集群跑大模型 baseline 一直很痛——llm-d 在 https://prism.llm-d.ai 公开了多套可复现 benchmark + manifests，写论文直接拿来对。

不太适用：

• 单卡 demo / 个人开发机——直接 vllm serve 就够了。
• 没有 K8s 运营能力的小团队——llm-d 的网关、Gateway API、kustomize 链路对小团队过重；先用 BentoML / Modal / Replicate 把链路走通。
• 训练路径——llm-d 不做训练；要做 SFT/PEFT 请走 Hugging Face accelerate / DeepSpeed / Megatron-LM。

坑与注意

1. K8s 网络基线：许多优化（prefill/decode disagg、wide-EP）依赖节点间低延迟互联，纯 TCP 跨 AZ 会把收益抹平；上生产前用 ib_write_bw/nccl-tests 跑通 baseline。
2. 硬件矩阵不等于全支持：v0.8 已经覆盖 NVIDIA H100/A100/B200、AMD MI300X、Google TPU、Intel XPU、AWS Trainium，但请以 https://llm-d.ai/docs/getting-started/accelerators 当下表为准；不要假设某型号已 GA。
3. 0.x 语义：v0.5 → v0.7 → v0.8 跨度里多次重构 Helm value key 与 chart 路径。升级前一定看 release notes，跑 migration script；用 ArgoCD/Flux 的团队建议把 chart 锁定到具体 patch。
4. CNCF Sandbox ≠ 1.0：API、CRD、annotation 都可能改；CI/CD 里"绿色构建"不等于"生产可用"，请另测 prefix-cache 命中率、TTFT、tail latency。
5. 依赖项庞杂：Gateway API Inference Extension、Envoy Gateway、NCCL/UCCL、GPU Operator、HPA 外部 metrics adapter——任意一环升级都可能撞兼容问题。CI 中需要锁版本矩阵。
6. 可观测性要自己接：llm-d 不内置完整 APM；推荐 Prometheus + OpenTelemetry Collector + Tempo/Loki，把 vLLM worker 的 metrics 直打到每 replica。
7. 安全姿态：CNCF 项目暂时没有 SOC2/ISO 之类的认证背书；金融/医疗部署要走自己的 SIG 评估，DMZ 与 IAM 选型自行加一层。
8. 版本号：上面示例默认对 v0.7/v0.8，v0.5 之前的 batch gateway 还是实验标签。要用 batch gateway + predicted-latency 调度建议至少升到 v0.7+。
9. 资源超配基线：prefill/decode 拆开意味着你要为 prefill 副本额外留 GPU 内存；如果只看 decode 占用规划，会出现"prefill OOM"而 decode 节点还空着。

与同类对比

一句话推荐结论

如果你的团队已经在 K8s 上跑 vLLM/GPU serving，llm-d 是当前 CNCF 视野里最值得评估的"vLLM 之上的瑞士军刀"——prefix-cache 路由、tiered KV、prefill/decode 拆、wide-EP、SLO-aware autoscaling 一站式解决了 2025 年以来大模型推理的几大主流痛点；但前提是：你得有 K8s + GPU 网络的运维底子，否则它会比裸 vLLM 重得多。