API Provider 健康监控

API Provider 健康监控

前置知识

需要了解 HTTP 请求延迟测量的基本概念。熔断器模式的相关知识可参考 熔断器模式与故障转移。

---

学习目标

• 理解 AI API Provider 健康度的多维度评估方法
• 掌握端点延迟测量、流式健康检查、故障率统计三种核心检测方式
• 了解 Provider 健康评分的计算模型
• 识别监控指标的误报陷阱与防抖策略

---

项目实践

核心问题

当管理多个 AI API 供应商时，如何判断哪个供应商当前可用？单纯”能收到响应”是不够的——一个延迟 30 秒的供应商虽然技术上”可用”，但用户体验已经不可接受。

Provider 健康监控需要从多个维度持续评估：

检测方式一：端点延迟测量

向供应商的 /v1/models 或类似的轻量端点发送请求，测量往返延迟（RTT）：

GET /v1/models
Authorization: Bearer <test-token>

测量: request_start → response_end = latency (ms)

延迟分级：

延迟范围	健康等级	建议动作
< 500ms	健康	正常使用
500-2000ms	亚健康	标记为候选，不主动选择
2000-5000ms	不健康	降低路由权重
> 5000ms	不可用	触发熔断器打开

轻量端点的选择：

• /v1/models：大多数 OpenAI-兼容 API 支持，返回模型列表，响应体小
• /v1/health：部分供应商提供的专用健康端点
• 带 max_tokens=1 的生成请求：最真实的测试，但会产生 Token 消耗

检测方式二：流式健康检查

发送一个极小的生成请求（如 “Say OK”），检查 SSE 流是否正常：

POST /v1/chat/completions
{
    "model": "test-model",
    "messages": [{"role": "user", "content": "OK"}],
    "max_tokens": 1,
    "stream": true
}

检查指标：

• 首 Token 时间（Time to First Token, TTFT）：从请求发送到收到第一个 chunk 的时间
• 流完整性：流是否正常结束（[DONE] 或 event: message_stop）
• 错误模式识别：5xx、超时、连接拒绝、认证失败

检测方式三：故障率统计

基于实际使用请求的统计数据，而非主动探测：

健康评分 = (成功请求数 / 总请求数) × 权重1
         + (平均延迟评分) × 权重2
         - (最近 N 次连续的失败惩罚)

关键指标：

• 成功率：最近 100 次请求中成功（HTTP 2xx 且响应完整）的比例
• P50/P95/P99 延迟：延迟的分位数，比平均值更能反映尾部体验
• 连续失败数：连续失败的次数，触发熔断器的关键指标
• 最后成功时间：多久没有成功过，用于判断是否长期不可用

自定义端点管理

用户可以添加自定义检测端点（如内部 API、中转服务器），系统定期对这些端点进行健康检测：

自定义端点 {
    id: string,
    name: string,           // 显示名称
    url: string,            // 检测 URL
    interval_seconds: 60,   // 检测间隔
    last_check: DateTime,
    last_latency: Option<u64>,
    last_status: Option<u16>,
    is_healthy: bool,
}

端点自动发现：首次添加供应商预设时，自动注册其默认端点到检测列表。

健康数据的存储与查询

健康检测数据需要时间序列存储，通常方案：

stream_check_logs 表 {
    id: INTEGER PRIMARY KEY,
    provider_id: TEXT,
    check_time: DATETIME,
    latency_ms: INTEGER,
    status_code: INTEGER,
    is_success: BOOLEAN,
    error_message: TEXT,
}

数据压缩策略：

• 原始日志保留 7 天（细粒度）
• 7 天前的数据聚合为小时/天级别的统计摘要
• 定期清理（PRUNE）过期数据，避免数据库膨胀

---

问题与规避

陷阱 1：健康检测产生 Token 费用

问题：使用生成请求做健康检测会产生 Token 消耗，频繁检测可能累积不可忽视的费用。

规避策略：

• 优先使用 /v1/models 等免费端点
• 生成请求设置 max_tokens=1 和最小模型
• 增加检测间隔（如从 30s 改为 120s）
• 在健康检测日志中记录 Token 消耗，让用户可见

陷阱 2：检测频率与误报的平衡

问题：检测间隔太短容易产生误报（网络抖动被误判为故障），检测间隔太长则响应故障不及时。

规避策略：

• 使用滑动窗口而非瞬时值判断健康度
• 连续 N 次检测失败才标记为不健康
• 从”不健康”恢复到”健康”需要更多次成功确认

陷阱 3：供应商间歇性超时

问题：某个供应商 95% 的请求正常，但偶尔出现 30 秒以上的超时。如果只记录平均延迟，这种问题会被掩盖。

规避策略：

• 监控 P99 延迟而非平均延迟
• 对超时请求单独统计，不计入延迟平均值（超时不代表供应商慢，可能代表网络问题）

陷阱 4：健康数据过期未清理

问题：如果健康检测日志不断积累，数据库会持续增大，影响查询性能。

规避策略：

• 启动时自动执行日志清理（PRUNE 7 天前的数据）
• 运行时定期清理（如每 24 小时）
• 使用 ROLLUP 聚合：将原始日志压缩为日级统计后再删除原始行

---

设计取舍

主动检测 vs 被动统计

维度	主动检测	被动统计
响应速度	快（按间隔主动探测）	慢（依赖实际请求积累）
额外开销	有（检测请求产生费用/延迟）	无
低频场景	不准确（可能错过间歇性故障）	数据不足
高频场景	可能误报（网络抖动）	准确度高

最佳实践：两者结合。主动检测用于快速发现故障，被动统计用于持续评估。当实际请求量足够时，被动统计的权重应该高于主动检测。

替代方案：第三方状态 API

部分供应商提供公开的状态页面（如 status.anthropic.com）。理论上可以直接查询这些 API 获取健康状态。

局限性：

• 状态页面的更新通常滞后（运维人员手动更新）
• 只反映供应商整体状态，不反映你个人的连接质量
• 依赖外部服务，增加了代理层的脆弱性

因此，第三方状态 API 适合作为辅助参考，不应作为主要的健康判断依据。

---

参考来源

• Anthropic API Status 页面. https://status.anthropic.com/
• OpenAI API Status 页面. https://status.openai.com/
• Google Cloud Status Dashboard. https://status.cloud.google.com/