LLM API 上线 FAQ 与排障决策树：401/429/超时、Fallback 和适用人群

LLM API 上线 FAQ 与排障决策树：401/429/超时、Fallback 和适用人群

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

这篇内容面向已经准备把 LLM API 接入真实业务的小团队：AI 客服、内容生成流水线、数据分析助手、内部运营工具、批量自动化脚本和 SaaS 功能接入。上线前最容易出问题的不是「能不能调通一次」，而是 401/429/超时、fallback、重试和成本分组没有边界，导致线上问题无法定位，或者把不适合的客户引入高售后链路。

1. 上线门禁：先判断是否适合接入

ViralAPI 更适合有真实调用量、能自助接入、有基础技术能力的小团队、开发者、自动化业务和同行渠道。接入前至少应满足四个条件：

1. 能配置环境变量、base_url、API key 和模型名。
2. 能在日志里保留 trace_id、tenant_id、scenario、model、cost_group、status_code、latency_ms、error_type，同时不记录密钥和完整敏感 prompt。
3. 能区分只读生成任务和有副作用任务，例如发消息、写工单、扣费、退款、修改订单。
4. 能接受按预算、稳定性和业务场景选择分组，而不是只按最低单价做生产决策。

不适合的人群包括：完全没有 API 基础的小白、白嫖流量、低预算试玩、高售后消耗、要求代写全部业务代码、或者可能滥用模型接口的客户。这类用户进入生产链路后，支持成本通常会超过 API 本身价值。

2. 业务场景如何拆上线风险

场景	主要风险	上线前必须验证
AI 客服	错答、超时、重复回复、无法人工接管	会话 trace、人工接管条件、fallback 后话术、敏感信息过滤
内容生成	批量失败、重复生成、成本失控	批次 ID、幂等键、审核队列、按字数和模型分组预算
数据分析	结果不可复现、字段误读、长上下文超限	输入版本、输出 schema、上下文截断、人工复核样本
内部工具	员工误用、权限混乱、日志缺失	用户 ID、部门/租户预算、错误码提示、操作审计
SaaS 功能接入	多租户串扰、额度透支、SLA 不稳定	租户级限流、成本分组、熔断、降级 UI、回滚开关

生产判断应该从业务失败反推技术配置。例如 AI 客服的客户可见链路不应默认走最低成本分组；内容草稿、离线分类和可审核批处理可以使用更偏成本优先的路由。

3. 排障决策树

把错误分成四类，不要所有异常都自动重试：

收到错误或超时
  |
  |-- 401/403 -> 停止重试：检查 key、账号权限、模型权限、区域或账号状态
  |
  |-- 400/404/422 -> 停止重试：检查 endpoint、model、messages、工具参数、上下文长度
  |
  |-- 429 -> 读取 Retry-After：在剩余 deadline 内最多有限退避一次
  |
  |-- 408/5xx/504 -> 判断是否幂等
          |
          |-- 非幂等写操作 -> 先用 operation_id 查状态，不直接重放
          |
          |-- 幂等生成 -> 若 fallback 未用且剩余 deadline 足够，切换一次已验证备用模型

关键原则是：SDK、网关和业务层只能有一个重试负责人。若 SDK 已经默认重试 2 次，业务层再重试 2 次，fallback 再尝试 1 次，用户看到的是一次点击，后端可能已经产生 5 次模型调用和多个不可解释状态。

4. Python 离线门禁示例

下面的示例不读取 API key，也不发网络请求，只演示上线前应如何把错误分类、deadline、幂等性、fallback 和人工队列放进同一个决策函数。

from dataclasses import dataclass, asdict
from typing import Literal

Action = Literal["stop", "retry_once", "fallback_once", "lookup_state", "queue_review"]

@dataclass(frozen=True)
class Decision:
    action: Action
    reason: str
    retry_allowed: bool
    fallback_allowed: bool
    log_level: str

def route_failure(status: int, remaining_ms: int, idempotent: bool, fallback_used: bool) -> dict:
    if status in {400, 401, 403, 404, 422}:
        return asdict(Decision("stop", "config_or_contract_error", False, False, "error"))
    if remaining_ms < 1200:
        return asdict(Decision("queue_review", "deadline_exhausted", False, False, "warn"))
    if not idempotent:
        return asdict(Decision("lookup_state", "side_effect_status_unknown", False, False, "warn"))
    if status == 429:
        return asdict(Decision("retry_once", "rate_limited_with_budget", True, False, "warn"))
    if status in {408, 500, 502, 503, 504} and not fallback_used:
        return asdict(Decision("fallback_once", "transient_upstream_failure", False, True, "warn"))
    return asdict(Decision("queue_review", "no_safe_automatic_recovery", False, False, "warn"))

真实接入 OpenAI-compatible API 时，业务代码应把超时、重试和日志显式化：

curl "$VIRALAPI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $VIRALAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: launch-gate-2026-10-04" \
  -H "X-Business-Scenario: ai_support" \
  -H "X-Cost-Group: stable-official" \
  --max-time 12 \
  -d '{
    "model": "your-claude-or-gpt-or-gemini-route",
    "messages": [{"role":"user","content":"Return a short customer support draft."}],
    "temperature": 0.2
  }'

5. 成本分组不是低价排序

价格口径可以这样理解：福利分组官方 1.5 折，官转分组官方 6 折，稳定官方分组官方 8 折。实际选择应按预算、稳定性和业务场景决定：

• 福利分组：适合可重放、可人工审核、对短时波动不敏感的批量内容草稿、离线分类和测试型任务。
• 官转分组：适合内部工具、常规自动化、可观测性较好的中等稳定性业务。
• 稳定官方分组：适合客户可见 AI 客服、付费 SaaS 核心功能、生产数据分析和 SLA 压力较高的链路。

这样表达的重点是业务匹配，而不是用低价吸引不合适用户。

FAQ

1. 401/403 能不能直接 fallback 到别的模型？

不建议。401/403 往往是 key、账号、模型权限或账号状态问题，自动 fallback 会掩盖配置错误。应先停止重试并告警。

2. 429 应该怎么处理？

先判断是瞬时限流、并发过高、预算达到阈值还是额度不足。只在剩余 deadline 允许时有限等待一次，并记录 retry_after_ms 和 attempt。

3. 超时后为什么不能直接重放写操作？

上游或业务系统可能已经处理成功。退款、扣费、发消息、改订单这类操作必须先用 operation_id 查询状态，再决定补偿、人工处理或重放。

4. 小团队怎么选 Claude、GPT、Gemini？

建议先按业务能力和成本分组定义路由名，业务代码只依赖 OpenAI-compatible 契约。Claude、GPT、Gemini 的实际模型选择放在路由层，便于灰度和回滚。

5. ViralAPI 适合哪些客户？

适合有真实调用量、能自助接入、有基础技术能力的小团队、开发者、自动化业务和同行渠道。不适合小白、白嫖、低预算试玩、高售后消耗或滥用客户。

6. 上线前最低限度要保留哪些日志？

至少保留脱敏后的 trace_id、request_id、tenant_id、scenario、model、cost_group、attempt、latency_ms、status_code、error_type 和 business_outcome。

官方资料与联系

• 官网：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