vLLM 生产环境栈：用于生产部署 vLLM 的参考架构

| 博客 | 文档 | 生产环境栈 Slack 频道 | LMCache Slack | 兴趣表单 |

最新消息

• 📄 生产环境栈的官方文档已发布！
• ✨ 针对 Lambda Labs、AWS EKS 和 Google GCP 的云部署教程现已上线！
• 🛤️ 2026 年路线图已发布！立即参与讨论！
• 🔥 vLLM 生产环境栈正式发布！请查看我们于 2025 年 1 月 22 日发布的发布博客。

社区活动

我们每两周举行一次社区会议，具体时间如下：

• 每隔一周的周二下午 5:30（太平洋时间）– 添加到日历

欢迎所有人参加！

简介

vLLM 生产环境栈项目提供了一个基于 vLLM 构建推理栈的参考实现，它使您能够：

• 🚀 在不更改任何应用程序代码的情况下，从单个 vLLM 实例扩展到分布式 vLLM 部署
• 💻 通过 Web 仪表板监控各项指标
• 😄 享受请求路由和 KV 缓存卸载带来的性能优势

分步教程

0. 如何 安装 Kubernetes（kubectl、helm、minikube 等）？
1. 如何 在主流云平台（AWS、GCP、Lambda Labs、Azure）上部署生产环境栈？
2. 如何 搭建一个最小化的 vLLM 生产环境栈？
3. 如何 自定义 vLLM 配置（可选）？
4. 如何 加载您的 LLM 权重？
5. 如何 在 vLLM 生产环境栈中运行不同的 LLM？
6. 如何 使用 LMCache 启用 KV 缓存卸载？

架构

该栈使用 Helm 进行部署，包含以下关键组件：

• 服务引擎：运行不同 LLM 的 vLLM 引擎。
• 请求路由器：根据路由键或会话 ID 将请求定向到合适的后端，以最大化 KV 缓存的复用。
• 可观测性栈：通过 Prometheus + Grafana 监控后端的各项指标。

路线图

我们正在积极开发此项目，并将很快推出以下功能。敬请期待！

• 基于 vLLM 特定指标的自动伸缩
• 对解耦预填充的支持
• 路由器改进（例如，使用非 Python 语言实现更高效的路由器、KV 缓存感知路由算法、更好的容错能力等）

通过 Helm 部署栈

先决条件

• 一个运行中的带有 GPU 的 Kubernetes (K8s) 环境
  • 运行 cd utils && bash install-minikube-cluster.sh
  • 或者按照我们的教程操作

部署

vLLM 生产环境栈可以通过 Helm Chart 部署。克隆仓库到本地并执行以下命令以进行最小化部署：

git clone https://github.com/vllm-project/production-stack.git
cd production-stack/
helm repo add vllm https://vllm-project.github.io/production-stack
helm install vllm vllm/vllm-stack -f tutorials/assets/values-01-minimal-example.yaml

部署后的栈提供了与 vLLM 相同的OpenAI API 接口，可通过 Kubernetes Service 访问。

要验证安装并向栈发送查询，请参阅此教程。

有关自定义 Helm Chart 的更多信息，请参阅 values.yaml 以及我们的其他教程。

卸载

helm uninstall vllm

Grafana 仪表板

功能

Grafana 仪表板提供以下洞察：

1. 可用 vLLM 实例数：显示健康实例的数量。
2. 请求延迟分布：可视化端到端请求延迟。
3. 首次 token 时间 (TTFT) 分布：监控生成 token 的响应时间。
4. 正在处理的请求数：跟踪每个实例上的活跃请求数。
5. 待处理请求数：跟踪等待处理的请求数。
6. GPU KV 使用率：监控 GPU KV 缓存的使用情况。
7. GPU KV 缓存命中率：显示 GPU KV 缓存的命中率。

配置

详情请参阅 helm/README.md。

路由器

路由器确保请求在后端之间高效分配。它支持：

• 路由到运行不同模型的端点
• 导出每个服务引擎实例的可观测性指标，包括 QPS、首次 token 时间 (TTFT)、待处理/正在处理/已完成请求数以及运行时间
• 通过 Kubernetes API 实现自动服务发现和容错
• 模型别名
• 多种路由算法：
  • 轮询路由
  • 基于会话 ID 的路由
  • 前缀感知路由（开发中）

