# vllm-gateway：为团队提供LLM推理成本与延迟归因的开源网关

> 一款基于Go语言开发的vLLM反向代理网关，支持按团队归因推理成本和延迟，集成ClickHouse存储、Prometheus监控和Grafana可视化，适用于企业级LLM服务治理。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-06-01T22:45:03.000Z
- 最近活动: 2026-06-01T22:49:01.350Z
- 热度: 145.9
- 关键词: vLLM, LLM推理, 成本归因, 延迟监控, 多租户, 网关, Prometheus, Grafana, ClickHouse, Go
- 页面链接: https://www.zingnex.cn/forum/thread/vllm-gateway-llm
- Canonical: https://www.zingnex.cn/forum/thread/vllm-gateway-llm
- Markdown 来源: ingested_event

---

# vllm-gateway：为团队提供LLM推理成本与延迟归因的开源网关

## 原作者与来源

- **原作者/维护者**: arnabguin
- **来源平台**: GitHub
- **原始标题**: vllm-gateway: vLLM inference cost and latency attribution for teams
- **原始链接**: https://github.com/arnabguin/vllm-gateway
- **发布时间**: 2026年6月1日

## 项目背景与问题陈述

随着大型语言模型（LLM）在企业中的广泛采用，推理成本控制和性能监控成为团队面临的核心挑战。传统的vLLM部署虽然提供了高性能的推理服务，但缺乏细粒度的成本归因能力——当多个团队共享同一个推理集群时，难以准确追踪每个团队的资源消耗和延迟表现。

vllm-gateway应运而生，它作为一个轻量级的Go语言反向代理层，架设在vLLM（或开发模拟环境）之前，专门解决以下痛点：

- **成本归因模糊**: 无法区分不同团队、不同项目的实际资源消耗
- **延迟监控缺失**: 缺乏首Token时间（TTFT）等关键指标的细粒度追踪
- **实时观测能力不足**: 缺少开箱即用的监控仪表板
- **多租户隔离困难**: 难以在共享基础设施上实现团队级别的资源隔离和计费

## 核心架构设计

vllm-gateway采用简洁的分层架构，在保持高性能的同时实现全面的可观测性：

```
客户端请求 → 网关(:8080) → vLLM/模拟服务(:8000/:8001)
    ↓
ClickHouse (事件存储 + 15秒聚合)
    ↓
Prometheus (5秒采集) → Grafana仪表板
    ↓
vLLM /metrics 抓取 (15秒间隔)
```

这种设计确保了三个层面的数据完整性：

**请求级事件流**: 每个推理请求都被记录到`request_events`表，包含Token数量、延迟、TTFT（如果是流式响应）等关键字段。

**聚合指标层**: `request_metrics`表按15秒间隔汇总各团队的延迟和TTFT百分位数，`vllm_system_metrics`则追踪队列深度和运行中请求数。

**实时监控层**: Prometheus以5秒间隔采集网关暴露的指标，配合预配置的Grafana仪表板实现可视化。

## 关键功能特性

### 团队级成本归因

网关通过HTTP头实现多租户识别：

- **X-Team-ID** (必需): 标识请求所属团队
- **X-Project** (可选): 进一步细分项目维度
- **X-User-ID** (可选): 追踪到具体用户

这种设计允许企业在共享的vLLM集群上实现精确的按团队计费，无需为每个团队单独部署推理实例。

### 流式响应支持

vllm-gateway完整支持OpenAI兼容的流式响应（SSE），并自动注入`stream_options.include_usage`参数，确保Token计数信息出现在最终的SSE数据块中。首Token时间（TTFT）作为流式场景的关键性能指标被单独记录。

### 完整的OpenAI API兼容

网关支持以下端点：

- `POST /v1/completions`: 文本补全
- `POST /v1/chat/completions`: 对话补全
- `POST /v1/embeddings`: 文本嵌入
- `GET /v1/metrics`: Prometheus指标暴露
- `GET /health`: 健康检查

### 开发环境友好

项目提供完整的开发模拟环境，无需GPU即可本地测试：

```bash
cp .env.example .env
./scripts/dev.sh mock  # 启动模拟vLLM环境
```

模拟环境包含ClickHouse、Prometheus、Grafana和负载模拟器，支持33%的流式请求比例模拟真实场景。

## 技术实现细节

### 存储层设计

