大模型API调用实战：60行Python实现重试、超时与降级策略

1. 为什么“裸调”大模型API是个坏主意

如果你正在开发一个集成了大语言模型（LLM）的应用，比如一个智能客服、一个内容生成工具，或者一个数据分析助手，那么你很可能写过类似下面这样的代码：

import openai

response = openai.ChatCompletion.create(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": "你好，请介绍一下你自己。"}]
)
print(response.choices[0].message.content)

看起来简洁明了，对吧？我把这种直接、不加任何包装的API调用方式，称为“裸调”。在原型验证阶段，这完全没问题。但一旦你的应用需要上线，面对真实用户和复杂的网络环境，“裸调”就会立刻暴露出它的脆弱性。我见过太多项目，在演示时运行流畅，一到生产环境就频频出错、响应缓慢，甚至整个服务挂掉，根源往往就在于对API调用缺乏最基本的健壮性处理。

“裸调”主要面临三大天敌： 网络波动与超时 、 服务端限流与错误 、 成本与体验的平衡 。网络请求可能因为各种原因（如运营商问题、服务器负载）而缓慢或中断；像OpenAI、Claude这样的API服务商都有严格的速率限制（Rate Limit），瞬间的大量请求会被拒绝；更不用说服务端自身也可能出现临时故障。如果你的代码没有应对这些情况的机制，那么一个简单的网络超时就可能导致用户等待数十秒后看到一个白屏，或者一个“429 Too Many Requests”错误就让整个功能瘫痪。

因此，为LLM调用加上“重试、超时、降级”这三重保障，不是“锦上添花”，而是生产级应用的“生存底线”。它意味着你的服务能从短暂的故障中自动恢复，能在资源受限时优雅降级，能给用户一个确定的、哪怕是降级后的响应，而不是一个冰冷的错误提示。接下来，我将用一个约60行的Python装饰器，手把手带你实现这套核心的韧性逻辑。

2. 核心防御策略：重试、超时与降级详解

在动手写代码之前，我们必须先厘清这三个策略各自的目标、实现方式以及它们之间的协作关系。这就像打仗前的兵法部署，理解透了，代码写起来才有的放矢。

2.1 指数退避重试：应对瞬时故障的智慧

重试的逻辑很简单：一次调用失败了，那就再试一次。但无脑的、立即的、无限次的重试是灾难性的，它会对下游服务造成“惊群效应”，加剧其压力，甚至可能让你的IP被拉黑。

指数退避（Exponential Backoff） 是一种经典且优雅的重试策略。它的核心思想是：每次重试之间的等待时间，随着重试次数的增加而呈指数级增长。例如，第一次失败后等1秒，第二次后等2秒，第三次后等4秒，以此类推。同时，通常会结合一个随机抖动（Jitter），即在等待时间上加一个随机值，以避免大量客户端在同一时刻重试，形成同步的“重试风暴”。

为什么选择指数退避？因为它能在“尽快恢复”和“避免加重负担”之间取得平衡。短暂的网络抖动可能在几百毫秒内恢复，所以首次快速重试是合理的。如果连续失败，说明问题可能更持久，延长等待时间既是给服务端喘息的机会，也是为了避免无意义的资源消耗。

2.2 超时控制：给等待设一个硬边界

超时分为连接超时和读取超时。连接超时指建立TCP连接的最大等待时间；读取超时指从连接建立成功到接收到完整响应数据的最大等待时间。对于LLM API，尤其是生成长文本时，读取超时至关重要。

如果不设置超时，一个慢速或无响应的请求可能会永远挂起你的工作线程，耗尽服务器资源，导致应用“假死”。设置一个合理的超时时间（例如10-30秒），并在超时后主动取消请求、抛出异常，是保证系统响应性的关键。超时异常通常会触发我们设计好的重试或降级流程。

2.3 降级方案：保底比完美更重要

当重试耗尽、超时发生，或者API返回了明确的不可用错误（如配额用尽）时，降级方案就是最后的防线。降级的本质是：在主方案不可用时，提供一个功能简化但可用的备选方案，保证核心业务流程不中断。

对于LLM调用，降级可以有很多形式：

1. 返回静态或缓存内容 ：例如，对于常见问题，直接返回预设的回答。
2. 切换到更轻量或免费的模型 ：比如从GPT-4降级到GPT-3.5-Turbo，或者使用开源的本地小模型。
3. 返回友好提示并记录任务 ：告知用户“服务繁忙，您的请求已记录，稍后将处理”，同时将任务放入队列异步执行。
4. 功能阉割 ：如果是一个总结功能，降级为返回原文的前N个字符。