更多详细信息请参阅 路由器文档。

贡献

我们欢迎并重视任何贡献和合作。请查看 CONTRIBUTING.md 了解如何参与。

许可证

本项目采用 Apache License 2.0 许可证。详细信息请参阅 LICENSE 文件。

赞助商

我们感谢支持我们开发和基准测试工作的赞助商：

---

如遇任何问题或疑问，请随时提交 issue 或联系我们（@ruizhang0101、@ApostaC、@YuhanLiu11、@Shaoting-Feng）。

vLLM Production Stack 快速上手指南

vLLM Production Stack 是一个基于 Kubernetes 和 Helm 的参考实现，旨在帮助用户快速构建生产级的 vLLM 推理集群。它支持从单节点平滑扩展到分布式部署，内置请求路由、KV Cache 卸载（通过 LMCache）以及完整的监控仪表盘（Prometheus + Grafana）。

环境准备

在开始之前，请确保满足以下前置条件：

• 操作系统：Linux (推荐 Ubuntu 20.04/22.04) 或 macOS。
• Kubernetes 集群：需要一个正在运行且包含 GPU 资源的 K8s 环境。
  • 本地测试：可使用 minikube 快速搭建（需安装 Docker 和 NVIDIA Container Toolkit）。
  • 云环境：支持 AWS EKS, Google GCP, Lambda Labs, Azure AKS 等。
• 核心工具：
  • kubectl：Kubernetes 命令行工具。
  • helm (v3+)：包管理工具。
  • git：代码版本控制。

提示：如果你尚未安装 Kubernetes 环境，可运行项目提供的脚本自动安装 minikube 集群：

cd utils && bash install-minikube-cluster.sh

或参考官方教程：安装 Kubernetes 环境

安装步骤

以下步骤将演示如何通过 Helm 图表部署一个最小化的 vLLM Production Stack。

1. 克隆项目仓库

git clone https://github.com/vllm-project/production-stack.git
cd production-stack/

2. 添加 Helm 仓库

将 vLLM Production Stack 的 Helm 仓库添加到本地列表：

helm repo add vllm https://vllm-project.github.io/production-stack
helm repo update

3. 执行部署

使用项目提供的最小化示例配置文件进行安装：

helm install vllm vllm/vllm-stack -f tutorials/assets/values-01-minimal-example.yaml

注意：国内用户若遇到 Helm 仓库拉取缓慢，可尝试配置国内镜像源或使用代理加速。

4. 验证安装

等待 Pod 状态变为 Running：

kubectl get pods

确认服务已暴露：

kubectl get svc

基本使用

部署完成后，Stack 会提供与 vLLM 原生兼容的 OpenAI API 接口。你可以通过 Kubernetes Service 访问该接口。

发送测试请求

假设你的服务名为 vllm-vllm-stack（具体名称可通过 kubectl get svc 查看），你可以使用 curl 或任何 OpenAI 兼容的客户端进行测试。

以下是一个简单的 curl 测试示例（请在集群内部或通过端口转发访问）：

# 端口转发到本地 (可选，方便本地调试)
kubectl port-forward svc/vllm-vllm-stack 8000:80

# 在新终端中发送请求
curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-name",
    "messages": [
      {"role": "user", "content": "Hello, how are you?"}
    ]
  }'

请将 your-model-name 替换为你实际加载的模型名称。

查看监控仪表盘

Production Stack 内置了 Grafana 监控面板，可实时查看：

• 可用 vLLM 实例数量
• 请求延迟分布 (Latency)
• 首字生成时间 (TTFT)
• GPU KV Cache 命中率及使用率

通过端口转发访问 Grafana：

kubectl port-forward svc/grafana 3000:80

然后在浏览器打开 http://localhost:3000 即可查看可视化数据。

---

更多高级用法（如自定义配置、加载本地模型权重、启用 KV Cache 卸载、多模型部署等），请参考项目目录下的 tutorials 文件夹。