性能与故障转移调优

本页讲清在高吞吐场景下如何调优上游接入的性能与韧性。调优分两类：一是韧性侧——超时、重试、健康检查、加权恢复，决定单个上游不稳定时请求如何容错；二是吞吐侧——并发处理度、请求队列容量、队列溢出策略，决定平台在高流量下如何排队与背压。两类参数均按上游分别配置，可在「模型接入」页或控制平面 /api/v1/providers 上调整。

1. 韧性参数：超时、重试、健康检查

每个上游接入维护一组韧性参数，控制请求在该上游上的容错行为：

curl https://your-platform/api/v1/providers/<上游标识> \
  -X PUT \
  -H "Content-Type: application/json" \
  -H "Cookie: <控制台会话凭证>" \
  -d '{
    "request_timeout": "60s",
    "max_retries": 1,
    "retry_backoff_initial": "100ms",
    "retry_backoff_max": "2s",
    "health_check": true
  }'

一次请求在韧性参数下的容错路径：

• 超时：上游调用超过 request_timeout 即判失败，进入重试或降级。
• 重试：在同一上游内按退避间隔重试，至多 max_retries 次；退避从 retry_backoff_initial 起、不超过 retry_backoff_max。
• 健康检查与熔断：选用候选前做健康检查；不健康的上游被短路熔断，按优先级或路由规则的 fallbacks 降级到下一候选（见通用接入规则 §5）。

2. 加权恢复

被熔断或降权的上游恢复后，平台采用加权恢复而非一次性满负荷切回——避免刚恢复的上游被瞬时流量再次压垮：

加权恢复使路由在上游抖动后能快速降权、又能在其恢复后稳健回切，整个过程的状态流转与权重变化可在「请求监控」页查看。

3. 吞吐参数：并发处理度与请求队列容量

每个上游接入配两个吞吐参数，按该上游的预期请求速率设定：

curl https://your-platform/api/v1/providers/<上游标识> \
  -X PUT \
  -H "Content-Type: application/json" \
  -H "Cookie: <控制台会话凭证>" \
  -d '{
    "concurrency": 200,
    "buffer_size": 1000
  }'

约束：队列容量 ≥ 并发处理度。 若 concurrency > buffer_size，上游接入配置会被拒绝。建议把队列容量设为并发处理度的约 1.5 倍，既能吸收突刺、又能在内存耗尽前及时背压。

3.1 取值指引

按该上游的预期请求速率设定，常用对照（速率单位：请求/秒）：

经验公式：

并发处理度   = 预期请求速率
请求队列容量 = 1.5 × 预期请求速率

各上游按各自的速率限制与时延特性独立调优——速率宽松、吞吐高的上游可取较大并发处理度；速率紧、时延高的上游应取较保守的值，否则只会触发上游限速。不要把并发处理度设得超过上游速率上限。

4. 队列溢出策略

当某上游的请求队列达到容量上限时，行为由 drop_excess_requests 控制：

curl https://your-platform/api/v1/providers/<上游标识> \
  -X PUT \
  -H "Content-Type: application/json" \
  -H "Cookie: <控制台会话凭证>" \
  -d '{ "drop_excess_requests": true }'

生产建议。 多数生产工作负载推荐"丢弃模式 + 队列容量取并发处理度 1.5 倍"：既能吸收合理的流量突刺，又能在极端过载时以背压保护内存，而非无限排队拖垮整体时延。

5. 监控与诊断

调优后须持续观测，按实际流量回调参数。关键指标与处置：

上述指标可在「请求监控」页（GET /api/v1/monitor/overview）查看；逐上游的探测耗时、队列深度与状态流转在「模型接入」页与监控视图中同源呈现，跨页面核对时数字一致。

6. 调优速查

韧性侧：
  request_timeout       按上游典型时延留余量
  max_retries           谨慎，避免放大上游压力
  health_check          默认开启，不健康即熔断降级
  加权恢复              渐进升权 + 探测放量，避免恢复瞬间再次压垮

吞吐侧：
  并发处理度   = 预期请求速率
  请求队列容量 = 1.5 × 预期请求速率（且 ≥ 并发处理度）
  队列溢出     生产推荐丢弃模式 + 1.5 倍队列容量

通用：
  起步从保守值开始，按观测到的队列深度/时延/丢弃率逐步上调
  各上游独立调优，并发处理度不超过上游速率上限

下一步

• 通用接入规则：接入探测、运行时健康检查与故障转移的基础规则。
• 路由规则：以容量水位（budget_used / tokens_used / request_rate）为条件的动态降级路由。
• 自定义上游接入：自托管/私有上游的接入与其超时、TLS 等网络配置。
• API 参考：上游接入与监控接口的完整端点契约。