Compare commits
5 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 vincent
|
8cfc7a9743 | ||
|
vincent
|
1513abbca8 | ||
|
vincent
|
e51a7c1b85 | ||
|
vincent
|
b18d243ef2 | ||
|
vincent
|
8a12ff9693 |
@@ -0,0 +1,644 @@
|
||||
# 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 项优化 |
|
||||
@@ -1,290 +0,0 @@
|
||||
# 石斛液态饮品全品类扩展可行性分析报告
|
||||
|
||||
**报告编号**：BIZ-64 | **日期**：2026年6月26日 | **分析师**：顾析策
|
||||
**基准企业**：云南品斛堂生物科技有限公司 | **参考文档**：石斛食品饮料全品类产品方向详细文档 + BIZ-53企业情报调研报告
|
||||
|
||||
---
|
||||
|
||||
## 一、摘要
|
||||
|
||||
**核心结论**：品斛堂具备从石斛原浆单品类冠军向液态饮品多品类平台跃迁的条件，但应遵循"近岸延伸、能力匹配"原则——优先巩固原浆优势+扩展酒类第二曲线，谨慎试水即饮植物饮料，暂不进入乳制品/发酵饮品。
|
||||
|
||||
**关键数据**：
|
||||
- 石斛淘系线上2025 Q1销售额1.25亿元，同比+42%，品类增速为药食同源赛道之首
|
||||
- 露酒行业2025年规模650亿元，2030年预测2000亿（CAGR约25%），品斛堂石斛酒已有"中国销量第一"认证
|
||||
- 功能饮料2025年中国市场规模超1800亿元，增速38%
|
||||
- 中式养生水（如红豆薏米水）年增速182%，一年内达10亿规模
|
||||
- 益生菌中国市场2025年约1400亿元，近五年CAGR 9.74%
|
||||
|
||||
**TOP5 优先级排序**：
|
||||
1. 🥇 **复合草本原浆**（可行性高，毛利率60-70%，现有渠道复用）
|
||||
2. 🥈 **石斛露酒/配制酒扩展**（可行性高，毛利率55-75%，独立增长极）
|
||||
3. 🥉 **功能定制原浆**（可行性高，毛利率65-80%，差异化壁垒）
|
||||
4. 🏅 **石斛养生茶包/冲调粉**（可行性中高，毛利率45-55%，产能灵活）
|
||||
5. 🏅 **中式养生即饮植物饮料**（可行性中，毛利率40-55%，需渠道突破）
|
||||
|
||||
---
|
||||
|
||||
## 二、分品类详细评估
|
||||
|
||||
### 2.1 即饮原浆/浓浆（王牌品类·核心市场）
|
||||
|
||||
#### 市场数据
|
||||
| 指标 | 数据 | 来源 |
|
||||
|------|------|------|
|
||||
| 品斛堂石斛原浆市场份额 | 45%+，全国销量第一 | 尚普咨询2026白皮书、CIC灼识认证 |
|
||||
| 石斛淘系线上销售额(Q1 2025) | 1.25亿元，同比+41.96% | 植提桥/Foodaily |
|
||||
| 品斛堂累计销售 | 超5亿袋 | 企业公开数据 |
|
||||
| 石斛原浆品类零售价带 | ¥199-2999（按品类规格） | 天猫/京东实时数据 |
|
||||
| 行业高端化增速（¥800/100g+） | 31%，远超大众市场 | 行业报告 |
|
||||
|
||||
#### 竞争格局
|
||||
| 梯队 | 品牌 | 核心优势 |
|
||||
|:---:|------|------|
|
||||
| 🥇 | 品斛堂 | 全产业链+品类开创者，综合评分最高 |
|
||||
| 🥈 | 同仁堂、东阿阿胶 | 老字号品牌溢价，送礼场景强 |
|
||||
| 🥉 | 芝康纪、斛妈妈 | 多糖含量碾压/社媒运营强势 |
|
||||
|
||||
#### 扩展可行性分析
|
||||
|
||||
**A. 单一石斛原浆**
|
||||
|
||||
| 产品 | 可行性 | 预期毛利率 | 竞争评估 | 关键成功因素 |
|
||||
|------|:---:|:---:|------|------|
|
||||
| 紫皮石斛原浆（旗舰） | **★★★★★** | 60-70% | 领先地位稳固 | 维持品牌溢价，持续原料品质升级 |
|
||||
| 铁皮石斛原浆（高端） | **★★★★☆** | 65-75% | 面临霍山产区竞争 | 强化多糖含量数据，产地溯源 |
|
||||
| 霍山米斛原浆（超高端） | **★★★☆☆** | 70-80% | 九仙尊/斛妈妈垄断霍山产区 | 原料需外采，产地话语权弱 |
|
||||
| 冷榨鲜原浆（创新） | **★★★★☆** | 55-65% | 差异化蓝海 | 48h鲜榨工艺，冷链物流是瓶颈 |
|
||||
|
||||
**B. 复合草本原浆（强烈推荐）**
|
||||
|
||||
| 产品 | 可行性 | 预期毛利率 | 目标人群规模 | 竞争强度 | 建议优先级 |
|
||||
|------|:---:|:---:|:---:|:---:|:---:|
|
||||
| 石斛+猴头菇+沙棘（养胃） | ★★★★★ | 60-70% | 肠胃不适人群巨大 | 中（江中/同仁堂） | 🥇 |
|
||||
| 石斛+葛根+五味子（护肝/解酒） | ★★★★★ | 60-70% | 饮酒人群+熬夜人群 | 中低（差异化强） | 🥇 |
|
||||
| 石斛+枸杞+菊花（护眼） | ★★★★☆ | 55-65% | 办公族/用眼过度 | 中 | 🥈 |
|
||||
| 石斛+西洋参+黄芪（补气） | ★★★★☆ | 60-70% | 亚健康/免疫力低下 | 中高（同仁堂/康恩贝） | 🥈 |
|
||||
| 石斛+酸枣仁+百合（助眠） | ★★★★★ | 60-70% | 失眠人群超3亿 | 中（同仁堂/东阿阿胶） | 🥇 |
|
||||
|
||||
**评估理由**：复合原浆是品斛堂最优先的扩展方向。理由：(1) 复用现有原浆产线和技术（生物酶解+低温浓缩），无需新增固定资产；(2) 复用天猫/京东/抖音/视频号现有渠道和用户群；(3) 复合配方通过功能场景化营销（护肝/助眠/养胃）实现差异化，降低教育成本；(4) 客单价提升和复购率提升显著。关键风险是合规边界——普通食品不得宣传保健功能，需以"草本配方""古方传承"等合规语言替代功效宣传。
|
||||
|
||||
**C. 功能定制原浆**
|
||||
|
||||
| 产品 | 可行性 | 预期毛利率 | 市场机会 |
|
||||
|------|:---:|:---:|------|
|
||||
| 无糖石斛原浆 | ★★★★☆ | 60-70% | 无糖饮料市场615.6亿元(2025)，CAGR 8%+ |
|
||||
| 有机石斛原浆 | ★★★☆☆ | 65-75% | 有机认证门槛高→溢价空间大 |
|
||||
| 儿童稀释版 | ★★★☆☆ | 50-60% | 需额外安全性论证，合规门槛高 |
|
||||
| 孕妇温和版 | ★★☆☆☆ | 55-65% | 合规风险极高，不建议 |
|
||||
|
||||
**⚠️ 合规提醒**：普通食品不得声称适用"儿童""孕妇"等特殊人群，相关产品须严格按照食品安全标准和广告法规范。
|
||||
|
||||
---
|
||||
|
||||
### 2.2 即饮植物饮料（千亿级大众市场·谨慎进入）
|
||||
|
||||
#### 市场数据
|
||||
| 指标 | 数据 | 来源 |
|
||||
|------|------|------|
|
||||
| 中国饮料市场2025年规模 | 15,170亿元 | 艾媒咨询 |
|
||||
| 功能饮料2025年规模 | 超1,800亿元 | 中商情报网/欧睿 |
|
||||
| 凉茶市场2025年规模 | 255亿元 | 艾媒咨询 |
|
||||
| 中式养生水增速 | 182%，一年达10亿规模 | 尼尔森IQ |
|
||||
| 无糖茶增速 | 双位数，全国线下+80% | 尼尔森IQ |
|
||||
| 植物饮料增速 | 125.9%（2025 H1） | 魔镜洞察 |
|
||||
| 电解质饮料增速 | 160%+（2025 H1） | 魔镜洞察 |
|
||||
| 功能饮料线上CAGR | 13.2%（2019-2024） | 行业报告 |
|
||||
|
||||
#### 品类可行性评估
|
||||
|
||||
| 子品类 | 市场规模 | 增速 | 品斛堂可行性 | 预期毛利率 | 核心壁垒 |
|
||||
|------|:---:|:---:|:---:|:---:|------|
|
||||
| 石斛草本凉茶 | 255亿（凉茶） | 存量博弈 | ★★★☆☆ | 40-50% | 口味研发+渠道覆盖 vs 王老吉/加多宝垄断 |
|
||||
| 石斛功能饮料（能量/电解质） | 1,800亿+ | 38% | ★★☆☆☆ | 45-55% | 红牛/东鹏/外星人寡头，品斛堂零经验 |
|
||||
| 石斛养生水/植物饮料 | 10亿+（新兴） | 125%+ | ★★★★☆ | 45-55% | 盒马石斛水已有验证，但品牌≠品斛堂 |
|
||||
| 石斛茶饮（绿茶/普洱） | 即饮茶第一大品类 | 双位数 | ★★☆☆☆ | 35-45% | 农夫山泉/康师傅/统一垄断 |
|
||||
| 石斛咖啡 | 116亿（即饮咖啡） | 增长中 | ★☆☆☆☆ | 40-50% | 星巴克/瑞幸品牌壁垒+品斛堂零经验 |
|
||||
|
||||
**关键判断**：
|
||||
|
||||
品斛堂切入即饮植物饮料面临**三重壁垒**：
|
||||
1. **产能壁垒**：即饮饮料需要独立的PET/易拉罐灌装线、大规模产能（日产能百万瓶级），品斛堂现有产能为原浆袋装线和酒类酿造线，不具备即饮灌装基础；
|
||||
2. **渠道壁垒**：即饮饮料依赖百万级线下终端（便利店/商超/餐饮），品斛堂线下渠道集中在药店/特产店/美容院，渠道错配严重；
|
||||
3. **品牌壁垒**：品斛堂在石斛滋补品领域有强认知，但在"解渴饮料"场景的品牌认知为零。
|
||||
|
||||
**破局路径**：
|
||||
- **最短路径**：石斛养生水/植物饮料，以ODM/OEM模式快速试水（品斛堂提供石斛原料+配方，由成熟饮料代工厂生产），借盒马/山姆等新零售渠道首发
|
||||
- **不推荐**：自建即饮产线、硬攻能量饮料/凉茶等成熟红海
|
||||
- **参考案例**：元气森林"自在水"（红豆薏米/红枣枸杞水）——以中式养生概念实现差异化破圈，一年内破亿
|
||||
|
||||
---
|
||||
|
||||
### 2.3 乳制品/发酵饮品（万亿级·现阶段不建议）
|
||||
|
||||
#### 市场数据
|
||||
| 指标 | 数据 | 来源 |
|
||||
|------|------|------|
|
||||
| 中国酸奶市场2024年规模 | 998.74亿元（同比-9%） | 智研咨询 |
|
||||
| 中国益生菌终端市场2025年 | 约1,400亿元 | 前瞻产业研究院 |
|
||||
| 全球益生菌市场2025年 | 731.3亿美元，CAGR 7.15% | Fortune Business Insights |
|
||||
| 肠道健康饮料全球2025年 | 242亿美元，CAGR 10.9% | GM Insights |
|
||||
| 酸奶市场格局 | 伊利+蒙牛双寡头，CR2约50%+ | 智研咨询 |
|
||||
| 酵素/醋饮市场 | 碎片化，头部品牌<10亿 | 行业估算 |
|
||||
|
||||
#### 可行性评估
|
||||
|
||||
| 子品类 | 可行性 | 预期毛利率 | 关键判断 |
|
||||
|------|:---:|:---:|------|
|
||||
| 石斛酸奶 | ★★☆☆☆ | 30-40% | 伊利/蒙牛双寡头控制冷链+货架+品牌，新进入者几乎无机会 |
|
||||
| 石斛益生菌粉/固体饮料 | ★★★★☆ | 50-65% | **属于冲调品类，不是乳制品**，可行性高（见2.5） |
|
||||
| 石斛酵素 | ★★★☆☆ | 55-70% | 碎片化市场，但消费者认知模糊，教育成本高 |
|
||||
| 石斛醋饮 | ★★☆☆☆ | 40-50% | 天地壹号一家独大，品类天花板低 |
|
||||
|
||||
**判断**：
|
||||
- **酸奶**——品斛堂无乳制品基础（无奶源、无冷链、无乳制品生产技术），进入成本极高。酸奶市场已进入存量博弈（2024年下滑9%），伊利/蒙牛双寡头格局难以撼动。**不推荐**。
|
||||
- **酵素/醋饮**——碎片市场有缝隙机会，但品类教育成本高，消费者信任度低。**暂不推荐**。
|
||||
- **益生菌粉**——这是品斛堂可以切入的方向（见2.5冲调饮品）。
|
||||
|
||||
---
|
||||
|
||||
### 2.4 酒类（第二增长曲线·高优先级扩展）
|
||||
|
||||
#### 市场数据
|
||||
| 指标 | 数据 | 来源 |
|
||||
|------|------|------|
|
||||
| 露酒行业2025年规模 | 650亿元 | 中国酒业协会 |
|
||||
| 露酒行业利润增速（2020-2024） | 接近200% | 中国酒业协会 |
|
||||
| 露酒2030年预测规模 | 2,000亿元 | 中国酒业协会 |
|
||||
| 露酒年销量增速 | 30%+ | 中国酒业协会 |
|
||||
| 劲酒2025年增长 | 超20%，新增900万年轻用户 | 证券时报/劲牌 |
|
||||
| 保健酒市场规模 | 约377亿元(2023) | 智研咨询 |
|
||||
| 低度潮饮2025年规模 | 突破600亿元 | 行业报告 |
|
||||
| 品斛堂酒业产能 | 万吨级，满产12,000吨 | 企业公开数据 |
|
||||
|
||||
#### 竞争格局
|
||||
| 梯队 | 企业/品牌 | 规模/定位 | 品斛堂对标 |
|
||||
|:---:|------|------|------|
|
||||
| 🥇 超级领跑 | 劲牌（劲酒+毛铺） | 130亿+，百亿级唯一 | — |
|
||||
| 🥈 头部冲刺 | 泸州老窖养生酒、汾酒竹叶青、五粮液本草、椰岛鹿龟酒 | 冲刺10亿级 | 追赶目标 |
|
||||
| 🥉 新锐入局 | 茅台保健酒"1+3"矩阵、古井神力酒 | 战略入局 | 差异化对象 |
|
||||
| 🏅 品斛堂 | 石斛酒中国销量第一 | 酒业独立运营，王朝成入股 | **差异化定位** |
|
||||
|
||||
#### 扩展可行性分析
|
||||
|
||||
| 产品方向 | 可行性 | 预期毛利率 | 市场空间 | 关键成功因素 |
|
||||
|------|:---:|:---:|------|------|
|
||||
| **石斛露酒/配制酒扩展**（石斛+西洋参+灵芝/枸杞/人参/青梅） | ★★★★★ | 60-75% | 露酒650亿→2000亿 | 蓝帽子批文+差异化石斛IP+酒业产能 |
|
||||
| **石斛米香型白酒** | ★★★★☆ | 50-65% | 云南本地+全国化 | 米香+石斛差异化，区域文化加持 |
|
||||
| **石斛酱香型白酒** | ★★★☆☆ | 55-70% | 酱酒3,000亿 | 茅台镇产能/品牌/渠道壁垒极高 |
|
||||
| **NANO小酒（年轻化）** | ★★★★☆ | 50-60% | 年轻化微醺市场爆发 | 对标江小白/梅见，石斛健康标签 |
|
||||
| **石斛青梅酒（女性向）** | ★★★★☆ | 55-65% | 低度果酒高速增长 | 女性消费者占比58%，年轻化 |
|
||||
|
||||
**详细分析**：
|
||||
|
||||
**露酒扩展（★★★★★）**：品斛堂酒业最大优势在于——(1) "石斛酒中国销量第一""中国石斛露酒开创者"双重认证；(2) 王朝成（中国酒业顶级智囊）现金入股；(3) 万吨级酿造基地产能充裕；(4) 徐瑞晟（省级白酒品评冠军）技术护城河。露酒行业正处于爆发前夜（30%+增速，2030年2000亿），且"石斛+酒"是品斛堂独有的品类定位，竞争对手无法复制。强烈推荐扩展石斛西洋参灵芝酒（蓝帽子）、石斛枸杞酒、石斛人参酒等产品线，并向青梅酒等低度果酒延伸。
|
||||
|
||||
**白酒扩展（★★★☆☆）**：米香型白酒在云南有文化根基，品斛堂可深耕区域市场。酱香型白酒则面临茅台/习酒/郎酒等巨头碾压，不建议重资产投入。
|
||||
|
||||
**年轻化小酒（★★★★☆）**：劲酒新增900万年轻用户中400万为女性，证明"养生+微醺"正在破圈。品斛堂推出125ml石斛小酒+石斛青梅酒，切入年轻消费者场景（酒吧/KTV/餐饮），机会明确。
|
||||
|
||||
**风险提示**：露酒市场"一超多强"格局正在形成（劲酒百亿级领跑，茅台/五粮液/泸州老窖/汾酒密集入局），品斛堂需在窗口期（2-3年）内快速建立规模壁垒，否则将面临头部企业的降维打击。
|
||||
|
||||
---
|
||||
|
||||
### 2.5 冲调饮品（灵活产能·稳定增长）
|
||||
|
||||
#### 市场数据
|
||||
| 指标 | 数据 | 来源 |
|
||||
|------|------|------|
|
||||
| 冲调泡品类增速 | 领跑食品饮料全行业（2025 H1） | 魔镜洞察 |
|
||||
| 益生菌终端市场（中国2025） | 约1,400亿元 | 前瞻产业研究院 |
|
||||
| 益生菌膳食补充剂CAGR | 18%（2021-2024） | 凯度/东吴证券 |
|
||||
| 肠道健康线上规模 | 约40亿元，益生菌占75%+ | 银河证券 |
|
||||
| 速溶粉/固体饮料市场 | 碎片化，养生类高速增长 | 行业估算 |
|
||||
|
||||
#### 可行性评估
|
||||
|
||||
| 产品 | 可行性 | 预期毛利率 | 竞争分析 | 产能匹配 |
|
||||
|------|:---:|:---:|------|:---:|
|
||||
| 石斛速溶粉/固体饮料 | ★★★★☆ | 50-60% | 碎片化市场，尚无绝对头部 | 现有粉剂产线可复用 |
|
||||
| 石斛益生菌粉 | ★★★★☆ | 55-65% | 竞争激烈但增长快 | 可OEM合作成熟菌粉供应商 |
|
||||
| 石斛养生茶包 | ★★★★★ | 45-55% | 同仁堂/五谷磨房等，但有差异化空间 | 设备投入低，可快速启动 |
|
||||
| 石斛蛋白粉 | ★★☆☆☆ | 50-60% | 汤臣倍健/康比特专业壁垒高 | 需运动营养领域研发 |
|
||||
|
||||
**判断**：
|
||||
- **茶包（★★★★★）**是最低成本的入门产品——设备投入低、渠道灵活（线上+药店+特产店+礼品渠道）、可快速迭代试错。石斛+陈皮/枸杞/菊花/桂圆等经典中式养生组合天然成立。
|
||||
- **益生菌粉（★★★★☆）**是增长最快的子品类——品斛堂无需自研菌株，可外采成熟益生菌原料+自有石斛多糖配方差异化。毛利率高（55-65%），线上渠道起量快。
|
||||
- **速溶粉（★★★★☆）**复用现有粉剂产线，主打"冷水速溶""办公便携"场景，与石斛原浆形成"即饮+冲调"组合覆盖。
|
||||
|
||||
---
|
||||
|
||||
## 三、综合对比矩阵
|
||||
|
||||
| 品类 | 市场规模 | 增速 | 可行性 | 预期毛利率 | 产能匹配 | 渠道匹配 | 品牌匹配 | 竞争强度 | 综合优先级 |
|
||||
|------|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
|
||||
| 复合草本原浆 | 120亿+ | 25%+ | ★★★★★ | 60-70% | ★★★★★ | ★★★★★ | ★★★★★ | 中 | **🥇 第一位** |
|
||||
| 石斛露酒扩展 | 650亿→2000亿 | 30%+ | ★★★★★ | 60-75% | ★★★★★ | ★★★★☆ | ★★★★★ | 中→高 | **🥈 第二位** |
|
||||
| 功能定制原浆 | 120亿+(子集) | 25%+ | ★★★★☆ | 65-80% | ★★★★★ | ★★★★★ | ★★★★★ | 低→中 | **🥉 第三位** |
|
||||
| 石斛养生茶包 | 500亿+(冲调) | 15%+ | ★★★★★ | 45-55% | ★★★★☆ | ★★★★☆ | ★★★★☆ | 中 | **🏅 第四位** |
|
||||
| 石斛养生水/植物饮料 | 10亿+(新兴) | 125%+ | ★★★★☆ | 40-55% | ★★☆☆☆ | ★★☆☆☆ | ★★★☆☆ | 中 | **🏅 第五位** |
|
||||
| 石斛益生菌粉 | 40亿+ | 18% | ★★★★☆ | 55-65% | ★★★☆☆ | ★★★★☆ | ★★★★☆ | 中高 | 第六位 |
|
||||
| 石斛功能饮料 | 1,800亿+ | 38% | ★★☆☆☆ | 45-55% | ★☆☆☆☆ | ★☆☆☆☆ | ★★☆☆☆ | 极高 | 暂不推荐 |
|
||||
| 石斛酸奶 | 998亿 | -9% | ★★☆☆☆ | 30-40% | ★☆☆☆☆ | ★☆☆☆☆ | ★★☆☆☆ | 极高 | 不建议 |
|
||||
| 石斛咖啡 | 116亿 | 增长中 | ★☆☆☆☆ | 40-50% | ★☆☆☆☆ | ★☆☆☆☆ | ★☆☆☆☆ | 极高 | 不建议 |
|
||||
|
||||
---
|
||||
|
||||
## 四、扩展路径建议（三年路线图）
|
||||
|
||||
### 第一年（2026-2027）：巩固+近岸扩展
|
||||
1. **复合草本原浆**：优先上市 护肝（葛根五味子）、助眠（酸枣仁百合）、养胃（猴头菇沙棘）三款
|
||||
2. **功能定制原浆**：推出无糖版，抢占控糖人群
|
||||
3. **露酒扩展**：推出石斛枸杞酒、石斛人参酒、石斛青梅酒
|
||||
4. **养生茶包**：石斛陈皮茶、石斛枸杞菊花茶
|
||||
|
||||
### 第二年（2027-2028）：规模化+渠道下沉
|
||||
1. 复合原浆全渠道铺开（药店/商超/便利店）
|
||||
2. 启动NANO小酒年轻化营销（小红书/抖音种草+餐饮渠道）
|
||||
3. 益生菌粉上市
|
||||
4. 试水石斛养生水（ODM模式，盒马/山姆首发）
|
||||
|
||||
### 第三年（2028-2029）：品牌升维+第二曲线
|
||||
1. 石斛露酒冲刺5-10亿级
|
||||
2. 评估是否需要自建即饮产线（基于养生水试水结果）
|
||||
3. 探索石斛酵素/发酵饮品
|
||||
4. 国际化试水（东南亚石斛原浆/酒类出口）
|
||||
|
||||
---
|
||||
|
||||
## 五、关键风险与应对
|
||||
|
||||
| 风险 | 等级 | 应对策略 |
|
||||
|------|:---:|------|
|
||||
| 复合原浆合规风险（功效宣传边界） | 🔴 | 严格以"草本配方""中式养生"替代功效宣传；法务前置审核 |
|
||||
| 露酒市场头部挤压（劲酒/茅台保健酒/五粮液） | 🟡 | 聚焦"石斛"差异化壁垒，避免与巨头正面价格战 |
|
||||
| 即饮饮料产线投资过大 | 🟡 | 以ODM模式试水，暂不自建产线 |
|
||||
| 多品类扩张导致品牌定位模糊 | 🟡 | 保持"元斛"品牌聚焦石斛原浆，"品斛堂"品牌聚焦酒类，新品类使用独立子品牌 |
|
||||
| 王红权星封禁关联舆情风险 | 🔴 | 清理合作痕迹，建立达人合作风控机制 |
|
||||
|
||||
---
|
||||
|
||||
## 六、数据来源
|
||||
|
||||
1. 尚普咨询《2026中国药食同源健康行业白皮书》—— 石斛原浆品牌梯队
|
||||
2. CIC灼识咨询认证 —— 品斛堂石斛原浆/石斛酒"第一"认证
|
||||
3. 中国酒业协会 —— 露酒行业规模650亿/2030年2000亿预测
|
||||
4. 艾媒咨询《2026年中国饮料行业发展状况及消费行为调查数据》—— 饮料市场15,170亿元
|
||||
5. 尼尔森IQ《2025 解构中国饮料行业增长新势能》—— 中式养生水增速182%，功能饮料增速第一
|
||||
6. Fortune Business Insights —— 全球益生菌市场731.3亿美元
|
||||
7. 前瞻产业研究院 —— 中国益生菌行业约1400亿元
|
||||
8. 智研咨询 —— 酸奶市场998.74亿元
|
||||
9. 魔镜洞察《2025年H1消费新潜力白皮书》—— 植物饮料增速125.9%
|
||||
10. 证券时报/劲牌公开数据 —— 劲酒2025年增长超20%，新增900万年轻用户
|
||||
11. 新京报《养生酒赛道扩容》—— 茅台保健酒"1+3"露酒矩阵
|
||||
12. 中商情报网 —— 中国功能饮料市场超1800亿元
|
||||
13. 品斛堂官网/天猫元斛旗舰店/京东品斛堂酒类旗舰店实时数据
|
||||
14. Foodaily/腾讯新闻 —— 盒马石斛水、每日乔安等新锐品牌动态
|
||||
|
||||
---
|
||||
|
||||
*注：部分预测数据基于行业增速假设推算，置信区间±15%。毛利率数据为行业经验估算，企业实际数据可能因规模效应和定价策略有所差异。*
|
||||
@@ -1,446 +0,0 @@
|
||||
# 石斛固态食品与烘焙全品类扩展可行性分析报告
|
||||
|
||||
**编号**：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月*
|
||||
*本报告基于公开市场数据和行业研究报告编制，品斛堂内部产能数据来源于公开信息（百度百科、什么值得买评测）*
|
||||
@@ -1,420 +0,0 @@
|
||||
# 石斛功能保健食品、礼品礼盒、创新跨界品类扩展可行性分析报告
|
||||
|
||||
**报告编号**：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日 | 顾析策 | 分析事业部 | 市场分析师*
|
||||
@@ -1,318 +0,0 @@
|
||||
# 石斛预制菜与调味品赛道切入可行性分析
|
||||
|
||||
**分析日期**：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,20 +0,0 @@
|
||||
# 品斛堂产品扩展可行性分析报告
|
||||
|
||||
**来源项目**：BIZ-53 云南品斛堂生物科技深度调研
|
||||
**分析人**：顾析策（marketanalysis 市场分析师）
|
||||
**分析日期**：2026年6月26日
|
||||
**父 Issue**：[BIZ-53](https://multica.bizurl.cn/issues/b619b988-2311-481d-bb95-409caa9ce82a)
|
||||
|
||||
## 报告索引
|
||||
|
||||
| 编号 | 报告 | 核心结论 |
|
||||
|------|------|----------|
|
||||
| BIZ-64 | 石斛液态饮品全品类扩展可行性分析 | 建议优先切入功能性饮品赛道 |
|
||||
| BIZ-65 | 石斛固态食品与烘焙全品类扩展可行性分析 | 膏滋蜜炼和压片糖果为最高优先级 |
|
||||
| BIZ-66 | 石斛功能保健食品-礼品-创新跨界可行性分析 | 蓝帽子保健品高壁垒高毛利，礼品方向可复用现有基础 |
|
||||
| BIZ-67 | 石斛预制菜与调味品赛道切入可行性分析 | 建议观望+轻资产试水 |
|
||||
|
||||
## 文档状态
|
||||
|
||||
- 4 份报告均为完整交付物，已提交至 Multica `in_review`
|
||||
- 等待刘总（Vincent）审阅确认
|
||||
@@ -0,0 +1,3 @@
|
||||
__pycache__/
|
||||
*.egg-info/
|
||||
.mypy_cache/
|
||||
@@ -0,0 +1,40 @@
|
||||
# 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"]
|
||||
@@ -0,0 +1,118 @@
|
||||
# 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，线程安全，支持阻塞/非阻塞消费
|
||||
@@ -0,0 +1,41 @@
|
||||
"""
|
||||
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",
|
||||
]
|
||||
@@ -0,0 +1,221 @@
|
||||
"""
|
||||
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
|
||||
@@ -0,0 +1,75 @@
|
||||
"""
|
||||
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
|
||||
@@ -0,0 +1,31 @@
|
||||
# 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
|
||||
@@ -0,0 +1,49 @@
|
||||
# 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
|
||||
@@ -0,0 +1,198 @@
|
||||
"""
|
||||
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
|
||||
@@ -0,0 +1,277 @@
|
||||
"""
|
||||
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)
|
||||
@@ -0,0 +1,253 @@
|
||||
"""
|
||||
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,
|
||||
}
|
||||
@@ -0,0 +1,48 @@
|
||||
[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
|
||||
@@ -0,0 +1,442 @@
|
||||
"""
|
||||
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] = {
|
||||
# OpenClaw 配置中全部的 NVIDIA provider 名称
|
||||
"nvidia",
|
||||
"nvidia-gateway",
|
||||
"nvidia98053",
|
||||
"nvidialiuweicheng84",
|
||||
"nvidiavx",
|
||||
"nvidiavx18088980513",
|
||||
"nvidiavx64391942",
|
||||
}
|
||||
|
||||
|
||||
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()
|
||||
@@ -0,0 +1,834 @@
|
||||
"""
|
||||
NVIDIA Sidecar 限流代理 — FastAPI 代理主入口 (§3.4)
|
||||
|
||||
完整的 API 代理链路：
|
||||
接收 → 网关识别 → [NVIDIA: 排队 → 令牌限流] → httpx 转发 → 返回
|
||||
|
||||
非 NVIDIA 请求直通上游，NVIDIA 请求经过四级优先级队列 + 令牌桶限流。
|
||||
|
||||
BIZ-46 Phase3: 架构解耦 — 所有全局状态收敛为 SidecarContext (§1)
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import json
|
||||
|
||||
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, PlainTextResponse, 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.stdlib.LoggerFactory(),
|
||||
wrapper_class=structlog.stdlib.BoundLogger,
|
||||
cache_logger_on_first_use=True,
|
||||
)
|
||||
logger: structlog.stdlib.BoundLogger = structlog.get_logger("nvidia_sidecar")
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# FastAPI 依赖注入
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def get_context() -> SidecarContext:
|
||||
"""从 app.state 获取 SidecarContext（FastAPI 依赖注入）。"""
|
||||
return 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 请求失败。
|
||||
"""
|
||||
# 构建上游 URL：如果 upstream_url 已经包含 /v1 路径，则避免路径重复
|
||||
base_url = ctx.config.upstream_url.rstrip("/")
|
||||
if base_url.endswith("/v1") and path.startswith("/v1"):
|
||||
upstream_url = base_url + path[3:] # 去掉 path 中的 /v1 前缀
|
||||
else:
|
||||
upstream_url = base_url + 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))
|
||||
|
||||
# Metrics 通过主服务器 `/metrics` 端点提供
|
||||
|
||||
# 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
|
||||
|
||||
await http_client.aclose()
|
||||
logger.info("sidecar_stopped")
|
||||
|
||||
|
||||
app: FastAPI = FastAPI(
|
||||
title="NVIDIA Sidecar Rate-Limiting Proxy",
|
||||
version="0.1.0",
|
||||
lifespan=lifespan,
|
||||
)
|
||||
|
||||
# CORS 中间件（在 lifespan 前添加，避免 RuntimeError）
|
||||
app.add_middleware(
|
||||
CORSMiddleware,
|
||||
allow_origins=["*"],
|
||||
allow_credentials=False,
|
||||
allow_methods=["*"],
|
||||
allow_headers=["*"],
|
||||
)
|
||||
|
||||
|
||||
def _mask_api_key(key: str) -> str:
|
||||
"""对 API Key 进行脱敏处理，仅保留前 4 位以供识别。"""
|
||||
if not key:
|
||||
return ""
|
||||
if len(key) <= 4:
|
||||
return key[:2] + "****"
|
||||
return key[:4] + "****"
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 核心代理处理器
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
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)
|
||||
# 剥离 NVIDIA provider 前缀（如 "nvidia/deepseek-ai/deepseek-v4-pro" → "deepseek-ai/deepseek-v4-pro"）
|
||||
if model and "/" in model:
|
||||
stripped_model: str = model.split("/", 1)[1]
|
||||
payload_for_queue["model"] = stripped_model
|
||||
bytes_model_stripped: bytes = json.dumps(body_json).encode()
|
||||
# Update model in the raw body bytes
|
||||
payload_for_queue["_raw_body"] = json.dumps(payload_for_queue).encode()
|
||||
|
||||
# 尝试入队；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) -> Response:
|
||||
"""OpenAI Chat Completions API 代理（含流式支持）。"""
|
||||
ctx: SidecarContext = get_context()
|
||||
return await _handle_proxy_request(ctx, request, "/v1/chat/completions")
|
||||
|
||||
|
||||
@app.post("/v1/completions")
|
||||
async def completions(request: Request) -> Response:
|
||||
ctx: SidecarContext = get_context()
|
||||
"""OpenAI Completions API 代理（legacy）。"""
|
||||
return await _handle_proxy_request(ctx, request, "/v1/completions")
|
||||
|
||||
|
||||
@app.post("/v1/embeddings")
|
||||
async def embeddings(request: Request) -> Response:
|
||||
ctx: SidecarContext = get_context()
|
||||
"""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) -> Response:
|
||||
ctx: SidecarContext = get_context()
|
||||
"""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) -> Response:
|
||||
ctx: SidecarContext = get_context()
|
||||
"""通用代理端点：转发任何未匹配的路径到上游。"""
|
||||
target_path = f"/{path}" if not path.startswith("/") else path
|
||||
return await _handle_proxy_request(ctx, request, target_path)
|
||||
|
||||
|
||||
@app.get("/metrics")
|
||||
async def metrics(ctx: SidecarContext = Depends(get_context)) -> PlainTextResponse:
|
||||
"""Prometheus 指标端点。"""
|
||||
return PlainTextResponse(
|
||||
content=ctx.prometheus.generate_latest().decode(),
|
||||
media_type="text/plain; version=0.0.4",
|
||||
)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 入口
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
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()
|
||||
@@ -0,0 +1,327 @@
|
||||
<!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>
|
||||
@@ -0,0 +1 @@
|
||||
# nvidia_sidecar tests
|
||||
@@ -0,0 +1,207 @@
|
||||
"""
|
||||
避退模式并发/死锁回归测试 (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}"
|
||||
)
|
||||
@@ -0,0 +1,325 @@
|
||||
"""
|
||||
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