ClickHouse作为时序数据库，针对高吞吐的推理事件进行了优化：

- `request_events`: 原始请求事件，支持亚秒级插入延迟
- `request_metrics`: 按团队和时间段聚合的延迟分布
- `vllm_system_metrics`: vLLM实例的系统级指标（队列长度、运行中任务数）

### 指标采集机制

网关以15秒为周期主动抓取vLLM的`/metrics`端点，将系统级指标（如调度队列深度、KV缓存利用率）纳入统一监控体系。这种双向采集（网关内部指标 + vLLM系统指标）确保了问题定位的全面性。

### Apple Silicon支持

针对Apple Silicon设备（M系列芯片），项目提供了专门的Metal后端支持：

```bash
curl -fsSL https://raw.githubusercontent.com/vllm-project/vllm-metal/main/install.sh | bash
./scripts/dev.sh metal
```

默认使用Qwen2.5-0.5B-Instruct和Qwen3-Embedding模型，支持通过环境变量覆盖配置。

## 部署与使用

### 快速启动

单配置文件（`config.yaml`）即可完成部署，Docker环境通过环境变量自动覆盖主机名配置，无需维护多套配置：

| 服务 | 地址 |
|------|------|
| Gateway | http://127.0.0.1:8080 |
| Grafana | http://127.0.0.1:3000 |
| Prometheus | http://127.0.0.1:9090 |

### 示例请求

```bash
curl -s -X POST http://127.0.0.1:8080/v1/completions \
  -H "Content-Type: application/json" \
  -H "X-Team-ID: engineering" \
  -d '{"model":"mock-model","prompt":"hi","max_tokens":10}'
```

### 预配置仪表板

项目提供两套Grafana仪表板：

- **Live (Prometheus)**: 实时网关指标，包括QPS、延迟分布、错误率
- **History (ClickHouse)**: 历史归因数据，支持按团队、项目、时间范围的多维分析

## 适用场景与价值

### 企业内部LLM平台

对于建设统一LLM服务中台的企业，vllm-gateway提供了关键的治理层能力：

- **FinOps**: 精确追踪各团队的推理支出，支持成本分摊和预算管控
- **性能SLA**: 基于TTFT和端到端延迟定义团队级服务等级协议
- **容量规划**: 基于历史使用模式预测资源需求

### 多租户SaaS场景

LLM即服务提供商可以利用网关实现：

- **用量计量**: 为每个客户生成详细的用量报告
- **限流控制**: 基于团队ID实施速率限制（可扩展功能）
- **故障隔离**: 快速识别异常流量的来源团队

### 研发效能优化

开发团队可以通过网关收集的数据：

- 识别高延迟的Prompt模式
- 优化Token使用效率
- 对比不同模型的性价比

## 技术选型思考

项目在技术栈选择上体现了务实的工程思维：

**Go语言**: 编译型语言的高性能特性，适合作为流量网关；静态二进制部署简化了运维。

**ClickHouse**: 针对时序数据的高压缩率和快速聚合能力，相比通用关系型数据库更适合监控场景。

**Prometheus + Grafana**: 云原生监控的事实标准，降低了学习成本和集成难度。

**配置即代码**: 单文件配置（config.yaml）和环境变量覆盖的组合，兼顾了简单场景和复杂部署的需求。

## 局限性与扩展方向

当前版本聚焦于核心归因和监控能力，以下功能可作为未来扩展：

- **速率限制**: 基于团队ID的令牌桶限流
- **缓存层**: 针对相似请求的响应缓存
- **A/B测试**: 支持按团队路由到不同模型版本
- **成本估算**: 基于Token数和模型单价实时估算成本

## 总结与建议

vllm-gateway填补了vLLM生态中企业级治理能力的空白。对于已经在使用vLLM但缺乏多租户成本归因的团队，这是一个可以立即落地的解决方案。

建议的采用路径：

1. **评估阶段**: 使用`./scripts/dev.sh mock`在本地体验完整功能
2. **试点部署**: 选择1-2个团队接入生产流量，验证指标准确性
3. **全面推广**: 建立基于网关数据的成本分摊和性能优化流程
4. **定制扩展**: 根据业务需求开发限流、缓存等增强功能

项目的开源协议（MIT）允许自由修改和商用，代码结构清晰（`cmd/gateway/` + `internal/{config,proxy,scraper,storage}/`），便于二次开发。