Compare commits
4 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 vincent
|
a6f473f836 | ||
|
vincent
|
929f13b11f | ||
|
vincent
|
3071a29313 | ||
 opengineer
|
0326c87c00 |
@@ -0,0 +1,71 @@
|
||||
# OpenClaw NVIDIA 网关切换至 Metapi — 配置修改指南
|
||||
|
||||
> 交付人：严维序（opengineer） | 交付日期：2026-07-03 | 关联Issue：BIZ-76
|
||||
|
||||
## 当前状态
|
||||
|
||||
你的 `openclaw.json` 中有 **12 个 NVIDIA 独立提供者**，每个直连 `https://integrate.api.nvidia.com/v1`，使用各自的 `nvapi-*` API Key。
|
||||
|
||||
Metapi 已部署在 http://192.168.1.99:4000，内部聚合了全部 12 个 NVIDIA 账号，通过代理令牌 `sk-bizwings-metapi-proxy` 对外提供统一的 `/v1` 端点，自动负载均衡。
|
||||
|
||||
## 方案 A：逐项修改（保留 12 个提供者结构）
|
||||
|
||||
对每个 NVIDIA 提供者做两处替换：
|
||||
|
||||
### 1. 修改 `baseUrl`
|
||||
```
|
||||
"baseUrl": "https://integrate.api.nvidia.com/v1"
|
||||
→ "baseUrl": "http://192.168.1.99:4000/v1"
|
||||
```
|
||||
|
||||
### 2. 修改 `apiKey`
|
||||
```
|
||||
"apiKey": "nvapi-xxx..."
|
||||
→ "apiKey": "sk-bizwings-metapi-proxy"
|
||||
```
|
||||
|
||||
## 方案 B：合并为单个提供者（推荐，精简配置）
|
||||
|
||||
将 12 个 NVIDIA 提供者合并为 1 个：
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "nvidia-metapi",
|
||||
"name": "NVIDIA via Metapi",
|
||||
"kind": "openai",
|
||||
"baseUrl": "http://192.168.1.99:4000/v1",
|
||||
"apiKey": "sk-bizwings-metapi-proxy",
|
||||
"models": {
|
||||
"deepseek-ai/deepseek-v4-flash": {},
|
||||
"deepseek-ai/deepseek-v4-pro": {},
|
||||
"z-ai/glm-5.1": {},
|
||||
"z-ai/glm-5.2": {},
|
||||
"qwen/qwen3.5-397b-a17b": {},
|
||||
"nvidia/llama-3.3-nemotron-super-49b-v1": {},
|
||||
"nvidia/mississippi": {}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Metapi 已部署信息：
|
||||
- 访问地址：http://192.168.1.99:4000
|
||||
- 管理员令牌：`bizwings-metapi-admin`
|
||||
- 代理令牌：`sk-bizwings-metapi-proxy`
|
||||
- 端口：4000
|
||||
|
||||
## 12 个 NVIDIA 账户清单
|
||||
|
||||
| # | 账号 | 状态 |
|
||||
|---|------|------|
|
||||
| 1 | NVIDIA-NIM-default | ✅ active |
|
||||
| 2 | NVIDIA-NIM-98053 | ✅ active |
|
||||
| 3 | NVIDIA-NIM-liuweicheng84 | ✅ active |
|
||||
| 4 | NVIDIA-NIM-vx18088980513 | ✅ active |
|
||||
| 5 | NVIDIA-NIM-vx64391942 | ✅ active |
|
||||
| 6 | NVIDIA-NIM-cgtest1 | ✅ active |
|
||||
| 7 | NVIDIA-NIM-cgtest2 | ✅ active |
|
||||
| 8 | NVIDIA-NIM-cgtest3 | ✅ active |
|
||||
| 9 | NVIDIA-NIM-15876517651 | ✅ active |
|
||||
| 10 | NVIDIA-NIM-19584586741 | ✅ active |
|
||||
| 11 | NVIDIA-NIM-18874954146 | ✅ active |
|
||||
| 12 | NVIDIA-NIM-2405483110 | ✅ active |
|
||||
@@ -1,644 +0,0 @@
|
||||
# BIZ-46 Phase3: NVIDIA Sidecar Follow-up 架构设计
|
||||
|
||||
> **架构师**: 梁思筑 (architect)
|
||||
> **日期**: 2026-06-24
|
||||
> **状态**: 已批准，推进实施
|
||||
> **来源**: BIZ-42 Phase2 二轮评审 follow-up
|
||||
|
||||
---
|
||||
|
||||
## 1. 架构解耦 / 依赖注入 — SidecarContext
|
||||
|
||||
### 1.1 现状分析
|
||||
|
||||
当前 `server.py` 使用 **模块级全局变量** 管理所有核心组件：
|
||||
|
||||
```python
|
||||
# server.py 全局状态（当前）
|
||||
_config: SidecarConfig
|
||||
_http_client: httpx.AsyncClient
|
||||
_priority_queue: PriorityRequestQueue
|
||||
_token_bucket: AdaptiveTokenBucket
|
||||
_prometheus: PrometheusMetrics
|
||||
_health_service: HealthService
|
||||
_pending_requests: dict[str, tuple[asyncio.Future, float]]
|
||||
_stats: dict[str, int]
|
||||
_stats_lock: asyncio.Lock
|
||||
```
|
||||
|
||||
**问题**：
|
||||
- `webui.py` 通过 `from nvidia_sidecar import server` 反向导入全局变量（循环依赖风险）
|
||||
- 单元测试需要 mock 模块级变量，无法并行运行测试
|
||||
- 未来多实例/多租户扩展需重写全部模块访问逻辑
|
||||
|
||||
### 1.2 设计方案 — SidecarContext + FastAPI Dependency Injection
|
||||
|
||||
#### 1.2.1 核心数据结构
|
||||
|
||||
```python
|
||||
# context.py
|
||||
from dataclasses import dataclass, field
|
||||
import asyncio
|
||||
import httpx
|
||||
from typing import Any
|
||||
|
||||
@dataclass
|
||||
class SidecarContext:
|
||||
"""Sidecar 全局运行时上下文 — 所有核心组件的唯一容器。
|
||||
|
||||
通过 app.state.sidecar 注入 FastAPI，路由通过 Depends 获取。
|
||||
"""
|
||||
config: 'SidecarConfig'
|
||||
http_client: httpx.AsyncClient
|
||||
token_bucket: 'AdaptiveTokenBucket'
|
||||
priority_queue: 'PriorityRequestQueue'
|
||||
prometheus: 'PrometheusMetrics'
|
||||
health: 'HealthService'
|
||||
pending_requests: dict[str, tuple['asyncio.Future', float]] = field(default_factory=dict)
|
||||
stats: dict[str, int] = field(default_factory=lambda: {
|
||||
"total_requests": 0,
|
||||
"nvidia_requests": 0,
|
||||
"passthrough_requests": 0,
|
||||
"ratelimited_requests": 0,
|
||||
"queue_full_rejects": 0,
|
||||
"upstream_errors": 0,
|
||||
"start_time": 0,
|
||||
})
|
||||
stats_lock: asyncio.Lock = field(default_factory=asyncio.Lock)
|
||||
|
||||
async def increment_stat(self, key: str, delta: int = 1) -> None:
|
||||
"""线程安全的统计计数器自增。"""
|
||||
async with self.stats_lock:
|
||||
self.stats[key] = self.stats.get(key, 0) + delta
|
||||
```
|
||||
|
||||
#### 1.2.2 注入方式
|
||||
|
||||
```python
|
||||
# server.py — lifespan 中创建 context
|
||||
from nvidia_sidecar.context import SidecarContext
|
||||
|
||||
@asynccontextmanager
|
||||
async def lifespan(app: FastAPI):
|
||||
ctx = SidecarContext(
|
||||
config=load_config(),
|
||||
http_client=httpx.AsyncClient(...),
|
||||
token_bucket=AdaptiveTokenBucket(...),
|
||||
priority_queue=PriorityRequestQueue(...),
|
||||
prometheus=PrometheusMetrics(),
|
||||
health=HealthService(),
|
||||
)
|
||||
app.state.sidecar = ctx # 注入 FastAPI
|
||||
# ... worker 启动 ...
|
||||
yield
|
||||
# ... 清理 ...
|
||||
|
||||
# 依赖注入函数
|
||||
def get_context(request: Request) -> SidecarContext:
|
||||
return request.app.state.sidecar
|
||||
|
||||
# 路由使用
|
||||
@app.post("/v1/chat/completions")
|
||||
async def chat_completions(request: Request, ctx: SidecarContext = Depends(get_context)):
|
||||
return await _handle_proxy_request(request, "/v1/chat/completions", ctx)
|
||||
```
|
||||
|
||||
#### 1.2.3 webui.py 解耦
|
||||
|
||||
```python
|
||||
# webui.py — 不再反向导入 server
|
||||
from nvidia_sidecar.context import SidecarContext
|
||||
from fastapi import Depends
|
||||
|
||||
def get_webui_router():
|
||||
router = APIRouter(prefix="/api", tags=["webui"])
|
||||
|
||||
def _get_ctx(request: Request) -> SidecarContext:
|
||||
return request.app.state.sidecar
|
||||
|
||||
@router.get("/dashboard/stream")
|
||||
async def dashboard_stream(request: Request, ctx: SidecarContext = Depends(_get_ctx)):
|
||||
return await _dashboard_stream(request, ctx)
|
||||
|
||||
@router.get("/admin/config")
|
||||
async def admin_get_config(ctx: SidecarContext = Depends(_get_ctx)):
|
||||
return await get_config(ctx)
|
||||
|
||||
return router
|
||||
```
|
||||
|
||||
#### 1.2.4 Trade-off 分析
|
||||
|
||||
| 维度 | 当前（全局变量） | 方案A（SidecarContext） | 方案B（FastAPI Dependency 全函数式） |
|
||||
|------|------------------|------------------------|-------------------------------------|
|
||||
| 可测试性 | 差（需 mock 模块） | 好（注入 mock context） | 优（每个依赖独立注入） |
|
||||
| 改动量 | 无 | 中等（~8 文件） | 大（每个函数签名变更） |
|
||||
| 可读性 | 一般 | 好（ctx 一目了然） | 差（参数列表膨胀） |
|
||||
| 多实例支持 | 不支持 | 支持（多 app 多 ctx） | 支持 |
|
||||
| 循环依赖 | 有（webui→server） | 消除 | 消除 |
|
||||
|
||||
**决策**: 采用方案A（SidecarContext），平衡改动量与收益。
|
||||
|
||||
### 1.3 迁移计划
|
||||
|
||||
分 3 步渐进迁移，每步可独立合入：
|
||||
|
||||
1. **Step 1**: 创建 `context.py`，定义 `SidecarContext`，在 `lifespan` 中实例化并挂到 `app.state`
|
||||
2. **Step 2**: 路由函数改为 `Depends(get_context)`，删除模块级 `_config`、`_http_client` 等
|
||||
3. **Step 3**: `webui.py` 移除 `from nvidia_sidecar import server`，改用依赖注入
|
||||
|
||||
---
|
||||
|
||||
## 2. Prometheus 标签基数治理
|
||||
|
||||
### 2.1 现状
|
||||
|
||||
当前使用 `model_id` 作为 label 的指标：
|
||||
|
||||
| 指标 | Label | 风险 |
|
||||
|------|-------|------|
|
||||
| `sidecar_upstream_latency_seconds` | `model_id` | **高** — NVIDIA 模型名含版本号，可能无界增长 |
|
||||
| `sidecar_upstream_errors_total` | `status_code`, `model_id` | **中** — 组合基数 = 模型数 × 状态码数 |
|
||||
|
||||
### 2.2 基数评估
|
||||
|
||||
NVIDIA API 当前已知模型约 20-30 个，但：
|
||||
- 新模型持续发布（每月 2-5 个）
|
||||
- 模型名含版本后缀（`nvidia/deepseek-ai/deepseek-v4-pro`、`nvidia/llama-3.1-70b-instruct` 等）
|
||||
- 长期运行（6 个月+）可能累积 100+ 标签组合
|
||||
|
||||
**结论**: 当前基数可控（<200 组合），但长期存在膨胀风险，应提前治理。
|
||||
|
||||
### 2.3 治理方案
|
||||
|
||||
| 指标 | 当前 Label | 调整后 Label | 理由 |
|
||||
|------|-----------|-------------|------|
|
||||
| `upstream_latency_seconds` | `model_id` | `provider` | provider 固定为 `nvidia`，基数=1 |
|
||||
| `upstream_errors_total` | `status_code`, `model_id` | `status_code`, `provider` | 同上 |
|
||||
|
||||
**模型级信息迁移路径**：
|
||||
- 模型 ID → 结构化 JSON 日志（structlog 已支持）
|
||||
- 需要模型级延迟分析时 → 临时 `/status` API 查询或日志聚合
|
||||
|
||||
```python
|
||||
# metrics.py 调整
|
||||
self.upstream_latency_seconds: Histogram = Histogram(
|
||||
"sidecar_upstream_latency_seconds",
|
||||
"Upstream response latency in seconds",
|
||||
labelnames=["provider"], # 原: ["model_id"]
|
||||
buckets=(...),
|
||||
)
|
||||
|
||||
self.upstream_errors_total: Counter = Counter(
|
||||
"sidecar_upstream_errors_total",
|
||||
"Upstream error count by status code",
|
||||
labelnames=["status_code", "provider"], # 原: ["status_code", "model_id"]
|
||||
)
|
||||
```
|
||||
|
||||
```python
|
||||
# server.py 调整 — 模型信息改记日志
|
||||
model_id = _extract_model(payload) or "unknown"
|
||||
provider = "nvidia" # 固定值，因为只有 NVIDIA 请求走 worker
|
||||
_prometheus.record_upstream_latency(provider, upstream_latency)
|
||||
if not resp.is_success:
|
||||
_prometheus.record_upstream_error(resp.status_code, provider)
|
||||
logger.info("request_completed", model_id=model_id, ...) # JSON 日志保留模型信息
|
||||
```
|
||||
|
||||
### 2.4 Trade-off
|
||||
|
||||
| 维度 | 保留 model_id | 收敛为 provider |
|
||||
|------|--------------|----------------|
|
||||
| 基数风险 | 高（无界） | 无（固定=1） |
|
||||
| 模型级分析 | Prometheus 原生查询 | 需日志聚合 |
|
||||
| 迁移成本 | 无 | 低（改 2 个指标定义 + 调用点） |
|
||||
|
||||
**决策**: 收敛为 `provider`，模型级分析通过 JSON 日志 + 日志聚合系统（ELK/Loki）完成。
|
||||
|
||||
---
|
||||
|
||||
## 3. SSE 快照共享缓存
|
||||
|
||||
### 3.1 现状
|
||||
|
||||
每个 SSE 客户端每秒独立调用 `_build_snapshot()`，该方法：
|
||||
- 获取 `_stats` 字典（需锁）
|
||||
- 调用 `_token_bucket.get_status()`（需锁）
|
||||
- 调用 `_priority_queue.get_stats()`（需 asyncio.Lock）
|
||||
|
||||
当 N 个仪表盘同时打开时，每秒 N 次锁竞争 + N 次重复计算。
|
||||
|
||||
### 3.2 设计方案 — 1s TTL 共享缓存
|
||||
|
||||
```python
|
||||
# webui.py
|
||||
_snapshot_cache: tuple[dict[str, Any], float] | None = None # (data, timestamp)
|
||||
_snapshot_lock: asyncio.Lock = asyncio.Lock()
|
||||
_SNAPSHOT_TTL: float = 1.0 # 1 秒 TTL
|
||||
|
||||
async def _build_snapshot_cached(ctx: SidecarContext) -> dict[str, Any]:
|
||||
"""带 1s TTL 的共享快照缓存。
|
||||
|
||||
多个 SSE 客户端共享同一份快照，避免重复计算和锁竞争。
|
||||
"""
|
||||
global _snapshot_cache
|
||||
|
||||
now = time.monotonic()
|
||||
if _snapshot_cache is not None:
|
||||
data, ts = _snapshot_cache
|
||||
if now - ts < _SNAPSHOT_TTL:
|
||||
return data
|
||||
|
||||
async with _snapshot_lock:
|
||||
# Double-check（避免多个协程同时 miss 后重复构建）
|
||||
if _snapshot_cache is not None:
|
||||
data, ts = _snapshot_cache
|
||||
if now - ts < _SNAPSHOT_TTL:
|
||||
return data
|
||||
|
||||
snapshot = await _build_snapshot(ctx)
|
||||
_snapshot_cache = (snapshot, now)
|
||||
return snapshot
|
||||
```
|
||||
|
||||
### 3.3 性能收益
|
||||
|
||||
| 场景 | 当前 | 优化后 |
|
||||
|------|------|--------|
|
||||
| 1 客户端 | 1 次/s 计算 | 1 次/s 计算（无变化） |
|
||||
| 5 客户端 | 5 次/s 计算，5 次锁竞争 | 1 次/s 计算，1 次锁竞争 |
|
||||
| 20 客户端 | 20 次/s 计算，20 次锁竞争 | 1 次/s 计算，1 次锁竞争 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 部署支撑
|
||||
|
||||
### 4.1 Dockerfile
|
||||
|
||||
```dockerfile
|
||||
# services/nvidia_sidecar/Dockerfile
|
||||
FROM python:3.12-slim AS base
|
||||
|
||||
WORKDIR /app
|
||||
|
||||
# 安装依赖（利用 Docker 层缓存）
|
||||
COPY pyproject.toml .
|
||||
RUN pip install --no-cache-dir -e .
|
||||
|
||||
# 复制源码
|
||||
COPY . .
|
||||
|
||||
# 非 root 用户运行
|
||||
RUN useradd -r -s /bin/false sidecar
|
||||
USER sidecar
|
||||
|
||||
# 健康检查
|
||||
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
|
||||
CMD python -c "import httpx; r=httpx.get('http://127.0.0.1:9190/health'); exit(0 if r.status_code==200 else 1)"
|
||||
|
||||
EXPOSE 9190 9191
|
||||
|
||||
CMD ["uvicorn", "nvidia_sidecar.server:app", "--host", "0.0.0.0", "--port", "9190"]
|
||||
```
|
||||
|
||||
### 4.2 systemd Service
|
||||
|
||||
```ini
|
||||
# services/nvidia_sidecar/deploy/nvidia-sidecar.service
|
||||
[Unit]
|
||||
Description=NVIDIA Sidecar Rate-Limiting Proxy
|
||||
After=network-online.target
|
||||
Wants=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=sidecar
|
||||
Group=sidecar
|
||||
WorkingDirectory=/opt/nvidia-sidecar
|
||||
ExecStart=/opt/nvidia-sidecar/.venv/bin/uvicorn nvidia_sidecar.server:app \
|
||||
--host 127.0.0.1 \
|
||||
--port 9190 \
|
||||
--log-level info
|
||||
Restart=always
|
||||
RestartSec=5
|
||||
|
||||
# 环境变量
|
||||
EnvironmentFile=/opt/nvidia-sidecar/.env
|
||||
|
||||
# 安全加固
|
||||
NoNewPrivileges=true
|
||||
ProtectSystem=strict
|
||||
ProtectHome=true
|
||||
PrivateTmp=true
|
||||
ReadWritePaths=/opt/nvidia-sidecar/logs
|
||||
|
||||
# 资源限制
|
||||
LimitNOFILE=65536
|
||||
MemoryMax=512M
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
### 4.3 环境变量清单
|
||||
|
||||
| 变量 | 默认值 | 说明 |
|
||||
|------|--------|------|
|
||||
| `SIDECAR_HOST` | `127.0.0.1` | 监听地址 |
|
||||
| `SIDECAR_PORT` | `9190` | 代理端口 |
|
||||
| `SIDECAR_METRICS_PORT` | `9191` | Prometheus 指标端口 |
|
||||
| `SIDECAR_UPSTREAM` | `https://integrate.api.nvidia.com/v1` | 上游 API |
|
||||
| `SIDECAR_API_KEY` | (必填) | NVIDIA API Key |
|
||||
| `SIDECAR_RATE_RPM` | `40` | 限流速率 (RPM) |
|
||||
| `SIDECAR_BUCKET_CAPACITY` | `40` | 令牌桶容量 |
|
||||
| `SIDECAR_TIMEOUT` | `60` | 请求超时 (秒) |
|
||||
| `SIDECAR_QUEUE_MAX` | `500` | 队列最大容量 |
|
||||
| `SIDECAR_LOW_TIMEOUT` | `2` | 低优先级超时 (秒) |
|
||||
| `SIDECAR_FALLBACK_PASSTHROUGH` | `true` | 队列满时是否直通 |
|
||||
| `SIDECAR_LOG_LEVEL` | `INFO` | 日志级别 |
|
||||
| `SIDECAR_ADMIN_TOKEN` | (可选) | Admin API 认证 Token |
|
||||
|
||||
### 4.4 防火墙建议
|
||||
|
||||
```
|
||||
# 仅允许内网访问代理端口
|
||||
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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Readiness HTTP Client 复用
|
||||
|
||||
### 5.1 现状
|
||||
|
||||
`HealthService.check_upstream()` 每次调用创建新的 `httpx.AsyncClient`：
|
||||
|
||||
```python
|
||||
# health.py — 当前
|
||||
async def check_upstream(self, upstream_url: str, timeout: float = 5.0, api_key: str = "") -> bool:
|
||||
async with httpx.AsyncClient(timeout=timeout) as client: # 每次新建！
|
||||
resp = await client.get(...)
|
||||
```
|
||||
|
||||
K8s/systemd 每 10-30s 探测一次，每次创建+销毁 HTTP client 带来不必要的 TCP 连接开销。
|
||||
|
||||
### 5.2 方案 — 复用主 http_client
|
||||
|
||||
```python
|
||||
# health.py — 优化后
|
||||
async def check_upstream(
|
||||
self,
|
||||
upstream_url: str,
|
||||
http_client: httpx.AsyncClient, # 注入主 client
|
||||
api_key: str = "",
|
||||
timeout: float = 5.0,
|
||||
) -> bool:
|
||||
try:
|
||||
headers = {}
|
||||
if api_key:
|
||||
headers["authorization"] = f"Bearer {api_key}"
|
||||
resp = await http_client.get(
|
||||
f"{upstream_url.rstrip('/')}/v1/models",
|
||||
headers=headers,
|
||||
timeout=timeout,
|
||||
)
|
||||
return resp.status_code < 500
|
||||
except Exception:
|
||||
return False
|
||||
```
|
||||
|
||||
```python
|
||||
# server.py — 路由调用处
|
||||
@app.get("/health/ready")
|
||||
async def health_ready(ctx: SidecarContext = Depends(get_context)):
|
||||
queue_size = await ctx.priority_queue.get_queue_size()
|
||||
bucket_status = ctx.token_bucket.get_status()
|
||||
return await ctx.health.readiness(
|
||||
upstream_url=ctx.config.upstream_url,
|
||||
http_client=ctx.http_client, # 复用主 client
|
||||
upstream_api_key=ctx.config.upstream_api_key or "",
|
||||
queue_current_size=queue_size,
|
||||
queue_max_size=ctx.config.queue_max_size,
|
||||
available_tokens=bucket_status["tokens"],
|
||||
bucket_capacity=bucket_status["capacity"],
|
||||
)
|
||||
```
|
||||
|
||||
**注意**: readiness 检查使用较短 timeout (5s)，不影响主代理请求的 timeout 配置。httpx 支持per-request timeout 覆盖。
|
||||
|
||||
---
|
||||
|
||||
## 6. Retreat 并发/死锁回归测试
|
||||
|
||||
### 6.1 风险点
|
||||
|
||||
`AdaptiveTokenBucket` 有两把锁：
|
||||
- `_lock` (Lock): 保护令牌消费/补充
|
||||
- `_retreat_lock` (RLock): 保护避退状态机
|
||||
|
||||
潜在死锁路径：
|
||||
1. `evaluate_retreat()` 持有 `_retreat_lock` → 调用 `get_429_rate()` (也获取 `_retreat_lock`，RLock 可重入 ✅)
|
||||
2. `evaluate_retreat()` → `_apply_retreat()` → `set_rate()` → 获取 `_lock` (另一把锁)
|
||||
3. Worker 线程: `consume()` 持有 `_lock` → 不调用 `_retreat_lock` (无交叉 ✅)
|
||||
|
||||
当前设计使用 RLock 已规避了重入死锁，但需要回归测试确保未来修改不引入死锁。
|
||||
|
||||
### 6.2 测试用例
|
||||
|
||||
```python
|
||||
# tests/test_retreat_concurrency.py
|
||||
import pytest
|
||||
import asyncio
|
||||
import threading
|
||||
from nvidia_sidecar.rate_limiter import AdaptiveTokenBucket, RetreatState
|
||||
|
||||
class TestRetreatConcurrency:
|
||||
"""避退模式并发安全回归测试。"""
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_concurrent_record_and_evaluate(self):
|
||||
"""多线程同时 record_response + evaluate_retreat 不死锁。"""
|
||||
bucket = AdaptiveTokenBucket(rate=40/60, capacity=40)
|
||||
errors: list[Exception] = []
|
||||
|
||||
def worker_record():
|
||||
for i in range(1000):
|
||||
try:
|
||||
bucket.record_response(is_429=(i % 10 == 0))
|
||||
except Exception as e:
|
||||
errors.append(e)
|
||||
|
||||
def worker_evaluate():
|
||||
for _ in range(1000):
|
||||
try:
|
||||
bucket.evaluate_retreat()
|
||||
except Exception as e:
|
||||
errors.append(e)
|
||||
|
||||
threads = [
|
||||
threading.Thread(target=worker_record),
|
||||
threading.Thread(target=worker_record),
|
||||
threading.Thread(target=worker_evaluate),
|
||||
threading.Thread(target=worker_evaluate),
|
||||
]
|
||||
for t in threads:
|
||||
t.start()
|
||||
for t in threads:
|
||||
t.join(timeout=10)
|
||||
|
||||
# 所有线程必须在 10s 内完成（无死锁）
|
||||
assert all(not t.is_alive() for t in threads), "线程未完成，疑似死锁"
|
||||
assert not errors, f"并发错误: {errors}"
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_concurrent_consume_and_retreat(self):
|
||||
"""多线程同时 consume + evaluate_retreat 不死锁。"""
|
||||
bucket = AdaptiveTokenBucket(rate=40/60, capacity=40)
|
||||
errors: list[Exception] = []
|
||||
|
||||
def worker_consume():
|
||||
for _ in range(500):
|
||||
try:
|
||||
bucket.consume(tokens=1)
|
||||
except Exception as e:
|
||||
errors.append(e)
|
||||
|
||||
def worker_retreat():
|
||||
for _ in range(500):
|
||||
try:
|
||||
bucket.record_response(is_429=False)
|
||||
bucket.evaluate_retreat()
|
||||
except Exception as e:
|
||||
errors.append(e)
|
||||
|
||||
threads = [
|
||||
threading.Thread(target=worker_consume),
|
||||
threading.Thread(target=worker_consume),
|
||||
threading.Thread(target=worker_retreat),
|
||||
threading.Thread(target=worker_retreat),
|
||||
]
|
||||
for t in threads:
|
||||
t.start()
|
||||
for t in threads:
|
||||
t.join(timeout=10)
|
||||
|
||||
assert all(not t.is_alive() for t in threads), "线程未完成，疑似死锁"
|
||||
assert not errors, f"并发错误: {errors}"
|
||||
|
||||
def test_retreat_state_transitions_under_load(self):
|
||||
"""高负载下避退状态转换正确。"""
|
||||
bucket = AdaptiveTokenBucket(
|
||||
rate=40/60, capacity=40,
|
||||
retreat_429_threshold=0.05,
|
||||
retreat_factor=0.75,
|
||||
)
|
||||
|
||||
# 模拟高 429 率
|
||||
for _ in range(100):
|
||||
bucket.record_response(is_429=True)
|
||||
|
||||
state = bucket.evaluate_retreat()
|
||||
assert state == RetreatState.RETREAT
|
||||
assert bucket.get_effective_rate_rpm() < bucket.get_base_rate_rpm()
|
||||
|
||||
# 模拟恢复
|
||||
for _ in range(200):
|
||||
bucket.record_response(is_429=False)
|
||||
|
||||
# 需要等待 RECOVER_WINDOW
|
||||
import time
|
||||
time.sleep(0.1) # 确保时间窗口过去
|
||||
bucket._last_state_change = 0 # 强制触发时间条件
|
||||
state = bucket.evaluate_retreat()
|
||||
assert state in (RetreatState.RECOVER, RetreatState.NORMAL)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Dashboard UX 优化
|
||||
|
||||
### 7.1 优化项清单
|
||||
|
||||
| # | 优化项 | 实现方式 | 优先级 |
|
||||
|---|--------|---------|--------|
|
||||
| 1 | 队列柱状图 300ms 平滑动画 | CSS `transition: height 300ms ease` | P1 |
|
||||
| 2 | SSE 断连 5s 遮罩 | JS 定时器 + DOM 遮罩层 | P1 |
|
||||
| 3 | 队列图标题显示总排队数 | SSE 数据已有 `current_size`，更新标题 | P2 |
|
||||
| 4 | 页面加载同步配置 | `fetch('/api/admin/config')` 初始化表单 | P2 |
|
||||
|
||||
### 7.2 关键实现
|
||||
|
||||
```javascript
|
||||
// dashboard.html — SSE 断连检测
|
||||
let lastSSETime = Date.now();
|
||||
let reconnectMask = document.getElementById('reconnect-mask');
|
||||
|
||||
eventSource.onmessage = (event) => {
|
||||
lastSSETime = Date.now();
|
||||
reconnectMask.style.display = 'none';
|
||||
// ... 更新 UI ...
|
||||
};
|
||||
|
||||
// 5s 无数据 → 显示遮罩
|
||||
setInterval(() => {
|
||||
if (Date.now() - lastSSETime > 5000) {
|
||||
reconnectMask.style.display = 'flex';
|
||||
}
|
||||
}, 1000);
|
||||
|
||||
// 队列柱状图动画
|
||||
// CSS: .queue-bar { transition: height 0.3s ease; }
|
||||
```
|
||||
|
||||
```javascript
|
||||
// 页面加载时同步配置
|
||||
async function loadConfig() {
|
||||
try {
|
||||
const resp = await fetch('/api/admin/config');
|
||||
if (resp.ok) {
|
||||
const config = await resp.json();
|
||||
document.getElementById('rate-rpm').value = config.rate_rpm;
|
||||
document.getElementById('queue-max').value = config.queue_max_size;
|
||||
// ...
|
||||
}
|
||||
} catch (e) {
|
||||
console.warn('配置加载失败（可能需要 Admin Token）', e);
|
||||
}
|
||||
}
|
||||
loadConfig();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 实施排期
|
||||
|
||||
| 阶段 | 内容 | 预估工时 | 依赖 |
|
||||
|------|------|---------|------|
|
||||
| **D1** | SidecarContext Step 1-3（解耦迁移） | 8h | 无 |
|
||||
| **D2** | Prometheus 标签收敛 + 日志增强 | 2h | D1 |
|
||||
| **D2** | SSE 共享缓存 | 2h | D1 |
|
||||
| **D2** | Readiness HTTP client 复用 | 1h | D1 |
|
||||
| **D3** | Dockerfile + systemd service | 2h | 无 |
|
||||
| **D3** | Dashboard UX 优化 | 3h | 无 |
|
||||
| **D3** | Retreat 并发回归测试 | 3h | 无 |
|
||||
| **D4** | 集成测试 + mypy strict | 4h | D1-D3 |
|
||||
| **合计** | | **25h** | |
|
||||
|
||||
---
|
||||
|
||||
## 9. 验收标准映射
|
||||
|
||||
| Issue 要求 | 本文档章节 | 状态 |
|
||||
|-----------|-----------|------|
|
||||
| SidecarContext / DI 方案落地或 ADR | §1 | ✅ 详细设计 + 迁移计划 |
|
||||
| Prometheus 高基数 label 收敛 | §2 | ✅ 收敛为 provider |
|
||||
| SSE snapshot 共享缓存 | §3 | ✅ 1s TTL 设计 |
|
||||
| Dockerfile + systemd + 部署 SOP | §4 | ✅ 完整文件 |
|
||||
| readiness 复用 HTTP client | §5 | ✅ 注入主 client |
|
||||
| retreat 并发/死锁回归测试 | §6 | ✅ 测试用例 |
|
||||
| Dashboard UX 细节 | §7 | ✅ 4 项优化 |
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,178 @@
|
||||
# 双色球系统部署文档
|
||||
|
||||
## 部署信息
|
||||
|
||||
| 项目 | 值 |
|
||||
|------|-----|
|
||||
| 项目名称 | 双色球自动化系统 |
|
||||
| 部署时间 | 2026-06-29 |
|
||||
| 部署人员 | 严维序 (opengineer) |
|
||||
| 服务地址 | http://192.168.1.99:5000 |
|
||||
| 宿主服务器 | Ubuntu-OpenClaw (192.168.1.99) |
|
||||
|
||||
---
|
||||
|
||||
## 一、项目结构
|
||||
|
||||
```
|
||||
/home/vincent/Studio/lottoData/
|
||||
├── venv/ # Python 虚拟环境
|
||||
├── web_executor.py # Flask Web 服务 (监听 0.0.0.0:5000)
|
||||
├── fetch_data.py # 数据抓取脚本
|
||||
├── lottery.py # 双色球号码生成器
|
||||
├── web_console.html # Web 控制台页面
|
||||
├── LottoSpider/ # 爬虫模块
|
||||
├── lottery/ # 彩票模块
|
||||
├── docs/ # 文档
|
||||
├── 双色球历史数据.xlsx # 历史数据文件
|
||||
└── deploy/ # 部署文件
|
||||
├── DEPLOY.md # 本文档
|
||||
├── lotto-web.service # systemd 服务文件
|
||||
├── fetch_daily.sh # 每日抓取脚本
|
||||
├── cron.log # Cron 执行日志
|
||||
└── fetch_YYYYMMDD.log # 每日抓取详细日志
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 二、依赖清单
|
||||
|
||||
| 包 | 版本 | 用途 |
|
||||
|----|------|------|
|
||||
| Flask | 3.1.3 | Web 服务框架 |
|
||||
| pandas | 3.0.4 | 数据处理 |
|
||||
| openpyxl | 3.1.5 | Excel 读写 |
|
||||
| requests | 2.34.2 | HTTP 请求 |
|
||||
| beautifulsoup4 | 4.15.0 | HTML 解析 |
|
||||
|
||||
安装命令：
|
||||
```bash
|
||||
python3 -m venv venv
|
||||
./venv/bin/pip install flask pandas openpyxl requests beautifulsoup4
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、systemd 服务配置
|
||||
|
||||
### 服务文件
|
||||
|
||||
`/etc/systemd/system/lotto-web.service`
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=双色球数据抓取 Web 服务
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=vincent
|
||||
WorkingDirectory=/home/vincent/Studio/lottoData
|
||||
ExecStart=/home/vincent/Studio/lottoData/venv/bin/python3 /home/vincent/Studio/lottoData/web_executor.py
|
||||
ExecStartPre=/home/vincent/Studio/lottoData/venv/bin/python3 -c "import flask; import pandas; import openpyxl; import requests; import bs4"
|
||||
Restart=on-failure
|
||||
RestartSec=5
|
||||
KillMode=control-group
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
### 管理命令
|
||||
|
||||
```bash
|
||||
# 安装/启用
|
||||
sudo cp deploy/lotto-web.service /etc/systemd/system/
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable lotto-web
|
||||
sudo systemctl start lotto-web
|
||||
|
||||
# 日常管理
|
||||
sudo systemctl status lotto-web # 查看状态
|
||||
sudo systemctl restart lotto-web # 重启
|
||||
sudo systemctl stop lotto-web # 停止
|
||||
sudo journalctl -u lotto-web -f # 查看实时日志
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、Cron 定时任务
|
||||
|
||||
### Cron 配置
|
||||
|
||||
```
|
||||
30 2 * * * /home/vincent/Studio/lottoData/deploy/fetch_daily.sh >> /home/vincent/Studio/lottoData/deploy/cron.log 2>&1
|
||||
```
|
||||
|
||||
每天凌晨 2:30 自动抓取双色球历史数据。
|
||||
|
||||
### 手动执行
|
||||
|
||||
```bash
|
||||
/home/vincent/Studio/lottoData/deploy/fetch_daily.sh
|
||||
# 或
|
||||
/home/vincent/Studio/lottoData/venv/bin/python3 /home/vincent/Studio/lottoData/fetch_data.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、Web 接口
|
||||
|
||||
| 路径 | 方法 | 说明 |
|
||||
|------|------|------|
|
||||
| `/` | GET | Web 控制台页面 |
|
||||
| `/api/status` | GET | 获取执行状态 |
|
||||
| `/api/execute` | POST | 触发数据抓取 |
|
||||
|
||||
### 示例
|
||||
|
||||
```bash
|
||||
# 查看状态
|
||||
curl http://192.168.1.99:5000/api/status
|
||||
|
||||
# 触发抓取
|
||||
curl -X POST http://192.168.1.99:5000/api/execute
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 六、验证清单
|
||||
|
||||
- [x] 依赖安装完整 (Flask, pandas, openpyxl, requests, beautifulsoup4)
|
||||
- [x] systemd 服务运行正常 (active, enabled)
|
||||
- [x] Web 服务可访问 (http://192.168.1.99:5000, HTTP 200)
|
||||
- [x] API 接口正常 (/api/status, /api/execute)
|
||||
- [x] Cron 定时任务已配置 (每日 2:30 抓取)
|
||||
- [x] 手动抓取测试通过 (121 条记录保存成功)
|
||||
- [x] 开机自启已配置 (systemd enable)
|
||||
|
||||
---
|
||||
|
||||
## 七、回滚方案
|
||||
|
||||
```bash
|
||||
# 停止服务
|
||||
sudo systemctl stop lotto-web
|
||||
sudo systemctl disable lotto-web
|
||||
sudo rm /etc/systemd/system/lotto-web.service
|
||||
sudo systemctl daemon-reload
|
||||
|
||||
# 移除 cron
|
||||
crontab -l | grep -v 'lottoData' | crontab -
|
||||
|
||||
# 不影响数据文件和代码
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 八、监控要点
|
||||
|
||||
1. **服务存活**：`systemctl status lotto-web` 确认 active
|
||||
2. **Web 可达**：`curl http://127.0.0.1:5000/api/status`
|
||||
3. **数据更新**：检查 `/home/vincent/Studio/lottoData/双色球历史数据.xlsx` 修改时间
|
||||
4. **Cron 日志**：检查 `/home/vincent/Studio/lottoData/deploy/cron.log`
|
||||
5. **磁盘空间**：Excel 文件约 250KB，可忽略
|
||||
|
||||
---
|
||||
|
||||
> 部署人：严维序 (opengineer) | 2026-06-29
|
||||
Executable
+17
@@ -0,0 +1,17 @@
|
||||
#!/bin/bash
|
||||
# 双色球历史数据每日自动抓取
|
||||
# Cron: 0 2 * * * /home/vincent/Studio/lottoData/deploy/fetch_daily.sh >> /home/vincent/Studio/lottoData/deploy/cron.log 2>&1
|
||||
|
||||
SCRIPT_DIR="/home/vincent/Studio/lottoData"
|
||||
VENV_PYTHON="${SCRIPT_DIR}/venv/bin/python3"
|
||||
FETCH_SCRIPT="${SCRIPT_DIR}/fetch_data.py"
|
||||
LOG_DIR="${SCRIPT_DIR}/deploy"
|
||||
LOG_FILE="${LOG_DIR}/fetch_$(date +%Y%m%d).log"
|
||||
|
||||
mkdir -p "${LOG_DIR}"
|
||||
|
||||
echo "=== $(date '+%Y-%m-%d %H:%M:%S') 开始执行双色球数据抓取 ==="
|
||||
"${VENV_PYTHON}" "${FETCH_SCRIPT}" >> "${LOG_FILE}" 2>&1
|
||||
RC=$?
|
||||
echo "=== $(date '+%Y-%m-%d %H:%M:%S') 执行完成, exit code=${RC} ==="
|
||||
exit ${RC}
|
||||
@@ -0,0 +1,16 @@
|
||||
[Unit]
|
||||
Description=双色球数据抓取 Web 服务
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=vincent
|
||||
WorkingDirectory=/home/vincent/Studio/lottoData
|
||||
ExecStart=/home/vincent/Studio/lottoData/venv/bin/python3 /home/vincent/Studio/lottoData/web_executor.py
|
||||
ExecStartPre=/home/vincent/Studio/lottoData/venv/bin/python3 -c "import flask; import pandas; import openpyxl; import requests; import bs4"
|
||||
Restart=on-failure
|
||||
RestartSec=5
|
||||
KillMode=control-group
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
@@ -0,0 +1,5 @@
|
||||
Flask==3.1.3
|
||||
pandas==3.0.4
|
||||
openpyxl==3.1.5
|
||||
requests==2.34.2
|
||||
beautifulsoup4==4.15.0
|
||||
@@ -0,0 +1,446 @@
|
||||
# 石斛固态食品与烘焙全品类扩展可行性分析报告
|
||||
|
||||
**编号**：BIZ-65
|
||||
**报告类型**：产品扩展可行性分析
|
||||
**分析日期**：2026年6月26日
|
||||
**分析人**：顾析策（市场分析师）
|
||||
**参考文档**：石斛食品饮料全品类产品方向详细文档、BIZ-53 品斛堂企业情报调研报告、BIZ-55 电商调研
|
||||
|
||||
---
|
||||
|
||||
## 摘要
|
||||
|
||||
**核心结论**：品斛堂以石斛为根基向固态食品扩展具备明确可行性。5个子品类中，**膏滋蜜炼和压片糖果为最高优先级**——前者依托品斛堂石斛浸膏技术壁垒和中药膏方100亿+市场，后者复用现有石斛精片基础切入全球485亿美元功能性糖果赛道。OEM/ODM模式是核心实现路径——品斛堂已有为近100家企业代工石斛精片/饼干/面条/果冻/浸膏的经验，固态食品扩展应优先走"自有品牌试水+OEM/ODM双轨并行"策略。
|
||||
|
||||
**关键数据**：
|
||||
- 功能性压片糖果亚太区CAGR 12.6%，中国本土企业TOP5市占率39.4%
|
||||
- 中药膏滋/煎膏剂100亿+市场（2024），补气补血类占50%+，院内市场同比增长17.2%
|
||||
- 中国烘焙市场2595亿元（2025欧睿），人均消费25.5美元仅为日本1/6
|
||||
- 果冻市场200-250亿元，功能型果冻增速最快
|
||||
- **品斛堂OEM能力已覆盖石斛精片/饼干/面条/果冻/浸膏全品类**
|
||||
|
||||
**TOP5推荐**：①膏滋蜜炼（石斛膏方→差异化壁垒）②压片糖果/含片（高频+功能性+复用基础）③烘焙饼干/节日烘焙（高潜力+代工成熟）④休闲零食（坚果蜜饯→OEM快起量）⑤果冻布丁（功能型差异化切入）
|
||||
|
||||
---
|
||||
|
||||
## 一、压片糖果/咀嚼片
|
||||
|
||||
### 1.1 市场规模与趋势
|
||||
|
||||
| 指标 | 数据 | 来源 |
|
||||
|------|------|------|
|
||||
| 全球压片糖果市场 | $485亿（2025）→ $512亿（2026E） | ZVZO消费观察 |
|
||||
| 中国市场占比 | 22.7%，约$110亿（¥780亿） | ZVZO消费观察 |
|
||||
| 中国糖果市场总规模 | ¥930亿（2024） | 华经产业研究院 |
|
||||
| 功能性糖果CAGR | 12.6%（亚太区） | ZVZO消费观察 |
|
||||
| 药用糖果全球市场 | $63.9亿（2025）→ $91.6亿（2035E） | Global Growth Insights |
|
||||
| 中国增速 | 8.3%以上，显著高于全球4.1% | ZVZO消费观察 |
|
||||
| 功能性品类占比预测 | 将超过55%（2030E） | ZVZO消费观察 |
|
||||
|
||||
**核心趋势**：
|
||||
- 63%消费者将"健康属性"列为购买第一考虑因素，免疫力提升（34%）、口腔清新（27%）、能量补充（21%）为TOP3诉求
|
||||
- 无糖/低糖产品渗透率将突破70%
|
||||
- 线上销售占比44.6%，直播电商+社区团购贡献线上增量57%
|
||||
- 年轻化："零食化+功效化"方向，年轻群体对便携小包装接受度71%
|
||||
|
||||
### 1.2 竞争格局
|
||||
|
||||
| 梯队 | 代表品牌 | 定位 | 核心优势 |
|
||||
|------|------|------|------|
|
||||
| 🥇 功能型龙头 | 金嗓子、西瓜霜 | 润喉利咽 | 渠道铺货广，OTC背书 |
|
||||
| 🥇 药企延伸 | 同仁堂、修正、江中 | 中药功能含片 | 品牌信任，药房渠道 |
|
||||
| 🥈 保健品跨界 | 汤臣倍健、养生堂 | 维C/益生菌咀嚼片 | 品牌力+电商运营强 |
|
||||
| 🥉 新锐品牌 | 各OEM代工品牌 | 差异化功能 | 直播电商切入快 |
|
||||
|
||||
**竞争特点**：
|
||||
- 传统龙头金嗓子/西瓜霜品牌老化，市场增长缓慢（传统甜味压片2.1%增速）
|
||||
- 功能性细分增速远超传统品类
|
||||
- 中国TOP5企业市占率39.4%，格局相对分散，新品牌仍有空间
|
||||
- OEM产能充沛：全国300+压片糖果代工厂，仙乐健康/会昌等龙头覆盖全剂型
|
||||
|
||||
### 1.3 品斛堂可行性评估
|
||||
|
||||
| 维度 | 评估 | 说明 |
|
||||
|------|:---:|------|
|
||||
| **产品基础** | ⭐⭐⭐⭐⭐ | 已有石斛精片产品，可直接升级为石斛含片/咀嚼片 |
|
||||
| **原料优势** | ⭐⭐⭐⭐⭐ | 自有石斛全产业链，提取物/多糖/干粉三种形态可做配方核心 |
|
||||
| **技术门槛** | ⭐⭐ | 压片工艺标准化，OEM代工成熟（MOQ≈3万包起订） |
|
||||
| **渠道匹配** | ⭐⭐⭐⭐ | 复用天猫/京东旗舰店+药房渠道，精准触达咽喉不适/养生人群 |
|
||||
| **品牌差异化** | ⭐⭐⭐⭐ | "石斛含片"定位对标金嗓子"咽炎"场景，差异化明显 |
|
||||
| **毛利率预估** | ⭐⭐⭐⭐ | 60-70%（压片糖果制造成本低，石斛原料自有优势加成） |
|
||||
|
||||
**可行性：★★★★★ 高**
|
||||
|
||||
**落地路径**：
|
||||
- 短期（1-3月）：将现有"石斛精片"升级为"石斛含片"（润喉利咽）+ "石斛西洋参咀嚼片"（补气提神），复用天猫元斛旗舰店渠道
|
||||
- 中期（3-6月）：开发"石斛维C咀嚼片"卡位功能维C赛道（对标汤臣倍健）
|
||||
- 代工策略：片剂生产线品斛堂已有基础（中药饮片GMP车间），可自主生产；如需扩产，珠三角/长三角OEM厂产能充裕
|
||||
|
||||
---
|
||||
|
||||
## 二、休闲零食（坚果炒货+蜜饯果干+纤维饼干）
|
||||
|
||||
### 2.1 市场规模与趋势
|
||||
|
||||
| 指标 | 数据 | 来源 |
|
||||
|------|------|------|
|
||||
| 中国休闲零食市场 | ¥1.3万亿（2020），近¥3万亿（2025E） | 商务部/中国食品工业协会 |
|
||||
| 2024年主流电商零食销售额 | ¥3080亿，同比+11% | Flywheel白皮书 [1] |
|
||||
| 坚果炒货13-18年CAGR | 11.0% | 欧睿国际 |
|
||||
| 人均消费量 | 2.15kg（2015），vs英国9.53kg/美国13.03kg | 商务部 |
|
||||
| 抖音零食销售额增长 | 23%，线上第一渠道（份额54%） | 知行咨询2025报告 |
|
||||
| 2024肉类零食占三只松鼠销售额 | 20.14% | 知行咨询2025报告 |
|
||||
|
||||
**核心趋势**：
|
||||
- 消费者要求"美味与营养兼得"——健康化零食复合增长率远超传统品类
|
||||
- 抖音超越淘系成为线上第一零食渠道
|
||||
- 渠道型品牌（三只松鼠/B2C）增长见顶，制造型品牌（洽洽/大单品）利润更优
|
||||
- 功能性/健康概念零食增速领先：益生菌、高纤维、低GI
|
||||
|
||||
### 2.2 竞争格局
|
||||
|
||||
| 梯队 | 代表品牌 | 2022年营收 | 模式 | 核心品类 |
|
||||
|------|------|:---:|------|------|
|
||||
| 🥇 | 三只松鼠 | ¥72.9亿 | B2C电商全品类 | 坚果+肉类零食 |
|
||||
| 🥇 | 良品铺子 | ¥66.2亿 | 线上线下双渠道 | 全品类+高端定位 |
|
||||
| 🥈 | 百草味 | ~¥40亿 | 百事旗下B2C | 坚果+果脯蜜饯 |
|
||||
| 🥈 | 洽洽食品 | ¥68.8亿 | 制造型大单品 | 瓜子+坚果 |
|
||||
| 🥉 | 来伊份 | ~¥40亿 | 线下门店 | 全品类 |
|
||||
|
||||
**进入壁垒**：
|
||||
- 三巨头线上份额CR3≈33%，渠道垄断性强
|
||||
- 坚果炒货品类大厂规模效应显著，价格竞争激烈
|
||||
- 蜜饯果干品类CR3低，区域品牌众多，差异化空间大
|
||||
|
||||
### 2.3 品斛堂可行性评估
|
||||
|
||||
| 维度 | 评估 | 说明 |
|
||||
|------|:---:|------|
|
||||
| **产品基础** | ⭐⭐⭐ | 已有石斛纤维饼（功能零食），缺少坚果/蜜饯加工能力 |
|
||||
| **原料优势** | ⭐⭐⭐ | 石斛粉/提取物可作为调味添加，但坚果/果干需外采 |
|
||||
| **技术门槛** | ⭐ | 坚果炒货、蜜饯果干标准化程度高，无技术壁垒 |
|
||||
| **渠道匹配** | ⭐⭐⭐ | 天猫/京东零食类目流量大，但需从零建立零食消费者认知 |
|
||||
| **品牌差异化** | ⭐⭐⭐ | "石斛+零食"概念有独特性，但需验证消费者接受度 |
|
||||
| **毛利率预估** | ⭐⭐ | 30-40%（代工成本高+坚果原料波动，自有品牌溢价有限） |
|
||||
|
||||
**可行性：★★★☆☆ 中**
|
||||
|
||||
**差异化切入策略**：
|
||||
- **不推荐**直接进入坚果炒货红海（三只松鼠/洽洽成本碾压）
|
||||
- **推荐**：石斛纤维饼升级为"石斛健康零食系列"（复用已有基础）
|
||||
- 石斛纤维饼→升级配方，推低GI/高纤维版本
|
||||
- 石斛山楂条→开胃消食+石斛养胃（蜜饯OEM成熟）
|
||||
- 石斛味坚果→轻添加概念（巴旦木/核桃+石斛粉涂层）
|
||||
- 代工策略：蜜饯果干OEM遍布云南/福建（鲜花饼供应链可复用），坚果OEM广东/安徽产能充裕
|
||||
|
||||
---
|
||||
|
||||
## 三、谷物主食（挂面+方便面+粥料）
|
||||
|
||||
### 3.1 市场规模与趋势
|
||||
|
||||
| 指标 | 数据 | 来源 |
|
||||
|------|------|------|
|
||||
| 中国挂面市场规模 | 419.92万吨产量（2021），预估>500万吨（2025E） | 中金企信/欧睿 |
|
||||
| 挂面市场销售额 | CAGR 10.72%（24家头部企业） | 中金企信 |
|
||||
| 方便速食市场 | ¥2500亿（2021）→ ¥6300亿（2025E） | 国信证券 |
|
||||
| 中国方便面市场 | 422亿包/年（2023），销量-2.3% CAGR | 勤策消费研究 |
|
||||
| 方便食品市场规模 | 2026年将突破万亿 | 勤策消费研究 |
|
||||
| 一人食经济 | 1.8万亿（2025，一二线55%宅家烹饪） | Flywheel白皮书 [1] |
|
||||
| 外卖市场规模 | 1.27万亿（2024），用户5.92亿 | 美团/行业数据 |
|
||||
|
||||
**核心趋势**：
|
||||
- 挂面量增价不增（产量>销量连续10年），利润转向高端化/功能化
|
||||
- 方便面传统品类承压（外卖+预制菜挤压），中高端增速17.1%（2016-20）为低端4.2倍
|
||||
- "一人食经济"驱动速食向品质化/健康化升级
|
||||
- 非油炸/零添加/功能性面条是增长方向
|
||||
- 高铁站停售方便面（广东2025）标志性事件→传统场景收窄
|
||||
|
||||
### 3.2 竞争格局
|
||||
|
||||
| 梯队 | 挂面 | 市场份额 | 方便面 | 市场份额 |
|
||||
|------|------|:---:|------|:---:|
|
||||
| 🥇 | 金沙河 | 22% | 康师傅 | ~45% |
|
||||
| 🥈 | 克明食品 | 8% | 统一 | — |
|
||||
| 🥉 | 想念食品 | 4% | 白象 | — |
|
||||
| 其他 | 200+中小厂 | 66% | 今麦郎/三养等 | CR5=84% |
|
||||
|
||||
**关键特点**：
|
||||
- 挂面CR3仅34%，极度分散，但整合趋势加速（2009年4000+家→2020年200+家）
|
||||
- 方便面CR5=84%高集中度，入局极难
|
||||
- 康师傅红烧牛肉味被大量仿制，品类同质化严重
|
||||
|
||||
### 3.3 品斛堂可行性评估
|
||||
|
||||
| 维度 | 评估 | 说明 |
|
||||
|------|:---:|------|
|
||||
| **产品基础** | ⭐ | 无面条制造经验，需完全依赖OEM |
|
||||
| **原料优势** | ⭐⭐ | 石斛粉可添加至面条配方，但小麦/面粉无优势 |
|
||||
| **技术门槛** | ⭐ | 挂面制造标准化，方便面需大量设备投入 |
|
||||
| **渠道匹配** | ⭐⭐ | 挂面以商超/粮油店为主，与品斛堂现有健康品渠道不匹配 |
|
||||
| **品牌差异化** | ⭐⭐ | "石斛养胃挂面"有概念吸引力，但消费者为功能性面条买单意愿待验证 |
|
||||
| **毛利率预估** | ⭐ | 15-25%（挂面毛利低，克明毛利率15.87%，想念14.19%） |
|
||||
|
||||
**可行性：★★☆☆☆ 低**
|
||||
|
||||
**判断**：谷物主食不是品斛堂当前优先级最高的扩展方向。理由：
|
||||
1. 挂面行业利润薄（克明食品2021年净利仅6700万，收入43亿），石斛添加只会进一步压缩毛利
|
||||
2. 渠道完全不匹配——挂面走商超/粮油店，品斛堂现有天猫+药房+酒类渠道
|
||||
3. 金沙河/克明双寡头成本碾压，新进入者无规模优势
|
||||
4. 唯一有吸引力的场景是"石斛面条"作为**品牌形象产品**（非利润产品）在旗舰店上架，配合石斛粥料做养生主食组合
|
||||
|
||||
**如仍需进入的建议**：OEM代工石斛养生粥料（谷物+石斛预拌包）→低风险入场，石斛面条作为品牌配套产品而非主推
|
||||
|
||||
---
|
||||
|
||||
## 四、半固态/凝胶食品（膏滋蜜炼+果冻布丁）
|
||||
|
||||
### 4.1 膏滋蜜炼（膏方）
|
||||
|
||||
#### 市场规模与趋势
|
||||
|
||||
| 指标 | 数据 | 来源 |
|
||||
|------|------|------|
|
||||
| 中成药浸膏/煎膏剂三大终端 | ¥100亿+（2024） | 米内网 |
|
||||
| 院内市场增速 | +17.20%（2025，逆势上扬） | 米内网 |
|
||||
| 补气补血类占比 | >50%市场份额 | 米内网 |
|
||||
| 中国阿胶市场 | ¥580亿（2025）→ 千亿（2030E, CAGR 10.4%） | 知乎/东阿阿胶年报 |
|
||||
| 东阿阿胶2025年营收 | ¥67亿（+13.17%），阿胶系列61.9亿 | 东阿阿胶年报 |
|
||||
| 药食同源市场 | ¥3800亿→¥7500亿（2030E, CAGR 10.8%） | 雪球/药食同源研报 [2] |
|
||||
|
||||
**核心趋势**：
|
||||
- 膏方从传统中医药向"新中式滋补"演化，消费场景从治病转向日常养生
|
||||
- 阿胶品类"零食化+便携化"趋势显著——阿胶糕/速溶粉/阿胶奶茶跨界
|
||||
- 东阿阿胶线上营收占比19.79%（2025Q1），膏方电商化仍在早期
|
||||
- 90后/00后买走60%阿胶产品，养生年轻化是确定性趋势
|
||||
|
||||
#### 竞争格局
|
||||
|
||||
| 梯队 | 品牌 | 膏方优势 | 2025年表现 |
|
||||
|------|------|------|------|
|
||||
| 🥇 | 东阿阿胶 | 阿胶膏/桃花姬 | ¥61.9亿阿胶系列 |
|
||||
| 🥇 | 同仁堂 | 传统膏方/秋梨膏 | 院外膏方TOP3 |
|
||||
| 🥈 | 胡庆余堂 | 江南膏方 | — |
|
||||
| 🥈 | 福牌阿胶 | 阿胶膏方 | 院外膏方TOP3 |
|
||||
| 🥉 | 白云山潘高寿 | 蜜炼川贝枇杷膏/养阴清肺膏 | 院内膏方第1 |
|
||||
| 🔑 | **品斛堂机会** | **石斛膏方=品类空白** | 已有石斛浸膏技术 |
|
||||
|
||||
#### 品斛堂可行性评估
|
||||
|
||||
| 维度 | 评估 | 说明 |
|
||||
|------|:---:|------|
|
||||
| **产品基础** | ⭐⭐⭐⭐⭐ | 已有石斛浸膏OEM能力，"铁皮石斛膏/秋梨石斛膏"配方有技术储备 |
|
||||
| **原料优势** | ⭐⭐⭐⭐⭐ | 石斛全产业链+石斛多糖提取物，膏方核心原料自有 |
|
||||
| **技术门槛** | ⭐⭐⭐⭐ | 中药浸膏制造有GMP门槛，品斛堂中药饮片/保健食品净化车间齐全 |
|
||||
| **渠道匹配** | ⭐⭐⭐⭐⭐ | 天猫健康品+药房+送礼场景→完美匹配膏方消费场景 |
|
||||
| **品牌差异化** | ⭐⭐⭐⭐⭐ | "石斛膏"品类无强势品牌占据，"秋梨石斛膏"对标"秋梨膏"差异明显 |
|
||||
| **毛利率预估** | ⭐⭐⭐⭐⭐ | 65-80%（膏方高毛利，东阿阿胶毛利率73.47%，石斛自有原料加成更高） |
|
||||
|
||||
**可行性：★★★★★ 高（最高优先级）**
|
||||
|
||||
**落地路径**：
|
||||
- 短期（1-3月）：复用现有石斛浸膏生产线，推出"铁皮石斛膏"（¥199-399/300g）+"秋梨石斛膏"（¥59-99），天猫旗舰店首发
|
||||
- 中期（3-6月）：开发"阿胶石斛膏"（女性气血）+石斛膏方礼盒（春节/中秋送礼）
|
||||
- 差异化定位：品斛堂膏方=石斛为核心（vs同仁堂/东阿阿胶以阿胶/人参为核心），开辟"石斛膏方"新品类
|
||||
|
||||
---
|
||||
|
||||
### 4.2 果冻布丁
|
||||
|
||||
#### 市场规模与趋势
|
||||
|
||||
| 指标 | 数据 | 来源 |
|
||||
|------|------|------|
|
||||
| 中国果冻市场 | ¥200-250亿（2023） | 中研普华/百度百科 |
|
||||
| 生产企业数量 | 2000+家（其中规模企业300+家） | 中研普华 |
|
||||
| 喜之郎年销售额 | ¥15亿+ | MBA智库百科 |
|
||||
| 功能型果冻趋势 | 乳酸菌/益生菌/代餐果冻增速最快 | 头豹研究院 |
|
||||
| 中国新式茶饮市场 | 突破4000亿（2028E） | 行业报告 |
|
||||
|
||||
**核心趋势**：
|
||||
- 果冻从"儿童零食"向"全年龄健康零食"转型
|
||||
- 益生菌果冻、蒟蒻果冻（低热量）、代餐果冻是三大增长方向
|
||||
- 女性消费者占食品网购65%，果冻天然受女性青睐
|
||||
|
||||
#### 品斛堂可行性评估
|
||||
|
||||
| 维度 | 评估 | 说明 |
|
||||
|------|:---:|------|
|
||||
| **产品基础** | ⭐⭐ | 品斛堂百度百科列有石斛果冻OEM能力，但无自有品牌产品 |
|
||||
| **原料优势** | ⭐⭐⭐ | 石斛多糖/提取物可添加至果冻配方，功能差异化 |
|
||||
| **技术门槛** | ⭐ | 果冻OEM极度成熟（全国386+食品代工厂可做果冻） |
|
||||
| **渠道匹配** | ⭐⭐⭐ | 天猫零食/女性健康品类目可覆盖 |
|
||||
| **品牌差异化** | ⭐⭐⭐ | "石斛仙草冻""石斛益生菌果冻"有差异化概念 |
|
||||
| **毛利率预估** | ⭐⭐⭐ | 40-55%（功能性果冻有溢价，但喜之郎量价优势明显） |
|
||||
|
||||
**可行性：★★★☆☆ 中（可作配套品类）**
|
||||
|
||||
**判断**：果冻布丁适合作为"石斛健康零食矩阵"的配套品类而非主力。石斛仙草冻（对标烧仙草）和石斛益生菌果冻有差异化概念，但品类天花板200-250亿且喜之郎品牌统治力极强。建议OEM少量试水，作为健康零食线的补充。
|
||||
|
||||
---
|
||||
|
||||
## 五、烘焙食品（面包吐司+饼干曲奇+节日烘焙）
|
||||
|
||||
### 5.1 市场规模与趋势
|
||||
|
||||
| 指标 | 数据 | 来源 |
|
||||
|------|------|------|
|
||||
| 中国烘焙市场（欧睿口径） | ¥2595亿（2025），CAGR 7.22% | 欧睿国际/桃李年报 |
|
||||
| 中国烘焙市场（广义） | ¥6110.7亿（2024），+8.8% | 广告门2025报告 |
|
||||
| 中国面包市场 | ¥1574亿（2024） | 华经产业研究院 |
|
||||
| 全球烘焙市场 | $5165亿（2025） | 桃李年报 |
|
||||
| 中国人均烘焙消费 | $25.5（vs日本$150+，美国$200+） | 欧睿国际 |
|
||||
| 短保面包龙头份额 | 桃李35%（2023） | 短保面包白皮书 |
|
||||
| 全国烘焙门店 | 33.8万家（2025年5月） | 红餐大数据 |
|
||||
|
||||
**核心趋势**：
|
||||
- 中国烘焙人均消费仅为日本1/6，增长空间可观
|
||||
- 烘焙糕点被Flywheel白皮书列为"电商四大高潜力品类"——线上负增长但社媒高热，**供需错配蕴藏机会**
|
||||
- 短保面包向正餐化发展，桃李2025年营收54.48亿但下滑10.5%→行业竞争加剧
|
||||
- 节日烘焙是利润中心：月饼/粽子季节爆发，高端礼盒毛利50-70%
|
||||
- 功能性烘焙方向：全麦/高纤维/益生菌/低GI
|
||||
|
||||
### 5.2 竞争格局
|
||||
|
||||
| 梯队 | 品牌 | 品类 | 2025年营收/表现 |
|
||||
|------|------|------|:---:|
|
||||
| 🥇 | 桃李面包 | 短保面包 | ¥54.48亿（-10.5%） |
|
||||
| 🥇 | 达利园 | 长保面包+糕点 | CR3≈3.9% |
|
||||
| 🥈 | 盼盼/曼可顿/美焙辰 | 短保/中保面包 | — |
|
||||
| 🥈 | 美心/杏花楼 | 月饼/节日烘焙 | — |
|
||||
| 🥉 | 33.8万家烘焙门店 | 现制烘焙 | 49.3%品牌5-30家门店 |
|
||||
|
||||
**行业特点**：
|
||||
- CR3仅8.9%，极度分散
|
||||
- 桃李"中央工厂+批发"模式面临现制烘焙门店冲击（33.8万家）
|
||||
- 外资品牌份额从28%（2023）降至20%（2025），本土品牌崛起
|
||||
|
||||
### 5.3 品斛堂可行性评估
|
||||
|
||||
| 维度 | 评估 | 说明 |
|
||||
|------|:---:|------|
|
||||
| **产品基础** | ⭐⭐ | 有石斛纤维饼（饼干类），无面包/烘焙经验 |
|
||||
| **原料优势** | ⭐⭐ | 石斛粉可作烘焙添加，但面粉/黄油无优势 |
|
||||
| **技术门槛** | ⭐ | 饼干/糕点OEM全国成熟（386+代工厂含烘焙） |
|
||||
| **渠道匹配** | ⭐⭐⭐ | 饼干→天猫零食类目；月饼→送礼渠道与酒类渠道复用 |
|
||||
| **品牌差异化** | ⭐⭐⭐ | "石斛养生月饼""石斛苏打饼干（养胃概念）"有差异化 |
|
||||
| **毛利率预估** | ⭐⭐⭐ | 40-55%（饼干/月饼毛利较高，桃李短保面包毛利更低） |
|
||||
|
||||
**可行性：★★★★☆ 中高**
|
||||
|
||||
**推荐路径**：
|
||||
- 饼干线（优先）：石斛苏打饼干（养胃概念）+石斛黄油曲奇→OEM代工，天猫零食线首发
|
||||
- 节日烘焙（高潜力）：石斛月饼（中秋）+"石斛粽子"（端午）→复用酒类送礼渠道+企业福利渠道
|
||||
- 面包吐司：**不推荐**——短保面包配送半径限制+桃李/曼可顿成本碾压+全国化物流投入巨大
|
||||
|
||||
---
|
||||
|
||||
## 六、OEM/ODM 可行性分析
|
||||
|
||||
### 6.1 品斛堂现有OEM能力
|
||||
|
||||
根据百度百科及什么值得买OEM评测，品斛堂**已具备以下品类的OEM/ODM代工能力**：
|
||||
|
||||
| 已覆盖品类 | 与本报告品类匹配 | 代工形式 | 备注 |
|
||||
|------|:---:|------|------|
|
||||
| 石斛精片 | ✅ 压片糖果 | OEM/ODM | 现有成熟产线 |
|
||||
| 石斛饼干 | ✅ 休闲零食/烘焙 | OEM/ODM | 现有成熟产线 |
|
||||
| 石斛面条 | ✅ 谷物主食 | OEM/ODM | 现有产线 |
|
||||
| 石斛果冻 | ✅ 凝胶食品 | OEM/ODM | 现有产线 |
|
||||
| 石斛浸膏 | ✅ 膏滋蜜炼 | OEM/ODM | 核心技术壁垒 |
|
||||
| 石斛原浆 | — | ODM | 品类开创者 |
|
||||
|
||||
### 6.2 双轨并行策略
|
||||
|
||||
品斛堂固态食品扩展的最佳路径是**"自有品牌试水 + OEM/ODM双轨并行"**：
|
||||
|
||||
| 策略方向 | 实施路径 | 适用品类 |
|
||||
|------|------|------|
|
||||
| **自有品牌试水** | 天猫/京东旗舰店先上2-3款爆品测试市场反应 | 膏方、含片、饼干 |
|
||||
| **OEM为品牌代工** | 以"石斛原料+制造"服务其他健康食品品牌 | 坚果、果冻、挂面 |
|
||||
| **ODM输出方案** | 为渠道品牌提供石斛食品整体ODM方案 | 全品类 |
|
||||
|
||||
**"卖铲子给掘金者"策略逻辑**：
|
||||
- 品斛堂全产业链石斛原料+三重生产资质（药品/保健食品/食品）→天然具备为其他品牌代工的优势
|
||||
- 固态食品扩展中，不必每条线都自建品牌——挂面/坚果/果冻的自有品牌投入产出比不高
|
||||
- **核心策略**：高价值品类自建品牌（膏方/含片）+低壁垒品类做OEM/ODM服务商
|
||||
|
||||
---
|
||||
|
||||
## 七、综合评估与TOP5推荐
|
||||
|
||||
### 7.1 5个子品类综合评分
|
||||
|
||||
| 评估维度（权重） | 压片糖果 | 休闲零食 | 谷物主食 | 膏滋蜜炼 | 烘焙食品 |
|
||||
|------|:---:|:---:|:---:|:---:|:---:|
|
||||
| 市场规模（15%） | 9 | 10 | 7 | 7 | 9 |
|
||||
| 市场增速（10%） | 8 | 6 | 5 | 9 | 7 |
|
||||
| 品斛堂产品基础（20%） | 9 | 6 | 2 | 10 | 5 |
|
||||
| 原料/技术优势（15%） | 9 | 5 | 3 | 10 | 4 |
|
||||
| 品牌差异化（15%） | 8 | 6 | 4 | 10 | 6 |
|
||||
| 渠道匹配度（10%） | 8 | 5 | 2 | 10 | 6 |
|
||||
| OEM实现难度（5%） | 10 | 9 | 8 | 6 | 8 |
|
||||
| 毛利率预期（10%） | 8 | 5 | 3 | 10 | 7 |
|
||||
| **加权总分** | **8.45** | **6.45** | **3.90** | **9.35** | **6.35** |
|
||||
|
||||
### 7.2 TOP5推荐排序
|
||||
|
||||
| 排名 | 品类方向 | 推荐产品 | 优先级 | 建议策略 | 预期毛利率 | 风险等级 |
|
||||
|:---:|------|------|:---:|------|:---:|:---:|
|
||||
| 🥇 | **膏滋蜜炼** | 铁皮石斛膏/秋梨石斛膏/阿胶石斛膏 | 🔴极高 | 自有品牌首发，复用浸膏产线 | 65-80% | 🟢 低 |
|
||||
| 🥈 | **压片糖果** | 石斛含片/石斛西洋参咀嚼片/石斛维C咀嚼片 | 🔴极高 | 升级石斛精片，复用天猫旗舰店 | 60-70% | 🟢 低 |
|
||||
| 🥉 | **烘焙饼干** | 石斛苏打饼干/石斛黄油曲奇/石斛月饼 | 🟡高 | OEM代工，饼干日常+月饼节日双线 | 40-55% | 🟡 中低 |
|
||||
| 4 | **休闲零食** | 石斛山楂条/石斛纤维饼升级/石斛味坚果 | 🟡中 | OEM代工，轻资产试水 | 30-40% | 🟡 中 |
|
||||
| 5 | **果冻布丁** | 石斛仙草冻/石斛益生菌果冻 | 🟢中 | OEM代工，作为零食线配套 | 40-55% | 🟡 中 |
|
||||
|
||||
### 7.3 不推荐进入的品类
|
||||
|
||||
| 品类 | 原因 |
|
||||
|------|------|
|
||||
| 挂面/方便面 | 利润极薄+渠道不匹配+金沙河/克明成本碾压 |
|
||||
| 石斛面包吐司 | 短保配送半径限制+桃李/曼可顿竞争+全国物流投入巨大 |
|
||||
| 大规模坚果炒货 | 三只松鼠/洽洽成本碾压+原料无优势 |
|
||||
|
||||
---
|
||||
|
||||
## 八、数据来源与假设说明
|
||||
|
||||
### 数据来源
|
||||
|
||||
| 编号 | 来源 | 覆盖数据项 |
|
||||
|:---:|------|------|
|
||||
| [1] | Flywheel《2025零食饮料趋势白皮书》 | 电商零食3080亿、一人食1.8万亿 |
|
||||
| [2] | ZVZO消费观察《全球及中国压片糖果市场趋势深度分析报告2026》 | 压片糖果全球$485亿、功能性CAGR 12.6% |
|
||||
| [3] | 华经产业研究院《2025年中国糖果行业分析》 | 中国糖果930亿 |
|
||||
| [4] | Global Growth Insights 药用糖果市场报告 | 药用糖果$63.9亿 |
|
||||
| [5] | 头豹研究院《大杯什锦果冻行业分析》 | 果冻市场200-250亿 |
|
||||
| [6] | 米内网《中成药浸膏剂/煎膏剂数据分析》 | 膏滋100亿+、同比增长17.2% |
|
||||
| [7] | 东阿阿胶2025年报 / 证券时报 | 东阿阿胶67亿、阿胶市场580亿 |
|
||||
| [8] | 欧睿国际 / 桃李面包2025年报 | 中国烘焙2595亿、人均$25.5 |
|
||||
| [9] | 中金企信 / 想念食品招股书 | 挂面市场500万吨、金沙河22%/克明8% |
|
||||
| [10] | 国信证券 / 勤策消费研究 | 方便速食2500-6300亿 |
|
||||
| [11] | 品斛堂百度百科 | OEM品类覆盖：精片/饼干/面条/果冻/浸膏 |
|
||||
| [12] | 什么值得买"品斛堂OEM评测" | OEM实操经验验证 |
|
||||
| [13] | 知行咨询《2025休闲零食行业年度洞察》 | 抖音零食份额54%、三只松鼠品类结构 |
|
||||
| [14] | 雪球/药食同源研报 [2] | 药食同源3800→7500亿 |
|
||||
| [15] | 品斛堂企业情报调研报告（BIZ-53） | 品斛堂产品线、DSR、电商数据 |
|
||||
|
||||
### 关键假设
|
||||
|
||||
1. 品斛堂现有石斛精片/纤维饼/浸膏OEM产线可快速转自有品牌生产——基于百度百科及OEM评测信息，假设成立
|
||||
2. 石斛膏方/含片毛利率估计基于中药行业同类产品（东阿阿胶73.47%毛利率、片剂保健食品60-80%），剔除石斛自有原料带来的成本优势后估算
|
||||
3. 饼干/坚果/果冻毛利率为行业平均水平，考虑规模劣势后下调5-10%
|
||||
4. 市场规模数据时效性：核心数据来源为2024-2026年报告，时效性满足当前分析需求
|
||||
5. 所有预测类数据已标注为"E"（预估），误差范围±15%
|
||||
|
||||
### 更新频率建议
|
||||
|
||||
- 核心市场数据（糖果/零食/烘焙）：年度更新
|
||||
- 竞品动态（三只松鼠/桃李/东阿阿胶）：季度追踪
|
||||
- 品斛堂自有品牌试水数据：月度复盘
|
||||
|
||||
---
|
||||
|
||||
*报告完成：顾析策 🔍 | 市场分析师 | 2026年6月26日*
|
||||
*数据截至：2026年6月*
|
||||
*本报告基于公开市场数据和行业研究报告编制，品斛堂内部产能数据来源于公开信息（百度百科、什么值得买评测）*
|
||||
@@ -0,0 +1,420 @@
|
||||
# 石斛功能保健食品、礼品礼盒、创新跨界品类扩展可行性分析报告
|
||||
|
||||
**报告编号**：BIZ-66
|
||||
**报告类型**：高毛利/差异化品类扩展可行性分析
|
||||
**分析日期**：2026年6月26日
|
||||
**分析人**：顾析策（市场分析师）
|
||||
**参考文档**：石斛食品饮料全品类产品方向详细文档、BIZ-53 企业情报调研报告、BIZ-64/BIZ-65 分析报告
|
||||
|
||||
---
|
||||
|
||||
## 一、摘要
|
||||
|
||||
**核心结论**：品斛堂在功能保健食品、礼品礼盒、创新跨界三大方向上存在明确的扩展机会，但需按"合规门槛→市场爆发力→品斛堂能力匹配"三维度排序——**蓝帽子保健食品是长期壁垒最高的方向，但需接受12-36个月审批周期；礼品礼盒是短期最容易变现的方向，可复用现有产品基础和渠道；创新跨界品类的ROI不确定性最高，适合小批量试水**。
|
||||
|
||||
**关键数据**：
|
||||
- 中国保健食品市场规模2024年达2308亿元（中商），2025年预计2447亿元；功能性食品市场2025年突破3700亿元（含食品化方向）
|
||||
- 2025年Q1蓝帽子获批504款（含备案），注册类新产品141款，保健食品零食化趋势加速
|
||||
- 中国礼物经济市场2025年预计达14498亿元，健康礼赠搜索量年增200%，天猫健康礼盒成交增长40%+
|
||||
- 全球植物基食品市场2026年预计945亿美元，中国占全球植物基奶市场34%
|
||||
- 药食同源市场3800亿元（2024）→7500亿元（2030），CAGR 10.8%；石斛淘系Q1线上销售额1.25亿元，同比+42%
|
||||
|
||||
**TOP5推荐排序**：
|
||||
|
||||
| 排名 | 品类 | 优先级 | 预期毛利率 | 核心逻辑 |
|
||||
|:---:|------|:---:|:---:|------|
|
||||
| 🥇 | **石斛礼品礼盒**（原浆+酒+枫斗） | ⭐⭐⭐⭐⭐ | 55-70% | 现有产品复用、节日脉冲、渠道成熟、极速落地 |
|
||||
| 🥈 | **石斛普通功能食品**（胶原蛋白肽饮/钙片） | ⭐⭐⭐⭐ | 50-65% | 备案制快速上市、无需蓝帽子审批、石斛成分差异化 |
|
||||
| 🥉 | **石斛蓝帽子保健食品**（胃黏膜保护片/增强免疫力胶囊） | ⭐⭐⭐⭐ | 65-80% | 长期壁垒最高、毛利率最高、品斛堂已有三重生产资质+功效实验数据 |
|
||||
| 4 | **石斛功能性口腔食品**（润喉糖/口香糖） | ⭐⭐⭐ | 45-55% | 高频快消、护喉需求爆发、OEM成熟 |
|
||||
| 5 | **石斛植物基食品**（石斛植物奶/豆腐） | ⭐⭐ | 35-50% | 趋势正确但品斛堂能力匹配度低、需新建产能 |
|
||||
|
||||
---
|
||||
|
||||
## 二、蓝帽子保健食品（需注册·高毛利高壁垒）
|
||||
|
||||
### 2.1 市场规模与趋势
|
||||
|
||||
| 指标 | 数据 | 来源 |
|
||||
|------|------|------|
|
||||
| 中国保健食品市场规模（2024） | 2308亿元，同比+6.9% | 中商产业研究院 [1] |
|
||||
| 2025年预测规模 | 2447亿元 | 中商 [1] |
|
||||
| 养生保健食品市场（2023） | 3282亿元，同比+8.29% | 新营养 [2] |
|
||||
| 药食同源市场（2024→2030） | 3800亿→7500亿，CAGR 10.8% | 雪球/行业研报 [3] |
|
||||
| 2024年获批国产注册类保健食品 | 391款（其中新注册329款） | 中商 [1] |
|
||||
| 2025年Q1获批保健食品 | 504款（含备案），注册类141款 | 新营养 [2] |
|
||||
| 2025年Q1获批TOP功能 | 血糖、脂肪控制、润肠通便 | 新营养 [2] |
|
||||
| 2024年获批国产备案凭证 | 4307款 | 中商 [1] |
|
||||
| 头部品牌毛利率 | 60-75%（汤臣倍健66.7%，健合60.7%） | 头豹 [4] |
|
||||
| 保健食品零食化剂型 | 软糖/爆珠等新剂型进入批文 | 新营养 [2] |
|
||||
|
||||
**趋势信号**：
|
||||
- 2025年Q1植物性营养素占比47.82%，传统中药类（灵芝、西洋参、酸枣仁）占主导，石斛注册产品目前稀缺——**蓝海窗口**
|
||||
- 药食同源目录已覆盖106种，石斛认知度加速提升
|
||||
- 2025年进口保健食品注册通道重启，6款进口获批——国内竞争加剧信号
|
||||
- 保健食品零食化趋势：糖果糕点类出现在批文中，打破"胶囊片剂"固有印象
|
||||
- 2025年3月政策："完善特殊食品注册许可制度，对符合条件的重点品种实施优先审评审批"——新《意见》利好创新品类
|
||||
|
||||
### 2.2 合规路径与时间成本
|
||||
|
||||
| 路径 | 适用条件 | 审批周期 | 审批级别 | 适合品斛堂的产品 |
|
||||
|------|----------|:---:|------|------|
|
||||
| **注册制** | 目录外原料/首次进口/新功能声称 | 12-36个月 | 国家市场监管总局 | 石斛胃黏膜保护片、增强免疫力胶囊、缓解疲劳口服液 |
|
||||
| **备案制** | 原料已列入保健食品原料目录 | 1-3个月 | 省级市场监管局 | 石斛营养素补充剂（若石斛进入目录后） |
|
||||
| **普通功能食品** | 无功能声称、按普通食品管理 | 无需审批 | — | 石斛胶原蛋白肽饮、石斛钙片 |
|
||||
|
||||
**品斛堂合规优势**：
|
||||
- ✅ 已具备药品+保健食品+食品三重生产资质
|
||||
- ✅ 已有斑马鱼功效实验数据（胃黏膜保护、免疫力方向）
|
||||
- ✅ 紫皮石斛全产业链控制（种植→加工→提取）
|
||||
- ⚠️ 需补充：注册制产品完整的毒理学试验+功能学试验+人体试食试验
|
||||
|
||||
**时间线建议**：
|
||||
- **短期（0-6个月）**：启动注册制申报资料准备（配方定型+安全性评价+功能学评价），同步上线普通功能食品
|
||||
- **中期（6-18个月）**：完成注册资料提交，进入技术审评阶段
|
||||
- **长期（18-36个月）**：获批蓝帽子批文，正式上市
|
||||
|
||||
### 2.3 品斛堂匹配度评估
|
||||
|
||||
| 维度 | 评分 | 说明 |
|
||||
|------|:---:|------|
|
||||
| 原料优势 | ⭐⭐⭐⭐⭐ | 自有千亩有机石斛基地，原料成本可控，多糖含量≥2200mg/100g |
|
||||
| 生产技术 | ⭐⭐⭐⭐ | 酶解+低温浓缩+超临界CO₂萃取技术已成熟，可支撑功能因子高保留 |
|
||||
| 合规资质 | ⭐⭐⭐⭐ | 已具备三重生产资质，但蓝帽子注册批文需从零申请 |
|
||||
| 研发能力 | ⭐⭐⭐ | 已有斑马鱼功效数据，但需补充完整GLP毒理+临床功能学试验 |
|
||||
| 品牌信任 | ⭐⭐⭐ | 石斛原浆第一品牌认知可转化，但"保健品"心智尚未建立 |
|
||||
|
||||
### 2.4 具体产品评估
|
||||
|
||||
#### A. 石斛胃黏膜保护片（蓝帽子注册制）
|
||||
|
||||
| 评估维度 | 内容 |
|
||||
|------|------|
|
||||
| 目标人群 | 胃黏膜损伤人群、慢性胃炎患者、长期服药人群 |
|
||||
| 市场规模 | 胃肠健康保健食品市场超200亿，TOP10胃肠功能产品年销过亿 |
|
||||
| 竞争格局 | 江中药业（健胃消食片年销20亿+）、修正药业、葵花药业主导，石斛差异化切入尚属空白 |
|
||||
| 预期毛利率 | 65-80%（对标江中药业毛利率67%） |
|
||||
| 品斛堂优势 | 斑马鱼实验已验证石斛多糖胃黏膜保护功效，紫皮石斛多糖含量行业领先 |
|
||||
| 时间成本 | 注册制审批12-36个月，申报资料准备3-6个月 |
|
||||
| 风险 | 审批不确定性；市场竞争激烈，品牌认知需长期建设 |
|
||||
|
||||
#### B. 石斛增强免疫力胶囊（蓝帽子注册制）
|
||||
|
||||
| 评估维度 | 内容 |
|
||||
|------|------|
|
||||
| 目标人群 | 免疫力低下人群、术后恢复、老年人群 |
|
||||
| 市场规模 | 增强免疫力为保健食品申报功能TOP1，2024年获批产品中免疫类占最大份额 |
|
||||
| 竞争格局 | 汤臣倍健蛋白粉、无限极增健口服液等已占据主流心智，但石斛+免疫是差异化组合 |
|
||||
| 预期毛利率 | 65-80% |
|
||||
| 品斛堂优势 | 石斛多糖增强免疫的文献研究充分，斑马鱼实验可支持功效声称 |
|
||||
| 时间成本 | 同上，注册制12-36个月 |
|
||||
| 风险 | 免疫力声称已是红海；需要差异化功效定位 |
|
||||
|
||||
#### C. 石斛缓解疲劳口服液（蓝帽子注册制）
|
||||
|
||||
| 评估维度 | 内容 |
|
||||
|------|------|
|
||||
| 目标人群 | 易疲劳人群、熬夜加班族、运动人群 |
|
||||
| 市场规模 | 缓解体力疲劳为保健食品TOP3申报功能，市场规模超150亿 |
|
||||
| 竞争格局 | 红牛（170亿+）、东鹏特饮、无限极主导；草本抗疲劳方向尚存差异化空间 |
|
||||
| 预期毛利率 | 65-75% |
|
||||
| 品斛堂优势 | 石斛西洋参复配属传统补气养阴经典组合，配方壁垒较高 |
|
||||
| 时间成本 | 同上 |
|
||||
| 风险 | 与红牛等功能饮料品类边界模糊，需明确"保健食品"而非"饮料"定位 |
|
||||
|
||||
---
|
||||
|
||||
## 三、普通功能食品（无需蓝帽子·快速上市）
|
||||
|
||||
### 3.1 市场规模与趋势
|
||||
|
||||
| 指标 | 数据 | 来源 |
|
||||
|------|------|------|
|
||||
| 中国功能性食品市场（2025） | 突破3700亿元，增长率12-15% | 知乎/行业研报 [5] |
|
||||
| 全球功能性食品（2024→2034） | $3322亿→$6380亿，CAGR 6.9% | GMInsights [6] |
|
||||
| 胶原蛋白肽市场 | 中国口服美容市场2024年超250亿元，CAGR 15%+ |
|
||||
| 钙补充剂市场 | 中国钙制剂市场2024年约180亿元，50+人群渗透率持续提升 |
|
||||
| 零食化养生趋势 | 72%的90后用功能性零食替代传统保健品 | 美团/小红书 [7] |
|
||||
|
||||
### 3.2 合规路径
|
||||
|
||||
普通功能食品的**核心合规策略**：
|
||||
- ✅ 按普通食品标准管理，上市无需审批
|
||||
- ✅ 可在包装标注"含石斛多糖""添加XX成分"（成分声称，不涉及功能声称）
|
||||
- ✅ 可通过小红书/抖音等渠道做成分科普和食疗内容（KOL种草+达人推荐）
|
||||
- ❌ 不得宣传任何保健功能（如"保护胃黏膜""增强免疫力"）
|
||||
- ❌ 产品名称不得含保健功能暗示
|
||||
|
||||
### 3.3 具体产品评估
|
||||
|
||||
#### A. 石斛胶原蛋白肽饮
|
||||
|
||||
| 评估维度 | 内容 |
|
||||
|------|------|
|
||||
| 目标人群 | 25-45岁女性，美容养颜+日常滋养 |
|
||||
| 市场规模 | 口服美容市场250亿+，胶原蛋白肽为核心品类 |
|
||||
| 对标品牌 | 汤臣倍健Yep、姿美堂、Swisse |
|
||||
| 预期毛利率 | 55-65% |
|
||||
| 差异化 | 石斛多糖"滋阴养胃+胶原蛋白美容"双重复配，传统滋养与现代功能性结合 |
|
||||
| 上市周期 | 3-6个月（配方定型+稳定性测试+备案上市） |
|
||||
| 渠道匹配 | 现有电商渠道可直接复用（天猫+抖音+视频号） |
|
||||
|
||||
#### B. 石斛钙片/钙咀嚼片
|
||||
|
||||
| 评估维度 | 内容 |
|
||||
|------|------|
|
||||
| 目标人群 | 中老年人群、骨健康关注者 |
|
||||
| 市场规模 | 钙制剂市场180亿+ |
|
||||
| 对标品牌 | 钙尔奇、迪巧、汤臣倍健 |
|
||||
| 预期毛利率 | 50-60% |
|
||||
| 差异化 | 钙+石斛多糖"补钙+养胃"，减少传统钙片对胃的刺激感 |
|
||||
| 上市周期 | 3-6个月 |
|
||||
| 渠道匹配 | 药店+电商+商超 |
|
||||
|
||||
#### C. 石斛益生菌粉/软糖
|
||||
|
||||
| 评估维度 | 内容 |
|
||||
|------|------|
|
||||
| 目标人群 | 肠胃不适人群、年轻养生族 |
|
||||
| 市场规模 | 益生菌市场2025年全球770亿美元，中国占25%，年增20%+ |
|
||||
| 对标品牌 | 合生元、妈咪爱、wonderlab |
|
||||
| 预期毛利率 | 50-65% |
|
||||
| 差异化 | 益生菌+石斛多糖"双重养胃"，肠道+胃黏膜协同保护 |
|
||||
| 趋势红利 | 保健食品零食化（软糖/爆珠剂型）——符合年轻化消费趋势 |
|
||||
| 上市周期 | 3-6个月 |
|
||||
|
||||
---
|
||||
|
||||
## 四、礼品礼盒（高毛利·节日爆发）
|
||||
|
||||
### 4.1 市场规模与趋势
|
||||
|
||||
| 指标 | 数据 | 来源 |
|
||||
|------|------|------|
|
||||
| 中国礼物经济市场（2025E） | 14498亿元，持续增长 | 艾媒咨询 [8] |
|
||||
| 2027年预测 | 16197亿元 | 艾媒 [8] |
|
||||
| 健康礼赠搜索量增长 | 年增200% | 天猫健康 [9] |
|
||||
| 天猫健康礼盒成交增长 | FY24同比增长40%+，3万+款礼盒 | 天猫健康 [9] |
|
||||
| 诞生千万单品数 | FY24期间27款 | 天猫健康 [9] |
|
||||
| 年轻人选健康类年礼比例 | 近70% | TMIC白皮书 [9] |
|
||||
| 近30%消费者送过最成功的礼品 | 与健康相关 | TMIC白皮书 [9] |
|
||||
| 春节/中秋销售额占比 | 全年约25% | Flywheel白皮书 |
|
||||
| 礼品行业复合增长率 | 7% | 凯度/励展华博 [10] |
|
||||
|
||||
**关键趋势**：
|
||||
- 送礼从"面子工程"转向"价值感+情绪表达"，健康礼赠成为确定性增长极
|
||||
- 天猫推出"送礼"功能，淘宝App全量上线——降低送礼决策成本
|
||||
- 燕之屋（燕窝礼盒）、小仙炖（燕窝礼盒）、东阿阿胶（阿胶礼盒）已在礼赠赛道验证——石斛礼盒尚未被头部品牌锁定
|
||||
- 一线品牌春节礼盒案例：燕之屋携手法国设计师，小仙炖联名非遗艺术家——**包装设计本身就是传播媒介**
|
||||
|
||||
### 4.2 品斛堂现有礼盒基础
|
||||
|
||||
| 现有产品 | 价格带 | 基础评价 |
|
||||
|------|:---:|------|
|
||||
| 紫皮石斛原浆至臻礼盒 | ¥900+ | 已有高端礼盒经验，原浆作为送礼主形态已验证 |
|
||||
| 石斛酒礼盒 | ¥300-900 | CIC认证"石斛酒中国销量第一"，酒礼盒天然适配商务送礼 |
|
||||
| 铁皮石斛原浆礼盒 | ¥499-799 | 中高端送礼定位，可扩展至年节礼盒 |
|
||||
|
||||
### 4.3 礼盒扩展建议
|
||||
|
||||
#### A. 石斛原浆礼盒体系化（首推）
|
||||
|
||||
| 维度 | 内容 |
|
||||
|------|------|
|
||||
| 策略 | 建立"原浆礼盒金字塔"——入门级(¥299-399)→中端(¥499-799)→高端(¥999-2999) |
|
||||
| 产品线 | 紫皮原浆入门礼盒、铁皮原浆中端礼盒、霍山米斛原浆高端礼盒、复合原浆组合礼盒 |
|
||||
| 场景匹配 | 春节全家福礼盒、中秋商务礼盒、日常拜访养生礼盒、长辈祝寿礼盒 |
|
||||
| 包装策略 | 联名非遗/IP设计师打造限定包装，强化"云南龙陵·道地石斛"产地叙事 |
|
||||
| 预期毛利率 | 55-70%（礼盒溢价+包装附加值） |
|
||||
| 竞争优势 | 石斛原浆第一品牌背书+全产业链透明溯源 |
|
||||
| 渠道 | 天猫健康礼赠会场+视频号礼赠营销+企业团购福利+线下药店铺货 |
|
||||
|
||||
#### B. 石斛酒礼盒升级
|
||||
|
||||
| 维度 | 内容 |
|
||||
|------|------|
|
||||
| 策略 | 围绕"中国石斛露酒开创者"身份，打造商务宴请+节日送礼双场景 |
|
||||
| 产品线 | 石斛西洋参灵芝酒礼盒（蓝帽子）、石斛米香白酒礼盒（云南特色）、石斛+原浆组合礼盒（酒+滋补） |
|
||||
| 预期毛利率 | 55-75%（蓝帽子酒礼盒毛利最高） |
|
||||
| 礼盒策略 | 云南民族文化元素包装+产地溯源二维码+限量版工艺 |
|
||||
|
||||
#### C. 石斛枫斗礼盒（传统高端）
|
||||
|
||||
| 维度 | 内容 |
|
||||
|------|------|
|
||||
| 策略 | 面向传统滋补送礼人群，强调"道地基源+手工精选" |
|
||||
| 产品线 | 铁皮石斛枫斗礼盒(¥599-999)、紫皮石斛枫斗礼盒(¥299-599)、霍山米斛枫斗礼盒(¥1299-2999) |
|
||||
| 预期毛利率 | 55-65% |
|
||||
| 适合人群 | 传统养生认知强的中老年送礼场景、高端商务馈赠 |
|
||||
|
||||
---
|
||||
|
||||
## 五、创新跨界品类（差异化·爆品潜力）
|
||||
|
||||
### 5.1 功能性口腔食品
|
||||
|
||||
#### 5.1.1 市场规模与趋势
|
||||
|
||||
| 指标 | 数据 | 来源 |
|
||||
|------|------|------|
|
||||
| 中国口香糖市场 | 约120亿元，增速放缓但功能性方向增长 |
|
||||
| 中国润喉糖/含片市场 | 约80亿元，后疫情时代护喉需求持续 |
|
||||
| 口腔护理食品趋势 | "清新口气+口腔健康"双功能融合，益生菌口香糖/含片兴起 |
|
||||
| 对标产品 | 金嗓子喉宝（年销20亿+）、王老吉润喉糖、绿箭/益达 |
|
||||
|
||||
#### 5.1.2 具体产品评估
|
||||
|
||||
| 产品 | 目标人群 | 价格带 | 预期毛利率 | 品斛堂匹配度 | 结论 |
|
||||
|------|----------|:---:|:---:|:---:|------|
|
||||
| 石斛润喉糖 | 用嗓过度、咽喉不适人群 | ¥12.9-22.9/盒 | 45-55% | ⭐⭐⭐⭐ | **首推**——石斛清咽利喉传统认知强，制造工艺成熟，OEM快启动 |
|
||||
| 石斛口香糖 | 口腔异味人群 | ¥9.9-19.9/盒 | 40-50% | ⭐⭐⭐ | 可试水——"保护口腔黏膜"的差异化卖点，但需教育市场 |
|
||||
|
||||
**可行性分析**：
|
||||
- 石斛传统用途中"清咽利喉"心智成熟，《本草纲目》记载"强阴益精，厚肠胃"，咽喉保护是其衍生功效认知
|
||||
- 润喉糖属高频快消品，复购率高，与品斛堂现有电商渠道天然匹配
|
||||
- 金嗓子、王老吉等品牌占据主流，但"石斛润喉"细分赛道空白
|
||||
- 可通过OEM代工快速试水，无需自建生产线
|
||||
|
||||
**推荐路径**：委托成熟润喉糖OEM工厂代工→自有品牌+电商测试→验证ROI后决定是否自建产能
|
||||
|
||||
### 5.2 植物基食品
|
||||
|
||||
#### 5.2.1 市场规模与趋势
|
||||
|
||||
| 指标 | 数据 | 来源 |
|
||||
|------|------|------|
|
||||
| 全球植物基食品市场（2026E） | 945亿美元，CAGR 12.24% | Straits Research [11] |
|
||||
| 全球植物基市场（2023→2033） | 113亿→355亿美元，CAGR 12.2% | DSM [12] |
|
||||
| 中国占全球植物基奶市场 | 34%（最大单一市场） | 艾媒 |
|
||||
| 植物基奶产品占植物基 | 54.65% | Straits [11] |
|
||||
| 中国现存植物基企业 | 8399家（截至2023.4），2017-2022新增1982家 | 力矩中国 |
|
||||
| Inova 2025趋势 | 55%消费者认为植物基应作为独立品类 |
|
||||
|
||||
#### 5.2.2 具体产品评估
|
||||
|
||||
| 产品 | 目标人群 | 价格带 | 预期毛利率 | 品斛堂匹配度 | 结论 |
|
||||
|------|----------|:---:|:---:|:---:|------|
|
||||
| 石斛植物奶 | 乳糖不耐受人群、健康饮品消费者 | ¥8-12/L | 35-45% | ⭐⭐ | **谨慎**——需要新建植物基产线，与现有核心能力差距大 |
|
||||
| 石斛豆腐 | 素食主义者、健康饮食人群 | ¥5.9-9.9/500g | 30-40% | ⭐ | **暂不推荐**——冷链依赖、区域性强、毛利率低 |
|
||||
|
||||
**可行性分析**：
|
||||
- 植物基大方向正确，但品斛堂能力圈（原浆酶解+酿酒+提取）与植物基（植物蛋白结构重组、发酵工艺）匹配度不足
|
||||
- Oatly、维他奶等已占据植物奶主流心智，石斛切入需差异化定位（"石斛多糖+植物蛋白"组合）
|
||||
- 植物奶毛利率35-45%，与品斛堂现有原浆业务（60-70%）相比显著偏低
|
||||
- 2025年植物基赛道竞争者已超8000家，赛道拥挤度急剧上升
|
||||
|
||||
**推荐路径**：
|
||||
- 植物奶：与现有植物基品牌（如Oatly）联名试水，而非自建产线
|
||||
- 石斛豆腐：属于区域型冷链产品，不适合品斛堂现有电商全国的渠道模型，**暂不推荐**
|
||||
|
||||
---
|
||||
|
||||
## 六、四维度横向对比与TOP5推荐
|
||||
|
||||
### 6.1 四维度综合评分
|
||||
|
||||
| 维度 | 蓝帽子保健食品 | 普通功能食品 | 礼品礼盒 | 创新跨界 |
|
||||
|------|:---:|:---:|:---:|:---:|
|
||||
| 市场规模 | ⭐⭐⭐⭐ 2308亿 | ⭐⭐⭐⭐⭐ 3700亿 | ⭐⭐⭐⭐⭐ 1.45万亿 | ⭐⭐⭐⭐ 945亿美元 |
|
||||
| 增速 | ⭐⭐⭐ 6.9% | ⭐⭐⭐⭐ 12-15% | ⭐⭐⭐ 7% | ⭐⭐⭐⭐ 12.24% |
|
||||
| 合规门槛 | ⭐⭐⭐ 12-36个月 | ⭐⭐⭐⭐⭐ 无需审批 | ⭐⭐⭐⭐ 食品标准即可 | ⭐⭐⭐⭐⭐ 无需审批 |
|
||||
| 品斛堂匹配度 | ⭐⭐⭐⭐ 原料+资质 | ⭐⭐⭐⭐ 配方+渠道 | ⭐⭐⭐⭐⭐ 现有产品复用 | ⭐⭐ 需新建产能 |
|
||||
| 预期毛利率 | ⭐⭐⭐⭐⭐ 65-80% | ⭐⭐⭐⭐ 50-65% | ⭐⭐⭐⭐⭐ 55-70% | ⭐⭐ 35-50% |
|
||||
| 竞争壁垒 | ⭐⭐⭐⭐⭐ 审批+品牌 | ⭐⭐⭐ 成分差异化 | ⭐⭐⭐⭐⭐ 产地+品牌 | ⭐ 低壁垒 |
|
||||
| 落地速度 | ⭐ 慢 | ⭐⭐⭐⭐⭐ 快 | ⭐⭐⭐⭐⭐ 极快 | ⭐⭐⭐ 快 |
|
||||
|
||||
### 6.2 TOP5推荐详细说明
|
||||
|
||||
#### 🥇 TOP1：石斛礼品礼盒体系化
|
||||
|
||||
- **推荐理由**：品斛堂已具备礼盒产品基础（原浆礼盒¥900+、酒礼盒¥300-900），无需新增产线或审批。健康礼赠市场正处爆发早期，天猫健康礼盒成交年增40%+，石斛礼盒赛道尚未被头部品牌锁定。
|
||||
- **落地路径**：
|
||||
- 立即启动：包装设计升级（联名非遗IP/设计师），建立"入门→中端→高端"礼盒金字塔
|
||||
- 3个月内：首批节日限定礼盒上线（中秋礼盒先行）
|
||||
- 渠道：天猫健康礼赠会场+视频号礼赠营销+企业团购+线下药店
|
||||
- **关键成功因素**：包装设计=传播媒介；产地叙事=信任壁垒；多价格带覆盖=市场扩容
|
||||
- **预期年增量营收**：3000-5000万（首年，复用现有产品）
|
||||
|
||||
#### 🥈 TOP2：石斛普通功能食品（胶原蛋白肽饮/益生菌软糖）
|
||||
|
||||
- **推荐理由**：无需蓝帽子审批，3-6个月可上市，毛利率50-65%，石斛成分差异化明确。口服美容+益生菌双赛道年增15%+，"零食化养生"趋势强劲。
|
||||
- **落地路径**：
|
||||
- 胶原蛋白肽饮：委托OEM代工→自有品牌+电商首测→3个月内上市
|
||||
- 益生菌石斛软糖：抓住保健食品零食化趋势，软糖剂型吸引年轻消费者
|
||||
- 渠道：天猫+抖音+小红书内容种草
|
||||
- **关键成功因素**：成分差异化（石斛多糖复配）、剂型零食化、内容营销驱动
|
||||
- **预期年增量营收**：2000-4000万
|
||||
|
||||
#### 🥉 TOP3：石斛蓝帽子保健食品（胃黏膜保护/增强免疫力）
|
||||
|
||||
- **推荐理由**：长期壁垒最高（审批+品牌）、毛利率最高（65-80%）、品斛堂已具备三重生产资质+斑马鱼功效数据。2025年政策利好"重点品种优先审评审批"，蓝帽子批文可形成10年+的独占期壁垒。
|
||||
- **落地路径**：
|
||||
- 立即启动：注册制申报资料准备（配方定型+GLP毒理+功能学评价），预算300-500万
|
||||
- 同步推进：斑马鱼功效数据整理为SCI论文，增强学术背书
|
||||
- 12-36个月：获批后正式上市
|
||||
- **关键成功因素**：审批成功=独占壁垒；学术论文=品牌信任；全产业链=成本优势
|
||||
- **风险提示**：审批周期长且存在不确定性，注册成本300-500万
|
||||
- **预期年增量营收**：获批后首年3000-5000万，长期有望过亿
|
||||
|
||||
#### ④ TOP4：石斛功能性润喉糖
|
||||
|
||||
- **推荐理由**：石斛"清咽利喉"传统心智成熟，润喉糖市场80亿+，OEM代工可快速启动。高频快消品属性带来复购率，与电商渠道天然匹配。
|
||||
- **落地路径**：
|
||||
- 委托成熟润喉糖OEM工厂代工→自有品牌→电商+便利店测试
|
||||
- 3个月内首批上市
|
||||
- **关键成功因素**：包装年轻化、渠道铺货、口味优化
|
||||
- **预期年增量营收**：500-1500万
|
||||
- **风险**：金嗓子/王老吉主导市场，品牌突围需要差异化营销投入
|
||||
|
||||
#### ⑤ TOP5：石斛植物基食品（联名试水）
|
||||
|
||||
- **推荐理由**：全球植物基CAGR 12.24%，中国是最大植物基奶市场。石斛多糖+植物蛋白组合有差异化空间。
|
||||
- **落地路径**：与Oatly/维他奶等品牌联名→石斛植物奶→电商测试→根据市场反馈决定是否深入
|
||||
- **关键成功因素**：联名降低试错成本、植物基趋势红利
|
||||
- **预期年增量营收**：试水阶段500-1000万
|
||||
- **风险**：品斛堂植物基能力不足，自建产线ROI存疑，建议仅限联名试水
|
||||
|
||||
---
|
||||
|
||||
## 七、综合落地路线图
|
||||
|
||||
| 时间线 | 行动 | 所需资源 | 预期成果 |
|
||||
|------|------|------|------|
|
||||
| **0-3个月** | ①礼盒包装升级+中秋礼盒上线 ②胶原蛋白肽饮OEM启动 ③润喉糖OEM启动 ④注册制申报准备启动 | 设计费50万+OEM试产费80万 | 3款新产品上市 |
|
||||
| **3-6个月** | ①春节礼盒预售 ②胶原蛋白肽饮正式上市 ③润喉糖上市 ④益生菌软糖启动 | OEM产能扩产100万 | 6款产品在售 |
|
||||
| **6-18个月** | ①礼盒体系化（全节日覆盖） ②蓝帽子注册资料提交 ③功能食品线扩展 | 注册费300-500万 | 形成完整产品矩阵 |
|
||||
| **18-36个月** | ①蓝帽子获批→正式上市 ②植物基联名试水 | 批文持有+营销投入 | 高壁垒护城河建成 |
|
||||
|
||||
---
|
||||
|
||||
## 八、数据来源与假设说明
|
||||
|
||||
**数据来源**：
|
||||
1. [1] 中商产业研究院《2025-2030年中国保健食品深度分析及发展前景研究预测报告》
|
||||
2. [2] 新营养《2025年Q1保健食品行业全景解析》（2025.4.10）
|
||||
3. [3] 雪球/药食同源行业研报：2024年3800亿→2030年7500亿
|
||||
4. [4] 头豹《2025年营养健康行业词条报告》（2025.7.30）
|
||||
5. [5] 知乎专栏《2025年中国功能性食品行业年末深入盘点》
|
||||
6. [6] GMInsights《功能性食品市场规模及份额 2025-2034》
|
||||
7. [7] 美团/小红书用户行为数据
|
||||
8. [8] 艾媒咨询《中国礼物经济产业市场规模》
|
||||
9. [9] 天猫健康·TMIC《健康礼赠行业趋势白皮书》（2024）
|
||||
10. [10] 励展华博×凯度《2025年中国礼品行业展望白皮书》
|
||||
11. [11] Straits Research《植物基食品和饮料市场规模 2026-2034》
|
||||
12. [12] DSM全球植物基市场报告（2024）
|
||||
|
||||
**关键假设**：
|
||||
- 保健食品市场增长率假设为6-8%，基于近3年平均增速
|
||||
- 礼盒毛利率假设基于品斛堂现有礼盒产品定价与行业均值
|
||||
- 蓝帽子审批周期假设基于2025年Q1实际审批节奏（Q1新注册116款）和国家市监局公开数据
|
||||
- 品斛堂年营收假设3-5亿元（基于BIZ-53情报调研）
|
||||
- 增量营收预测基于可触及市场（SAM）而非总可寻址市场（TAM）
|
||||
|
||||
**置信区间**：
|
||||
- 市场规模数据：±5-10%（多源交叉验证）
|
||||
- 毛利率预测：±5%（行业对标+品斛堂现有产品毛利率反推）
|
||||
- 增量营收预测：±30%（首年试水阶段不确定性高）
|
||||
|
||||
---
|
||||
|
||||
*报告完成于2026年6月26日 | 顾析策 | 分析事业部 | 市场分析师*
|
||||
@@ -0,0 +1,318 @@
|
||||
# 石斛预制菜与调味品赛道切入可行性分析
|
||||
|
||||
**分析日期**：2026年6月26日
|
||||
**分析师**：顾析策（市场分析）
|
||||
**关联议题**：BIZ-67（父议题：BIZ-53 品斛堂企业情报调研）
|
||||
|
||||
---
|
||||
|
||||
## 一、摘要
|
||||
|
||||
**核心结论**：品斛堂当前阶段**不建议直接进入预制菜/调味品赛道**，建议采取"**观望+轻资产试水**"策略——优先以OEM模式试水石斛养生汤料包/石斛火锅底料，待市场验证后再决定是否加大投入。
|
||||
|
||||
**关键数据**：
|
||||
- 中国调味品市场规模 6871 亿（2024），酱油品类 1041 亿；海天酱油市占率 13.2%
|
||||
- 中国预制菜市场规模 4850-6000 亿（2024），预计 2026 年达 7490-10720 亿
|
||||
- 预制菜行业毛利率仅 10-15%，CR10 仅 14%，7.2 万家企业高度碎片化
|
||||
- 药膳预制菜抖音电商 2023 年 1-9 月同比增长 605%，细分赛道高速增长
|
||||
|
||||
**建议**：观望着手养生汤料包 OEM 试水，6-12 个月后根据销售数据决定下一步。
|
||||
|
||||
---
|
||||
|
||||
## 二、调味品赛道分析
|
||||
|
||||
### 2.1 市场规模与增长
|
||||
|
||||
| 指标 | 数据 | 来源 |
|
||||
|------|------|------|
|
||||
| 2024 年调味品市场总规模 | 6871 亿元，YoY +16.0% | 艾媒咨询 2025H1 |
|
||||
| 2027 年调味品市场预测 | 10028 亿元 | 艾媒咨询 |
|
||||
| 2016-2023 CAGR | 10.12% | 华经产业研究院 |
|
||||
| 2024 年复合调味品市场 | 2301 亿元 | 艾媒咨询 |
|
||||
| 2024 年酱油市场（国内） | 1041 亿元 | 弗诺斯特沙利文 |
|
||||
| 2024 年菜谱式调味品 | 522 亿元，2027 年预计 1033 亿 | 艾媒咨询 |
|
||||
| 酱油 CAGR（2019-2024） | 2.6%，预测 2024-2029 为 4.8% | 弗诺斯特沙利文 |
|
||||
|
||||
**判断**：调味品市场稳健增长但已进入**存量竞争**阶段，基础调味品增速放缓，复合调味品是增量来源。
|
||||
|
||||
### 2.2 竞争格局
|
||||
|
||||
| 排名 | 企业 | 整体市占率（2024） | 核心品类 | 2024 年营收 |
|
||||
|:---:|------|:---:|------|------|
|
||||
| 1 | 海天味业 | 4.8% | 酱油（13.2%）/蚝油（40.2%）/酱类 | ~269 亿 |
|
||||
| 2 | 阜丰集团 | 1.4% | 味精/氨基酸 | — |
|
||||
| 3 | 李锦记 | ~1.4% | 酱油/蚝油/酱类 | 非上市 |
|
||||
| — | 中炬高新（美味鲜） | — | 酱油第二 | ~30 亿 |
|
||||
| — | 千禾味业 | — | 高端酱油 | ~20 亿 |
|
||||
| — | 天味食品 | — | 火锅底料/中式复调 | 31.5 亿（2023） |
|
||||
|
||||
**关键发现**：
|
||||
- **寡头格局已形成**：海天+李锦记+中炬高新占据酱油市场头部，海天渠道下沉至乡镇
|
||||
- **酱油价格战白热化**：9.9 元/L 特级酱油已成常态，新品牌突围极难
|
||||
- **"零添加"标签被禁**：2025 年 3 月新国标（GB 7718-2025）规定 2027 年起禁标"零添加""不添加"，对差异化新品牌构成政策风险
|
||||
|
||||
### 2.3 石斛调味品可行性评估
|
||||
|
||||
#### 石斛酱油
|
||||
- **对标现状**：海天酱油 2025 年营收 149 亿，市占率 13.2%，规模效应碾压级
|
||||
- **差异化空间**：极小。酱油消费者核心决策因素为"品牌+价格+口味"，"养生"属性在酱油品类中尚未成为主流需求
|
||||
- **品斛堂劣势**：无酿造产能、无渠道、无品牌认知、远离大豆主产区（云南非大豆产区）
|
||||
- **成本劣势**：石斛添加推高成本，终端定价可能在 19.9-29.9 元/500ml，而主流酱油 9.9 元/L，价格差 2-3 倍
|
||||
|
||||
#### 石斛火锅底料
|
||||
- **对标现状**：海底捞（颐海国际）、天味食品（好人家）、德庄、红九九
|
||||
- **差异化空间**：中等。"不上火"概念在火锅场景有消费者感知，石斛+云南菌菇/酸汤可打造"云南养生火锅"概念
|
||||
- **机会点**：复合调味品增速 13%+，CR 低，OEM 进入门槛低于酱油
|
||||
- **品斛堂劣势**：无火锅底料研发经验，口味研发需外部合作
|
||||
|
||||
### 2.4 调味品切入评分：★★☆☆☆（2/5）
|
||||
|
||||
| 维度 | 评分 | 说明 |
|
||||
|------|:---:|------|
|
||||
| 市场规模 | 4/5 | 6871 亿大市场，复合调味品增长快 |
|
||||
| 竞争强度 | 1/5 | 寡头格局，酱油价格战，新品牌生存空间极小 |
|
||||
| 品斛堂匹配度 | 2/5 | 有原料优势但无生产/渠道/品牌能力 |
|
||||
| 差异化空间 | 2/5 | 火锅底料有"养生"概念空间，酱油基本没有 |
|
||||
| 进入门槛 | 2/5 | 酱油需酿造产能（重资产），火锅底料可 OEM（轻资产） |
|
||||
| 盈利预期 | 2/5 | 头部企业净利率 15-20%，新品可能需要 2-3 年培育 |
|
||||
|
||||
---
|
||||
|
||||
## 三、预制菜赛道分析
|
||||
|
||||
### 3.1 市场规模与增长
|
||||
|
||||
| 指标 | 数据 | 来源 |
|
||||
|------|------|------|
|
||||
| 2022 年市场规模 | 4196 亿元，YoY +21.3% | 艾媒咨询 |
|
||||
| 2023 年市场规模 | 5165 亿元 | 艾媒/人民网研究院 |
|
||||
| 2024 年市场规模 | 4850-6000+ 亿元 | 艾媒蓝皮书（4850）/新华网（6000+） |
|
||||
| 2026 年预测 | 7490-10720 亿元 | 艾媒蓝皮书/早期预测 |
|
||||
| 全球预制食品市场（2025） | 3981 亿美元→2030 年 5316 亿美元，CAGR 6% | Statista |
|
||||
| B:C 端比例 | 约 7:3（B 端仍为主力） | 嘉世咨询 |
|
||||
| 渗透率 | 10-15%（美/日 60%+） | 艾媒/中国连锁餐饮报告 |
|
||||
| 企业数量 | 7.2 万+ 家 | 天眼查/企查查 |
|
||||
| 连锁化率驱动 | 2023 年餐饮连锁化率约 21%（美 54%/日 48%） | 中国连锁餐饮报告 |
|
||||
|
||||
**判断**：预制菜是确定性强的万亿赛道，但当前已从"野蛮生长"进入"规范整合"阶段。
|
||||
|
||||
### 3.2 竞争格局
|
||||
|
||||
#### 四类玩家错位竞争
|
||||
|
||||
| 类型 | 代表企业 | 优势 | 劣势 | 毛利率 |
|
||||
|------|------|------|------|:---:|
|
||||
| **上游农牧水产** | 国联水产、龙大美食、新希望 | 原料成本优势、规模化 | C 端品牌力弱 | 10-15% |
|
||||
| **传统速冻食品** | 安井食品、三全、千味央厨 | 规模化生产、渠道分销强 | B 端定制弱 | 25-30% |
|
||||
| **专业预制菜** | 味知香、蒸烩煮、聪厨 | 经验丰富、研发能力强 | 规模小、区域性强 | 25-30% |
|
||||
| **餐饮/零售** | 西贝、盒马、广州酒家、海底捞 | C 端品牌强、终端直连 | 渠道单一、自建中央厨房成本高 | 10-15% |
|
||||
|
||||
**关键发现**：
|
||||
- **行业高度分散**：CR10 仅 14%，无全国性龙头
|
||||
- **毛利率普遍偏低**：安井预制菜毛利率从 29.7%（2018）降至 11.4%（2022）
|
||||
- **同质化严重**：酸菜鱼、佛跳墙、小龙虾是最大单品，企业扎堆
|
||||
- **70% 企业为作坊式**：产品标准缺失，食品安全风险大
|
||||
|
||||
### 3.3 石斛预制菜可行性评估
|
||||
|
||||
#### 石斛炖鸡/排骨汤预制菜
|
||||
- **对标**：盒马（鲜食预制菜）、西贝（贾国龙功夫菜）、海底捞（预制菜线）
|
||||
- **差异化定位**："养生药膳预制菜"——区别于市面主流的麻辣/酸辣类
|
||||
- **理论优势**：石斛的"养生"心智 + 鸡汤的国民认知度 + 药膳文化底蕴
|
||||
- **实际挑战**：
|
||||
- 养生预制菜目前仍是极小众品类，主流消费者预制菜核心诉求是"便捷+好吃"而非"养生"
|
||||
- 药膳预制菜需要兼顾"功效"与"口味"，研发难度远超普通预制菜
|
||||
- "药膳"的保健功能宣传在合规层面存在极大风险（普通食品不得宣称保健功能）
|
||||
|
||||
#### 药膳预制菜市场信号（正面）
|
||||
- 抖音电商 2023 年 1-9 月药膳类预制菜销售额同比增长 605%
|
||||
- 温氏食品+昆中药推出参苓鸡系列
|
||||
- 磐安"盘安药膳"推出黄精肉、玉竹老鸭等产品
|
||||
- 广州酒家推出人参老鸭汤、人参益智仁乌鸡汤
|
||||
- **但注意**：这些均为大企业试水或区域特色产品，尚未出现药膳预制菜爆品
|
||||
|
||||
### 3.4 预制菜切入评分：★★☆☆☆（2/5）
|
||||
|
||||
| 维度 | 评分 | 说明 |
|
||||
|------|:---:|------|
|
||||
| 市场规模 | 5/5 | 万亿级赛道，增速 20%+ |
|
||||
| 竞争强度 | 2/5 | 高度碎片化、同质化，价格战正在蔓延 |
|
||||
| 品斛堂匹配度 | 1/5 | 无生产经验、无冷链、无渠道、远离消费市场 |
|
||||
| 差异化空间 | 3/5 | "养生药膳预制菜"有独特定位，但品类尚未验证 |
|
||||
| 进入门槛 | 2/5 | 冷链物流+口味研发+渠道建设均需重投入 |
|
||||
| 盈利预期 | 1/5 | 头部企业毛利率仅 10-15%，新品培育期可能长期亏损 |
|
||||
|
||||
---
|
||||
|
||||
## 四、品斛堂匹配度总体评估
|
||||
|
||||
### 4.1 优劣势对比
|
||||
|
||||
| 优势 | 劣势 |
|
||||
|------|------|
|
||||
| ✅ 石斛原料自供，全产业链成本可控 | ❌ **无预制菜/调味品生产经验** |
|
||||
| ✅ 食品生产资质齐全（药品+保健食品+食品） | ❌ **无冷链仓储和配送网络** |
|
||||
| ✅ OEM/ODM 服务经验（服务近 100 家企业） | ❌ **地处云南龙陵，远离核心消费市场** |
|
||||
| ✅ "养生"品牌心智（石斛原浆第一品牌） | ❌ **销售渠道以线上为主，线下商超/便利店覆盖弱** |
|
||||
| ✅ 云南地方特色食材资源（菌菇/酸汤等） | ❌ **预制菜和调味品研发团队缺失** |
|
||||
| ✅ 石斛多糖等原料可赋能产品差异化 | ❌ **调味品口味研发能力为零（酱油/火锅底料均需专业研发）** |
|
||||
|
||||
### 4.2 风险矩阵
|
||||
|
||||
| 风险类型 | 具体描述 | 严重程度 | 发生概率 |
|
||||
|------|------|:---:|:---:|
|
||||
| **市场风险** | 预制菜/调味品竞争白热化，新品牌存活率低 | 🔴 高 | 🔴 高 |
|
||||
| **运营风险** | 缺乏冷链物流和生产经验，产品质量难以保证 | 🔴 高 | 🔴 高 |
|
||||
| **财务风险** | 毛利率极低（10-15%），初期投入大、回收慢 | 🟡 中 | 🔴 高 |
|
||||
| **合规风险** | "养生药膳"概念在食品宣传中触碰《广告法》红线 | 🔴 高 | 🟡 中 |
|
||||
| **品牌风险** | 预制菜若出食品安全问题，反噬石斛原浆主品牌 | 🔴 高 | 🟡 中 |
|
||||
|
||||
---
|
||||
|
||||
## 五、三种切入路径对比
|
||||
|
||||
### 路径 A：轻资产 OEM 试水（推荐指数：★★★★☆）
|
||||
|
||||
| 维度 | 详情 |
|
||||
|------|------|
|
||||
| **方式** | 与成熟预制菜/调味品代工厂合作，品斛堂提供石斛原料+品牌+渠道 |
|
||||
| **首推产品** | ① 石斛菌菇养生汤料包（常温/冷冻） ② 石斛云南酸汤火锅底料 |
|
||||
| **启动资金** | 300-500 万元（含研发费+首批生产+包装设计+渠道推广） |
|
||||
| **时间线** | 3-6 个月产品上市，12 个月验证期 |
|
||||
| **主要风险** | 品控依赖代工厂；利润被代工费挤压；产品差异化不够 |
|
||||
| **退出成本** | 低——可随时停止而不影响主营业务 |
|
||||
|
||||
### 路径 B：战略合作/合资（推荐指数：★★★☆☆）
|
||||
|
||||
| 维度 | 详情 |
|
||||
|------|------|
|
||||
| **方式** | 与云南本地餐饮集团或预制菜企业成立合资公司，共同开发云南药膳预制菜 |
|
||||
| **首推产品** | 石斛汽锅鸡预制菜、石斛菌汤包、云南过桥米线石斛汤底 |
|
||||
| **启动资金** | 1000-2000 万元（含合资公司注册+产线改造+冷链建设） |
|
||||
| **时间线** | 6-12 个月产品上市，18-24 个月盈亏平衡 |
|
||||
| **主要风险** | 合作伙伴选择失误；利益分配冲突；管理复杂度高 |
|
||||
| **退出成本** | 中——合资公司清算或股权转让 |
|
||||
|
||||
### 路径 C：自建产线重资产进入（推荐指数：★☆☆☆☆）
|
||||
|
||||
| 维度 | 详情 |
|
||||
|------|------|
|
||||
| **方式** | 在龙陵或昆明自建预制菜中央厨房/调味品生产线 |
|
||||
| **首推产品** | 全系列石斛预制菜+石斛调味品 |
|
||||
| **启动资金** | 5000 万-1 亿元（含厂房+设备+冷链物流+团队+渠道） |
|
||||
| **时间线** | 18-24 个月产品上市，36-48 个月盈亏平衡 |
|
||||
| **主要风险** | 资金压力大；产能利用率不足；远离消费市场导致冷链成本高 |
|
||||
| **退出成本** | 极高——固定资产沉没，转型困难 |
|
||||
| **当前阶段** | **强烈不建议** |
|
||||
|
||||
### 三路径对照总结
|
||||
|
||||
| 维度 | 路径 A OEM 试水 | 路径 B 战略合作 | 路径 C 重资产自建 |
|
||||
|------|:---:|:---:|:---:|
|
||||
| 启动资金 | 300-500 万 | 1000-2000 万 | 5000 万-1 亿 |
|
||||
| 上市时间 | 3-6 个月 | 6-12 个月 | 18-24 个月 |
|
||||
| 盈亏平衡 | 6-12 个月 | 18-24 个月 | 36-48 个月 |
|
||||
| 风险等级 | 低 | 中 | 极高 |
|
||||
| 可控性 | 中 | 中高 | 高 |
|
||||
| 利润空间 | 低（代工费挤压） | 中（合资分成） | 中高（规模效应后） |
|
||||
| 推荐指数 | ★★★★☆ | ★★★☆☆ | ★☆☆☆☆ |
|
||||
|
||||
---
|
||||
|
||||
## 六、预期投入与回报周期（路径 A）
|
||||
|
||||
| 项目 | 明细 | 金额（万元） |
|
||||
|------|------|:---:|
|
||||
| **一次性投入** | | |
|
||||
| 产品研发（汤料/火锅底料配方+石斛添加比例测试+保质期验证） | 外部研发合作 | 50-80 |
|
||||
| 包装设计（品牌视觉+包材+首批印刷） | 设计+模具 | 30-50 |
|
||||
| 首批生产（最小起订量，含石斛原料成本） | 3-5 个 SKU | 100-150 |
|
||||
| 渠道铺设（线上详情页+达播合作+线下试销进场费） | | 50-80 |
|
||||
| **一次性投入合计** | | **230-360 万** |
|
||||
| **月度运营** | | |
|
||||
| 线上运营（投流+平台佣金+团队） | 月均 | 20-40 |
|
||||
| 线下促销/试吃/陈列费 | 月均 | 10-20 |
|
||||
| **首年总投入** | | **约 500-700 万** |
|
||||
|
||||
| 时间节点 | 里程碑 | 预期表现 |
|
||||
|------|------|------|
|
||||
| 第 3 个月 | 产品上市（天猫/抖音首发） | 月销 10-20 万 |
|
||||
| 第 6 个月 | 首轮数据验证 | 月销 30-50 万，复购率 > 15% → 继续投入 |
|
||||
| 第 12 个月 | Go/No-Go 决策 | 月销 100 万+ → 考虑路径 B；< 30 万 → 停项目 |
|
||||
|
||||
---
|
||||
|
||||
## 七、最终建议
|
||||
|
||||
### 🟡 总体判断：**观望**
|
||||
|
||||
**进入** ❌
|
||||
**观望** ✅（选择此项）
|
||||
**放弃** ❌
|
||||
|
||||
### 核心理由
|
||||
|
||||
1. **预制菜/调味品均处于格局剧变期**：预制菜国家标准正在制定中，行业即将洗牌；调味品"零添加"禁令 2027 年全面生效，整个行业的产品和营销逻辑都在重构。此时贸然进入意味着在不确定的规则下做重投入决策。
|
||||
|
||||
2. **品斛堂的核心能力与预制菜/调味品的核心要求不匹配**：
|
||||
- 预制菜的核心竞争力 = **冷链物流网络 + 口味研发 + 渠道效率 + 成本控制**
|
||||
- 调味品的核心竞争力 = **酿造产能 + 品牌认知 + 百万终端覆盖 + 规模效应**
|
||||
- 品斛堂的核心优势 = **石斛全产业链 + 原浆品类开创者 + 线上电商运营**
|
||||
- 这三个集合的交集非常小
|
||||
|
||||
3. **资源应该聚焦核心战场**：
|
||||
- 石斛原浆市场规模 120 亿，品斛堂市占率 45%+，还有 55%+ 的空间
|
||||
- 复合原浆是第二增长曲线，增速 25%+，且与现有能力高度匹配
|
||||
- 保健品蓝帽子注册是高毛利壁垒型业务（毛利率 60-80%）
|
||||
- 这些机会的投入产出比远高于预制菜/调味品
|
||||
|
||||
4. **但不应完全放弃——可以"轻试水"**：
|
||||
- 石斛养生汤料包和火锅底料可以极低成本试水（路径 A，300-500 万）
|
||||
- 利用现有天猫/京东/抖音渠道做首发，不用新建渠道
|
||||
- 本质上是将石斛原料以"汤料包"形式触达消费者
|
||||
- 12 个月后根据数据决定是继续还是止损
|
||||
|
||||
### 行动建议
|
||||
|
||||
| 优先级 | 行动 | 时间 |
|
||||
|:---:|------|------|
|
||||
| P0 | 保持预制菜/调味品赛道月度舆情监控 | 即刻开始 |
|
||||
| P1 | 石斛菌菇养生汤料包 OEM 试水立项（路径 A） | 下季度 |
|
||||
| P2 | 调研云南本地预制菜合作伙伴（路径 B 前期） | 6 个月后 |
|
||||
| P3 | 关注预制菜国家标准出台后的行业洗牌窗口 | 持续跟踪 |
|
||||
|
||||
---
|
||||
|
||||
## 八、数据来源与假设说明
|
||||
|
||||
### 主要数据来源
|
||||
|
||||
| 编号 | 来源 | 数据类型 | 时效 |
|
||||
|:---:|------|------|:---:|
|
||||
| [1] | 艾媒咨询《2023-2025 年中国预制菜行业运行及投资决策分析报告》 | 预制菜市场规模/格局 | 2024 |
|
||||
| [2] | 艾媒咨询《2024-2025 年中国预制菜产业发展蓝皮书》 | 预制菜市场最新数据 | 2025 |
|
||||
| [3] | 艾媒咨询《2025 年 H1 中国调味品行业运行数据监测半年报》 | 调味品市场数据 | 2025 |
|
||||
| [4] | 华经产业研究院《中国复合调味品行业发展现状》 | 复合调味品市场规模 | 2024 |
|
||||
| [5] | 弗诺斯特沙利文 | 酱油市场数据 | 2024-2025 |
|
||||
| [6] | 嘉世咨询《2025 年中国调味品行业报告》 | 调味品竞争格局 | 2025 |
|
||||
| [7] | 新华网/中国商报 | 预制菜企业数量/国家标准进展 | 2025 |
|
||||
| [8] | 华鑫证券/平安证券预制菜行业研报 | 预制菜供应链/竞争分析 | 2023-2024 |
|
||||
| [9] | 灼识咨询《2022 中国预制菜行业蓝皮书》 | 竞争格局 | 2022 |
|
||||
| [10] | FDL 数食主张《药膳预制菜》 | 药膳预制菜趋势 | 2023 |
|
||||
| [11] | 抖音电商数据（引用自食品伙伴网） | 药膳预制菜增长 | 2023 |
|
||||
| [12] | 品斛堂企业调研报告（BIZ-53） | 品斛堂企业情报 | 2026.06 |
|
||||
| [13] | 石斛食品饮料全品类产品方向详细文档 | 参考产品规划 | 2026 |
|
||||
|
||||
### 关键假设
|
||||
|
||||
- 2026 年预制菜市场规模取艾媒蓝皮书 7490 亿（较保守口径）
|
||||
- 品斛堂参考文档中预制菜/调味品毛利预期 30-50%，本报告校正为更保守的 10-25%（基于上市公司实际数据）
|
||||
- 药膳预制菜"增速数据（605%）基于抖音电商单一渠道，不代表全渠道增速
|
||||
- 投资金额估算为行业平均水平参考值，实际可能因合作伙伴、地区政策等因素而浮动
|
||||
- 石斛火锅底料的"不上火"概念为市场假设，需通过消费者调研验证
|
||||
|
||||
---
|
||||
|
||||
*本报告仅供内部决策参考，不构成对外投资建议。*
|
||||
*数据截止日期：2026 年 6 月 26 日*
|
||||
@@ -1,3 +0,0 @@
|
||||
__pycache__/
|
||||
*.egg-info/
|
||||
.mypy_cache/
|
||||
@@ -1,40 +0,0 @@
|
||||
# NVIDIA Sidecar 限流代理 — 生产 Docker 镜像 (BIZ-46 Phase3 §4)
|
||||
#
|
||||
# 构建：
|
||||
# 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" \
|
||||
# -e SIDECAR_RATE_RPM=40 \
|
||||
# -v $(pwd)/logs:/opt/nvidia-sidecar/logs \
|
||||
# nvidia-sidecar:latest
|
||||
|
||||
FROM python:3.12-slim AS base
|
||||
|
||||
WORKDIR /app
|
||||
|
||||
# 安装依赖（利用 Docker 层缓存）
|
||||
COPY pyproject.toml .
|
||||
RUN pip install --no-cache-dir fastapi>=0.115 \
|
||||
"uvicorn[standard]>=0.34" httpx>=0.28 PyYAML>=6.0 \
|
||||
structlog>=24.4 "prometheus-client>=0.21" pydantic>=2.0
|
||||
|
||||
# 复制源码
|
||||
COPY . .
|
||||
|
||||
# 非 root 用户运行
|
||||
RUN useradd -r -m -s /bin/false sidecar \
|
||||
&& mkdir -p /opt/nvidia-sidecar/logs \
|
||||
&& chown -R sidecar:sidecar /app /opt/nvidia-sidecar/logs
|
||||
USER sidecar
|
||||
|
||||
# 健康检查
|
||||
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
|
||||
CMD python -c "import httpx; r=httpx.get('http://127.0.0.1:9190/health'); exit(0 if r.status_code==200 else 1)"
|
||||
|
||||
EXPOSE 9190 9191
|
||||
|
||||
CMD ["uvicorn", "nvidia_sidecar.server:app", "--host", "0.0.0.0", "--port", "9190"]
|
||||
@@ -1,118 +0,0 @@
|
||||
# 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` | `60` | 上游请求超时（秒） |
|
||||
| `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，线程安全，支持阻塞/非阻塞消费
|
||||
@@ -1,41 +0,0 @@
|
||||
"""
|
||||
NVIDIA Sidecar 限流代理 — 核心代理模块。
|
||||
|
||||
为 OpenAI Chat Completions 兼容 API 提供四层防护：
|
||||
1. 请求接收（FastAPI）
|
||||
2. 网关识别 → 非 NVIDIA 直通
|
||||
3. 优先级排队 → 令牌桶限流
|
||||
4. httpx 异步转发到 NVIDIA 上游
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from nvidia_sidecar.config import SidecarConfig, load_config
|
||||
from nvidia_sidecar.rate_limiter import (
|
||||
Priority,
|
||||
TokenBucket,
|
||||
is_nvidia_gateway,
|
||||
normalize_gateway_name,
|
||||
)
|
||||
from nvidia_sidecar.priority_queue import (
|
||||
PriorityQueueItem,
|
||||
PriorityRequestQueue,
|
||||
QueueFullError,
|
||||
QueueFullPassthrough,
|
||||
QueueFullPolicy,
|
||||
)
|
||||
|
||||
__version__ = "0.1.0"
|
||||
__all__ = [
|
||||
"SidecarConfig",
|
||||
"load_config",
|
||||
"Priority",
|
||||
"TokenBucket",
|
||||
"is_nvidia_gateway",
|
||||
"normalize_gateway_name",
|
||||
"PriorityQueueItem",
|
||||
"PriorityRequestQueue",
|
||||
"QueueFullError",
|
||||
"QueueFullPassthrough",
|
||||
"QueueFullPolicy",
|
||||
]
|
||||
@@ -1,221 +0,0 @@
|
||||
"""
|
||||
NVIDIA Sidecar 限流代理 — 配置管理模块 (§3.1)
|
||||
|
||||
集中管理 Sidecar 运行参数，支持环境变量覆盖和 YAML 配置文件。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
import warnings
|
||||
from dataclasses import dataclass, field
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
|
||||
@dataclass
|
||||
class SidecarConfig:
|
||||
"""Sidecar 运行配置数据类。
|
||||
|
||||
所有字段可通过环境变量覆盖，优先级：环境变量 > YAML 配置文件 > 默认值。
|
||||
"""
|
||||
|
||||
# ---- 网络 ----
|
||||
listen_host: str = field(
|
||||
default="127.0.0.1",
|
||||
metadata={"env": "SIDECAR_HOST"},
|
||||
)
|
||||
listen_port: int = field(
|
||||
default=9190,
|
||||
metadata={"env": "SIDECAR_PORT"},
|
||||
)
|
||||
metrics_port: int = field(
|
||||
default=9191,
|
||||
metadata={"env": "SIDECAR_METRICS_PORT"},
|
||||
)
|
||||
|
||||
# ---- 上游 ----
|
||||
upstream_url: str = field(
|
||||
default="https://integrate.api.nvidia.com/v1",
|
||||
metadata={"env": "SIDECAR_UPSTREAM"},
|
||||
)
|
||||
upstream_api_key: str = field(
|
||||
default="",
|
||||
metadata={"env": "SIDECAR_API_KEY"},
|
||||
)
|
||||
|
||||
# ---- 限流 ----
|
||||
rate_rpm: int = field(
|
||||
default=40,
|
||||
metadata={"env": "SIDECAR_RATE_RPM"},
|
||||
)
|
||||
bucket_capacity: int = field(
|
||||
default=40,
|
||||
metadata={"env": "SIDECAR_BUCKET_CAPACITY"},
|
||||
)
|
||||
|
||||
# ---- 超时 ----
|
||||
request_timeout: float = field(
|
||||
default=60.0,
|
||||
metadata={"env": "SIDECAR_TIMEOUT"},
|
||||
)
|
||||
|
||||
# ---- 队列 ----
|
||||
queue_max_size: int = field(
|
||||
default=500,
|
||||
metadata={"env": "SIDECAR_QUEUE_MAX"},
|
||||
)
|
||||
low_priority_timeout: float = field(
|
||||
default=2.0,
|
||||
metadata={"env": "SIDECAR_LOW_TIMEOUT"},
|
||||
)
|
||||
|
||||
# ---- 降级 ----
|
||||
fallback_enabled_passthrough: bool = field(
|
||||
default=True,
|
||||
metadata={"env": "SIDECAR_FALLBACK_PASSTHROUGH"},
|
||||
)
|
||||
|
||||
# ---- 日志 ----
|
||||
log_level: str = field(
|
||||
default="INFO",
|
||||
metadata={"env": "SIDECAR_LOG_LEVEL"},
|
||||
)
|
||||
|
||||
|
||||
def _apply_env_overrides(config: SidecarConfig) -> SidecarConfig:
|
||||
"""用环境变量覆盖配置字段。
|
||||
|
||||
遍历 SidecarConfig 的 dataclass fields，对每个声明了 ``metadata={"env": ...}``
|
||||
的字段检查环境变量是否存在，存在则用对应类型转换后覆盖。
|
||||
"""
|
||||
import dataclasses as _dc
|
||||
|
||||
# 使用 typing.get_type_hints 解析 from __future__ import annotations
|
||||
# 引入的字符串化类型注解 (PEP 563)
|
||||
try:
|
||||
resolved_types = __import__("typing").get_type_hints(type(config))
|
||||
except Exception:
|
||||
resolved_types = {}
|
||||
|
||||
for fld in _dc.fields(config):
|
||||
env_key: str | None = fld.metadata.get("env")
|
||||
if env_key is None:
|
||||
continue
|
||||
env_val = os.environ.get(env_key)
|
||||
if env_val is None:
|
||||
continue
|
||||
|
||||
target_type = resolved_types.get(fld.name, fld.type)
|
||||
target_type_name: str = getattr(target_type, "__name__", str(target_type))
|
||||
try:
|
||||
if target_type is bool or target_type == "bool":
|
||||
parsed: bool = env_val.strip().lower() in ("true", "1", "yes", "on")
|
||||
setattr(config, fld.name, parsed)
|
||||
elif target_type is int or target_type == "int":
|
||||
setattr(config, fld.name, int(env_val))
|
||||
elif target_type is float or target_type == "float":
|
||||
setattr(config, fld.name, float(env_val))
|
||||
else:
|
||||
setattr(config, fld.name, env_val)
|
||||
except (ValueError, TypeError) as exc:
|
||||
warnings.warn(
|
||||
f"无法将环境变量 {env_key}={env_val!r} 转换为 {target_type_name}: {exc}"
|
||||
)
|
||||
|
||||
return config
|
||||
|
||||
|
||||
def _validate_config(config: SidecarConfig) -> list[str]:
|
||||
"""验证配置合理性，返回警告/问题列表。"""
|
||||
issues: list[str] = []
|
||||
|
||||
# 端口冲突检查
|
||||
if config.listen_port == config.metrics_port:
|
||||
issues.append(
|
||||
f"listen_port ({config.listen_port}) 与 metrics_port ({config.metrics_port}) 相同"
|
||||
)
|
||||
|
||||
# rate_rpm 边界检查
|
||||
if config.rate_rpm <= 0:
|
||||
issues.append(
|
||||
f"rate_rpm ({config.rate_rpm}) 无效，回退到默认值 40"
|
||||
)
|
||||
config.rate_rpm = 40
|
||||
|
||||
# queue_max_size 合理性
|
||||
if config.queue_max_size <= 0:
|
||||
issues.append(
|
||||
f"queue_max_size ({config.queue_max_size}) 无效，回退到默认值 500"
|
||||
)
|
||||
config.queue_max_size = 500
|
||||
|
||||
# request_timeout 合理性
|
||||
if config.request_timeout <= 0:
|
||||
issues.append(
|
||||
f"request_timeout ({config.request_timeout}) 无效，回退到默认值 60"
|
||||
)
|
||||
config.request_timeout = 60.0
|
||||
elif config.request_timeout > 300.0:
|
||||
issues.append(
|
||||
f"request_timeout ({config.request_timeout}) 异常偏高，已截断为 300"
|
||||
)
|
||||
config.request_timeout = 300.0
|
||||
|
||||
return issues
|
||||
|
||||
|
||||
def load_config(path: str | None = None) -> SidecarConfig:
|
||||
"""加载 Sidecar 配置。
|
||||
|
||||
加载顺序（后者覆盖前者）：
|
||||
1. 默认值（SidecarConfig dataclass defaults）
|
||||
2. YAML 配置文件（如果 path 提供）
|
||||
3. 环境变量覆盖
|
||||
|
||||
Args:
|
||||
path: 可选 YAML 配置文件路径。为 None 时只使用默认值 + 环境变量。
|
||||
|
||||
Returns:
|
||||
经过验证的 SidecarConfig 实例。
|
||||
|
||||
Raises:
|
||||
FileNotFoundError: path 指定的文件不存在。
|
||||
yaml.YAMLError: YAML 解析失败。
|
||||
"""
|
||||
config = SidecarConfig()
|
||||
|
||||
if path is not None:
|
||||
import yaml
|
||||
|
||||
cfg_path = Path(path)
|
||||
if not cfg_path.is_file():
|
||||
raise FileNotFoundError(f"配置文件不存在: {cfg_path}")
|
||||
|
||||
try:
|
||||
raw: dict[str, Any] = yaml.safe_load(cfg_path.read_text(encoding="utf-8")) or {}
|
||||
except yaml.YAMLError as exc:
|
||||
raise yaml.YAMLError(f"YAML 解析失败 ({cfg_path}): {exc}") from exc
|
||||
|
||||
# 覆盖已声明的字段
|
||||
for fld_name in (
|
||||
"listen_host", "listen_port", "metrics_port",
|
||||
"upstream_url", "upstream_api_key",
|
||||
"rate_rpm", "bucket_capacity",
|
||||
"request_timeout",
|
||||
"queue_max_size", "low_priority_timeout",
|
||||
"fallback_enabled_passthrough",
|
||||
"log_level",
|
||||
):
|
||||
if fld_name in raw:
|
||||
setattr(config, fld_name, raw[fld_name])
|
||||
|
||||
# 环境变量覆盖（最高优先级）
|
||||
config = _apply_env_overrides(config)
|
||||
|
||||
# 验证
|
||||
issues = _validate_config(config)
|
||||
for issue in issues:
|
||||
warnings.warn(issue)
|
||||
|
||||
return config
|
||||
@@ -1,75 +0,0 @@
|
||||
"""
|
||||
NVIDIA Sidecar — SidecarContext 依赖注入容器 (§BIZ-46 Phase3)
|
||||
|
||||
将所有模块级全局状态收敛为单一 dataclass，通过 FastAPI app.state 注入，
|
||||
消除 webui.py → server 的反向导入，支持可测试性和多实例扩展。
|
||||
|
||||
设计文档: docs/architecture/BIZ-46_Phase3_Architecture_Design.md §1
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import time
|
||||
from dataclasses import dataclass, field
|
||||
from typing import TYPE_CHECKING, Any
|
||||
|
||||
import httpx
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from nvidia_sidecar.config import SidecarConfig
|
||||
from nvidia_sidecar.rate_limiter import AdaptiveTokenBucket
|
||||
from nvidia_sidecar.priority_queue import PriorityRequestQueue
|
||||
from nvidia_sidecar.metrics import PrometheusMetrics
|
||||
from nvidia_sidecar.health import HealthService
|
||||
|
||||
|
||||
@dataclass
|
||||
class SidecarContext:
|
||||
"""Sidecar 全局运行时上下文 — 所有核心组件的唯一容器。
|
||||
|
||||
通过 ``app.state.sidecar`` 注入 FastAPI，路由通过 ``Depends(get_context)`` 获取。
|
||||
"""
|
||||
|
||||
# ---- 核心组件 ----
|
||||
config: SidecarConfig
|
||||
http_client: httpx.AsyncClient
|
||||
token_bucket: AdaptiveTokenBucket
|
||||
priority_queue: PriorityRequestQueue
|
||||
prometheus: PrometheusMetrics
|
||||
health: HealthService
|
||||
|
||||
# ---- 运行时状态 ----
|
||||
pending_requests: dict[str, tuple["asyncio.Future[Any]", float]] = field(default_factory=dict)
|
||||
"""request_id → (response future, enqueued_at) 的映射。"""
|
||||
|
||||
stats: dict[str, int] = field(default_factory=lambda: {
|
||||
"total_requests": 0,
|
||||
"nvidia_requests": 0,
|
||||
"passthrough_requests": 0,
|
||||
"ratelimited_requests": 0,
|
||||
"queue_full_rejects": 0,
|
||||
"upstream_errors": 0,
|
||||
"start_time": 0,
|
||||
})
|
||||
|
||||
stats_lock: asyncio.Lock = field(default_factory=asyncio.Lock)
|
||||
|
||||
# ---- 缓存 ----
|
||||
snapshot_cache: tuple["dict[str, Any]", float] | None = None
|
||||
"""SSE 快照共享缓存: (data, timestamp)。"""
|
||||
snapshot_cache_lock: asyncio.Lock = field(default_factory=asyncio.Lock)
|
||||
SNAPSHOT_CACHE_TTL: float = 1.0
|
||||
|
||||
# ---- 便捷方法 ----
|
||||
|
||||
async def increment_stat(self, key: str, delta: int = 1) -> None:
|
||||
"""线程安全的统计计数器自增。"""
|
||||
async with self.stats_lock:
|
||||
self.stats[key] = self.stats.get(key, 0) + delta
|
||||
|
||||
@property
|
||||
def uptime_seconds(self) -> int:
|
||||
"""服务运行时长（秒）。"""
|
||||
st = self.stats.get("start_time", 0)
|
||||
return int(time.time() - st) if st else 0
|
||||
@@ -1,31 +0,0 @@
|
||||
# NVIDIA Sidecar 环境变量清单 (BIZ-46 Phase3 §4)
|
||||
# 复制为 .env 后按需修改，供 Docker / systemd 使用。
|
||||
|
||||
# 网络
|
||||
SIDECAR_HOST=127.0.0.1
|
||||
SIDECAR_PORT=9190
|
||||
SIDECAR_METRICS_PORT=9191
|
||||
|
||||
# 上游 API（必填）
|
||||
SIDECAR_UPSTREAM=https://integrate.api.nvidia.com/v1
|
||||
SIDECAR_API_KEY=nvapi-your-key-here
|
||||
|
||||
# 限流
|
||||
SIDECAR_RATE_RPM=40
|
||||
SIDECAR_BUCKET_CAPACITY=40
|
||||
|
||||
# 超时
|
||||
SIDECAR_TIMEOUT=60
|
||||
|
||||
# 队列
|
||||
SIDECAR_QUEUE_MAX=500
|
||||
SIDECAR_LOW_TIMEOUT=2
|
||||
|
||||
# 降级
|
||||
SIDECAR_FALLBACK_PASSTHROUGH=true
|
||||
|
||||
# 日志
|
||||
SIDECAR_LOG_LEVEL=INFO
|
||||
|
||||
# Admin API 认证（可选，不设置则跳过认证）
|
||||
# SIDECAR_ADMIN_TOKEN=your-admin-token-here
|
||||
@@ -1,49 +0,0 @@
|
||||
# NVIDIA Sidecar 限流代理 — systemd service (BIZ-46 Phase3 §4)
|
||||
#
|
||||
# 安装：
|
||||
# sudo cp deploy/nvidia-sidecar.service /etc/systemd/system/
|
||||
# sudo systemctl daemon-reload
|
||||
# sudo systemctl enable nvidia-sidecar
|
||||
# sudo systemctl start nvidia-sidecar
|
||||
#
|
||||
# 运维：
|
||||
# sudo systemctl status nvidia-sidecar
|
||||
# sudo journalctl -u nvidia-sidecar -f
|
||||
|
||||
[Unit]
|
||||
Description=NVIDIA Sidecar Rate-Limiting Proxy
|
||||
Documentation=https://github.com/bizwings/nvidia-sidecar
|
||||
After=network-online.target
|
||||
Wants=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=sidecar
|
||||
Group=sidecar
|
||||
WorkingDirectory=/opt/nvidia-sidecar
|
||||
ExecStart=/opt/nvidia-sidecar/.venv/bin/uvicorn nvidia_sidecar.server:app \
|
||||
--host 127.0.0.1 \
|
||||
--port 9190 \
|
||||
--log-level info
|
||||
Restart=always
|
||||
RestartSec=5
|
||||
|
||||
# 环境变量
|
||||
EnvironmentFile=/opt/nvidia-sidecar/.env
|
||||
|
||||
# 安全加固
|
||||
NoNewPrivileges=true
|
||||
ProtectSystem=strict
|
||||
ProtectHome=true
|
||||
PrivateTmp=true
|
||||
ReadWritePaths=/opt/nvidia-sidecar/logs
|
||||
|
||||
# 资源限制
|
||||
LimitNOFILE=65536
|
||||
MemoryMax=512M
|
||||
|
||||
# 启动延迟（等待网络就绪）
|
||||
ExecStartPre=/bin/sleep 1
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
@@ -1,198 +0,0 @@
|
||||
"""
|
||||
NVIDIA Sidecar 限流代理 — 健康检查端点 (§3.6)
|
||||
|
||||
提供 Kubernetes / systemd 兼容的健康检查：
|
||||
GET /health — 存活检查
|
||||
GET /health/ready — 就绪检查（含上游连通性）
|
||||
|
||||
BIZ-46 Phase3: Readiness HTTP Client 复用 — 注入主 http_client，
|
||||
不再每次检查创建新 client，降低 K8s/systemd 高频探测的连接开销。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import time
|
||||
from dataclasses import dataclass
|
||||
from typing import Any
|
||||
|
||||
import httpx
|
||||
|
||||
|
||||
@dataclass
|
||||
class HealthService:
|
||||
"""健康检查服务。
|
||||
|
||||
封装存活检查和就绪检查的逻辑，供 server.py 路由调用。
|
||||
"""
|
||||
|
||||
start_time: float = 0.0
|
||||
version: str = "0.1.0"
|
||||
|
||||
def __post_init__(self) -> None:
|
||||
if self.start_time == 0.0:
|
||||
self.start_time = time.time()
|
||||
|
||||
@property
|
||||
def uptime_seconds(self) -> float:
|
||||
"""服务运行时长（秒）。"""
|
||||
return time.time() - self.start_time
|
||||
|
||||
async def check_upstream(
|
||||
self,
|
||||
upstream_url: str,
|
||||
http_client: httpx.AsyncClient,
|
||||
timeout: float = 5.0,
|
||||
api_key: str = "",
|
||||
) -> bool:
|
||||
"""检查上游连通性（复用注入的 http_client，BIZ-46 Phase3）。
|
||||
|
||||
Args:
|
||||
upstream_url: NVIDIA API base URL。
|
||||
http_client: 复用的 httpx.AsyncClient（来自 ctx）。
|
||||
timeout: 超时秒数（per-request override）。
|
||||
api_key: 可选的 API Key 用于认证。
|
||||
|
||||
Returns:
|
||||
True 上游可达。
|
||||
"""
|
||||
try:
|
||||
headers: dict[str, str] = {}
|
||||
if api_key:
|
||||
headers["authorization"] = f"Bearer {api_key}"
|
||||
|
||||
resp = await http_client.get(
|
||||
f"{upstream_url.rstrip('/')}/v1/models",
|
||||
headers=headers,
|
||||
timeout=timeout,
|
||||
)
|
||||
return resp.status_code < 500
|
||||
except Exception:
|
||||
return False
|
||||
|
||||
def check_queue_healthy(
|
||||
self,
|
||||
current_size: int,
|
||||
max_size: int,
|
||||
threshold_ratio: float = 0.9,
|
||||
) -> bool:
|
||||
"""检查队列是否健康（未接近满载）。
|
||||
|
||||
Args:
|
||||
current_size: 当前队列长度。
|
||||
max_size: 队列最大容量。
|
||||
threshold_ratio: 告警阈值比例，默认 0.9。
|
||||
|
||||
Returns:
|
||||
True 队列健康。
|
||||
"""
|
||||
if max_size <= 0:
|
||||
return True
|
||||
return current_size < max_size * threshold_ratio
|
||||
|
||||
def check_token_bucket_healthy(
|
||||
self,
|
||||
available_tokens: float,
|
||||
capacity: int,
|
||||
threshold: float = 0.05,
|
||||
) -> bool:
|
||||
"""检查令牌桶是否健康（token 未耗尽）。
|
||||
|
||||
Args:
|
||||
available_tokens: 当前可用令牌数。
|
||||
capacity: 桶容量。
|
||||
threshold: 令牌数低于此比例视为不健康。
|
||||
|
||||
Returns:
|
||||
True 令牌桶健康。
|
||||
"""
|
||||
if capacity <= 0:
|
||||
return False
|
||||
return available_tokens > capacity * threshold
|
||||
|
||||
def liveness(self) -> dict[str, Any]:
|
||||
"""存活检查响应。
|
||||
|
||||
Returns:
|
||||
liveness JSON payload。
|
||||
"""
|
||||
return {
|
||||
"status": "ok",
|
||||
"uptime": round(self.uptime_seconds, 1),
|
||||
"version": self.version,
|
||||
}
|
||||
|
||||
async def readiness(
|
||||
self,
|
||||
upstream_url: str,
|
||||
upstream_api_key: str = "",
|
||||
queue_current_size: int = 0,
|
||||
queue_max_size: int = 500,
|
||||
available_tokens: float = 0.0,
|
||||
bucket_capacity: int = 40,
|
||||
http_client: httpx.AsyncClient | None = None,
|
||||
) -> dict[str, Any]:
|
||||
"""就绪检查响应。
|
||||
|
||||
Args:
|
||||
upstream_url: 上游 API 地址。
|
||||
upstream_api_key: API Key。
|
||||
queue_current_size: 当前队列长度。
|
||||
queue_max_size: 队列最大容量。
|
||||
available_tokens: 当前令牌数。
|
||||
bucket_capacity: 桶容量。
|
||||
http_client: 复用的 httpx.AsyncClient（BIZ-46 Phase3）。
|
||||
为 None 时回退到每次创建新 client（兼容旧调用）。
|
||||
|
||||
Returns:
|
||||
readiness JSON payload。
|
||||
"""
|
||||
if http_client is not None:
|
||||
upstream_ok = await self.check_upstream(
|
||||
upstream_url, http_client=http_client, api_key=upstream_api_key,
|
||||
)
|
||||
else:
|
||||
# 向后兼容：无 http_client 时沿用旧行为
|
||||
upstream_ok = await self.check_upstream_standalone(
|
||||
upstream_url, api_key=upstream_api_key,
|
||||
)
|
||||
|
||||
queue_ok = self.check_queue_healthy(queue_current_size, queue_max_size)
|
||||
token_ok = self.check_token_bucket_healthy(available_tokens, bucket_capacity)
|
||||
all_ready = upstream_ok and queue_ok and token_ok
|
||||
|
||||
return {
|
||||
"ready": all_ready,
|
||||
"upstream_reachable": upstream_ok,
|
||||
"queue_healthy": queue_ok,
|
||||
"token_bucket_healthy": token_ok,
|
||||
}
|
||||
|
||||
async def check_upstream_standalone(
|
||||
self,
|
||||
upstream_url: str,
|
||||
timeout: float = 5.0,
|
||||
api_key: str = "",
|
||||
) -> bool:
|
||||
"""独立检查上游连通性（向后兼容，每次创建新 client）。
|
||||
|
||||
Args:
|
||||
upstream_url: NVIDIA API base URL。
|
||||
timeout: 超时秒数。
|
||||
api_key: 可选的 API Key。
|
||||
|
||||
Returns:
|
||||
True 上游可达。
|
||||
"""
|
||||
try:
|
||||
headers: dict[str, str] = {}
|
||||
if api_key:
|
||||
headers["authorization"] = f"Bearer {api_key}"
|
||||
|
||||
async with httpx.AsyncClient(timeout=timeout) as client:
|
||||
resp = await client.get(
|
||||
f"{upstream_url.rstrip('/')}/v1/models",
|
||||
headers=headers,
|
||||
)
|
||||
return resp.status_code < 500
|
||||
except Exception:
|
||||
return False
|
||||
@@ -1,277 +0,0 @@
|
||||
"""
|
||||
NVIDIA Sidecar 限流代理 — Prometheus 指标端点 (§3.5)
|
||||
|
||||
10 个指标，独立端口 :9191，与代理端口 :9190 分离。
|
||||
|
||||
BIZ-46 Phase3: Prometheus 标签基数治理 — model_id label 收敛为 provider。
|
||||
- upstream_latency_seconds: model_id → provider (固定值 "nvidia", 基数=1)
|
||||
- upstream_errors_total: model_id → provider
|
||||
- 模型级信息迁移到 structlog JSON 日志
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import time
|
||||
import threading
|
||||
from typing import Any
|
||||
|
||||
from prometheus_client import (
|
||||
CollectorRegistry,
|
||||
Counter,
|
||||
Gauge,
|
||||
Histogram,
|
||||
generate_latest,
|
||||
make_asgi_app,
|
||||
)
|
||||
|
||||
|
||||
class PrometheusMetrics:
|
||||
"""Sidecar Prometheus 指标收集器。
|
||||
|
||||
线程安全，所有公开方法通过 ``threading.Lock`` 保护。
|
||||
"""
|
||||
|
||||
def __init__(self, registry: CollectorRegistry | None = None) -> None:
|
||||
"""初始化所有 10 个 Prometheus 指标。
|
||||
|
||||
Args:
|
||||
registry: 可选自定义 Registry；None 则使用默认全局 registry。
|
||||
"""
|
||||
self._registry: CollectorRegistry = registry or CollectorRegistry()
|
||||
self._lock: threading.Lock = threading.Lock()
|
||||
self._start_time: float = time.time()
|
||||
|
||||
# ---- 1. 总请求数（按优先级 + 状态分组） ----
|
||||
self.requests_total: Counter = Counter(
|
||||
"sidecar_requests_total",
|
||||
"Total requests processed by priority and status",
|
||||
labelnames=["priority", "status"],
|
||||
registry=self._registry,
|
||||
)
|
||||
|
||||
# ---- 2. 可用令牌数 ----
|
||||
self.tokens_available: Gauge = Gauge(
|
||||
"sidecar_tokens_available",
|
||||
"Current number of available tokens",
|
||||
registry=self._registry,
|
||||
)
|
||||
|
||||
# ---- 3. 令牌生成速率 ----
|
||||
self.tokens_rate: Gauge = Gauge(
|
||||
"sidecar_tokens_rate",
|
||||
"Current token generation rate (tokens per minute)",
|
||||
registry=self._registry,
|
||||
)
|
||||
|
||||
# ---- 4. 各优先级队列深度 ----
|
||||
self.queue_depth: Gauge = Gauge(
|
||||
"sidecar_queue_depth",
|
||||
"Queue depth by priority",
|
||||
labelnames=["priority"],
|
||||
registry=self._registry,
|
||||
)
|
||||
|
||||
# ---- 5. 队列等待时间 Histogram ----
|
||||
self.queue_latency_seconds: Histogram = Histogram(
|
||||
"sidecar_queue_latency_seconds",
|
||||
"Request wait time in queue in seconds",
|
||||
labelnames=["priority"],
|
||||
buckets=(0.01, 0.05, 0.1, 0.5, 1.0, 2.0, 5.0, 10.0, 30.0, 60.0, 120.0),
|
||||
registry=self._registry,
|
||||
)
|
||||
|
||||
# ---- 6. 上游响应延迟 Histogram（label 收敛: model_id → provider） ----
|
||||
self.upstream_latency_seconds: Histogram = Histogram(
|
||||
"sidecar_upstream_latency_seconds",
|
||||
"Upstream response latency in seconds",
|
||||
labelnames=["provider"], # BIZ-46: was ["model_id"], converged to fixed-cardinality provider
|
||||
buckets=(0.1, 0.5, 1.0, 2.0, 5.0, 10.0, 30.0, 60.0, 120.0, 300.0, 600.0),
|
||||
registry=self._registry,
|
||||
)
|
||||
|
||||
# ---- 7. 上游错误计数（label 收敛: model_id → provider） ----
|
||||
self.upstream_errors_total: Counter = Counter(
|
||||
"sidecar_upstream_errors_total",
|
||||
"Upstream error count by status code and provider",
|
||||
labelnames=["status_code", "provider"], # BIZ-46: was ["model_id"], converged
|
||||
registry=self._registry,
|
||||
)
|
||||
|
||||
# ---- 8. 降级直通次数 ----
|
||||
self.fallback_passthrough_total: Counter = Counter(
|
||||
"sidecar_fallback_passthrough_total",
|
||||
"Total fallback / passthrough events (queue full or sidecar unavailable)",
|
||||
registry=self._registry,
|
||||
)
|
||||
|
||||
# ---- 9. 健康状态 ----
|
||||
self.health_status: Gauge = Gauge(
|
||||
"sidecar_health_status",
|
||||
"Sidecar health: 0=unhealthy, 1=healthy",
|
||||
registry=self._registry,
|
||||
)
|
||||
|
||||
# ---- 10. 运行时长 ----
|
||||
self.uptime_seconds: Gauge = Gauge(
|
||||
"sidecar_uptime_seconds",
|
||||
"Process uptime in seconds",
|
||||
registry=self._registry,
|
||||
)
|
||||
|
||||
# 避退模式指标（附加，不计入基础 10 个）
|
||||
self.retreat_state: Gauge = Gauge(
|
||||
"sidecar_retreat_state",
|
||||
"Adaptive retreat state: 0=NORMAL, 1=RETREAT, 2=RECOVER",
|
||||
registry=self._registry,
|
||||
)
|
||||
self.effective_rate_rpm: Gauge = Gauge(
|
||||
"sidecar_effective_rate_rpm",
|
||||
"Current effective rate in RPM (after retreat adjustments)",
|
||||
registry=self._registry,
|
||||
)
|
||||
self.upstream_429_rate: Gauge = Gauge(
|
||||
"sidecar_upstream_429_rate",
|
||||
"Upstream 429 rate over the retreat observation window (0.0-1.0)",
|
||||
registry=self._registry,
|
||||
)
|
||||
|
||||
# 初始化
|
||||
self.health_status.set(1)
|
||||
|
||||
# ---- ASGI app 生成 ----
|
||||
|
||||
def build_asgi_app(self) -> Any:
|
||||
"""生成 Prometheus ASGI 应用，挂载到独立端口。
|
||||
|
||||
Returns:
|
||||
可传给 uvicorn 的 ASGI app。
|
||||
"""
|
||||
return make_asgi_app(registry=self._registry)
|
||||
|
||||
# ---- 指标记录方法 ----
|
||||
|
||||
def record_request(self, priority: str, status: str) -> None:
|
||||
"""记录一次请求。
|
||||
|
||||
Args:
|
||||
priority: 优先级名（URGENT / HIGH / NORMAL / LOW）。
|
||||
status: 状态（success / ratelimited / error）。
|
||||
"""
|
||||
with self._lock:
|
||||
self.requests_total.labels(priority=priority, status=status).inc()
|
||||
|
||||
def record_queue_latency(self, priority: str, seconds: float) -> None:
|
||||
"""记录排队延迟。
|
||||
|
||||
Args:
|
||||
priority: 优先级名。
|
||||
seconds: 排队等待秒数。
|
||||
"""
|
||||
with self._lock:
|
||||
self.queue_latency_seconds.labels(priority=priority).observe(seconds)
|
||||
|
||||
def record_upstream(self, status_code: int, provider: str) -> None:
|
||||
"""记录上游响应（label 收敛: provider 替代 model_id，BIZ-46 Phase3）。
|
||||
|
||||
Args:
|
||||
status_code: HTTP 状态码。
|
||||
provider: 上游提供商标识（固定 "nvidia"）。
|
||||
"""
|
||||
with self._lock:
|
||||
self.upstream_latency_seconds.labels(provider=provider).observe(0.0)
|
||||
|
||||
def record_upstream_error(self, status_code: int, provider: str) -> None:
|
||||
"""记录上游错误（label 收敛: provider 替代 model_id，BIZ-46 Phase3）。
|
||||
|
||||
Args:
|
||||
status_code: 错误 HTTP 状态码。
|
||||
provider: 上游提供商标识（固定 "nvidia"）。
|
||||
"""
|
||||
with self._lock:
|
||||
self.upstream_errors_total.labels(
|
||||
status_code=str(status_code), provider=provider
|
||||
).inc()
|
||||
|
||||
def record_upstream_latency(self, provider: str, seconds: float) -> None:
|
||||
"""记录上游响应延迟（label 收敛: provider 替代 model_id，BIZ-46 Phase3）。
|
||||
|
||||
Args:
|
||||
provider: 上游提供商标识（固定 "nvidia"）。
|
||||
seconds: 响应延迟秒数。
|
||||
"""
|
||||
with self._lock:
|
||||
self.upstream_latency_seconds.labels(provider=provider).observe(seconds)
|
||||
|
||||
def update_token_status(self, tokens: float, rate_per_minute: float) -> None:
|
||||
"""更新令牌桶状态。
|
||||
|
||||
Args:
|
||||
tokens: 当前可用令牌数。
|
||||
rate_per_minute: 每分钟速率。
|
||||
"""
|
||||
with self._lock:
|
||||
self.tokens_available.set(tokens)
|
||||
self.tokens_rate.set(rate_per_minute)
|
||||
|
||||
def update_queue_depth(self, depths: dict[str, int]) -> None:
|
||||
"""更新各优先级队列深度。
|
||||
|
||||
Args:
|
||||
depths: {priority_name: count} 映射。
|
||||
"""
|
||||
with self._lock:
|
||||
# 先清零所有已知标签再设置，避免残留旧值
|
||||
for pri in ("URGENT", "HIGH", "NORMAL", "LOW"):
|
||||
self.queue_depth.labels(priority=pri).set(depths.get(pri, 0))
|
||||
|
||||
def increment_fallback(self) -> None:
|
||||
"""降级直通计数 +1。"""
|
||||
with self._lock:
|
||||
self.fallback_passthrough_total.inc()
|
||||
|
||||
def set_health(self, healthy: bool) -> None:
|
||||
"""设置健康状态。
|
||||
|
||||
Args:
|
||||
healthy: True=健康, False=不健康。
|
||||
"""
|
||||
with self._lock:
|
||||
self.health_status.set(1 if healthy else 0)
|
||||
|
||||
def update_uptime(self) -> None:
|
||||
"""更新运行时长。"""
|
||||
with self._lock:
|
||||
self.uptime_seconds.set(time.time() - self._start_time)
|
||||
|
||||
# ---- 避退模式指标 ----
|
||||
|
||||
def update_retreat_metrics(
|
||||
self,
|
||||
retreat_state: str,
|
||||
effective_rate_rpm: float,
|
||||
upstream_429_rate: float,
|
||||
) -> None:
|
||||
"""更新避退模式指标。
|
||||
|
||||
Args:
|
||||
retreat_state: "normal" / "retreat" / "recover".
|
||||
effective_rate_rpm: 当前实际速率 (RPM)。
|
||||
upstream_429_rate: 上游 429 率 (0.0-1.0)。
|
||||
"""
|
||||
state_map: dict[str, int] = {"normal": 0, "retreat": 1, "recover": 2}
|
||||
with self._lock:
|
||||
self.retreat_state.set(state_map.get(retreat_state, 0))
|
||||
self.effective_rate_rpm.set(effective_rate_rpm)
|
||||
self.upstream_429_rate.set(upstream_429_rate)
|
||||
|
||||
# ---- 导出 ----
|
||||
|
||||
def generate_latest(self) -> bytes:
|
||||
"""生成 Prometheus 文本格式的指标数据。
|
||||
|
||||
Returns:
|
||||
Prometheus 文本格式 bytes。
|
||||
"""
|
||||
with self._lock:
|
||||
self.update_uptime()
|
||||
return generate_latest(self._registry)
|
||||
@@ -1,253 +0,0 @@
|
||||
"""
|
||||
NVIDIA Sidecar 限流代理 — 四级优先级请求队列模块 (§3.3)
|
||||
|
||||
管理待处理的 NVIDIA API 请求，按优先级 + FIFO 出队。
|
||||
支持三种队列满策略：PASSTHROUGH / REJECT / DROP_LOWEST。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import heapq
|
||||
import time
|
||||
import uuid
|
||||
from dataclasses import dataclass, field
|
||||
from enum import Enum
|
||||
from typing import Any
|
||||
|
||||
from nvidia_sidecar.rate_limiter import Priority
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 队列满策略
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
class QueueFullPolicy(str, Enum):
|
||||
"""队列满时的处理策略。"""
|
||||
PASSTHROUGH = "passthrough" # 直通上游，绕过排队（fail-open 子策略）
|
||||
REJECT = "reject" # 返回 503 Service Unavailable
|
||||
DROP_LOWEST = "drop_lowest" # 丢弃队列中最低优先级元素，插入新请求
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 队列元素
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
@dataclass(order=True)
|
||||
class PriorityQueueItem:
|
||||
"""优先级队列元素。
|
||||
|
||||
``sort_index`` 由 ``(priority, timestamp)`` 组成，
|
||||
Python 的 ``__lt__`` 按字段顺序比较：先比 priority，再比 timestamp。
|
||||
数值越小越优先（URGENT=1 优于 HIGH=2）。
|
||||
"""
|
||||
sort_index: tuple[int, float] = field(compare=True)
|
||||
priority: Priority = field(compare=False)
|
||||
request_id: str = field(compare=False)
|
||||
payload: dict[str, Any] = field(compare=False)
|
||||
enqueued_at: float = field(compare=False)
|
||||
headers: dict[str, str] = field(default_factory=dict, compare=False)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 优先级请求队列
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
class QueueFullError(Exception):
|
||||
"""队列已满且策略为 REJECT 时抛出。"""
|
||||
pass
|
||||
|
||||
|
||||
class QueueFullPassthrough(Exception):
|
||||
"""队列已满且策略为 PASSTHROUGH 时抛出，由调用方绕过队列直通上游。"""
|
||||
pass
|
||||
|
||||
|
||||
class PriorityRequestQueue:
|
||||
"""异步线程安全的四级优先级请求队列。
|
||||
|
||||
内部使用 ``asyncio.Lock`` 保护并发操作，
|
||||
基于 ``heapq`` + ``asyncio.Event`` 实现阻塞出队。
|
||||
"""
|
||||
|
||||
def __init__(self, max_size: int = 500) -> None:
|
||||
"""初始化优先级队列。
|
||||
|
||||
Args:
|
||||
max_size: 队列最大容量。
|
||||
|
||||
Raises:
|
||||
ValueError: max_size <= 0。
|
||||
"""
|
||||
if max_size <= 0:
|
||||
raise ValueError(f"max_size 必须为正整数，当前值: {max_size}")
|
||||
self.max_size: int = max_size
|
||||
self._heap: list[PriorityQueueItem] = []
|
||||
self._lock: asyncio.Lock = asyncio.Lock()
|
||||
self._not_empty: asyncio.Event = asyncio.Event()
|
||||
self._full_policy: QueueFullPolicy = QueueFullPolicy.PASSTHROUGH
|
||||
|
||||
# 统计
|
||||
self._total_enqueued: int = 0
|
||||
self._total_dequeued: int = 0
|
||||
self._total_dropped: int = 0
|
||||
|
||||
# ---- 队列满策略 ----
|
||||
|
||||
def set_full_policy(self, policy: QueueFullPolicy) -> None:
|
||||
"""设置队列满时的处理策略。
|
||||
|
||||
Args:
|
||||
policy: QueueFullPolicy 枚举值。
|
||||
"""
|
||||
self._full_policy = policy
|
||||
|
||||
@property
|
||||
def full_policy(self) -> QueueFullPolicy:
|
||||
"""当前队列满策略。"""
|
||||
return self._full_policy
|
||||
|
||||
# ---- 动态容量调整 ----
|
||||
|
||||
def set_max_size(self, new_size: int) -> tuple[bool, str]:
|
||||
"""动态调整队列最大容量（热重载）。
|
||||
|
||||
缩小操作受保护：如果 new_size 小于当前排队数，拒绝变更并
|
||||
提示当前队列深度。
|
||||
|
||||
Args:
|
||||
new_size: 新的最大容量。
|
||||
|
||||
Returns:
|
||||
(成功标志, 消息)。成功时标志为 True，消息含新旧容量对比；
|
||||
失败时标志为 False，消息含拒绝原因和当前深度。
|
||||
|
||||
Raises:
|
||||
ValueError: new_size <= 0。
|
||||
"""
|
||||
if new_size <= 0:
|
||||
raise ValueError(f"max_size 必须为正整数，当前值: {new_size}")
|
||||
current = len(self._heap)
|
||||
if new_size < current:
|
||||
return (False, f"拒绝缩小：新上限 {new_size} < 当前排队数 {current}，需要先排空或提升上限")
|
||||
old = self.max_size
|
||||
self.max_size = new_size
|
||||
return (True, f"队列上限已调整：{old} → {new_size}{'（当前排队 ' + str(current) + '）' if current > 0 else ''}")
|
||||
|
||||
# ---- 入队 ----
|
||||
|
||||
async def put(
|
||||
self,
|
||||
item: dict[str, Any],
|
||||
priority: Priority = Priority.NORMAL,
|
||||
headers: dict[str, str] | None = None,
|
||||
) -> str:
|
||||
"""将请求放入队列。
|
||||
|
||||
Args:
|
||||
item: 请求体（JSON 序列化的 dict）。
|
||||
priority: 请求优先级，默认 NORMAL。
|
||||
headers: 原始请求 headers。
|
||||
|
||||
Returns:
|
||||
分配的唯一 request_id。
|
||||
|
||||
Raises:
|
||||
QueueFullError: 队列满且策略为 REJECT。
|
||||
"""
|
||||
request_id = str(uuid.uuid4())
|
||||
headers = headers or {}
|
||||
|
||||
queue_item = PriorityQueueItem(
|
||||
sort_index=(int(priority), time.monotonic()),
|
||||
priority=priority,
|
||||
request_id=request_id,
|
||||
payload=item,
|
||||
enqueued_at=time.monotonic(),
|
||||
headers=headers,
|
||||
)
|
||||
|
||||
async with self._lock:
|
||||
queue_size = len(self._heap)
|
||||
if queue_size >= self.max_size:
|
||||
if self._full_policy == QueueFullPolicy.REJECT:
|
||||
raise QueueFullError(
|
||||
f"队列已满 ({queue_size}/{self.max_size})，策略: reject"
|
||||
)
|
||||
elif self._full_policy == QueueFullPolicy.DROP_LOWEST:
|
||||
# 丢弃 heap 中优先级最低（值最大）的元素
|
||||
# heap 是最小堆，找最大值需要遍历
|
||||
max_val_item = max(self._heap, key=lambda x: x.sort_index)
|
||||
self._heap.remove(max_val_item)
|
||||
heapq.heapify(self._heap)
|
||||
self._total_dropped += 1
|
||||
# PASSTHROUGH 策略：不插入队列，抛异常让调用方绕过排队
|
||||
else:
|
||||
raise QueueFullPassthrough(
|
||||
f"队列已满 ({queue_size}/{self.max_size})，策略: passthrough"
|
||||
)
|
||||
|
||||
heapq.heappush(self._heap, queue_item)
|
||||
self._total_enqueued += 1
|
||||
|
||||
self._not_empty.set()
|
||||
return request_id
|
||||
|
||||
# ---- 出队 ----
|
||||
|
||||
async def get(self, timeout: float = 1.0) -> PriorityQueueItem | None:
|
||||
"""从队列取出下一个元素（阻塞、优先级排序）。
|
||||
|
||||
Args:
|
||||
timeout: 阻塞等待的最大秒数，默认 1.0。
|
||||
|
||||
Returns:
|
||||
优先级最高的队列元素；超时无元素时返回 None。
|
||||
"""
|
||||
deadline = time.monotonic() + timeout
|
||||
while True:
|
||||
async with self._lock:
|
||||
if self._heap:
|
||||
item = heapq.heappop(self._heap)
|
||||
self._total_dequeued += 1
|
||||
if not self._heap:
|
||||
self._not_empty.clear()
|
||||
return item
|
||||
|
||||
# 队列为空，等待新元素入队
|
||||
remaining = deadline - time.monotonic()
|
||||
if remaining <= 0:
|
||||
return None
|
||||
try:
|
||||
await asyncio.wait_for(
|
||||
self._not_empty.wait(),
|
||||
timeout=remaining,
|
||||
)
|
||||
except asyncio.TimeoutError:
|
||||
return None
|
||||
|
||||
# ---- 状态查询 ----
|
||||
|
||||
async def get_queue_size(self) -> int:
|
||||
"""返回当前队列长度。"""
|
||||
async with self._lock:
|
||||
return len(self._heap)
|
||||
|
||||
async def get_stats(self) -> dict[str, Any]:
|
||||
"""返回队列统计信息。"""
|
||||
async with self._lock:
|
||||
depth_by_priority: dict[str, int] = {}
|
||||
for item in self._heap:
|
||||
key = item.priority.name
|
||||
depth_by_priority[key] = depth_by_priority.get(key, 0) + 1
|
||||
|
||||
return {
|
||||
"max_size": self.max_size,
|
||||
"current_size": len(self._heap),
|
||||
"total_enqueued": self._total_enqueued,
|
||||
"total_dequeued": self._total_dequeued,
|
||||
"total_dropped": self._total_dropped,
|
||||
"depth_by_priority": depth_by_priority,
|
||||
"full_policy": self._full_policy.value,
|
||||
"utilization": len(self._heap) / self.max_size if self.max_size > 0 else 0.0,
|
||||
}
|
||||
@@ -1,48 +0,0 @@
|
||||
[project]
|
||||
name = "nvidia_sidecar"
|
||||
version = "0.1.0"
|
||||
description = "NVIDIA Sidecar 限流代理 — 为 NVIDIA API 提供优先级排队 + 令牌桶限流"
|
||||
readme = "README.md"
|
||||
license = { text = "MIT" }
|
||||
requires-python = ">=3.12"
|
||||
dependencies = [
|
||||
"fastapi>=0.115",
|
||||
"uvicorn[standard]>=0.34",
|
||||
"httpx>=0.28",
|
||||
"PyYAML>=6.0",
|
||||
"structlog>=24.4",
|
||||
"prometheus-client>=0.21",
|
||||
"pydantic>=2.0",
|
||||
]
|
||||
|
||||
[project.optional-dependencies]
|
||||
dev = [
|
||||
"pytest>=8.3",
|
||||
"pytest-asyncio>=0.24",
|
||||
"httpx>=0.28",
|
||||
"mypy>=1.14",
|
||||
"types-PyYAML",
|
||||
]
|
||||
|
||||
[project.scripts]
|
||||
nvidia-sidecar = "nvidia_sidecar.server:main"
|
||||
|
||||
[build-system]
|
||||
requires = ["setuptools>=75", "wheel"]
|
||||
build-backend = "setuptools.build_meta"
|
||||
|
||||
[tool.setuptools]
|
||||
packages = ["nvidia_sidecar"]
|
||||
|
||||
[tool.setuptools.package-dir]
|
||||
# Flat layout: __init__.py + all .py files at project root
|
||||
"nvidia_sidecar" = "."
|
||||
|
||||
[tool.mypy]
|
||||
python_version = "3.12"
|
||||
strict = true
|
||||
warn_return_any = true
|
||||
warn_unused_configs = true
|
||||
[[tool.mypy.overrides]]
|
||||
module = "structlog.*"
|
||||
ignore_missing_imports = true
|
||||
@@ -1,438 +0,0 @@
|
||||
"""
|
||||
NVIDIA Sidecar 限流代理 — 令牌桶 + 网关识别模块 (§3.2)
|
||||
|
||||
从 BIZ-26 rate_limiter.py 提取核心限流逻辑，去除多线程调度器、缓存管理等。
|
||||
保留：Priority, TokenBucket, is_nvidia_gateway, normalize_gateway_name。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import time
|
||||
import threading
|
||||
from enum import IntEnum
|
||||
from typing import Any
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 优先级枚举
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
class Priority(IntEnum):
|
||||
"""请求优先级（数值越小优先级越高）。"""
|
||||
URGENT = 1
|
||||
HIGH = 2
|
||||
NORMAL = 3
|
||||
LOW = 4
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# NVIDIA 网关别名集
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
NVIDIA_GATEWAY_ALIASES: set[str] = {
|
||||
"nvidia",
|
||||
"nvidia-gateway",
|
||||
"nvidiavx",
|
||||
"nvidiavx18088980513",
|
||||
}
|
||||
|
||||
|
||||
def is_nvidia_gateway(value: str | None) -> bool:
|
||||
"""判断给定网关名/模型全路径是否属于 NVIDIA 网关。
|
||||
|
||||
Args:
|
||||
value: 网关名（如 ``"nvidia"``）或模型全路径前缀
|
||||
（如 ``"nvidia/deepseek-ai/deepseek-v4-pro"``）。
|
||||
None 时直接返回 False。
|
||||
|
||||
Returns:
|
||||
True 当 value 的 provider 部分匹配已知 NVIDIA 别名。
|
||||
"""
|
||||
if value is None:
|
||||
return False
|
||||
|
||||
# 提取 provider 前缀：取 "/" 前第一个部分
|
||||
provider = value.split("/", 1)[0].lower().strip()
|
||||
return provider in NVIDIA_GATEWAY_ALIASES
|
||||
|
||||
|
||||
def normalize_gateway_name(value: str | None) -> str | None:
|
||||
"""规范化网关名：提取 provider 前缀并转为小写。
|
||||
|
||||
Args:
|
||||
value: 网关名或模型全路径。None 时返回 None。
|
||||
|
||||
Returns:
|
||||
provider 前缀的小写形式，或 None。
|
||||
"""
|
||||
if value is None:
|
||||
return None
|
||||
return value.split("/", 1)[0].lower().strip()
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 令牌桶（线程安全）
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
class TokenBucket:
|
||||
"""线程安全的令牌桶实现。
|
||||
|
||||
支持固定速率令牌补充和消费，带有溢出保护和可选的阻塞等待。
|
||||
"""
|
||||
|
||||
def __init__(self, rate: float = 40 / 60, capacity: int = 40) -> None:
|
||||
"""初始化令牌桶。
|
||||
|
||||
Args:
|
||||
rate: 令牌补充速率（令牌/秒）。默认 40/60 ≈ 0.667 token/s（40 RPM）。
|
||||
capacity: 桶最大容量（令牌数）。默认 40。
|
||||
"""
|
||||
self._rate: float = float(rate)
|
||||
self._capacity: int = int(capacity)
|
||||
self._tokens: float = float(capacity) # 启动时桶满
|
||||
self._last_refill: float = time.monotonic()
|
||||
self._lock: threading.Lock = threading.Lock()
|
||||
|
||||
# ---- 内部方法 ----
|
||||
|
||||
def _refill(self) -> None:
|
||||
"""补充令牌（调用方需持有 _lock）。
|
||||
|
||||
根据距上次补充的时间差计算新增令牌数，不超过 capacity。
|
||||
"""
|
||||
now = time.monotonic()
|
||||
elapsed = now - self._last_refill
|
||||
if elapsed > 0 and self._rate > 0:
|
||||
new_tokens = elapsed * self._rate
|
||||
self._tokens = min(self._tokens + new_tokens, float(self._capacity))
|
||||
self._last_refill = now
|
||||
|
||||
# ---- 公开方法 ----
|
||||
|
||||
def consume(self, tokens: int = 1) -> bool:
|
||||
"""尝试立即消费令牌（非阻塞）。
|
||||
|
||||
Args:
|
||||
tokens: 要消费的令牌数，默认 1。
|
||||
|
||||
Returns:
|
||||
True 消费成功；False 令牌不足。
|
||||
"""
|
||||
if tokens <= 0:
|
||||
return True
|
||||
|
||||
with self._lock:
|
||||
self._refill()
|
||||
if self._tokens >= tokens:
|
||||
self._tokens -= tokens
|
||||
return True
|
||||
return False
|
||||
|
||||
def try_consume(self, tokens: int = 1, timeout: float = 2.0) -> bool:
|
||||
"""尝试在指定时间内消费令牌（阻塞）。
|
||||
|
||||
Args:
|
||||
tokens: 要消费的令牌数，默认 1。
|
||||
timeout: 最大等待秒数，默认 2.0。
|
||||
|
||||
Returns:
|
||||
True 在超时前成功消费；False 超时。
|
||||
"""
|
||||
if tokens <= 0:
|
||||
return True
|
||||
|
||||
deadline = time.monotonic() + timeout
|
||||
while True:
|
||||
with self._lock:
|
||||
self._refill()
|
||||
if self._tokens >= tokens:
|
||||
self._tokens -= tokens
|
||||
return True
|
||||
|
||||
# 释放锁后计算剩余等待时间
|
||||
remaining = deadline - time.monotonic()
|
||||
if remaining <= 0:
|
||||
return False
|
||||
# 等待到下一个令牌应该补充的时间点
|
||||
sleep_time = min(remaining, max(0.05, 1.0 / self._rate) if self._rate > 0 else remaining)
|
||||
time.sleep(sleep_time)
|
||||
|
||||
def wait_for_token(self, timeout: float | None = None) -> bool:
|
||||
"""等待并尝试消费 1 个令牌。
|
||||
|
||||
Args:
|
||||
timeout: 最大等待秒数；None 表示无限等待（不推荐）。
|
||||
|
||||
Returns:
|
||||
True 成功消费；False 超时。
|
||||
"""
|
||||
return self.try_consume(tokens=1, timeout=timeout if timeout is not None else float("inf"))
|
||||
|
||||
def get_status(self) -> dict[str, Any]:
|
||||
"""获取令牌桶当前状态。
|
||||
|
||||
Returns:
|
||||
包含 tokens, capacity, rate_per_minute, utilization 的字典。
|
||||
"""
|
||||
with self._lock:
|
||||
self._refill()
|
||||
rate_per_minute = self._rate * 60.0
|
||||
utilization = 0.0 if self._capacity == 0 else (
|
||||
(self._capacity - self._tokens) / self._capacity
|
||||
)
|
||||
return {
|
||||
"tokens": round(self._tokens, 2),
|
||||
"capacity": self._capacity,
|
||||
"rate_per_minute": round(rate_per_minute, 1),
|
||||
"utilization": round(utilization, 4),
|
||||
}
|
||||
|
||||
# ---- 属性 ----
|
||||
|
||||
@property
|
||||
def rate(self) -> float:
|
||||
"""当前令牌补充速率（令牌/秒）。"""
|
||||
return self._rate
|
||||
|
||||
@property
|
||||
def capacity(self) -> int:
|
||||
"""桶容量。"""
|
||||
return self._capacity
|
||||
|
||||
# ---- 动态速率调整（供 AdaptiveTokenBucket 使用） ----
|
||||
|
||||
def set_rate(self, rate: float) -> None:
|
||||
"""动态调整令牌补充速率（令牌/秒）。
|
||||
|
||||
Args:
|
||||
rate: 新速率（令牌/秒）。
|
||||
"""
|
||||
with self._lock:
|
||||
self._refill() # 先补充现有令牌再切换速率
|
||||
self._rate = float(rate)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 避退模式：AdaptiveTokenBucket (§ADR-009)
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
class RetreatState:
|
||||
"""避退状态机常量。"""
|
||||
NORMAL: str = "normal"
|
||||
RETREAT: str = "retreat"
|
||||
RECOVER: str = "recover"
|
||||
|
||||
|
||||
class AdaptiveTokenBucket(TokenBucket):
|
||||
"""自适应避退令牌桶（ADR-009）。
|
||||
|
||||
监控上游 429 率（60s 滑动窗口），自动调整发射速率：
|
||||
|
||||
- 429 率 < 5% → NORMAL，保持基准速率
|
||||
- 429 率 5-10% → RETREAT，速率 × 0.75
|
||||
- 429 率 10-20% → RETREAT，再次降速
|
||||
- 429 率 > 20% → RETREAT，最低 5 RPM + 告警
|
||||
- 连续 120s 429 率 < 2% → RECOVER，逐步 +2 RPM 恢复
|
||||
|
||||
线程安全，继承 TokenBucket 的所有公共接口。
|
||||
"""
|
||||
|
||||
# ADR-009 参数（可通过构造函数覆盖）
|
||||
RETREAT_WINDOW_SECONDS: float = 60.0
|
||||
RETREAT_429_THRESHOLD: float = 0.05
|
||||
RETREAT_FACTOR: float = 0.75
|
||||
RETREAT_MIN_RPM: float = 5.0
|
||||
RECOVER_WINDOW_SECONDS: float = 120.0
|
||||
RECOVER_429_THRESHOLD: float = 0.02
|
||||
RECOVER_INCREMENT_RPM: float = 2.0
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
rate: float = 40 / 60,
|
||||
capacity: int = 40,
|
||||
*,
|
||||
retreat_window_seconds: float = 60.0,
|
||||
retreat_429_threshold: float = 0.05,
|
||||
retreat_factor: float = 0.75,
|
||||
retreat_min_rpm: float = 5.0,
|
||||
recover_window_seconds: float = 120.0,
|
||||
recover_429_threshold: float = 0.02,
|
||||
recover_increment_rpm: float = 2.0,
|
||||
) -> None:
|
||||
"""初始化自适应避退令牌桶。
|
||||
|
||||
Args:
|
||||
rate: 基准令牌补充速率（令牌/秒）。默认 40/60 ≈ 0.667 token/s。
|
||||
capacity: 桶最大容量。默认 40。
|
||||
retreat_window_seconds: 429 率滑动窗口大小（秒）。
|
||||
retreat_429_threshold: 触发避退的 429 率阈值。
|
||||
retreat_factor: 每次避退速率乘数。
|
||||
retreat_min_rpm: 避退最低 RPM。
|
||||
recover_window_seconds: 恢复观察窗口大小（秒）。
|
||||
recover_429_threshold: 触发恢复的 429 率阈值。
|
||||
recover_increment_rpm: 每次恢复增加的 RPM。
|
||||
"""
|
||||
super().__init__(rate=rate, capacity=capacity)
|
||||
|
||||
# 基准速率（不变）
|
||||
self._base_rate: float = float(rate)
|
||||
|
||||
# 避退参数
|
||||
self.RETREAT_WINDOW_SECONDS = retreat_window_seconds
|
||||
self.RETREAT_429_THRESHOLD = retreat_429_threshold
|
||||
self.RETREAT_FACTOR = retreat_factor
|
||||
self.RETREAT_MIN_RPM = retreat_min_rpm
|
||||
self.RECOVER_WINDOW_SECONDS = recover_window_seconds
|
||||
self.RECOVER_429_THRESHOLD = recover_429_threshold
|
||||
self.RECOVER_INCREMENT_RPM = recover_increment_rpm
|
||||
|
||||
# 避退状态机
|
||||
self._retreat_state: str = RetreatState.NORMAL
|
||||
|
||||
# 429 滑动窗口：[(timestamp, is_429), ...]
|
||||
self._429_window: list[tuple[float, bool]] = []
|
||||
|
||||
# 上次状态变更时间
|
||||
self._last_state_change: float = time.monotonic()
|
||||
|
||||
# 避退状态锁（RLock 防止 evaluate_retreat() → get_429_rate() 重入死锁）
|
||||
self._retreat_lock: threading.RLock = threading.RLock()
|
||||
|
||||
# ---- 429 反馈 ----
|
||||
|
||||
def record_response(self, is_429: bool) -> None:
|
||||
"""记录一次上游响应是否为 429。
|
||||
|
||||
Args:
|
||||
is_429: True 表示上游返回了 429。
|
||||
"""
|
||||
now = time.monotonic()
|
||||
with self._retreat_lock:
|
||||
self._429_window.append((now, is_429))
|
||||
# 清理超出观察窗口的旧记录
|
||||
cutoff = now - max(
|
||||
self.RETREAT_WINDOW_SECONDS,
|
||||
self.RECOVER_WINDOW_SECONDS,
|
||||
)
|
||||
self._429_window = [
|
||||
(ts, flag) for ts, flag in self._429_window
|
||||
if ts >= cutoff
|
||||
]
|
||||
|
||||
def get_429_rate(self, window_seconds: float | None = None) -> float:
|
||||
"""获取指定窗口内的 429 率。
|
||||
|
||||
Args:
|
||||
window_seconds: 滑动窗口大小；None 使用 RETREAT_WINDOW_SECONDS。
|
||||
|
||||
Returns:
|
||||
0.0-1.0 之间的 429 率。
|
||||
"""
|
||||
ws = window_seconds or self.RETREAT_WINDOW_SECONDS
|
||||
now = time.monotonic()
|
||||
with self._retreat_lock:
|
||||
in_window = [flag for ts, flag in self._429_window if now - ts <= ws]
|
||||
if not in_window:
|
||||
return 0.0
|
||||
return sum(1 for f in in_window if f) / len(in_window)
|
||||
|
||||
# ---- 避退状态评估 ----
|
||||
|
||||
def evaluate_retreat(self) -> str:
|
||||
"""评估并更新避退状态，返回新状态名。
|
||||
|
||||
每次调用根据当前 429 率 + 持续时间决定是否进入 RETREAT / RECOVER。
|
||||
|
||||
Returns:
|
||||
"normal" / "retreat" / "recover"。
|
||||
"""
|
||||
now = time.monotonic()
|
||||
with self._retreat_lock:
|
||||
retreat_rate = self.get_429_rate(self.RETREAT_WINDOW_SECONDS)
|
||||
recover_rate = self.get_429_rate(self.RECOVER_WINDOW_SECONDS)
|
||||
|
||||
if self._retreat_state == RetreatState.NORMAL:
|
||||
if retreat_rate >= self.RETREAT_429_THRESHOLD:
|
||||
self._retreat_state = RetreatState.RETREAT
|
||||
self._last_state_change = now
|
||||
self._apply_retreat()
|
||||
|
||||
elif self._retreat_state == RetreatState.RETREAT:
|
||||
# 持续高 429 率 → 再次降速
|
||||
if retreat_rate >= self.RETREAT_429_THRESHOLD * 2:
|
||||
# 429 > 10%，再次降速
|
||||
if self._rate > self.RETREAT_MIN_RPM / 60.0:
|
||||
self._apply_retreat()
|
||||
elif recover_rate < self.RECOVER_429_THRESHOLD:
|
||||
time_in_low = now - self._last_state_change
|
||||
if time_in_low >= self.RECOVER_WINDOW_SECONDS:
|
||||
self._retreat_state = RetreatState.RECOVER
|
||||
self._last_state_change = now
|
||||
self._apply_recover()
|
||||
|
||||
elif self._retreat_state == RetreatState.RECOVER:
|
||||
if retreat_rate >= self.RETREAT_429_THRESHOLD:
|
||||
# 恢复期间 429 回升，重新进入避退
|
||||
self._retreat_state = RetreatState.RETREAT
|
||||
self._last_state_change = now
|
||||
self._apply_retreat()
|
||||
elif self._rate >= self._base_rate:
|
||||
# 已恢复到基准速率
|
||||
self._rate = self._base_rate
|
||||
self._retreat_state = RetreatState.NORMAL
|
||||
self._last_state_change = now
|
||||
else:
|
||||
# 继续逐步恢复
|
||||
self._apply_recover()
|
||||
|
||||
return self._retreat_state
|
||||
|
||||
def _apply_retreat(self) -> None:
|
||||
"""执行一次避退降速。"""
|
||||
new_rate: float = max(
|
||||
self.RETREAT_MIN_RPM / 60.0,
|
||||
self._rate * self.RETREAT_FACTOR,
|
||||
)
|
||||
self._rate = new_rate
|
||||
|
||||
def _apply_recover(self) -> None:
|
||||
"""执行一次恢复提速。"""
|
||||
increment: float = self.RECOVER_INCREMENT_RPM / 60.0
|
||||
new_rate: float = min(self._base_rate, self._rate + increment)
|
||||
self._rate = new_rate
|
||||
|
||||
# ---- 状态查询 ----
|
||||
|
||||
def get_retreat_state(self) -> str:
|
||||
"""获取当前避退状态。
|
||||
|
||||
Returns:
|
||||
"normal" / "retreat" / "recover"。
|
||||
"""
|
||||
with self._retreat_lock:
|
||||
return self._retreat_state
|
||||
|
||||
def get_effective_rate_rpm(self) -> float:
|
||||
"""获取当前实际速率（RPM），考虑避退乘数。
|
||||
|
||||
Returns:
|
||||
当前每分钟速率。
|
||||
"""
|
||||
with self._lock:
|
||||
return self._rate * 60.0
|
||||
|
||||
def get_base_rate_rpm(self) -> float:
|
||||
"""获取基准速率（RPM），即未避退时的速率。
|
||||
|
||||
Returns:
|
||||
基准每分钟速率。
|
||||
"""
|
||||
return self._base_rate * 60.0
|
||||
|
||||
def reset_to_base(self) -> None:
|
||||
"""手动重置到基准速率（用于运维干预）。"""
|
||||
with self._retreat_lock:
|
||||
self._rate = self._base_rate
|
||||
self._retreat_state = RetreatState.NORMAL
|
||||
self._last_state_change = time.monotonic()
|
||||
self._429_window.clear()
|
||||
@@ -1,822 +0,0 @@
|
||||
"""
|
||||
NVIDIA Sidecar 限流代理 — FastAPI 代理主入口 (§3.4)
|
||||
|
||||
完整的 API 代理链路：
|
||||
接收 → 网关识别 → [NVIDIA: 排队 → 令牌限流] → httpx 转发 → 返回
|
||||
|
||||
非 NVIDIA 请求直通上游，NVIDIA 请求经过四级优先级队列 + 令牌桶限流。
|
||||
|
||||
BIZ-46 Phase3: 架构解耦 — 所有全局状态收敛为 SidecarContext (§1)
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import logging
|
||||
import time
|
||||
from collections.abc import AsyncGenerator
|
||||
from contextlib import asynccontextmanager
|
||||
from typing import Any
|
||||
|
||||
import httpx
|
||||
import structlog
|
||||
import uvicorn
|
||||
from fastapi import Depends, FastAPI, Request, Response
|
||||
from fastapi.middleware.cors import CORSMiddleware
|
||||
from fastapi.responses import JSONResponse, StreamingResponse
|
||||
|
||||
from nvidia_sidecar.config import load_config, SidecarConfig
|
||||
from nvidia_sidecar.context import SidecarContext
|
||||
from nvidia_sidecar.rate_limiter import (
|
||||
Priority,
|
||||
AdaptiveTokenBucket,
|
||||
is_nvidia_gateway,
|
||||
)
|
||||
from nvidia_sidecar.priority_queue import (
|
||||
PriorityRequestQueue,
|
||||
QueueFullError,
|
||||
QueueFullPassthrough,
|
||||
QueueFullPolicy,
|
||||
)
|
||||
from nvidia_sidecar.metrics import PrometheusMetrics
|
||||
from nvidia_sidecar.health import HealthService
|
||||
from nvidia_sidecar.webui import webui_router
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 结构化日志
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
structlog.configure(
|
||||
processors=[
|
||||
structlog.stdlib.filter_by_level,
|
||||
structlog.stdlib.add_logger_name,
|
||||
structlog.stdlib.add_log_level,
|
||||
structlog.stdlib.PositionalArgumentsFormatter(),
|
||||
structlog.processors.TimeStamper(fmt="iso"),
|
||||
structlog.processors.StackInfoRenderer(),
|
||||
structlog.processors.format_exc_info,
|
||||
structlog.processors.UnicodeDecoder(),
|
||||
structlog.processors.JSONRenderer(),
|
||||
],
|
||||
context_class=dict,
|
||||
logger_factory=structlog.PrintLoggerFactory(),
|
||||
wrapper_class=structlog.stdlib.BoundLogger,
|
||||
cache_logger_on_first_use=True,
|
||||
)
|
||||
logger: structlog.stdlib.BoundLogger = structlog.get_logger("nvidia_sidecar")
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# FastAPI 依赖注入
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def get_context(request: Request) -> SidecarContext:
|
||||
"""从 app.state 获取 SidecarContext（FastAPI 依赖注入）。"""
|
||||
return request.app.state.sidecar # type: ignore[no-any-return]
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 工具函数
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def _extract_model(body: Any) -> str | None:
|
||||
"""从请求体中提取模型标识符（兼容 OpenAI Chat/Completions 格式）。
|
||||
|
||||
Args:
|
||||
body: 已解析的 JSON 请求体。
|
||||
|
||||
Returns:
|
||||
模型标识符字符串，或 None。
|
||||
"""
|
||||
if isinstance(body, dict):
|
||||
return str(body.get("model", "")) or None
|
||||
return None
|
||||
|
||||
|
||||
def _resolve_priority(headers: dict[str, str]) -> Priority:
|
||||
"""从请求 headers 解析优先级。
|
||||
|
||||
检查 ``X-Priority`` header，值为 ``urgent``/``high``/``normal``/``low``，
|
||||
不区分大小写。默认 NORMAL。
|
||||
"""
|
||||
raw = headers.get("x-priority", "").strip().lower()
|
||||
mapping: dict[str, Priority] = {
|
||||
"urgent": Priority.URGENT,
|
||||
"high": Priority.HIGH,
|
||||
"normal": Priority.NORMAL,
|
||||
"low": Priority.LOW,
|
||||
}
|
||||
return mapping.get(raw, Priority.NORMAL)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 上游转发
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
async def _forward_to_upstream(
|
||||
ctx: SidecarContext,
|
||||
method: str,
|
||||
path: str,
|
||||
body: bytes | None,
|
||||
headers: dict[str, str],
|
||||
stream: bool = False,
|
||||
) -> httpx.Response:
|
||||
"""将请求转发到 NVIDIA 上游 API。
|
||||
|
||||
Args:
|
||||
ctx: SidecarContext 运行时上下文。
|
||||
method: HTTP 方法。
|
||||
path: 请求路径（如 ``/v1/chat/completions``）。
|
||||
body: 原始请求体 bytes。
|
||||
headers: 要转发的请求 headers（会追加 Authorization）。
|
||||
stream: 是否请求流式响应。
|
||||
|
||||
Returns:
|
||||
httpx.Response 对象。
|
||||
|
||||
Raises:
|
||||
httpx.HTTPError: HTTP 请求失败。
|
||||
"""
|
||||
upstream_url = ctx.config.upstream_url.rstrip("/") + path
|
||||
forward_headers: dict[str, str] = {
|
||||
k: v for k, v in headers.items()
|
||||
if k.lower() not in ("host", "content-length", "transfer-encoding")
|
||||
}
|
||||
if ctx.config.upstream_api_key:
|
||||
forward_headers["authorization"] = f"Bearer {ctx.config.upstream_api_key}"
|
||||
elif "authorization" not in {k.lower() for k in forward_headers}:
|
||||
forward_headers["authorization"] = "Bearer nvidia"
|
||||
|
||||
try:
|
||||
req = ctx.http_client.build_request(
|
||||
method=method,
|
||||
url=upstream_url,
|
||||
headers=forward_headers,
|
||||
content=body,
|
||||
timeout=ctx.config.request_timeout,
|
||||
)
|
||||
response = await ctx.http_client.send(req, stream=stream)
|
||||
return response
|
||||
except httpx.TimeoutException:
|
||||
logger.warning("upstream_timeout", path=path, timeout=ctx.config.request_timeout)
|
||||
raise
|
||||
except httpx.HTTPError as exc:
|
||||
logger.error("upstream_error", path=path, error=str(exc))
|
||||
raise
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# worker 协程：消费优先级队列 + 令牌桶 + 转发
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
async def _worker_loop(ctx: SidecarContext) -> None:
|
||||
"""后台 worker：持续从优先级队列取请求 → 令牌限流 → 转发 → 设置 future 结果。
|
||||
|
||||
Args:
|
||||
ctx: SidecarContext 运行时上下文。
|
||||
"""
|
||||
log = logger.bind(worker="main")
|
||||
log.info("worker_started")
|
||||
|
||||
while True:
|
||||
try:
|
||||
queue_item = await ctx.priority_queue.get(timeout=1.0)
|
||||
if queue_item is None:
|
||||
continue
|
||||
|
||||
request_id = queue_item.request_id
|
||||
payload = queue_item.payload
|
||||
headers = queue_item.headers
|
||||
enqueued_at = queue_item.enqueued_at
|
||||
|
||||
# 查找对应的 pending future
|
||||
pending_entry = ctx.pending_requests.get(request_id)
|
||||
if pending_entry is None:
|
||||
log.warning("orphan_request", request_id=request_id)
|
||||
continue
|
||||
future, _ = pending_entry
|
||||
|
||||
# 低优先级令牌等待超时处理
|
||||
if queue_item.priority == Priority.LOW:
|
||||
# 放线程池执行阻塞的令牌桶调用
|
||||
got_token = await asyncio.to_thread(
|
||||
ctx.token_bucket.try_consume,
|
||||
tokens=1,
|
||||
timeout=ctx.config.low_priority_timeout,
|
||||
)
|
||||
if not got_token:
|
||||
log.info("low_priority_timeout", request_id=request_id)
|
||||
await ctx.increment_stat("ratelimited_requests")
|
||||
ctx.prometheus.record_request(queue_item.priority.name, "ratelimited")
|
||||
if not future.done():
|
||||
future.set_exception(
|
||||
_RateLimitedError(
|
||||
f"低优先级请求令牌等待超时 ({ctx.config.low_priority_timeout}s)"
|
||||
)
|
||||
)
|
||||
ctx.pending_requests.pop(request_id, None)
|
||||
continue
|
||||
else:
|
||||
# 非低优先级：在 worker 内轮询等待令牌，避免重入队导致 future 悬挂
|
||||
got_token = await asyncio.to_thread(ctx.token_bucket.consume, tokens=1)
|
||||
if not got_token:
|
||||
token_deadline = time.monotonic() + ctx.config.request_timeout
|
||||
while not got_token:
|
||||
await asyncio.sleep(0.1)
|
||||
got_token = await asyncio.to_thread(ctx.token_bucket.consume, tokens=1)
|
||||
if time.monotonic() > token_deadline:
|
||||
break
|
||||
if not got_token:
|
||||
log.warning(
|
||||
"token_wait_timeout",
|
||||
request_id=request_id,
|
||||
priority=queue_item.priority.name,
|
||||
timeout=ctx.config.request_timeout,
|
||||
)
|
||||
await ctx.increment_stat("ratelimited_requests")
|
||||
ctx.prometheus.record_request(queue_item.priority.name, "ratelimited")
|
||||
if not future.done():
|
||||
future.set_exception(
|
||||
_RateLimitedError(
|
||||
f"令牌等待超时 ({ctx.config.request_timeout:.0f}s)"
|
||||
)
|
||||
)
|
||||
ctx.pending_requests.pop(request_id, None)
|
||||
continue
|
||||
|
||||
# 转发到上游
|
||||
upstream_start = time.monotonic()
|
||||
try:
|
||||
path = headers.get("x-original-path", "/v1/chat/completions")
|
||||
method = headers.get("x-original-method", "POST")
|
||||
# 过滤内部 headers
|
||||
clean_headers = {
|
||||
k: v for k, v in headers.items()
|
||||
if not k.startswith("x-original-") and not k.startswith("x-request-id")
|
||||
}
|
||||
|
||||
resp = await _forward_to_upstream(
|
||||
ctx=ctx,
|
||||
method=method,
|
||||
path=path,
|
||||
body=payload.get("_raw_body"),
|
||||
headers=clean_headers,
|
||||
stream=payload.get("stream", False),
|
||||
)
|
||||
|
||||
upstream_latency = time.monotonic() - upstream_start
|
||||
queue_latency = time.monotonic() - enqueued_at
|
||||
total_latency = upstream_latency + queue_latency
|
||||
|
||||
is_429: bool = resp.status_code == 429
|
||||
ctx.token_bucket.record_response(is_429)
|
||||
|
||||
# 避退状态评估 + 指标更新
|
||||
ctx.token_bucket.evaluate_retreat()
|
||||
retreat_state = ctx.token_bucket.get_retreat_state()
|
||||
effective_rpm = ctx.token_bucket.get_effective_rate_rpm()
|
||||
upstream_429_rate = ctx.token_bucket.get_429_rate()
|
||||
ctx.prometheus.update_retreat_metrics(retreat_state, effective_rpm, upstream_429_rate)
|
||||
|
||||
# 模型级信息写入 JSON 日志 (BIZ-46 Phase3: provider label 收敛后保留)
|
||||
model_id = _extract_model(payload) or "unknown"
|
||||
log.info(
|
||||
"request_completed",
|
||||
request_id=request_id,
|
||||
status=resp.status_code,
|
||||
model_id=model_id,
|
||||
upstream_latency=round(upstream_latency, 3),
|
||||
queue_latency=round(queue_latency, 3),
|
||||
total_latency=round(total_latency, 3),
|
||||
retreat_state=retreat_state,
|
||||
effective_rpm=round(effective_rpm, 1),
|
||||
)
|
||||
|
||||
# 记录 Prometheus 指标 — provider 收敛（BIZ-46 Phase3）
|
||||
provider = "nvidia"
|
||||
ctx.prometheus.record_upstream_latency(provider, upstream_latency)
|
||||
if not resp.is_success:
|
||||
ctx.prometheus.record_upstream_error(resp.status_code, provider)
|
||||
ctx.prometheus.record_request(queue_item.priority.name, "success" if resp.is_success else "error")
|
||||
ctx.prometheus.record_queue_latency(queue_item.priority.name, queue_latency)
|
||||
|
||||
if not future.done():
|
||||
future.set_result(resp)
|
||||
|
||||
except (httpx.HTTPError, OSError) as exc:
|
||||
log.error("upstream_request_failed", request_id=request_id, error=str(exc))
|
||||
await ctx.increment_stat("upstream_errors")
|
||||
ctx.prometheus.record_request(queue_item.priority.name, "error")
|
||||
ctx.prometheus.set_health(False)
|
||||
if not future.done():
|
||||
future.set_exception(exc)
|
||||
|
||||
ctx.pending_requests.pop(request_id, None)
|
||||
|
||||
except asyncio.CancelledError:
|
||||
log.info("worker_cancelled")
|
||||
break
|
||||
except Exception:
|
||||
log.exception("worker_unexpected_error")
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# PASSTHROUGH 直通路径（队列满 + PASSTHROUGH 策略）
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
async def _passthrough_with_rate_limit(
|
||||
ctx: SidecarContext,
|
||||
request: Request,
|
||||
path: str,
|
||||
body_bytes: bytes,
|
||||
raw_headers: dict[str, str],
|
||||
priority: Priority,
|
||||
) -> Response:
|
||||
"""队列满时的 PASSSTHROUGH 直通路径：仍受令牌桶限流，但不排队。
|
||||
|
||||
Args:
|
||||
ctx: SidecarContext 运行时上下文。
|
||||
request: FastAPI Request。
|
||||
path: 请求路径。
|
||||
body_bytes: 原始请求体。
|
||||
raw_headers: 请求 headers。
|
||||
priority: 请求优先级。
|
||||
|
||||
Returns:
|
||||
FastAPI Response。
|
||||
"""
|
||||
await ctx.increment_stat("passthrough_requests")
|
||||
ctx.prometheus.increment_fallback()
|
||||
|
||||
# 低优先级走令牌桶等待
|
||||
if priority == Priority.LOW:
|
||||
got_token = await asyncio.to_thread(
|
||||
ctx.token_bucket.try_consume,
|
||||
tokens=1,
|
||||
timeout=ctx.config.low_priority_timeout,
|
||||
)
|
||||
if not got_token:
|
||||
await ctx.increment_stat("ratelimited_requests")
|
||||
ctx.prometheus.record_request(priority.name, "ratelimited")
|
||||
return JSONResponse(
|
||||
status_code=429,
|
||||
content={
|
||||
"error": {
|
||||
"message": f"令牌不足（队列满 + passthrough），超时 {ctx.config.low_priority_timeout}s",
|
||||
"type": "RateLimitedError",
|
||||
}
|
||||
},
|
||||
)
|
||||
else:
|
||||
got_token = await asyncio.to_thread(ctx.token_bucket.consume, tokens=1)
|
||||
if not got_token:
|
||||
deadline = time.monotonic() + ctx.config.request_timeout
|
||||
while not got_token:
|
||||
await asyncio.sleep(0.1)
|
||||
got_token = await asyncio.to_thread(ctx.token_bucket.consume, tokens=1)
|
||||
if time.monotonic() > deadline:
|
||||
await ctx.increment_stat("ratelimited_requests")
|
||||
ctx.prometheus.record_request(priority.name, "ratelimited")
|
||||
return JSONResponse(
|
||||
status_code=429,
|
||||
content={
|
||||
"error": {
|
||||
"message": f"令牌不足（队列满 + passthrough），等待超时 {ctx.config.request_timeout:.0f}s",
|
||||
"type": "RateLimitedError",
|
||||
}
|
||||
},
|
||||
)
|
||||
|
||||
# 拿到令牌，直接转发
|
||||
try:
|
||||
clean_headers = {k: v for k, v in raw_headers.items()}
|
||||
resp = await _forward_to_upstream(
|
||||
ctx=ctx,
|
||||
method=request.method,
|
||||
path=path,
|
||||
body=body_bytes if body_bytes else None,
|
||||
headers=clean_headers,
|
||||
stream=False,
|
||||
)
|
||||
retreat_state = ctx.token_bucket.get_retreat_state()
|
||||
ctx.token_bucket.evaluate_retreat()
|
||||
ctx.prometheus.update_retreat_metrics(
|
||||
retreat_state,
|
||||
ctx.token_bucket.get_effective_rate_rpm(),
|
||||
ctx.token_bucket.get_429_rate(),
|
||||
)
|
||||
return _build_response(resp)
|
||||
except Exception as exc:
|
||||
status, msg = _map_exception(exc)
|
||||
logger.error("passthrough_error", path=path, error=str(exc))
|
||||
ctx.prometheus.set_health(False)
|
||||
return JSONResponse(
|
||||
status_code=status,
|
||||
content={"error": {"message": msg, "type": type(exc).__name__}},
|
||||
)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 自定义异常
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
class _RateLimitedError(Exception):
|
||||
"""429 限流错误。"""
|
||||
pass
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 异常处理矩阵 (§3.4)
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
_EXCEPTION_MATRIX: dict[type[Exception], tuple[int, str]] = {
|
||||
_RateLimitedError: (429, "Too Many Requests — 令牌不足"),
|
||||
QueueFullError: (503, "Service Unavailable — 队列已满"),
|
||||
httpx.TimeoutException: (504, "Gateway Timeout — 上游超时"),
|
||||
httpx.ConnectError: (502, "Bad Gateway — 上游连接失败"),
|
||||
httpx.HTTPStatusError: (502, "Bad Gateway — 上游返回错误状态"),
|
||||
}
|
||||
|
||||
|
||||
def _map_exception(exc: Exception) -> tuple[int, str]:
|
||||
"""将异常映射为 HTTP 状态码 + 错误信息。"""
|
||||
for exc_type, (status, msg) in _EXCEPTION_MATRIX.items():
|
||||
if isinstance(exc, exc_type):
|
||||
return status, msg
|
||||
return 500, f"Internal Server Error — {type(exc).__name__}"
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# FastAPI 应用 + lifespan
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
@asynccontextmanager
|
||||
async def lifespan(app: FastAPI) -> AsyncGenerator[None, Any]:
|
||||
"""应用生命周期管理：初始化/清理全局资源。
|
||||
|
||||
BIZ-46 Phase3: 所有资源收敛到 SidecarContext，挂载于 app.state.sidecar。
|
||||
"""
|
||||
# 启动
|
||||
config: SidecarConfig = load_config()
|
||||
logging.getLogger().setLevel(config.log_level.upper())
|
||||
|
||||
http_client: httpx.AsyncClient = httpx.AsyncClient(
|
||||
timeout=httpx.Timeout(config.request_timeout),
|
||||
limits=httpx.Limits(
|
||||
max_connections=100,
|
||||
max_keepalive_connections=20,
|
||||
),
|
||||
)
|
||||
priority_queue: PriorityRequestQueue = PriorityRequestQueue(max_size=config.queue_max_size)
|
||||
token_bucket: AdaptiveTokenBucket = AdaptiveTokenBucket(
|
||||
rate=config.rate_rpm / 60.0,
|
||||
capacity=config.bucket_capacity,
|
||||
)
|
||||
prometheus: PrometheusMetrics = PrometheusMetrics()
|
||||
health: HealthService = HealthService()
|
||||
|
||||
ctx: SidecarContext = SidecarContext(
|
||||
config=config,
|
||||
http_client=http_client,
|
||||
token_bucket=token_bucket,
|
||||
priority_queue=priority_queue,
|
||||
prometheus=prometheus,
|
||||
health=health,
|
||||
)
|
||||
ctx.stats["start_time"] = int(time.time())
|
||||
app.state.sidecar = ctx # 注入 FastAPI
|
||||
|
||||
# 启动 worker 协程
|
||||
worker_task = asyncio.create_task(_worker_loop(ctx))
|
||||
|
||||
# 在独立端口 :9191 启动 Prometheus metrics 服务器
|
||||
metrics_app = prometheus.build_asgi_app()
|
||||
metrics_config = uvicorn.Config(
|
||||
metrics_app,
|
||||
host=config.listen_host,
|
||||
port=config.metrics_port,
|
||||
log_level="error",
|
||||
)
|
||||
metrics_server = uvicorn.Server(metrics_config)
|
||||
_metrics_task = asyncio.create_task(metrics_server.serve())
|
||||
|
||||
# CORS 中间件（严维序评审 #8）
|
||||
app.add_middleware(
|
||||
CORSMiddleware,
|
||||
allow_origins=["*"],
|
||||
allow_credentials=False,
|
||||
allow_methods=["*"],
|
||||
allow_headers=["*"],
|
||||
)
|
||||
|
||||
# 挂载 webui 子路由
|
||||
app.include_router(webui_router)
|
||||
|
||||
# upstream_api_key 启动检查（严维序评审 #5）
|
||||
if not config.upstream_api_key:
|
||||
logger.warning(
|
||||
"upstream_api_key_empty",
|
||||
message="SIDECAR_API_KEY 未设置，NVIDIA 请求将因 401 认证失败",
|
||||
)
|
||||
|
||||
logger.info(
|
||||
"sidecar_started",
|
||||
host=config.listen_host,
|
||||
port=config.listen_port,
|
||||
metrics_port=config.metrics_port,
|
||||
rate_rpm=config.rate_rpm,
|
||||
queue_max=config.queue_max_size,
|
||||
retreat_enabled=True,
|
||||
)
|
||||
|
||||
yield # app 运行中
|
||||
|
||||
# 关闭
|
||||
worker_task.cancel()
|
||||
try:
|
||||
await worker_task
|
||||
except asyncio.CancelledError:
|
||||
pass
|
||||
|
||||
_metrics_task.cancel()
|
||||
try:
|
||||
await _metrics_task
|
||||
except asyncio.CancelledError:
|
||||
pass
|
||||
|
||||
await http_client.aclose()
|
||||
logger.info("sidecar_stopped")
|
||||
|
||||
|
||||
def _mask_api_key(key: str) -> str:
|
||||
"""对 API Key 进行脱敏处理，仅保留前 4 位以供识别。"""
|
||||
if not key:
|
||||
return ""
|
||||
if len(key) <= 4:
|
||||
return key[:2] + "****"
|
||||
return key[:4] + "****"
|
||||
|
||||
|
||||
app: FastAPI = FastAPI(
|
||||
title="NVIDIA Sidecar Rate-Limiting Proxy",
|
||||
version="0.1.0",
|
||||
lifespan=lifespan,
|
||||
)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 核心代理处理器
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
async def _handle_proxy_request(ctx: SidecarContext, request: Request, path: str) -> Response:
|
||||
"""统一的代理请求处理入口。
|
||||
|
||||
执行完整链路：
|
||||
1. 解析请求体 → 提取 model
|
||||
2. 网关识别 → 非 NVIDIA 直通
|
||||
3. NVIDIA → 排队 + 令牌限流 + 转发
|
||||
"""
|
||||
await ctx.increment_stat("total_requests")
|
||||
|
||||
# 解析请求
|
||||
body_bytes: bytes = await request.body()
|
||||
raw_headers: dict[str, str] = dict(request.headers)
|
||||
|
||||
# 尝试解析 JSON body
|
||||
body_json: dict[str, Any] = {}
|
||||
try:
|
||||
if body_bytes:
|
||||
body_json = __import__("json").loads(body_bytes)
|
||||
except (ValueError, TypeError):
|
||||
body_json = {}
|
||||
|
||||
# 提取 model 进行网关识别
|
||||
model: str | None = _extract_model(body_json)
|
||||
is_nvidia: bool = is_nvidia_gateway(model)
|
||||
|
||||
# 非 NVIDIA → 直接转发
|
||||
if not is_nvidia:
|
||||
await ctx.increment_stat("passthrough_requests")
|
||||
try:
|
||||
resp = await _forward_to_upstream(
|
||||
ctx=ctx,
|
||||
method=request.method,
|
||||
path=path,
|
||||
body=body_bytes if body_bytes else None,
|
||||
headers=raw_headers,
|
||||
stream=body_json.get("stream", False),
|
||||
)
|
||||
return _build_response(resp)
|
||||
except Exception as exc:
|
||||
status, msg = _map_exception(exc)
|
||||
logger.error("passthrough_error", path=path, error=str(exc))
|
||||
return JSONResponse(
|
||||
status_code=status,
|
||||
content={"error": {"message": msg, "type": type(exc).__name__}},
|
||||
)
|
||||
|
||||
# NVIDIA → 排队 + 限流 + 转发
|
||||
await ctx.increment_stat("nvidia_requests")
|
||||
priority: Priority = _resolve_priority(raw_headers)
|
||||
|
||||
# 注入内部元数据到 payload
|
||||
payload_for_queue: dict[str, Any] = dict(body_json)
|
||||
payload_for_queue["_raw_body"] = body_bytes
|
||||
|
||||
# 尝试入队；PASSTHROUGH 策略下队列满时走直通路径
|
||||
try:
|
||||
request_id = await ctx.priority_queue.put(
|
||||
item=payload_for_queue,
|
||||
priority=priority,
|
||||
headers={
|
||||
**raw_headers,
|
||||
"x-original-path": path,
|
||||
"x-original-method": request.method,
|
||||
},
|
||||
)
|
||||
except QueueFullError:
|
||||
await ctx.increment_stat("queue_full_rejects")
|
||||
return JSONResponse(
|
||||
status_code=503,
|
||||
content={
|
||||
"error": {
|
||||
"message": "队列已满，当前策略: reject",
|
||||
"type": "QueueFullError",
|
||||
}
|
||||
},
|
||||
)
|
||||
except QueueFullPassthrough:
|
||||
await ctx.increment_stat("passthrough_requests")
|
||||
logger.info("queue_full_passthrough", path=path)
|
||||
return await _passthrough_with_rate_limit(ctx, request, path, body_bytes, raw_headers, priority)
|
||||
|
||||
# 创建 future 并注册到 pending
|
||||
loop = asyncio.get_running_loop()
|
||||
future: asyncio.Future[httpx.Response] = loop.create_future()
|
||||
ctx.pending_requests[request_id] = (future, time.monotonic())
|
||||
|
||||
try:
|
||||
resp = await future
|
||||
return _build_response(resp)
|
||||
except _RateLimitedError as exc:
|
||||
return JSONResponse(
|
||||
status_code=429,
|
||||
content={
|
||||
"error": {
|
||||
"message": str(exc),
|
||||
"type": "RateLimitedError",
|
||||
}
|
||||
},
|
||||
)
|
||||
except Exception as exc:
|
||||
status, msg = _map_exception(exc)
|
||||
logger.error("proxy_error", path=path, request_id=request_id, error=str(exc))
|
||||
return JSONResponse(
|
||||
status_code=status,
|
||||
content={"error": {"message": msg, "type": type(exc).__name__}},
|
||||
)
|
||||
|
||||
|
||||
def _build_response(resp: httpx.Response) -> Response:
|
||||
"""将 httpx.Response 转换为 FastAPI Response。
|
||||
|
||||
支持 JSON 和流式 (SSE) 两种响应类型。
|
||||
"""
|
||||
content_type = resp.headers.get("content-type", "")
|
||||
|
||||
# 流式响应 (SSE)
|
||||
if "text/event-stream" in content_type or "stream" in content_type:
|
||||
return StreamingResponse(
|
||||
content=resp.aiter_bytes(),
|
||||
status_code=resp.status_code,
|
||||
headers={
|
||||
k: v for k, v in resp.headers.items()
|
||||
if k.lower() not in ("content-encoding", "transfer-encoding")
|
||||
},
|
||||
media_type="text/event-stream",
|
||||
)
|
||||
|
||||
# 普通 JSON 响应
|
||||
return Response(
|
||||
content=resp.content,
|
||||
status_code=resp.status_code,
|
||||
headers={
|
||||
k: v for k, v in resp.headers.items()
|
||||
if k.lower() not in ("content-encoding", "transfer-encoding")
|
||||
},
|
||||
media_type=content_type or "application/json",
|
||||
)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 路由
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
@app.get("/health")
|
||||
async def health(ctx: SidecarContext = Depends(get_context)) -> dict[str, Any]:
|
||||
"""存活检查 (liveness)。"""
|
||||
return ctx.health.liveness()
|
||||
|
||||
|
||||
@app.get("/health/ready")
|
||||
async def health_ready(ctx: SidecarContext = Depends(get_context)) -> dict[str, Any]:
|
||||
"""就绪检查 (readiness)，含上游连通性。
|
||||
|
||||
BIZ-46 Phase3: 复用 ctx.http_client，不再每次创建新 client。
|
||||
"""
|
||||
queue_size = await ctx.priority_queue.get_queue_size()
|
||||
bucket_status = ctx.token_bucket.get_status()
|
||||
return await ctx.health.readiness(
|
||||
upstream_url=ctx.config.upstream_url,
|
||||
upstream_api_key=ctx.config.upstream_api_key or "",
|
||||
queue_current_size=queue_size,
|
||||
queue_max_size=ctx.config.queue_max_size,
|
||||
available_tokens=bucket_status["tokens"],
|
||||
bucket_capacity=bucket_status["capacity"],
|
||||
http_client=ctx.http_client, # 复用主 client
|
||||
)
|
||||
|
||||
|
||||
@app.get("/status")
|
||||
async def status(ctx: SidecarContext = Depends(get_context)) -> dict[str, Any]:
|
||||
"""调试用：限流器 + 队列 + 避退完整状态。"""
|
||||
queue_stats = await ctx.priority_queue.get_stats()
|
||||
bucket_status = ctx.token_bucket.get_status()
|
||||
return {
|
||||
"requests": {
|
||||
"total": ctx.stats["total_requests"],
|
||||
"nvidia": ctx.stats["nvidia_requests"],
|
||||
"passthrough": ctx.stats["passthrough_requests"],
|
||||
"ratelimited": ctx.stats["ratelimited_requests"],
|
||||
},
|
||||
"errors": {
|
||||
"queue_full_rejects": ctx.stats["queue_full_rejects"],
|
||||
"upstream_errors": ctx.stats["upstream_errors"],
|
||||
},
|
||||
"queue": queue_stats,
|
||||
"token_bucket": bucket_status,
|
||||
"retreat": {
|
||||
"state": ctx.token_bucket.get_retreat_state(),
|
||||
"effective_rpm": round(ctx.token_bucket.get_effective_rate_rpm(), 1),
|
||||
"base_rpm": round(ctx.token_bucket.get_base_rate_rpm(), 1),
|
||||
"upstream_429_rate": round(ctx.token_bucket.get_429_rate(), 4),
|
||||
},
|
||||
"uptime_seconds": ctx.uptime_seconds,
|
||||
}
|
||||
|
||||
|
||||
# ---- OpenAI 兼容端点 ----
|
||||
|
||||
@app.post("/v1/chat/completions")
|
||||
async def chat_completions(request: Request, ctx: SidecarContext = Depends(get_context)) -> Response:
|
||||
"""OpenAI Chat Completions API 代理（含流式支持）。"""
|
||||
return await _handle_proxy_request(ctx, request, "/v1/chat/completions")
|
||||
|
||||
|
||||
@app.post("/v1/completions")
|
||||
async def completions(request: Request, ctx: SidecarContext = Depends(get_context)) -> Response:
|
||||
"""OpenAI Completions API 代理（legacy）。"""
|
||||
return await _handle_proxy_request(ctx, request, "/v1/completions")
|
||||
|
||||
|
||||
@app.post("/v1/embeddings")
|
||||
async def embeddings(request: Request, ctx: SidecarContext = Depends(get_context)) -> Response:
|
||||
"""OpenAI Embeddings API 代理。"""
|
||||
return await _handle_proxy_request(ctx, request, "/v1/embeddings")
|
||||
|
||||
|
||||
@app.get("/v1/models")
|
||||
@app.get("/v1/models/{model_id:path}")
|
||||
async def list_models(request: Request, model_id: str | None = None, ctx: SidecarContext = Depends(get_context)) -> Response:
|
||||
"""OpenAI Models API 代理。"""
|
||||
path = f"/v1/models/{model_id}" if model_id else "/v1/models"
|
||||
return await _handle_proxy_request(ctx, request, path)
|
||||
|
||||
|
||||
# ---- 通用代理（catch-all 用于非标准 NVIDIA 端点） ----
|
||||
|
||||
@app.api_route("/{path:path}", methods=["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"])
|
||||
async def catch_all(request: Request, path: str, ctx: SidecarContext = Depends(get_context)) -> Response:
|
||||
"""通用代理端点：转发任何未匹配的路径到上游。"""
|
||||
target_path = f"/{path}" if not path.startswith("/") else path
|
||||
return await _handle_proxy_request(ctx, request, target_path)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 入口
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def main() -> None:
|
||||
"""开发/调试入口。"""
|
||||
import uvicorn
|
||||
cfg: SidecarConfig = load_config()
|
||||
uvicorn.run(
|
||||
"nvidia_sidecar.server:app",
|
||||
host=cfg.listen_host,
|
||||
port=cfg.listen_port,
|
||||
log_level=cfg.log_level.lower(),
|
||||
)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -1,327 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>NVIDIA Sidecar — 实时仪表盘</title>
|
||||
<script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.7/dist/chart.umd.min.js"></script>
|
||||
<style>
|
||||
* { margin: 0; padding: 0; box-sizing: border-box; }
|
||||
body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #0f172a; color: #e2e8f0; padding: 24px; }
|
||||
h1 { font-size: 22px; font-weight: 600; margin-bottom: 4px; color: #f8fafc; }
|
||||
.subtitle { color: #94a3b8; font-size: 13px; margin-bottom: 24px; }
|
||||
.grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(380px, 1fr)); gap: 20px; margin-bottom: 24px; }
|
||||
.card { background: #1e293b; border-radius: 12px; padding: 20px; border: 1px solid #334155; }
|
||||
.card h2 { font-size: 15px; font-weight: 600; color: #94a3b8; margin-bottom: 14px; text-transform: uppercase; letter-spacing: 0.05em; }
|
||||
.card canvas { max-height: 220px; }
|
||||
.stat-row { display: flex; gap: 16px; flex-wrap: wrap; }
|
||||
.stat { flex: 1; min-width: 100px; background: #0f172a; border-radius: 8px; padding: 12px; text-align: center; border: 1px solid #334155; }
|
||||
.stat .value { font-size: 28px; font-weight: 700; color: #38bdf8; }
|
||||
.stat .label { font-size: 11px; color: #64748b; margin-top: 4px; text-transform: uppercase; }
|
||||
.stat.warn .value { color: #f59e0b; }
|
||||
.stat.danger .value { color: #ef4444; }
|
||||
.retreat-badge { display: inline-block; padding: 2px 10px; border-radius: 999px; font-size: 12px; font-weight: 600; }
|
||||
.retreat-badge.normal { background: #065f46; color: #6ee7b7; }
|
||||
.retreat-badge.retreat { background: #78350f; color: #fbbf24; }
|
||||
.retreat-badge.recover { background: #1e3a5f; color: #60a5fa; }
|
||||
.config-panel { background: #1e293b; border-radius: 12px; padding: 20px; border: 1px solid #334155; }
|
||||
.config-panel h2 { font-size: 15px; font-weight: 600; color: #94a3b8; margin-bottom: 14px; text-transform: uppercase; letter-spacing: 0.05em; }
|
||||
.config-row { display: flex; align-items: center; gap: 12px; margin-bottom: 12px; flex-wrap: wrap; }
|
||||
.config-row label { min-width: 100px; font-size: 13px; color: #cbd5e1; }
|
||||
.config-row input, .config-row select { background: #0f172a; border: 1px solid #334155; border-radius: 6px; color: #e2e8f0; padding: 6px 10px; font-size: 13px; }
|
||||
.config-row input[type="range"] { width: 140px; }
|
||||
.config-row button { background: #38bdf8; color: #0f172a; border: none; border-radius: 6px; padding: 6px 16px; font-size: 13px; font-weight: 600; cursor: pointer; }
|
||||
.config-row button:hover { background: #7dd3fc; }
|
||||
.config-row button:disabled { background: #475569; cursor: not-allowed; }
|
||||
.toast { position: fixed; top: 16px; right: 16px; padding: 10px 20px; border-radius: 8px; font-size: 13px; z-index: 999; animation: fadeInOut 3s; }
|
||||
.toast.success { background: #065f46; color: #6ee7b7; }
|
||||
.toast.error { background: #7f1d1d; color: #fca5a5; }
|
||||
@keyframes fadeInOut { 0% { opacity: 0; transform: translateY(-8px); } 10% { opacity: 1; transform: translateY(0); } 80% { opacity: 1; } 100% { opacity: 0; } }
|
||||
.disconnected { background: #7f1d1d; color: #fca5a5; padding: 4px 10px; border-radius: 4px; font-size: 12px; display: inline-block; margin-left: 8px; }
|
||||
.connected { background: #065f46; color: #6ee7b7; padding: 4px 10px; border-radius: 4px; font-size: 12px; display: inline-block; margin-left: 8px; }
|
||||
|
||||
/* BIZ-46 Phase3: 队列柱状图 300ms 平滑动画 */
|
||||
.queue-bar { transition: height 0.3s ease; }
|
||||
|
||||
/* BIZ-46 Phase3: SSE 断连 5s 半透明遮罩 */
|
||||
#reconnect-mask {
|
||||
display: none;
|
||||
position: fixed;
|
||||
top: 0; left: 0; right: 0; bottom: 0;
|
||||
background: rgba(15, 23, 42, 0.85);
|
||||
z-index: 1000;
|
||||
justify-content: center;
|
||||
align-items: center;
|
||||
flex-direction: column;
|
||||
}
|
||||
#reconnect-mask.visible { display: flex; }
|
||||
#reconnect-mask .mask-icon { font-size: 48px; margin-bottom: 16px; }
|
||||
#reconnect-mask .mask-text { color: #94a3b8; font-size: 16px; font-weight: 500; }
|
||||
#reconnect-mask .mask-sub { color: #64748b; font-size: 13px; margin-top: 8px; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<!-- BIZ-46 Phase3: SSE 断连遮罩 -->
|
||||
<div id="reconnect-mask">
|
||||
<div class="mask-icon">⚠️</div>
|
||||
<div class="mask-text">数据暂不可用</div>
|
||||
<div class="mask-sub">SSE 连接中断，正在重连…</div>
|
||||
</div>
|
||||
|
||||
<h1>🚀 NVIDIA Sidecar 实时仪表盘
|
||||
<span id="conn-status" class="connected">已连接</span>
|
||||
</h1>
|
||||
<p class="subtitle">令牌桶限流 · 优先级队列 · 避退模式 · 实时监控</p>
|
||||
|
||||
<!-- 状态卡片 -->
|
||||
<div class="stat-row" style="margin-bottom: 24px;">
|
||||
<div class="stat"><div class="value" id="val-total">0</div><div class="label">总请求</div></div>
|
||||
<div class="stat"><div class="value" id="val-nvidia">0</div><div class="label">NVIDIA 请求</div></div>
|
||||
<div class="stat"><div class="value" id="val-rate">0</div><div class="label">当前 RPM</div></div>
|
||||
<div class="stat"><div class="value" id="val-429">0%</div><div class="label">上游 429 率</div></div>
|
||||
<div class="stat"><div class="value" id="val-retreat">正常</div><div class="label">避退状态</div></div>
|
||||
<div class="stat"><div class="value" id="val-uptime">0s</div><div class="label">运行时间</div></div>
|
||||
</div>
|
||||
|
||||
<!-- 图表 -->
|
||||
<div class="grid">
|
||||
<div class="card">
|
||||
<h2>📊 令牌桶使用率</h2>
|
||||
<canvas id="chart-tokens"></canvas>
|
||||
</div>
|
||||
<div class="card">
|
||||
<!-- BIZ-46 Phase3: 队列图标题显示总排队数 -->
|
||||
<h2>📈 队列深度 <span id="queue-total" style="font-size:13px;color:#38bdf8;">(共 0)</span></h2>
|
||||
<canvas id="chart-queue"></canvas>
|
||||
</div>
|
||||
<div class="card">
|
||||
<h2>📉 请求吞吐量 (最近 20 点)</h2>
|
||||
<canvas id="chart-throughput"></canvas>
|
||||
</div>
|
||||
<div class="card">
|
||||
<h2>⚙️ 速率历史</h2>
|
||||
<canvas id="chart-rate"></canvas>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- 配置面板 -->
|
||||
<div class="config-panel">
|
||||
<h2>🔧 实时配置</h2>
|
||||
<div class="config-row">
|
||||
<label>速率 (RPM)</label>
|
||||
<input type="range" id="cfg-rate-rpm" min="1" max="100" value="40" oninput="document.getElementById('cfg-rate-val').textContent=this.value">
|
||||
<span id="cfg-rate-val" style="min-width:30px;">40</span>
|
||||
</div>
|
||||
<div class="config-row">
|
||||
<label>队列上限</label>
|
||||
<input type="number" id="cfg-queue-max" value="500" min="1" max="2000" style="width:80px;">
|
||||
</div>
|
||||
<div class="config-row">
|
||||
<button onclick="applyConfig()">应用配置</button>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<script>
|
||||
// SSE 连接
|
||||
let evtSource = null;
|
||||
let dataHistory = { throughput: [], rates: [] };
|
||||
const MAX_HISTORY = 20;
|
||||
let lastSSETime = Date.now();
|
||||
|
||||
// BIZ-46 Phase3: SSE 断连 5s 遮罩
|
||||
function checkReconnect() {
|
||||
const mask = document.getElementById('reconnect-mask');
|
||||
if (Date.now() - lastSSETime > 5000) {
|
||||
mask.classList.add('visible');
|
||||
}
|
||||
}
|
||||
setInterval(checkReconnect, 1000);
|
||||
|
||||
function connectSSE() {
|
||||
if (evtSource) evtSource.close();
|
||||
evtSource = new EventSource('/api/dashboard/stream');
|
||||
evtSource.onmessage = (e) => {
|
||||
try {
|
||||
const snap = JSON.parse(e.data);
|
||||
lastSSETime = Date.now();
|
||||
// 隐藏断连遮罩
|
||||
document.getElementById('reconnect-mask').classList.remove('visible');
|
||||
updateDashboard(snap);
|
||||
document.getElementById('conn-status').className = 'connected';
|
||||
document.getElementById('conn-status').textContent = '已连接';
|
||||
} catch (err) {
|
||||
document.getElementById('conn-status').className = 'disconnected';
|
||||
document.getElementById('conn-status').textContent = '解析错误';
|
||||
}
|
||||
};
|
||||
evtSource.onerror = () => {
|
||||
document.getElementById('conn-status').className = 'disconnected';
|
||||
document.getElementById('conn-status').textContent = '断开 - 重连中';
|
||||
};
|
||||
}
|
||||
|
||||
// 初始化 Chart.js
|
||||
const ctxTokens = document.getElementById('chart-tokens').getContext('2d');
|
||||
const chartTokens = new Chart(ctxTokens, {
|
||||
type: 'doughnut',
|
||||
data: {
|
||||
labels: ['已用令牌', '可用令牌'],
|
||||
datasets: [{ data: [0, 40], backgroundColor: ['#ef4444', '#22c55e'], borderWidth: 0 }]
|
||||
},
|
||||
options: { responsive: true, maintainAspectRatio: true, cutout: '65%', plugins: { legend: { position: 'bottom', labels: { color: '#94a3b8' } } },
|
||||
// BIZ-46 Phase3: 300ms 平滑动画
|
||||
animation: { duration: 300 } }
|
||||
});
|
||||
|
||||
const ctxQueue = document.getElementById('chart-queue').getContext('2d');
|
||||
const chartQueue = new Chart(ctxQueue, {
|
||||
type: 'bar',
|
||||
data: {
|
||||
labels: ['URGENT', 'HIGH', 'NORMAL', 'LOW'],
|
||||
datasets: [{ label: '排队数', data: [0, 0, 0, 0], backgroundColor: ['#ef4444', '#f59e0b', '#38bdf8', '#a78bfa'] }]
|
||||
},
|
||||
options: { responsive: true, maintainAspectRatio: true,
|
||||
scales: { y: { beginAtZero: true, ticks: { color: '#94a3b8' } }, x: { ticks: { color: '#94a3b8' } } },
|
||||
plugins: { legend: { display: false } },
|
||||
// BIZ-46 Phase3: 300ms 平滑动画
|
||||
animation: { duration: 300 } }
|
||||
});
|
||||
|
||||
const ctxThroughput = document.getElementById('chart-throughput').getContext('2d');
|
||||
const chartThroughput = new Chart(ctxThroughput, {
|
||||
type: 'line',
|
||||
data: { labels: [], datasets: [
|
||||
{ label: '成功', data: [], borderColor: '#22c55e', backgroundColor: '#22c55e20', fill: false, tension: 0.3, pointRadius: 2 },
|
||||
{ label: '429', data: [], borderColor: '#f59e0b', backgroundColor: '#f59e0b20', fill: false, tension: 0.3, pointRadius: 2 },
|
||||
{ label: '直通', data: [], borderColor: '#a78bfa', backgroundColor: '#a78bfa20', fill: false, tension: 0.3, pointRadius: 2 },
|
||||
]},
|
||||
options: { responsive: true, maintainAspectRatio: true,
|
||||
scales: { y: { beginAtZero: true, ticks: { color: '#94a3b8' } }, x: { ticks: { color: '#94a3b8' } } },
|
||||
plugins: { legend: { position: 'bottom', labels: { color: '#94a3b8' } } },
|
||||
animation: { duration: 300 } }
|
||||
});
|
||||
|
||||
const ctxRate = document.getElementById('chart-rate').getContext('2d');
|
||||
const chartRate = new Chart(ctxRate, {
|
||||
type: 'line',
|
||||
data: { labels: [], datasets: [
|
||||
{ label: '有效 RPM', data: [], borderColor: '#38bdf8', fill: false, tension: 0.3, pointRadius: 2 },
|
||||
{ label: '基准 RPM', data: [], borderColor: '#64748b', fill: false, tension: 0.3, pointRadius: 2, borderDash: [4, 4] },
|
||||
]},
|
||||
options: { responsive: true, maintainAspectRatio: true,
|
||||
scales: { y: { beginAtZero: true, ticks: { color: '#94a3b8' } }, x: { ticks: { color: '#94a3b8' } } },
|
||||
plugins: { legend: { position: 'bottom', labels: { color: '#94a3b8' } } },
|
||||
animation: { duration: 300 } }
|
||||
});
|
||||
|
||||
function updateDashboard(snap) {
|
||||
const r = snap.requests || {};
|
||||
const tb = snap.token_bucket || {};
|
||||
const rt = snap.retreat || {};
|
||||
|
||||
document.getElementById('val-total').textContent = (r.total || 0).toLocaleString();
|
||||
document.getElementById('val-nvidia').textContent = (r.nvidia || 0).toLocaleString();
|
||||
document.getElementById('val-rate').textContent = Math.round(rt.effective_rpm || 40);
|
||||
document.getElementById('val-429').textContent = ((rt.upstream_429_rate || 0) * 100).toFixed(1) + '%';
|
||||
document.getElementById('val-uptime').textContent = fmtDuration(snap.uptime_seconds || 0);
|
||||
|
||||
const retreatEl = document.getElementById('val-retreat');
|
||||
const state = rt.state || 'normal';
|
||||
retreatEl.textContent = state === 'retreat' ? '⚠️ 避退' : state === 'recover' ? '↗ 恢复中' : '✅ 正常';
|
||||
retreatEl.style.color = state === 'retreat' ? '#f59e0b' : state === 'recover' ? '#60a5fa' : '#22c55e';
|
||||
|
||||
chartTokens.data.datasets[0].data = [
|
||||
Math.round((tb.capacity || 40) - (tb.tokens || 40)),
|
||||
Math.round(tb.tokens || 0)
|
||||
];
|
||||
chartTokens.update();
|
||||
|
||||
const qs = snap.queue || {};
|
||||
const perPriority = qs.per_priority || {};
|
||||
const totalQueued = perPriority.URGENT + perPriority.HIGH + perPriority.NORMAL + perPriority.LOW || qs.current_size || 0;
|
||||
chartQueue.data.datasets[0].data = [
|
||||
perPriority.URGENT || 0,
|
||||
perPriority.HIGH || 0,
|
||||
perPriority.NORMAL || 0,
|
||||
perPriority.LOW || 0
|
||||
];
|
||||
chartQueue.update();
|
||||
|
||||
// BIZ-46 Phase3: 队列图标题显示总排队数
|
||||
document.getElementById('queue-total').textContent = '(共 ' + totalQueued + ')';
|
||||
|
||||
const now = new Date().toLocaleTimeString();
|
||||
const prev = dataHistory.throughput.length > 0 ? dataHistory.throughput[dataHistory.throughput.length - 1].nvidia : 0;
|
||||
const throughput = Math.max(0, (r.nvidia || 0) - prev);
|
||||
|
||||
dataHistory.throughput.push({ time: now, nvidia: throughput, ratelimited: r.ratelimited || 0, passthrough: r.passthrough || 0 });
|
||||
dataHistory.rates.push({ time: now, effective: rt.effective_rpm || 40, base: rt.base_rpm || 40 });
|
||||
if (dataHistory.throughput.length > MAX_HISTORY) dataHistory.throughput.shift();
|
||||
if (dataHistory.rates.length > MAX_HISTORY) dataHistory.rates.shift();
|
||||
|
||||
chartThroughput.data.labels = dataHistory.throughput.map(d => d.time);
|
||||
chartThroughput.data.datasets[0].data = dataHistory.throughput.map(d => d.nvidia);
|
||||
chartThroughput.data.datasets[1].data = dataHistory.throughput.map(d => d.ratelimited);
|
||||
chartThroughput.data.datasets[2].data = dataHistory.throughput.map(d => d.passthrough);
|
||||
chartThroughput.update();
|
||||
|
||||
chartRate.data.labels = dataHistory.rates.map(d => d.time);
|
||||
chartRate.data.datasets[0].data = dataHistory.rates.map(d => d.effective);
|
||||
chartRate.data.datasets[1].data = dataHistory.rates.map(d => d.base);
|
||||
chartRate.update();
|
||||
}
|
||||
|
||||
function fmtDuration(s) {
|
||||
if (s < 60) return s + 's';
|
||||
if (s < 3600) return Math.floor(s/60) + 'm ' + (s%60) + 's';
|
||||
return Math.floor(s/3600) + 'h ' + Math.floor((s%3600)/60) + 'm';
|
||||
}
|
||||
|
||||
async function applyConfig() {
|
||||
const btn = document.querySelector('.config-row button');
|
||||
btn.disabled = true;
|
||||
try {
|
||||
const resp = await fetch('/api/admin/config', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({
|
||||
rate_rpm: parseInt(document.getElementById('cfg-rate-rpm').value),
|
||||
queue_max_size: parseInt(document.getElementById('cfg-queue-max').value),
|
||||
})
|
||||
});
|
||||
const result = await resp.json();
|
||||
showToast(resp.ok ? 'success' : 'error', resp.ok ? '配置已更新' : (result.detail || '配置更新失败'));
|
||||
} catch (err) {
|
||||
showToast('error', '请求失败: ' + err.message);
|
||||
}
|
||||
btn.disabled = false;
|
||||
}
|
||||
|
||||
function showToast(type, msg) {
|
||||
const t = document.createElement('div');
|
||||
t.className = 'toast ' + type;
|
||||
t.textContent = msg;
|
||||
document.body.appendChild(t);
|
||||
setTimeout(() => t.remove(), 3000);
|
||||
}
|
||||
|
||||
// BIZ-46 Phase3: 页面加载时同步当前配置值
|
||||
async function loadConfig() {
|
||||
try {
|
||||
const resp = await fetch('/api/admin/config');
|
||||
if (resp.ok) {
|
||||
const config = await resp.json();
|
||||
document.getElementById('cfg-rate-rpm').value = config.rate_rpm || 40;
|
||||
document.getElementById('cfg-rate-val').textContent = config.rate_rpm || 40;
|
||||
document.getElementById('cfg-queue-max').value = config.queue_max_size || 500;
|
||||
}
|
||||
} catch (e) {
|
||||
console.warn('配置加载失败（可能需要 Admin Token）', e);
|
||||
}
|
||||
}
|
||||
|
||||
loadConfig();
|
||||
connectSSE();
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -1 +0,0 @@
|
||||
# nvidia_sidecar tests
|
||||
@@ -1,207 +0,0 @@
|
||||
"""
|
||||
避退模式并发/死锁回归测试 (BIZ-46 Phase3 6)
|
||||
|
||||
覆盖多线程场景下的 AdaptiveTokenBucket 线程安全性：
|
||||
- 并发 record_response + evaluate_retreat
|
||||
- 并发 consume + record_response + evaluate_retreat
|
||||
- 高负载下避退状态转换正确性
|
||||
|
||||
设计文档: docs/architecture/BIZ-46_Phase3_Architecture_Design.md 6
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import threading
|
||||
import time
|
||||
|
||||
import pytest
|
||||
|
||||
from nvidia_sidecar.rate_limiter import AdaptiveTokenBucket, RetreatState
|
||||
|
||||
|
||||
class TestRetreatConcurrency:
|
||||
"""避退模式并发安全回归测试。"""
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_concurrent_record_and_evaluate(self) -> None:
|
||||
"""多线程同时 record_response + evaluate_retreat 不死锁。
|
||||
|
||||
4 个线程同时操作：
|
||||
- 2 个线程执行 record_response (1000 次)
|
||||
- 2 个线程执行 evaluate_retreat (1000 次)
|
||||
|
||||
所有线程必须在 10s 内完成，否则判定为死锁。
|
||||
"""
|
||||
bucket = AdaptiveTokenBucket(rate=40 / 60, capacity=40)
|
||||
errors: list[Exception] = []
|
||||
|
||||
def worker_record() -> None:
|
||||
for i in range(1000):
|
||||
try:
|
||||
bucket.record_response(is_429=(i % 10 == 0))
|
||||
except Exception as e:
|
||||
errors.append(e)
|
||||
|
||||
def worker_evaluate() -> None:
|
||||
for _ in range(1000):
|
||||
try:
|
||||
bucket.evaluate_retreat()
|
||||
except Exception as e:
|
||||
errors.append(e)
|
||||
|
||||
threads = [
|
||||
threading.Thread(target=worker_record),
|
||||
threading.Thread(target=worker_record),
|
||||
threading.Thread(target=worker_evaluate),
|
||||
threading.Thread(target=worker_evaluate),
|
||||
]
|
||||
for t in threads:
|
||||
t.start()
|
||||
for t in threads:
|
||||
t.join(timeout=10)
|
||||
|
||||
alive_threads = [t for t in threads if t.is_alive()]
|
||||
assert not alive_threads, (
|
||||
f"{len(alive_threads)} 个线程未完成，疑似死锁"
|
||||
)
|
||||
assert not errors, f"并发错误: {errors}"
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_concurrent_consume_and_retreat(self) -> None:
|
||||
"""多线程同时 consume + record_response + evaluate_retreat 不死锁。
|
||||
|
||||
覆盖 _lock (TokenBucket) 和 _retreat_lock (AdaptiveTokenBucket)
|
||||
同时被不同线程持有时的交叉锁场景。
|
||||
"""
|
||||
bucket = AdaptiveTokenBucket(rate=40 / 60, capacity=40)
|
||||
errors: list[Exception] = []
|
||||
|
||||
def worker_consume() -> None:
|
||||
for _ in range(500):
|
||||
try:
|
||||
bucket.consume(tokens=1)
|
||||
except Exception as e:
|
||||
errors.append(e)
|
||||
|
||||
def worker_retreat() -> None:
|
||||
for _ in range(500):
|
||||
try:
|
||||
bucket.record_response(is_429=False)
|
||||
bucket.evaluate_retreat()
|
||||
except Exception as e:
|
||||
errors.append(e)
|
||||
|
||||
threads = [
|
||||
threading.Thread(target=worker_consume),
|
||||
threading.Thread(target=worker_consume),
|
||||
threading.Thread(target=worker_retreat),
|
||||
threading.Thread(target=worker_retreat),
|
||||
]
|
||||
for t in threads:
|
||||
t.start()
|
||||
for t in threads:
|
||||
t.join(timeout=10)
|
||||
|
||||
alive_threads = [t for t in threads if t.is_alive()]
|
||||
assert not alive_threads, (
|
||||
f"{len(alive_threads)} 个线程未完成，疑似死锁"
|
||||
)
|
||||
assert not errors, f"并发错误: {errors}"
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_retreat_state_transitions_under_load(self) -> None:
|
||||
"""高负载下避退状态转换正确。
|
||||
|
||||
1. 注入 100 个 429 → 验证进入 RETREAT
|
||||
2. 注入 200 个成功 → 手动推进时间 → 验证恢复
|
||||
"""
|
||||
bucket = AdaptiveTokenBucket(
|
||||
rate=40 / 60,
|
||||
capacity=40,
|
||||
retreat_window_seconds=0.1,
|
||||
retreat_429_threshold=0.05,
|
||||
retreat_factor=0.75,
|
||||
retreat_min_rpm=5.0,
|
||||
recover_window_seconds=0.01,
|
||||
)
|
||||
|
||||
# 阶段 1：模拟高 429 率
|
||||
for _ in range(100):
|
||||
bucket.record_response(is_429=True)
|
||||
|
||||
state = bucket.evaluate_retreat()
|
||||
assert state == RetreatState.RETREAT, (
|
||||
f"高 429 率应触发避退，实际: {state}"
|
||||
)
|
||||
assert bucket.get_effective_rate_rpm() < bucket.get_base_rate_rpm(), (
|
||||
f"避退后速率应低于基准，实际: "
|
||||
f"{bucket.get_effective_rate_rpm()} vs {bucket.get_base_rate_rpm()}"
|
||||
)
|
||||
|
||||
# 阶段 2：模拟恢复
|
||||
time.sleep(0.15) # 等待 429 从短窗口中过期
|
||||
for _ in range(200):
|
||||
bucket.record_response(is_429=False)
|
||||
|
||||
for _ in range(10):
|
||||
state = bucket.evaluate_retreat()
|
||||
|
||||
assert state in (RetreatState.RECOVER, RetreatState.NORMAL), (
|
||||
f"恢复后应为 RECOVER 或 NORMAL，实际: {state}"
|
||||
)
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_try_consume_concurrency_safety(self) -> None:
|
||||
"""并发 try_consume 不死锁。"""
|
||||
bucket = AdaptiveTokenBucket(rate=40 / 60, capacity=40)
|
||||
errors: list[Exception] = []
|
||||
results: list[bool] = []
|
||||
|
||||
def worker() -> None:
|
||||
for _ in range(200):
|
||||
try:
|
||||
got = bucket.try_consume(tokens=1, timeout=0.1)
|
||||
results.append(got)
|
||||
except Exception as e:
|
||||
errors.append(e)
|
||||
|
||||
threads = [threading.Thread(target=worker) for _ in range(8)]
|
||||
for t in threads:
|
||||
t.start()
|
||||
for t in threads:
|
||||
t.join(timeout=10)
|
||||
|
||||
alive = [t for t in threads if t.is_alive()]
|
||||
assert not alive, f"{len(alive)} 个线程未完成，疑似死锁"
|
||||
assert not errors, f"并发错误: {errors}"
|
||||
successful = sum(1 for r in results if r)
|
||||
assert successful > 0, (
|
||||
f"令牌桶应至少成功消费一些令牌，成功: {successful}/{len(results)}"
|
||||
)
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_high_load_state_coherence(self) -> None:
|
||||
"""高负载下令牌桶状态一致性：消费总量 ≤ 初始 token + 补充量。"""
|
||||
bucket = AdaptiveTokenBucket(rate=10.0, capacity=100)
|
||||
consumed_count: list[int] = [0]
|
||||
lock = threading.Lock()
|
||||
|
||||
def worker() -> None:
|
||||
local_consumed = 0
|
||||
for _ in range(50):
|
||||
if bucket.consume(tokens=1):
|
||||
local_consumed += 1
|
||||
time.sleep(0.001)
|
||||
with lock:
|
||||
consumed_count[0] += local_consumed
|
||||
|
||||
threads = [threading.Thread(target=worker) for _ in range(10)]
|
||||
for t in threads:
|
||||
t.start()
|
||||
for t in threads:
|
||||
t.join(timeout=15)
|
||||
|
||||
max_expected = 100 + int(10.0 * 5)
|
||||
assert consumed_count[0] <= max_expected, (
|
||||
f"消费量异常: {consumed_count[0]}，应 ≤ {max_expected}"
|
||||
)
|
||||
@@ -1,325 +0,0 @@
|
||||
"""
|
||||
NVIDIA Sidecar — WebUI 后端 API
|
||||
|
||||
提供仪表盘 SSE 实时推送 + 配置热重载 API。
|
||||
|
||||
BIZ-46 Phase3:
|
||||
- 架构解耦：移除反向导入 server，改用 Depends(get_context) (§1)
|
||||
- SSE 共享缓存：1s TTL snapshot cache，多客户端不重复构建 (§3)
|
||||
- Dashboard UX：页面加载同步配置 + 队列深度标题 (§7)
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import json
|
||||
import os
|
||||
import time
|
||||
from pathlib import Path
|
||||
from typing import Any, AsyncGenerator
|
||||
|
||||
import structlog
|
||||
from fastapi import APIRouter, Depends, HTTPException, Request
|
||||
from fastapi.responses import HTMLResponse, JSONResponse, StreamingResponse
|
||||
from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
|
||||
from pydantic import BaseModel
|
||||
|
||||
from nvidia_sidecar.context import SidecarContext
|
||||
|
||||
webui_router: APIRouter = APIRouter(prefix="/api", tags=["webui"])
|
||||
logger: structlog.stdlib.BoundLogger = structlog.get_logger("nvidia_sidecar.webui")
|
||||
|
||||
STATIC_DIR: Path = Path(__file__).parent / "static"
|
||||
|
||||
# dashboard.html 缓存（严维序评审 #6 / 梁思筑评审 #8：避免每次请求读磁盘）
|
||||
_dashboard_html_cache: tuple[str, float] | None = None
|
||||
_DASHBOARD_CACHE_TTL: float = 300.0 # 5 分钟
|
||||
|
||||
# Admin API 认证（严维序评审 #1）
|
||||
_ADMIN_TOKEN: str | None = os.environ.get("SIDECAR_ADMIN_TOKEN")
|
||||
_admin_auth_scheme: HTTPBearer = HTTPBearer(auto_error=False)
|
||||
|
||||
|
||||
def _get_ctx(request: Request) -> SidecarContext:
|
||||
"""获取 SidecarContext（webui 路由级注入，避免循环导入 server）。"""
|
||||
return request.app.state.sidecar # type: ignore[no-any-return]
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 配置热重载模型
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
class ConfigPatch(BaseModel):
|
||||
"""可在线修改的配置字段。"""
|
||||
rate_rpm: int | None = None
|
||||
queue_max_size: int | None = None
|
||||
fallback_enabled_passthrough: bool | None = None
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# SSE 快照构建（BIZ-46 Phase3: 1s TTL 共享缓存）
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
async def _build_snapshot(ctx: SidecarContext) -> dict[str, Any]:
|
||||
"""构建当前状态快照（从 SidecarContext 读取，含队列深度）。
|
||||
|
||||
BIZ-46 Phase3: 不再通过反向导入 server 访问全局变量。
|
||||
"""
|
||||
try:
|
||||
bucket_status = ctx.token_bucket.get_status()
|
||||
now = time.time()
|
||||
|
||||
queue_data: dict[str, Any] = {"current_size": 0, "per_priority": {}}
|
||||
try:
|
||||
queue_stats = await ctx.priority_queue.get_stats()
|
||||
queue_data = {
|
||||
"max_size": queue_stats.get("max_size", 0),
|
||||
"current_size": queue_stats.get("current_size", 0),
|
||||
"per_priority": queue_stats.get("depth_by_priority", {}),
|
||||
"total_enqueued": queue_stats.get("total_enqueued", 0),
|
||||
"total_dequeued": queue_stats.get("total_dequeued", 0),
|
||||
"total_dropped": queue_stats.get("total_dropped", 0),
|
||||
}
|
||||
except Exception:
|
||||
logger.warning(
|
||||
"queue_stats_unavailable",
|
||||
message="队列统计获取失败，仪表盘队列深度可能不准确",
|
||||
)
|
||||
|
||||
return {
|
||||
"timestamp": now,
|
||||
"uptime_seconds": ctx.uptime_seconds,
|
||||
"token_bucket": bucket_status,
|
||||
"queue": queue_data,
|
||||
"retreat": {
|
||||
"state": ctx.token_bucket.get_retreat_state(),
|
||||
"effective_rpm": round(ctx.token_bucket.get_effective_rate_rpm(), 1),
|
||||
"base_rpm": round(ctx.token_bucket.get_base_rate_rpm(), 1),
|
||||
"upstream_429_rate": round(ctx.token_bucket.get_429_rate(), 4),
|
||||
},
|
||||
"requests": {
|
||||
"total": ctx.stats.get("total_requests", 0),
|
||||
"nvidia": ctx.stats.get("nvidia_requests", 0),
|
||||
"passthrough": ctx.stats.get("passthrough_requests", 0),
|
||||
"ratelimited": ctx.stats.get("ratelimited_requests", 0),
|
||||
},
|
||||
"errors": {
|
||||
"queue_full_rejects": ctx.stats.get("queue_full_rejects", 0),
|
||||
"upstream_errors": ctx.stats.get("upstream_errors", 0),
|
||||
},
|
||||
}
|
||||
except Exception:
|
||||
logger.exception("snapshot_build_error")
|
||||
return {"error": "snapshot_unavailable", "timestamp": time.time()}
|
||||
|
||||
|
||||
async def _build_snapshot_cached(ctx: SidecarContext) -> dict[str, Any]:
|
||||
"""带 1s TTL 的共享快照缓存（BIZ-46 Phase3 §3）。
|
||||
|
||||
多个 SSE 客户端共享同一份快照，避免重复计算和锁竞争。
|
||||
|
||||
性能收益：
|
||||
- 1 客户端: 1 次/s 计算（无变化）
|
||||
- 5 客户端: ~5 次/s → 1 次/s
|
||||
- 20 客户端: ~20 次/s → 1 次/s
|
||||
"""
|
||||
now_cache = time.monotonic()
|
||||
if ctx.snapshot_cache is not None:
|
||||
data, ts = ctx.snapshot_cache
|
||||
if now_cache - ts < ctx.SNAPSHOT_CACHE_TTL:
|
||||
return data
|
||||
|
||||
async with ctx.snapshot_cache_lock:
|
||||
# Double-check（避免多个协程同时 miss 后重复构建）
|
||||
if ctx.snapshot_cache is not None:
|
||||
data, ts = ctx.snapshot_cache
|
||||
if now_cache - ts < ctx.SNAPSHOT_CACHE_TTL:
|
||||
return data
|
||||
|
||||
snapshot = await _build_snapshot(ctx)
|
||||
ctx.snapshot_cache = (snapshot, now_cache)
|
||||
return snapshot
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 仪表盘 SSE 推送
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
async def _dashboard_stream(request: Request, ctx: SidecarContext) -> StreamingResponse:
|
||||
"""SSE 实时推送 Sidecar 完整状态快照（每秒一次）。
|
||||
|
||||
供 dashboard.html 的 EventSource 消费。
|
||||
|
||||
BIZ-46 Phase3: 使用共享缓存 _build_snapshot_cached，多客户端不重复计算。
|
||||
"""
|
||||
async def event_generator() -> AsyncGenerator[str, None]:
|
||||
first_frame = True
|
||||
while True:
|
||||
if await request.is_disconnected():
|
||||
break
|
||||
try:
|
||||
snapshot: dict[str, Any] = await _build_snapshot_cached(ctx)
|
||||
payload_sse = f"data: {json.dumps(snapshot, ensure_ascii=False)}\n\n"
|
||||
if first_frame:
|
||||
payload_sse = f"retry: 3000\n{payload_sse}"
|
||||
first_frame = False
|
||||
yield payload_sse
|
||||
except Exception:
|
||||
logger.exception("dashboard_sse_error")
|
||||
yield f"data: {json.dumps({'error': 'internal'})}\n\n"
|
||||
await asyncio.sleep(1.0)
|
||||
|
||||
return StreamingResponse(
|
||||
event_generator(),
|
||||
media_type="text/event-stream",
|
||||
headers={
|
||||
"Cache-Control": "no-cache",
|
||||
"X-Accel-Buffering": "no",
|
||||
},
|
||||
)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 配置热重载
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
async def get_config(ctx: SidecarContext) -> dict[str, Any]:
|
||||
"""获取当前完整配置（从 SidecarContext 读取）。"""
|
||||
config = ctx.config
|
||||
effective_rpm = float(ctx.token_bucket.get_effective_rate_rpm())
|
||||
return {
|
||||
"listen_host": config.listen_host,
|
||||
"listen_port": config.listen_port,
|
||||
"metrics_port": config.metrics_port,
|
||||
"upstream_url": config.upstream_url,
|
||||
"upstream_api_key": _mask_api_key(config.upstream_api_key),
|
||||
"rate_rpm": round(effective_rpm, 1),
|
||||
"bucket_capacity": config.bucket_capacity,
|
||||
"request_timeout": config.request_timeout,
|
||||
"queue_max_size": config.queue_max_size,
|
||||
"low_priority_timeout": config.low_priority_timeout,
|
||||
"fallback_enabled_passthrough": config.fallback_enabled_passthrough,
|
||||
"log_level": config.log_level,
|
||||
}
|
||||
|
||||
|
||||
async def update_config(body: ConfigPatch, ctx: SidecarContext) -> JSONResponse:
|
||||
"""在线修改配置项并即时生效。"""
|
||||
config = ctx.config
|
||||
changed: list[str] = []
|
||||
|
||||
if body.rate_rpm is not None:
|
||||
if body.rate_rpm <= 0:
|
||||
raise HTTPException(status_code=400, detail="rate_rpm must be > 0")
|
||||
config.rate_rpm = body.rate_rpm
|
||||
ctx.token_bucket.set_rate(body.rate_rpm / 60.0)
|
||||
changed.append("rate_rpm")
|
||||
|
||||
if body.queue_max_size is not None:
|
||||
if body.queue_max_size <= 0:
|
||||
raise HTTPException(status_code=400, detail="queue_max_size must be > 0")
|
||||
ok, msg = ctx.priority_queue.set_max_size(body.queue_max_size)
|
||||
if not ok:
|
||||
raise HTTPException(status_code=400, detail=msg)
|
||||
config.queue_max_size = body.queue_max_size
|
||||
changed.append("queue_max_size")
|
||||
logger.info("queue_max_size_updated", detail=msg)
|
||||
|
||||
if body.fallback_enabled_passthrough is not None:
|
||||
config.fallback_enabled_passthrough = body.fallback_enabled_passthrough
|
||||
changed.append("fallback_enabled_passthrough")
|
||||
|
||||
logger.info("config_updated", changed=changed)
|
||||
return JSONResponse(
|
||||
content={"status": "ok", "changed": changed},
|
||||
)
|
||||
|
||||
|
||||
def _mask_api_key(key: str) -> str:
|
||||
"""对 API Key 进行脱敏处理，仅保留前 4 位以供识别。
|
||||
|
||||
严维序评审 #2 / 沈路明评审 #3：防止 API Key 明文泄露。
|
||||
"""
|
||||
if not key:
|
||||
return ""
|
||||
if len(key) <= 4:
|
||||
return key[:2] + "****"
|
||||
return key[:4] + "****"
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 路由注册
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
@webui_router.get("/dashboard/stream")
|
||||
async def dashboard_stream(
|
||||
request: Request,
|
||||
ctx: SidecarContext = Depends(_get_ctx),
|
||||
) -> StreamingResponse:
|
||||
"""SSE 仪表盘实时推送端点（BIZ-46 Phase3: 使用共享缓存）。"""
|
||||
return await _dashboard_stream(request, ctx)
|
||||
|
||||
|
||||
async def _verify_admin_auth(
|
||||
credentials: HTTPAuthorizationCredentials | None = Depends(_admin_auth_scheme),
|
||||
) -> None:
|
||||
"""Admin API Bearer Token 认证（严维序评审 #1）。
|
||||
|
||||
若设置了 SIDECAR_ADMIN_TOKEN 环境变量，则要求请求携带匹配的 Bearer Token。
|
||||
未设置时跳过认证（开发/测试环境）。
|
||||
"""
|
||||
if _ADMIN_TOKEN is None:
|
||||
return # 未配置认证 token，允许无认证访问
|
||||
if credentials is None:
|
||||
raise HTTPException(status_code=401, detail="需要 Bearer Token 认证（Admin API）")
|
||||
if credentials.credentials != _ADMIN_TOKEN:
|
||||
raise HTTPException(status_code=403, detail="Admin Token 无效")
|
||||
|
||||
|
||||
@webui_router.get("/admin/config")
|
||||
async def admin_get_config(
|
||||
_auth: None = Depends(_verify_admin_auth),
|
||||
ctx: SidecarContext = Depends(_get_ctx),
|
||||
) -> JSONResponse:
|
||||
"""获取当前配置（需要 Admin 认证）。"""
|
||||
return JSONResponse(content=await get_config(ctx))
|
||||
|
||||
|
||||
@webui_router.post("/admin/config")
|
||||
async def admin_update_config(
|
||||
body: ConfigPatch,
|
||||
_auth: None = Depends(_verify_admin_auth),
|
||||
ctx: SidecarContext = Depends(_get_ctx),
|
||||
) -> JSONResponse:
|
||||
"""在线修改配置（热重载，需要 Admin 认证）。"""
|
||||
return await update_config(body, ctx)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 仪表盘静态页面
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def _get_dashboard_html() -> str:
|
||||
"""获取仪表盘 HTML（带缓存，严维序评审 #6 / 梁思筑评审 #8）。
|
||||
|
||||
首次加载后缓存 5 分钟，避免每次请求读磁盘。
|
||||
"""
|
||||
global _dashboard_html_cache
|
||||
now = time.monotonic()
|
||||
if _dashboard_html_cache is not None:
|
||||
cached_content, cached_at = _dashboard_html_cache
|
||||
if now - cached_at < _DASHBOARD_CACHE_TTL:
|
||||
return cached_content
|
||||
|
||||
dashboard_path = STATIC_DIR / "dashboard.html"
|
||||
if dashboard_path.is_file():
|
||||
content = dashboard_path.read_text(encoding="utf-8")
|
||||
_dashboard_html_cache = (content, now)
|
||||
return content
|
||||
return "<h1>dashboard.html not found</h1>"
|
||||
|
||||
|
||||
@webui_router.get("/dashboard", include_in_schema=False)
|
||||
async def dashboard_page() -> HTMLResponse:
|
||||
"""仪表盘 HTML 页面（含缓存策略）。"""
|
||||
return HTMLResponse(content=_get_dashboard_html())
|
||||
Reference in New Issue
Block a user