选择哪种降级方案，取决于你的业务场景。核心原则是：降级方案必须稳定、快速、且不会失败。在我们的实现中，降级函数将作为一个可配置的回调参数。

3. 60行Python实现：一个通用的韧性装饰器

理论清晰后，我们开始编码。我们将实现一个名为 @retry_with_timeout_and_fallback 的装饰器。使用装饰器的好处是 非侵入性 ：你无需修改原有的业务函数逻辑，只需在函数定义前加一行 @decorator ，就能为它赋予重试、超时、降级的能力，非常符合Python的优雅哲学。

下面是完整的代码实现，我将逐部分进行解释：

import time
import random
from functools import wraps
from typing import Callable, Any, Optional
import requests

def retry_with_timeout_and_fallback(
    max_retries: int = 3,
    initial_delay: float = 1.0,
    exponential_base: float = 2.0,
    jitter: bool = True,
    timeout: float = 30.0,
    fallback_func: Optional[Callable[[Exception, dict], Any]] = None
):
    """
    一个为LLM API调用（或任何网络请求）添加重试、超时和降级功能的装饰器。

    参数:
        max_retries: 最大重试次数（不包括首次调用）。
        initial_delay: 首次重试前的初始延迟（秒）。
        exponential_base: 延迟指数增长的基数。
        jitter: 是否在延迟时间上增加随机抖动，避免重试风暴。
        timeout: 单个请求的超时时间（秒）。
        fallback_func: 降级函数。接受两个参数：最后捕获的异常和原始调用参数（以字典形式）。
    """
    def decorator(func: Callable):
        @wraps(func)
        def wrapper(*args, **kwargs):
            last_exception = None
            # 记录原始参数，供降级函数使用
            call_args = {"args": args, "kwargs": kwargs}

            for attempt in range(max_retries + 1):  # 尝试次数 = 重试次数 + 1
                try:
                    # 关键点：在这里为被装饰的函数注入超时逻辑
                    # 假设被装饰函数支持`timeout`参数（如requests.get或某些SDK）
                    # 如果原函数不支持，需要更复杂的包装，这里以requests风格为例
                    if 'timeout' in kwargs:
                        # 如果调用者自己传了timeout，尊重其设置
                        pass
                    else:
                        # 否则，使用装饰器设置的超时
                        kwargs['timeout'] = timeout

                    return func(*args, **kwargs)

                except (requests.exceptions.Timeout,
                        requests.exceptions.ConnectionError,
                        requests.exceptions.ReadTimeout) as e:
                    # 捕获超时、连接错误等瞬时网络异常，进行重试
                    last_exception = e
                    print(f"Attempt {attempt + 1} failed with {type(e).__name__}: {e}")

                except Exception as e:
                    # 这里可以更精细地判断哪些异常需要重试（如429状态码）
                    # 以OpenAI API为例，可能遇到openai.error.RateLimitError
                    # 为了通用性，我们简单重试所有非降级触发的异常
                    # 生产环境中应根据具体SDK的错误类型进行判断
                    last_exception = e
                    print(f"Attempt {attempt + 1} failed with {type(e).__name__}: {e}")

                # 检查是否还有重试机会
                if attempt < max_retries:
                    # 计算指数退避延迟
                    delay = initial_delay * (exponential_base ** attempt)
                    if jitter:
                        # 增加最多25%的随机抖动
                        delay = delay * (0.75 + 0.5 * random.random())
                    print(f"Retrying in {delay:.2f} seconds...")
                    time.sleep(delay)
                else:
                    # 重试次数用尽，跳出循环
                    break

            # 所有重试都失败后的处理
            print(f"All {max_retries + 1} attempts failed.")
            if fallback_func is not None:
                print("Attempting fallback...")
                try:
                    return fallback_func(last_exception, call_args)
                except Exception as fb_e:
                    print(f"Fallback function also failed: {fb_e}")
                    # 如果降级函数也失败，抛出原始异常
                    raise last_exception from fb_e
            else:
                # 没有设置降级，直接抛出最后的异常
                raise last_exception
        return wrapper
    return decorator

代码核心逻辑拆解：

1. 装饰器工厂 ： retry_with_timeout_and_fallback 是一个返回装饰器函数的函数。它接收我们之前讨论的所有策略参数（重试次数、延迟、超时等），这样我们可以为不同的函数灵活配置不同的韧性策略。

