NVIDIA Sidecar 限流代理
为 NVIDIA API 提供优先级排队 + 令牌桶限流的透明代理层。
BIZ-46 Phase3: 架构解耦、Prometheus 标签治理、SSE 共享缓存、部署支撑、测试完善、Dashboard UX 优化。
生产部署入口： Docker 部署 | systemd 部署 | 防火墙配置 | 环境变量清单
快速启动
pip install .
nvidia-sidecar
监听 127.0.0.1:9190，代理到 NVIDIA API。
环境变量
| 变量 | 默认值 | 说明 |
|---|---|---|
SIDECAR_HOST |
127.0.0.1 |
监听地址 |
SIDECAR_PORT |
9190 |
监听端口 |
SIDECAR_METRICS_PORT |
9191 |
Metrics 端口 |
SIDECAR_UPSTREAM |
https://integrate.api.nvidia.com/v1 |
上游 API 地址 |
SIDECAR_API_KEY |
— | NVIDIA API Key（必填） |
SIDECAR_RATE_RPM |
40 |
每分钟请求数限制 |
SIDECAR_BUCKET_CAPACITY |
40 |
令牌桶容量 |
SIDECAR_TIMEOUT |
60 |
上游请求超时（秒） |
SIDECAR_QUEUE_MAX |
500 |
队列最大长度 |
SIDECAR_LOW_TIMEOUT |
2.0 |
低优先级令牌等待超时（秒） |
SIDECAR_FALLBACK_PASSTHROUGH |
true |
队列满时是否直通上游 |
SIDECAR_LOG_LEVEL |
INFO |
日志级别 |
YAML 配置
listen_port: 9292
rate_rpm: 60
upstream_api_key: "nvapi-xxx"
nvidia-sidecar --config /etc/nvidia-sidecar.yaml
API 端点
| 路径 | 方法 | 说明 |
|---|---|---|
/v1/chat/completions |
POST | OpenAI Chat Completions 代理 |
/v1/completions |
POST | OpenAI Completions 代理（legacy） |
/v1/embeddings |
POST | OpenAI Embeddings 代理 |
/v1/models |
GET | 模型列表代理 |
/health |
GET | 存活检查 (liveness) |
/health/ready |
GET | 就绪检查 (readiness，含上游连通性) |
/status |
GET | 调试用完整状态（限流器 + 队列 + 避退） |
/api/dashboard/stream |
GET | SSE 仪表盘实时推送 |
/api/dashboard |
GET | 仪表盘 HTML 页面 |
/api/admin/config |
GET/POST | 配置查询/热重载（需 Admin Token） |
/metrics |
:9191 | Prometheus 指标端点（独立端口） |
部署方式
Docker（推荐）
# 构建
docker build -t nvidia-sidecar:latest .
# 运行
docker run -d --name nvidia-sidecar \
-p 127.0.0.1:9190:9190 \
-p 127.0.0.1:9191:9191 \
-e SIDECAR_API_KEY="nvapi-xxx" \
nvidia-sidecar:latest
systemd
# 安装
sudo cp deploy/nvidia-sidecar.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable nvidia-sidecar
# 配置环境变量
sudo cp deploy/.env.example /opt/nvidia-sidecar/.env
sudo vim /opt/nvidia-sidecar/.env # 填入实际值
# 启动
sudo systemctl start nvidia-sidecar
sudo journalctl -u nvidia-sidecar -f # 查看日志
环境变量清单
详见 deploy/.env.example。
防火墙建议
# 仅允许内网访问代理端口
sudo ufw allow from 192.168.1.0/24 to any port 9190
sudo ufw allow from 192.168.1.0/24 to any port 9191
# 禁止外网访问
sudo ufw deny 9190
sudo ufw deny 9191
架构
请求 → 网关识别 → [NVIDIA: 优先级排队 → 令牌桶限流] → httpx → NVIDIA API
→ [非 NVIDIA: 直通] → httpx → 上游
- 四级优先级: URGENT > HIGH > NORMAL > LOW（通过
X-Priorityheader 指定） - 队列满策略: PASSTHROUGH（直通）/ REJECT（503）/ DROP_LOWEST（丢弃最低优先级）
- 令牌桶: 40 RPM，线程安全，支持阻塞/非阻塞消费