LLM API 上线演练与回滚清单：如何排查 401、429、超时和 fallback 失效

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

上线前最容易遗漏的不是“请求能不能成功”，而是失败时能否快速判断：这是认证问题、限流问题、跨区网络问题、模型降级问题，还是业务输出不合格。本文把一次上线演练拆成可执行的检查项，适合 AI 客服、内容生成、数据分析、内部工具、批量自动化和 SaaS 功能接入。

1. 先定义演练边界

演练至少要准备四类请求：

正常请求：验证 endpoint、模型名、鉴权和最小输出。
可重试请求：模拟 429、408、502 或读取超时，确认有限重试不会形成重试风暴。
可降级请求：让主模型失败，确认 GPT、Claude 或 Gemini 的 fallback 顺序和输出校验仍然生效。
不可重试请求：模拟 401、400、输出 schema 错误或带外部副作用的操作，确认系统直接告警而不是重复提交。

每次演练都保存 request_id、tenant_id、scenario、model、cost_group、attempt、fallback_index、status、latency_ms 和 rollback_version。没有这些证据，事后很难区分模型故障和应用重试造成的放大流量。

2. Python：有限重试、fallback 和回滚标记

下面的示例使用 OpenAI-compatible SDK，适合放在业务服务的 provider 层。它只对幂等的文本生成任务重试；扣费、发信、写入客户可见数据等副作用必须拆成“生成”和“提交”两步。

import json
import logging
import os
import time
import uuid
from openai import OpenAI

LOG = logging.getLogger("viralapi.launch_drill")
RETRYABLE = {408, 409, 425, 429, 500, 502, 503, 504}
ROUTES = [
    ("claude-sonnet-4", "stable_official"),
    ("gpt-4o-mini", "official_transfer"),
]


def complete(messages, *, tenant_id, scenario, idempotent=True):
    request_id = str(uuid.uuid4())
    client = OpenAI(
        api_key=os.environ["VIRALAPI_API_KEY"],
        base_url=os.getenv("VIRALAPI_BASE_URL", "https://viralapi.ai/v1"),
        timeout=12.0,
        max_retries=0,
    )
    max_attempts = 2 if idempotent else 1

    for fallback_index, (model, cost_group) in enumerate(ROUTES):
        for attempt in range(1, max_attempts + 1):
            started = time.monotonic()
            try:
                result = client.chat.completions.create(
                    model=model, messages=messages, temperature=0.2
                )
                LOG.info(json.dumps({
                    "event": "llm_call_ok", "request_id": request_id,
                    "tenant_id": tenant_id, "scenario": scenario,
                    "model": model, "cost_group": cost_group,
                    "fallback_index": fallback_index, "attempt": attempt,
                    "latency_ms": round((time.monotonic() - started) * 1000),
                    "rollback_version": os.getenv("RELEASE_VERSION", "unknown"),
                }))
                return result.choices[0].message.content or ""
            except Exception as exc:
                status = getattr(exc, "status_code", None)
                LOG.warning(json.dumps({
                    "event": "llm_call_error", "request_id": request_id,
                    "tenant_id": tenant_id, "scenario": scenario,
                    "model": model, "cost_group": cost_group,
                    "fallback_index": fallback_index, "attempt": attempt,
                    "status": status, "error_type": type(exc).__name__,
                }))
                if status not in RETRYABLE or attempt == max_attempts:
                    break
                time.sleep(0.5 * (2 ** (attempt - 1)))

    raise RuntimeError(f"all_routes_failed request_id={request_id}")

这里有三个上线保护点：SDK 自己的自动重试被关闭，避免和业务层重复；非幂等任务最多尝试一次；每次 fallback 都留下模型、分组和版本信息。真实部署时还应加总 deadline，例如客服请求 20 秒内结束，超过 deadline 就返回明确的降级提示或转人工。

3. 错误分类与回滚条件

401 / 403：停止重试

