vincent
b18d243ef2
1. 架构解耦 — SidecarContext + FastAPI Depends 注入 - 新增 context.py: SidecarContext dataclass 收敛全部全局状态 - server.py: 移除模块级全局变量，lifespan 创建 ctx → app.state.sidecar - webui.py: 移除反向导入 server，改用 Depends(get_context) 2. Prometheus 标签基数治理 — model_id → provider - upstream_latency_seconds / upstream_errors_total label 收敛为 provider - 模型级信息保留在 structlog JSON 日志 3. SSE 快照共享缓存 - 1s TTL 共享 snapshot cache + double-check locking - 多客户端不重复构建快照 4. 部署支撑 - Dockerfile (python:3.12-slim, 非 root 用户, HEALTHCHECK) - systemd service (安全加固, 资源限制) - .env.example (完整环境变量清单) 5. Readiness HTTP Client 复用 - check_upstream() 注入主 http_client，不再每次创建新 client 6. Retreat 并发回归测试 - 5 个测试用例全部通过（死锁检测 + 状态转换 + 并发安全） 7. Dashboard UX 优化 - 队列柱状图 300ms 平滑动画 - SSE 断连 5s 半透明遮罩 - 队列图标题显示总排队数 - 页面加载同步配置 验证: mypy strict 通过 (0 errors), pytest 5/5 通过, server 导入正常 (13 routes) Co-authored-by: multica-agent <github@multica.ai>
118 lines
3.4 KiB
Markdown
118 lines
3.4 KiB
Markdown
# NVIDIA Sidecar 限流代理
|
||
|
||
为 NVIDIA API 提供**优先级排队 + 令牌桶限流**的透明代理层。
|
||
|
||
> BIZ-46 Phase3: 架构解耦、Prometheus 标签治理、SSE 共享缓存、部署支撑、测试完善、Dashboard UX 优化。
|
||
|
||
## 快速启动
|
||
|
||
```bash
|
||
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` | `6000` | 上游请求超时（秒） |
|
||
| `SIDECAR_QUEUE_MAX` | `500` | 队列最大长度 |
|
||
| `SIDECAR_LOW_TIMEOUT` | `2.0` | 低优先级令牌等待超时（秒） |
|
||
| `SIDECAR_FALLBACK_PASSTHROUGH` | `true` | 队列满时是否直通上游 |
|
||
| `SIDECAR_LOG_LEVEL` | `INFO` | 日志级别 |
|
||
|
||
## YAML 配置
|
||
|
||
```yaml
|
||
listen_port: 9292
|
||
rate_rpm: 60
|
||
upstream_api_key: "nvapi-xxx"
|
||
```
|
||
|
||
```bash
|
||
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（推荐）
|
||
|
||
```bash
|
||
# 构建
|
||
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
|
||
|
||
```bash
|
||
# 安装
|
||
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`。
|
||
|
||
### 防火墙建议
|
||
|
||
```bash
|
||
# 仅允许内网访问代理端口
|
||
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，线程安全，支持阻塞/非阻塞消费 |