2. 核心包装器 ：内部的 wrapper 函数是实际包裹原函数 func 的逻辑。它用一个 for 循环控制重试次数（ attempt 从0到 max_retries ，总共尝试 max_retries + 1 次）。

3. 超时注入 ：在 try 块中，我们尝试执行原函数。这里有一个关键实现细节：我们假设被装饰的函数（比如 requests.get 或 openai.ChatCompletion.create ）接受一个 timeout 参数。我们检查调用者是否已经传入了 timeout ，如果没有，就自动注入装饰器设置的 timeout 值。这是一种非常实用的设计，既提供了默认超时，又尊重了调用者的特殊需求。

   注意 ：并非所有SDK都使用 timeout 这个参数名。例如， openai 库的早期版本可能用 request_timeout 。在实际应用中，你可能需要根据你使用的具体客户端库调整这个参数注入的逻辑，或者采用更通用的方式（如使用 signal 模块或 asyncio.wait_for 实现超时）。为了示例清晰，这里采用了最常见的形式。

4. 异常捕获与判断 ： except 块捕获异常。我们首先捕获明确的网络超时和连接错误（ requests.exceptions 中的相关异常），这些是重试的主要目标。然后用一个更通用的 Exception 捕获其他错误。在生产代码中，你应该根据你所用的LLM SDK（如 openai 、 anthropic ）的具体错误类型来细化判断，例如专门捕获 RateLimitError 并进行重试。

5. 指数退避与等待 ：如果捕获到可重试的异常，并且重试次数未用完，则计算等待时间 delay ，加入随机抖动，然后调用 time.sleep(delay) 。打印日志有助于调试。

6. 降级触发 ：当循环结束（所有重试都失败），如果用户提供了降级函数 fallback_func ，则调用它，并将最后的异常和原始参数传递过去。如果降级函数也失败了，则抛出原始异常。如果没有降级函数，直接抛出最后一次的异常。

4. 实战应用：装饰你的LLM调用函数

现在，让我们看看如何将这个装饰器应用到实际的LLM调用中。我将以OpenAI API和简单的模拟请求为例。

4.1 示例一：装饰OpenAI API调用

假设我们有一个调用GPT的函数。首先，确保你安装了openai库： pip install openai 。

import openai
from openai import OpenAI

# 初始化客户端
client = OpenAI(api_key="your-api-key")

# 应用我们的韧性装饰器
@retry_with_timeout_and_fallback(
    max_retries=2,
    initial_delay=1,
    exponential_base=2,
    jitter=True,
    timeout=15.0, # 设置一个合理的超时
    fallback_func=lambda e, args: "抱歉，AI服务暂时不可用，请稍后再试。"
)
def call_gpt_with_retry(prompt: str, model: str = "gpt-3.5-turbo") -> str:
    """
    调用GPT，自带重试、超时和降级。
    """
    response = client.chat.completions.create(
        model=model,
        messages=[{"role": "user", "content": prompt}],
        timeout=15.0  # OpenAI Python SDK支持timeout参数
    )
    return response.choices[0].message.content

# 使用方式完全不变
try:
    answer = call_gpt_with_retry("请用Python写一个快速排序函数。")
    print(answer)
except Exception as e:
    print(f"最终失败: {e}")

关键点说明：

• 装饰器配置了最多重试2次（共3次尝试），初始延迟1秒，超时15秒。
• 降级方案是一个简单的lambda函数，直接返回友好的提示文本。
• 在函数内部，我们调用了 client.chat.completions.create ，并传入了 timeout 参数。这个参数会被OpenAI的底层HTTP客户端使用。
• 调用时，我们像使用普通函数一样使用 call_gpt_with_retry 。所有的韧性逻辑都在背后默默运行。

4.2 示例二：装饰通用的requests请求

也许你的LLM调用是基于更底层的HTTP库，或者你想保护其他外部服务调用。

import requests

# 定义一个模拟的、不稳定的API
def unstable_api():
    import random
    if random.random() < 0.7:  # 70%的概率模拟失败
        raise requests.exceptions.ConnectionError("模拟连接错误")
    return {"status": "success", "data": "Hello from API"}

@retry_with_timeout_and_fallback(
    max_retries=3,
    initial_delay=0.5,
    exponential_base=1.5,
    timeout=5.0,
    fallback_func=lambda e, args: {"status": "fallback", "data": "使用本地缓存数据"}
)
def call_external_api():
    # 这里可以替换成任何requests请求
    # response = requests.get("https://api.example.com/llm", timeout=5)
    # return response.json()
    return unstable_api()