检查服务端环境变量、endpoint、模型名、账号权限和密钥注入方式。认证错误通常不是瞬时故障，继续 fallback 只会制造更多无效请求。若新版本刚上线，记录发布版本并回滚到上一版本配置。

429：先限流，再决定是否降级

按 tenant_id、场景和成本分组统计请求速率。优先检查是否存在客户端重试风暴、队列堆积或单租户占满配额。批量内容生成可以排队，客户可见的 AI 客服请求可以切换已通过回归测试的备用路由，但必须有总 deadline。

5xx / 网络超时：只对幂等任务有限重试

区分连接超时、读取超时和上游 5xx。一次指数退避重试失败后再进入 fallback，重试次数通常不应超过 2 次。每个候选路由都要有独立 timeout，不能让两个路由叠加后突破业务 SLA。

HTTP 200 但输出不合格：按业务失败处理

对 JSON schema、工具调用参数、必填字段、敏感信息和业务规则做校验。fallback 成功不代表可以直接写入生产系统。输出校验失败时记录 validation_error，并根据业务选择重试、人工复核或回滚。

满足以下任一条件就回滚

认证配置错误导致大面积 401/403。
客户可见链路的 p95 延迟连续超过约定 SLA。
fallback 成功率下降且输出校验失败率上升。
429 主要由新版本的重试策略或并发配置造成。
成本分组路由错误，导致高价值请求大量进入不匹配的低稳定性分组。

回滚不是删除日志或重放全部请求。应保留发布版本、配置版本、受影响租户、失败 request ID 和最后一次成功路由，必要时对幂等任务做有界重放。

4. ViralAPI 分组如何用于演练

ViralAPI 的价格口径是：福利分组约官方 1.5 折，官转分组约官方 6 折，稳定官方分组约官方 8 折。选择应基于预算、稳定性和业务场景，而不是只追求低价：

福利分组：适合可重跑的草稿、批量标题和内部整理，演练时要验证排队与人工复核。
官转分组：适合日常数据分析、内部工具和常规自动化，演练重点是限流、超时和成本上限。
稳定官方分组：适合客户可见的 AI 客服、付费 SaaS 功能和关键交付，演练重点是 SLA、fallback 和回滚。

5. 适合 / 不适合人群

适合有真实调用量、能自助接入、有基础技术能力的小团队、开发者、同行渠道和自动化业务团队；尤其适合愿意维护错误分类、日志、限流和上线演练的客户。

不适合小白、白嫖、低预算试玩、高售后消耗或滥用客户，也不适合希望接入后完全不维护环境变量、告警和业务输出校验的人群。

6. FAQ

Q1：401 发生时要不要切换到另一个模型？

通常不要。先检查密钥、endpoint、模型名和权限。只有确认是单一上游路由故障，而不是网关鉴权配置错误时，才考虑 fallback。

Q2：429 和超时都应该重试两次吗？

不一定。只对幂等任务做有限重试，并结合总 deadline、租户限流和队列长度。带外部副作用的操作不应自动重放。

Q3：为什么需要记录 rollback_version？

因为相同的错误码可能来自不同版本的代码、配置或路由策略。版本字段能把故障时间线和回滚结果关联起来。

Q4：福利分组能不能用于 AI 客服？

如果是客户可见且影响 SLA 的客服链路，不应只按价格选择。福利分组更适合可重跑、可人工复核的后台任务；客服通常优先评估稳定官方分组。

Q5：小团队上线前最少要做什么？

至少做一次正常请求、一次 429/超时演练、一次主路由失败后的 fallback 演练，并确认日志能按 request ID 找到完整链路。没有这些证据，不建议直接接入关键客户流量。

7. 资源与联系

官网：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
价格分组：福利分组官方 1.5 折；官转分组官方 6 折；稳定官方分组官方 8 折。请按预算、稳定性和业务场景选择。
邮箱：miutayoung@gmail.com
Telegram：viral_8866
WeChat：viral_8866