贡献的厂商 key 在进入轮换前先做体检：把坏 key 挡在聚合站之外

为什么要在入池前做“体检”

聚合站的核心价值是一个 API key 调用多个模型。如果贡献的厂商 key 本身失效、被限流或配置错误，它进入轮换池后会导致部分用户请求失败，影响体验。因此，在 key 入池前做一次轻量探测，把坏 key 挡在外面，是保障池子健康的关键步骤。

探测设计原则

• 最小花费：每次探测只消耗极少量 token，避免给贡献者带来额外成本。
• 快速失败：设置合理的超时，避免长时间等待拖慢入池流程。
• 全面覆盖：至少覆盖认证、模型可用性、限流状态三个维度。
• 可归类：失败原因要能区分，便于后续处理（如通知贡献者、延迟重试、直接拒绝）。

最小花费调用

用最低成本的请求验证 key 的有效性：

• 选择该厂商最便宜的模型（如小参数模型或专用轻量模型）。
• 请求内容极简，例如只生成一个短词或单字符。
• 设置 max_tokens 为最小值（如 1 或 2）。
• 如果厂商支持，优先使用流式响应并尽快中断，进一步减少消耗。

这样单次探测的成本几乎可以忽略，但足以验证 key 能否正常调用。

超时与延迟阈值

• 连接超时：设置较短时间（如 5 秒），快速排除网络或 DNS 问题。
• 响应超时：根据厂商典型延迟设定，一般 15-30 秒。如果超时，视为失败。
• 延迟阈值：记录成功请求的延迟，如果显著高于该厂商的正常水平（例如超过 2 倍中位数），可标记为“慢 key”，但不一定拒绝，可降低权重或延迟入池。

注意：阈值应基于实际观测动态调整，避免硬编码。

失败归类与处理

探测失败后，根据错误类型分类处理：

• 认证失败（401/403）：key 无效或权限不足，直接拒绝入池，并通知贡献者检查 key。
• 限流（429）：key 当前被限流，可标记为“暂时不可用”，延迟一段时间后重试探测，或入池但降低权重。
• 配额耗尽（402 或特定错误码）：key 余额不足，拒绝入池并通知贡献者充值。
• 模型不可用（404 或 400）：key 无权访问该模型或模型不存在，记录并跳过该模型。
• 网络/超时：可能是临时问题，重试 1-2 次，若仍失败则拒绝或标记为待观察。
• 未知错误：记录详细信息，人工审查。

自动化探测流程

建议将探测流程自动化：

1. 贡献者提交 key 后，触发异步探测任务。
2. 按上述最小花费调用执行探测，记录结果。
3. 根据失败归类决定：通过、拒绝、延迟重试。
4. 通过后，key 进入轮换池，并定期（如每天）做健康检查，确保持续可用。
5. 所有探测结果写入日志，便于审计和优化阈值。

定期健康检查

入池前的探测只能保证初始状态。key 在池中可能因余额耗尽、限流策略变化而失效。因此需要定期健康检查：

• 对池中每个 key 周期性执行最小花费调用。
• 连续失败多次则自动移出池子，并通知贡献者。
• 检查频率不宜过高，避免增加厂商侧负载和探测成本。

总结

通过最小花费调用、合理的超时与延迟阈值、清晰的失败归类，可以在贡献 key 进入轮换池前有效拦截失效或被限流的 key。配合定期健康检查，能持续维护池子的可用性，让用户享受稳定的多模型 API 服务。