EnterpriseArchitect/services/nvidia_sidecar/README.md

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-Priority header 指定）
• 队列满策略: PASSTHROUGH（直通）/ REJECT（503）/ DROP_LOWEST（丢弃最低优先级）
• 令牌桶: 40 RPM，线程安全，支持阻塞/非阻塞消费