# 多次调用，观察重试和降级行为
for i in range(5):
    print(f"\n--- 调用 {i+1} ---")
    result = call_external_api()
    print(f"结果: {result}")

运行这段代码，你会看到装饰器在频繁的模拟失败下，如何进行重试，并在重试耗尽后返回降级数据。这完美模拟了生产环境中API不稳定的情况。

4.3 参数化降级：更灵活的保底策略

上面的降级函数比较简单。有时我们需要更复杂的降级逻辑，比如根据不同的异常类型或原始请求参数来决定降级行为。

def sophisticated_fallback(last_exception: Exception, call_args: dict) -> str:
    """一个复杂的降级函数示例"""
    original_prompt = call_args['kwargs'].get('prompt', '')
    
    if isinstance(last_exception, requests.exceptions.Timeout):
        # 如果是超时，返回一个提示，并建议简化问题
        return f"请求超时。您的问题‘{original_prompt[:50]}...’可能过于复杂，请尝试简化问题或稍后重试。"
    elif "rate limit" in str(last_exception).lower():
        # 如果是限流，切换到备用方案（这里模拟返回一个固定回答）
        return "当前服务使用人数过多，已为您启用轻量级模式：这是一个关于AI的通用介绍。"
    else:
        # 其他未知错误
        return "系统暂时无法处理您的请求，请稍后再试。"

@retry_with_timeout_and_fallback(
    max_retries=2,
    fallback_func=sophisticated_fallback
)
def call_llm_complex(prompt: str):
    # 这里是真实的LLM调用逻辑
    # ... 
    raise requests.exceptions.Timeout("模拟超时") # 模拟超时异常

result = call_llm_complex(prompt="请详细解释量子计算的原理及其未来影响。")
print(result) # 输出：请求超时。您的问题‘请详细解释量子计算的原理及其未来影响。’可能过于复杂...

通过访问 call_args 字典（其中包含了被装饰函数最初被调用时的 *args 和 **kwargs ），降级函数可以获取到原始请求的上下文，从而做出更精准的降级决策。

5. 高级考量与生产环境建议

这个60行的装饰器提供了一个强大的基础，但在将其用于关键生产环境前，还有一些重要的方面需要考虑和增强。

5.1 错误分类：哪些该重试，哪些不该？

不是所有异常都值得重试。盲目重试某些错误是浪费资源甚至危险的。

• 必须重试的 ：连接超时、连接断开、网关错误（502/503/504）、以及API返回的明确要求重试的错误（如 429 Too Many Requests ，但需注意延迟）。
• 不应重试的 ：客户端错误（如 400 Bad Request ，参数错误重试也没用）、认证错误（ 401 Unauthorized ，密钥错了）、权限错误（ 403 Forbidden ）、资源不存在（ 404 Not Found ）以及 422 等业务逻辑错误。重试这些错误没有意义。
• 需要谨慎重试的 ：服务器内部错误（ 500 Internal Server Error ）。有时是瞬时的，有时是持久的，需要结合其他信息判断。

在我们的装饰器中，你需要根据所用SDK的具体异常类来细化 except 块。例如，对于OpenAI：

import openai

try:
    # ... API调用
except openai.RateLimitError:
    # 速率限制，应重试
    last_exception = e
    is_retriable = True
except openai.APITimeoutError:
    # API超时，应重试
    last_exception = e
    is_retriable = True
except openai.APIError as e:
    # 其他API错误，检查状态码
    if e.status_code >= 500:
        # 5xx服务器错误，可重试
        is_retriable = True
    else:
        # 4xx客户端错误，不应重试
        is_retriable = False
    last_exception = e
except (requests.exceptions.ConnectionError, requests.exceptions.Timeout) as e:
    # 底层网络错误，应重试
    last_exception = e
    is_retriable = True

5.2 结合Circuit Breaker（熔断器）

在微服务架构中， 熔断器模式 是重试机制的黄金搭档。它的原理类似于电路保险丝：当某个服务的失败率超过一定阈值时，熔断器“跳闸”，在接下来的一段时间内，所有对该服务的请求会立即失败（快速失败），而不再真正发起调用。经过一个冷却期后，熔断器会进入“半开”状态，尝试放行少量请求，如果成功则关闭熔断器，恢复服务；如果仍然失败，则继续保持打开状态。

