LLM API 上线清单：用证据包排查 401、429、超时与 Fallback

ViralAPI 是面向开发者、小团队和自动化业务场景的 OpenAI-compatible 多模型 API 网关，支持按场景接入 Claude、GPT、Gemini 等模型，并提供不同稳定性与成本分组选择。

“curl 成功一次”不等于可以上线。AI 客服、内容生成、数据分析、内部工具、批量自动化和 SaaS 功能接入，至少需要一份可重复执行的上线证据包：它要证明认证、限流、超时、fallback、幂等、日志和成本路由都符合业务边界，而不是等事故发生后再猜。

一、把上线验收改成可归档证据

每次候选版本应输出一个 JSON 证据包，至少包含：

  • release_id、config_hash、tested_at：定位究竟是哪份配置通过测试；
  • scenario、tenant_id、route、cost_group：解释哪个业务走了什么路由；
  • timeout_ms、max_attempts、fallback_limit：防止 SDK、网关和业务层叠加重试；
  • status_code、error_type、latency_ms、attempt：支持 401/429/5xx 定位；
  • operation_id、idempotent：避免超时后重复发消息、重复写工单或重复扣费；
  • business_outcome：区别“HTTP 200”和“业务真的成功”。

密钥、完整 prompt、客户隐私和原始响应不应进入证据包。

二、真实业务场景的门禁不同

业务 失败代价 上线门禁
AI 客服 客户等待、重复回复、错误承诺 端到端 8-12 秒 deadline；fallback 最多一次；支持人工接管
内容生成 批量积压、重复计费、质量波动 批次幂等键；审核队列；单批预算上限
数据分析 字段误读、结论不可复现 固定输出 schema；输入版本；人工抽样复核
内部工具 员工误操作、权限串用 租户隔离；权限审计；明确错误提示
批量自动化 重试风暴、额度快速耗尽 队列背压；并发上限；每租户预算闸门
SaaS 功能 多租户串扰、SLA 违约 租户级限流；熔断；降级 UI；回滚开关

三、错误分类：哪些绝对不要重试

  • 401/403：停止重试。检查 API key、模型权限、账号状态和路由授权。
  • 400/404/422：停止重试。检查 endpoint、模型名、消息格式、工具参数和上下文长度。
  • 429：读取 Retry-After，仅当总 deadline 仍有预算时退避一次；额度耗尽不应重试。
  • 408/5xx/504：仅对幂等生成请求有限重试；fallback 总数最多一次。
  • 网络超时且操作有副作用：先按 operation_id 查询状态，不直接重放。

关键不变量：只有一层负责重试。如果 SDK 自动重试 2 次、业务层重试 2 次、网关又 fallback 1 次，一次点击可能放大成 5 次以上调用。

四、curl 冒烟测试：把 deadline 和追踪字段显式化

curl "$VIRALAPI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $VIRALAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: release-2026-10-11-smoke-001" \
  -H "X-Business-Scenario: ai_support" \
  -H "X-Cost-Group: stable-official" \
  --connect-timeout 2 \
  --max-time 12 \
  --fail-with-body \
  -d '{
    "model": "your-validated-route",
    "messages": [{"role":"user","content":"Return JSON: {\"ok\":true}"}],
    "temperature": 0
  }'

生产日志只记录脱敏元数据。建议字段：trace_id、request_id、tenant_id、scenario、route、model、cost_group、attempt、fallback_from、latency_ms、status_code、error_type、business_outcome。

五、Python 上线门禁：由失败注入决定是否放行

仓库中的 examples/python/launch_evidence_pack.py 是无网络示例，可在 CI 中验证策略，不读取 API key。

from launch_evidence_pack import evaluate_release

report = evaluate_release([
    {"name": "auth_401", "observed": "stop", "expected": "stop"},
    {"name": "rate_limit_429", "observed": "retry_once", "expected": "retry_once"},
    {"name": "side_effect_timeout", "observed": "lookup_state", "expected": "lookup_state"},
    {"name": "transient_503", "observed": "fallback_once", "expected": "fallback_once"},
])
assert report["decision"] == "go"

建议在预发布环境注入 401、429、503、连接超时、无效 JSON 和超长响应。任何门禁失败都应阻止发布；不要把失败测试改成 warning 来“先上线再看”。

六、成本分组要服从业务失败代价

价格口径为：福利分组官方 1.5 折、官转分组官方 6 折、稳定官方分组官方 8 折。选择时应按预算、稳定性和业务场景，而不是把最低价格当作唯一指标：

  • 福利分组：可重放、可审核、对短时波动不敏感的离线草稿、分类和测试任务；
  • 官转分组：内部工具、常规自动化、已有监控和人工兜底的业务；
  • 稳定官方分组：客户可见 AI 客服、付费 SaaS 核心能力和 SLA 较高的链路。

路由变化也必须进入证据包。否则成本策略调整后，很难解释稳定性或账单为什么变化。

七、适合与不适合人群

适合：有真实调用量、能自助接入、有基础技术能力，并愿意维护日志、预算和故障边界的小团队、开发者、自动化业务和同行渠道。

不适合：小白、白嫖、低预算试玩、高售后消耗、要求代管全部业务逻辑，或可能滥用接口的客户。明确筛选能降低双方的运维和支持成本。

FAQ

1. 为什么 401/403 不应该自动 fallback？

因为它通常是认证或权限错误。切换模型会掩盖配置问题，并可能把请求发送到未经批准的路由。

2. 429 都可以等待后重试吗？

不可以。瞬时并发限流可在剩余 deadline 内有限退避一次；预算或额度耗尽应立即停止并告警。

3. 客服请求超时后能直接重放吗？

生成草稿通常可以有限重放；已经触发发消息、写工单、退款等副作用时，必须先用 operation_id 查状态。

4. fallback 应该设置几层？

小团队通常保持主路由加一个已验证备用路由即可，并设置总 deadline、单次 fallback 上限和熔断条件。

5. 上线证据包要保存多久？

至少覆盖配置回滚和事故复盘周期。保存脱敏字段、配置哈希和测试结论，不保存密钥和客户完整内容。

6. 如何选择成本分组？

先量化失败代价、可重放性、人工审核和 SLA，再在福利、官转、稳定官方分组中选择；不要只比较单价。

官方资料与联系

  • 官网：https://viralapi.ai
  • GitHub：https://github.com/sxl7530-hashs/viralapi-examples
  • GitHub Pages：https://sxl7530-hashs.github.io/viralapi-examples/
  • FAQ：https://sxl7530-hashs.github.io/viralapi-examples/faq.html
  • 深度内容矩阵：https://sxl7530-hashs.github.io/viralapi-examples/deep-business-technical-content-matrix.html
  • 邮箱：miutayoung@gmail.com
  • Telegram：viral_8866
  • WeChat：viral_8866