为什么需要它？如果一个下游服务已经彻底宕机，持续的重试只会浪费资源并增加系统负载。熔断器通过快速失败，保护了调用方系统的稳定性。你可以使用 pybreaker 这样的库来实现熔断器，并将我们的重试装饰器与熔断器结合使用：先经过熔断器判断，如果电路是闭合的，再进入重试逻辑。

5.3 分布式环境下的重试

在拥有多个应用实例的分布式系统中，简单的本地重试可能不够。例如，速率限制（Rate Limit）通常是针对API Key或IP的。如果多个实例同时重试，它们会共享同一个速率限制配额，可能导致更快的触发限流。

在这种情况下，需要考虑：

• 集中式协调 ：使用Redis等分布式锁或计数器，在集群层面协调重试间隔，避免多个客户端同时重试。
• 客户端退避 ：确保每个客户端使用足够的随机抖动（Jitter），这能在一定程度上缓解同步问题。
• 服务端返回 ：关注API响应头，如 Retry-After ，它明确告诉客户端应该等待多久再重试，这是最权威的指导。

5.4 监控与日志

生产系统中，必须对重试和降级行为进行监控和记录。

• 记录指标 ：重试次数、失败原因（超时、429等）、降级触发次数、请求总延迟（P50， P95， P99）。这些指标能帮助你评估API的稳定性和装饰器的效果。
• 结构化日志 ：不要只使用 print 。使用像 structlog 或 logging 模块，记录结构化的日志，包含请求ID、重试尝试次数、延迟时间、异常类型等字段，便于后续排查问题。
• 告警 ：当降级触发频率超过某个阈值（例如，过去5分钟内超过10%的请求触发了降级），应该触发告警，提示工程师关注下游服务的健康状况。

将我们的装饰器升级为生产版本，可能需要集成这些监控能力，例如在重试循环中递增一个计数器，在触发降级时发送一个日志事件。

6. 避坑指南：我踩过的那些“坑”

在实际部署这套机制的过程中，我遇到了一些预料之外的问题，这里分享出来，希望能帮你绕开。

坑1：超时参数传递的“隐形”冲突 最初，我像示例中那样，在装饰器里向 kwargs 注入 timeout 。但后来发现，被装饰的函数内部可能又调用了另一个也支持 timeout 的函数。如果内部函数期望 timeout 是另一个含义（例如，单位是毫秒而不是秒），就会产生混淆。更稳妥的做法是， 不直接修改 kwargs ，而是通过上下文管理器或信号（signal）来实现超时控制 ，或者确保你的装饰器只用于你明确知道其参数约定的函数。对于 requests 和 openai 这种明确使用秒级 timeout 的库，直接注入是安全的。

坑2：降级函数本身的故障 降级是你的最后一道防线，它自己绝不能垮。我曾写过一个降级函数，它试图从另一个备用API获取数据，结果那个备用API也挂了，导致整个流程抛出两个异常的链式错误，让问题排查变得复杂。因此， 降级函数必须尽可能简单、稳定、无外部依赖 。最好是返回静态内容、本地缓存或极其简单的计算。如果降级函数可能失败，一定要像示例代码那样用 try...except 包住，并在失败时抛出清晰的异常。

坑3：无限重试循环 在早期版本，我错误地将一个永久性错误（如无效的API密钥）也加入了重试列表，导致程序陷入无限重试循环，直到达到最大重试次数上限，浪费了大量时间和资源。这强调了 精细化的错误分类 的重要性。一定要区分瞬时故障和永久故障。

坑4：忽略“副作用” 如果你的被装饰函数有副作用（例如，扣减余额、发送消息），重试可能导致副作用被重复执行。这是一个经典问题。对于这类 非幂等 的操作，重试必须非常小心。可能的解决方案包括：

1. 在业务层实现幂等性（例如，通过唯一的请求ID来确保同一操作只执行一次）。
2. 将重试逻辑放在副作用发生之前的纯查询/计算阶段。
3. 明确识别这类函数，不对它们使用自动重试装饰器。

LLM的Completion调用通常是幂等的（相同输入产生相同输出），但如果你在调用前后有数据库写入等操作，就需要仔细设计流程了。

为LLM调用添加韧性，是从“玩具代码”走向“生产代码”的标志性一步。这个60行的装饰器是一个起点，你可以根据项目的复杂度和要求，对其进行扩展和强化。核心思想始终不变： 让你的应用在面对外部服务的不确定性时，依然能保持稳定和可靠。 下次在调用 client.chat.completions.create 之前，不妨花几分钟给它套上这层“铠甲”，你会发现，夜晚的告警电话会少很多。