构建LLM API调用韧性：重试策略、熔断与故障转移实战

1. 项目概述：为什么我们需要一个聪明的重试策略？

如果你正在调用各种大语言模型（LLM）的API，无论是OpenAI、Claude、DeepSeek还是智谱，那么“请求失败”这个场景你一定不陌生。屏幕上弹出来的错误信息五花八门： 429 Too Many Requests 、 503 Service Unavailable 、 402 Insufficient Balance ，甚至是让人摸不着头脑的 529 Overloaded 。对于依赖这些API进行应用开发、自动化流程或者研究的我们来说，一次简单的网络抖动或者服务端临时过载，就可能导致整个流程中断，用户体验直线下降，甚至丢失关键数据。

free-llm-api-resources 这个项目名字本身就点明了两个核心痛点： 免费 和 资源 。免费或低成本的API资源往往伴随着更严格的使用限制（如速率限制）和相对不稳定的服务。直接调用这些API而不做任何容错处理，无异于在钢丝上跳舞。一个健壮的重试策略，就是你的安全网。它不仅仅是“失败了就再试一次”这么简单，而是一套结合了错误识别、等待策略、后备方案和监控告警的完整机制。它的目标是最大化请求的成功率，同时在遇到不可恢复的错误时，能够优雅地降级或快速失败，避免陷入无意义的死循环。

简单来说，这个项目的核心价值在于： 用代码的“韧性”来弥补服务“稳定性”的不足 。尤其是在多API源、混合免费与付费资源的场景下，一个精心设计的重试策略能让你用更低的成本，获得接近商业级API的可靠性体验。接下来，我将拆解如何从零构建这样一个策略，并分享我在实际项目中踩过的坑和总结的经验。

2. 重试策略的核心设计哲学

设计重试策略，首先要抛弃“蛮力重试”的思维。无脑、固定间隔的无限重试，不仅效率低下，还可能因为持续轰炸而触发服务端的更严厉限制，甚至被拉黑。一个优秀的重试策略，应该遵循以下几个核心原则：

2.1 理解错误类型：哪些该重试，哪些不该？

这是所有策略的基石。我们必须对API返回的错误进行精细分类。

1. 可重试错误（Transient Errors） 这类错误通常是暂时的，重试后很可能成功。

• 429 Too Many Requests (Rate Limit) ：速率限制。这是最常见的可重试错误，意味着你在单位时间内请求太频繁。
• 503 Service Unavailable / 529 Overloaded ：服务端过载或临时不可用。这通常是服务提供方的问题，等待一会儿可能恢复。
• 500 Internal Server Error ：服务器内部错误。有时是偶发的。
• 网络层错误 ：如超时（Timeout）、连接被拒绝（ConnectionRefused）、连接重置（ConnectionReset）。这些通常与网络环境有关。

2. 不可重试错误（Client Errors） 这类错误是客户端的请求本身有问题，重试多少次都没用，必须修改请求。

• 400 Bad Request ：请求参数错误、格式不对。例如， 400 this model‘s maximum context length is ... 提示你的输入超出了模型上下文长度限制。
• 401 Unauthorized ：API密钥无效或过期。
• 402 Insufficient Balance ：账户余额不足。重试不会变出钱来。
• 404 Not Found ：请求的端点或资源不存在。
• 413 Payload Too Large ：请求体过大。

3. 内容相关错误（Content Errors） 这类错误比较特殊，发生在服务端已响应，但返回内容不符合预期时。

• 输出长度超限 ：如 Claude‘s response exceeded the 32000 output token maximum 。这需要你调整请求参数（如减少 max_tokens ），然后重试。
• 内容过滤/安全策略拒绝 ：请求或生成的内容触发了服务商的安全策略。可能需要修改提示词（Prompt）。

设计策略时，必须针对第一类错误进行重试，对第二类错误立即失败并记录日志，对第三类错误则需要有条件的、带参数调整的重试逻辑。

2.2 退避算法：如何等待？

确定了要重试，下一个问题就是：等多久再试？立即重试（No Backoff）会给压力巨大的服务器雪上加霜。常用的退避算法有：

• 固定间隔退避 ：每次等待固定的时间（如2秒）。简单，但不够智能。
• 指数退避 ：等待时间随重试次数指数级增加。例如，第一次等1秒，第二次等2秒，第三次等4秒……这是最常用、最有效的策略，能有效避免请求“风暴”。
• 随机退避 ：在固定或指数退避的基础上，增加一个随机抖动（Jitter）。例如，在指数退避计算的等待时间上，加上一个±50%的随机值。这能防止在分布式环境下，多个客户端在完全相同的时刻重试，形成“重试共振”。

在 free-llm-api-resources 场景下， 带抖动的指数退避 通常是首选。它能很好地应对服务端的瞬时压力，并为不同客户端提供错峰重试的机会。

2.3 熔断与降级：何时放弃？

重试不是无限的。我们需要设置安全边界：

• 最大重试次数 ：例如3-5次。超过这个次数，就认为当前问题可能不是暂时的，应停止重试。
• 超时时间 ：包括单次请求的超时和整个重试过程的总超时。
• 熔断器模式 ：如果某个API在短时间内失败率过高（如10次请求失败8次），则暂时“熔断”对该API的请求，直接快速失败。经过一个冷却期后，再尝试放行少量请求进行探测，如果成功则关闭熔断。这能防止持续调用一个已经宕机的服务。
• 服务降级 ：当主API（如免费的A）因熔断或持续失败不可用时，自动切换到备用的API（如免费的B，或一个低配的付费API C）。这就是 free-llm-api-resources 项目发挥威力的地方——维护一个可用的资源池。

3. 实现方法：从理论到代码

我们将使用 Python 语言，结合 tenacity 和 httpx 库，来实现一个功能完整的重试策略。 tenacity 是一个强大的重试库，而 httpx 是现代、异步友好的 HTTP 客户端。

3.1 基础环境与依赖准备

首先，确保你的环境已安装必要的库。

pip install tenacity httpx

如果项目涉及多个API供应商，你可能还需要安装他们的官方SDK或继续使用 httpx 直接调用其REST接口。

3.2 构建核心重试装饰器

我们将创建一个灵活的重试装饰器，它可以根据不同的错误类型应用不同的策略。

import httpx
from tenacity import (
    retry,
    stop_after_attempt,
    wait_exponential,
    wait_random,
    retry_if_exception_type,
    before_sleep_log,
    after_log,
    before_log
)
import logging
from typing import Type, Tuple, Callable, Optional

# 设置日志
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

def create_llm_retry_decorator(
    max_retries: int = 3,
    base_delay: float = 1.0, # 指数退避的基准等待时间（秒）
    max_delay: float = 60.0, # 最大等待时间（秒）
    retry_on_status: Tuple[int, ...] = (429, 500, 502, 503, 504, 529), # 针对哪些HTTP状态码重试
    retry_on_exceptions: Tuple[Type[Exception], ...] = (
        httpx.TimeoutException,
        httpx.NetworkError,
        httpx.ConnectError,
        httpx.ReadError,
    ) # 针对哪些网络异常重试
):
    """
    创建一个适用于LLM API调用的重试装饰器工厂函数。
    """
    # 定义等待策略：指数退避 + 随机抖动
    wait_strategy = wait_exponential(
        multiplier=base_delay,
        max=max_delay
    ) + wait_random(0, 0.2 * base_delay) # 增加最多20%基准时间的随机抖动

    # 定义停止策略：达到最大重试次数后停止
    stop_strategy = stop_after_attempt(max_retries)

    # 定义重试条件：满足HTTP状态码异常或网络异常
    def retry_condition(exception):
        # 1. 检查是否是 httpx.HTTPStatusError (包含状态码)
        if isinstance(exception, httpx.HTTPStatusError):
            return exception.response.status_code in retry_on_status
        # 2. 检查是否是其他指定的网络异常
        return isinstance(exception, retry_on_exceptions)

    # 构建并返回装饰器
    def decorator(func: Callable):
        return retry(
            stop=stop_strategy,
            wait=wait_strategy,
            retry=retry_if_exception_type(retry_condition),
            before_sleep=before_sleep_log(logger, logging.WARNING), # 重试前记录日志
            after=after_log(logger, logging.INFO), # 重试成功后记录日志
            reraise=True, # 重试耗尽后，抛出原始异常
        )(func)
    return decorator

# 使用示例：创建一个默认的重试装饰器
llm_retry = create_llm_retry_decorator()

关键点解析：

1. retry_on_status ：我们默认对 429 （限速）、 5xx 系列服务器错误以及特殊的 529 （过载）进行重试。 特别注意，我们没有包含 400 或 401 ，因为它们是客户端错误，重试无意义。
2. wait_strategy ： wait_exponential 实现指数退避， + wait_random 为其增加了随机抖动，这是避免重试共振的标准做法。
3. retry_condition 函数 ：这是核心逻辑。它首先判断异常是否是 HTTPStatusError （即服务器返回了错误状态码），并检查状态码是否在可重试列表中。如果不是，再检查是否是网络层异常（如超时）。
4. 日志记录 ： before_sleep_log 和 after_log 帮助我们在重试等待前和重试成功后记录信息，便于监控和调试。

3.3 集成API调用与错误处理

现在，我们将重试装饰器应用到具体的API调用函数上，并处理更复杂的错误，如上下文长度超限和余额不足。

import json
from tenacity import RetryError

class LLMAPIError(Exception):
    """自定义LLM API异常基类"""
    pass

class ContentLengthError(LLMAPIError):
    """上下文长度或输出长度超限"""
    pass

class InsufficientBalanceError(LLMAPIError):
    """账户余额不足"""
    pass

class LLMClient:
    def __init__(self, api_key: str, base_url: str = “https://api.example-llm.com/v1”):
        self.api_key = api_key
        self.base_url = base_url
        self.client = httpx.AsyncClient(timeout=30.0) # 设置单次请求超时
        # 使用我们创建的重试装饰器
        self.call_api_with_retry = llm_retry(self._raw_call_api)

    async def _raw_call_api(self, messages: list, model: str, **kwargs):
        """原始的、不带高级错误处理的API调用"""
        url = f“{self.base_url}/chat/completions”
        headers = {
            “Authorization”: f“Bearer {self.api_key}”,
            “Content-Type”: “application/json”
        }
        data = {
            “model”: model,
            “messages”: messages,
            **kwargs
        }
        response = await self.client.post(url, headers=headers, json=data)
        response.raise_for_status() # 如果状态码不是2xx，抛出HTTPStatusError
        return response.json()

    async def chat_completion(self, messages: list, model: str = “gpt-3.5-turbo”, **kwargs):
        """
        增强的聊天补全方法，集成了重试和特定错误处理。
        """
        try:
            result = await self.call_api_with_retry(messages, model, **kwargs)
            return result
        except httpx.HTTPStatusError as e:
            # 处理特定的、不可重试的客户端错误
            error_detail = e.response.text
            if e.response.status_code == 400:
                # 尝试解析错误信息
                try:
                    error_data = json.loads(error_detail)
                    error_msg = error_data.get(‘error’, {}).get(‘message’, ‘’).lower()
                    if ‘maximum context length’ in error_msg or ‘max_tokens’ in error_msg:
                        # 触发内容长度错误，这可能需要调整参数后重试，但这里我们选择抛出特定异常让上层处理
                        raise ContentLengthError(f“上下文或输出长度超限: {error_msg}”) from e
                except json.JSONDecodeError:
                    pass
                # 其他400错误，直接包装抛出
                raise LLMAPIError(f“请求参数错误: {error_detail}”) from e
            elif e.response.status_code == 402:
                raise InsufficientBalanceError(“账户余额不足，请充值”) from e
            elif e.response.status_code == 401:
                raise LLMAPIError(“API密钥无效或过期”) from e
            # 对于已在重试策略中处理的状态码（如429, 503），如果还能执行到这里，说明重试已耗尽，直接抛出
            raise LLMAPIError(f“API请求失败，状态码: {e.response.status_code}, 详情: {error_detail}”) from e
        except RetryError as e:
            # 重试耗尽后，tenacity会抛出RetryError，其内部包裹了最后一次的异常
            last_attempt = e.last_attempt
            raise LLMAPIError(f“经过{last_attempt.attempt_number}次重试后仍然失败。最后异常: {last_attempt.exception()}”) from e
        except Exception as e:
            # 捕获其他未预见的异常
            raise LLMAPIError(f“未知错误: {str(e)}”) from e

    async def close(self):
        await self.client.aclose()

实操心得：

1. 错误信息解析 ：不同LLM提供商（OpenAI, Anthropic, DeepSeek等）的400错误信息格式可能不同。上述代码仅是一个示例。在实际项目中，你需要根据你调用的具体API文档来解析错误响应体，准确判断是上下文超长、参数错误还是其他问题。
2. 异常封装 ：自定义异常类（如 ContentLengthError ）非常有用。它允许调用方根据异常类型采取不同的恢复策略。例如，遇到 ContentLengthError ，上层逻辑可以尝试截断输入消息或减少 max_tokens 后重新调用。
3. RetryError 处理 ：当 tenacity 的重试次数用尽后，它会抛出一个 RetryError 。我们需要从中提取最后一次尝试的信息，并抛出一个更友好的业务异常，而不是让 RetryError 直接暴露给上层。

4. 构建多资源池与故障转移策略

对于 free-llm-api-resources ，单一API端点是不够的。我们需要一个资源池，并在主资源失败时，自动切换到备用资源。

4.1 定义资源与健康检查

首先，我们定义一个资源类，并为其添加简单的健康检查逻辑。

import asyncio
from dataclasses import dataclass
from enum import Enum
import time

class ResourceStatus(Enum):
    HEALTHY = “healthy”
    UNHEALTHY = “unhealthy”
    UNKNOWN = “unknown”

@dataclass
class APIResource:
    name: str
    api_key: str
    base_url: str
    priority: int = 1 # 优先级，数字越小优先级越高
    weight: int = 10 # 权重，可用于加权随机选择
    status: ResourceStatus = ResourceStatus.UNKNOWN
    last_checked: float = 0.0
    consecutive_failures: int = 0
    failure_threshold: int = 5 # 连续失败多少次标记为不健康
    health_check_interval: int = 30 # 健康检查间隔（秒）

    async def health_check(self, client: httpx.AsyncClient) -> bool:
        """执行一个简单的健康检查（例如，调用一个轻量级端点）"""
        # 避免过于频繁的检查
        if time.time() - self.last_checked < self.health_check_interval:
            return self.status == ResourceStatus.HEALTHY

        self.last_checked = time.time()
        check_url = f“{self.base_url}/health” # 假设有健康检查端点
        # 或者用一个极简的对话请求来检查
        # check_url = f“{self.base_url}/chat/completions”
        # check_data = {“model”: “gpt-3.5-turbo”, “messages”: [{“role”: “user”, “content”: “ping”}], “max_tokens”: 1}

        try:
            # 使用一个很短的超时时间
            resp = await client.get(check_url, timeout=5.0)
            if resp.status_code < 500: # 认为5xx是服务端问题，4xx可能是配置问题但端点可达
                self.status = ResourceStatus.HEALTHY
                self.consecutive_failures = 0
                return True
            else:
                self.consecutive_failures += 1
        except Exception:
            self.consecutive_failures += 1

        # 判断是否超过失败阈值
        if self.consecutive_failures >= self.failure_threshold:
            self.status = ResourceStatus.UNHEALTHY
        else:
            self.status = ResourceStatus.UNKNOWN
        return False

4.2 实现带熔断和负载均衡的资源管理器

现在，我们创建一个管理器来维护资源池，并提供获取“最佳”资源的策略。

class ResourceManager:
    def __init__(self):
        self.resources: list[APIResource] = []
        self._client = httpx.AsyncClient()
        self._lock = asyncio.Lock()

    def add_resource(self, resource: APIResource):
        self.resources.append(resource)

    async def get_healthy_resource(self, strategy: str = “priority”) -> Optional[APIResource]:
        """
        根据策略获取一个健康的资源。
        策略: ‘priority‘ (按优先级), ‘random‘ (随机), ‘round_robin‘ (轮询)
        """
        async with self._lock:
            healthy_resources = []
            # 快速筛选状态为HEALTHY的资源，对UNKNOWN的进行即时检查
            for resource in self.resources:
                if resource.status == ResourceStatus.HEALTHY:
                    healthy_resources.append(resource)
                elif resource.status == ResourceStatus.UNKNOWN:
                    # 异步执行健康检查，但不等待所有结果，避免阻塞
                    # 这里简化处理：直接检查，因为资源数通常不多
                    is_healthy = await resource.health_check(self._client)
                    if is_healthy:
                        healthy_resources.append(resource)

            if not healthy_resources:
                # 没有健康资源，尝试强制检查所有不健康的资源（可能已恢复）
                for resource in self.resources:
                    if resource.status != ResourceStatus.HEALTHY:
                        if await resource.health_check(self._client):
                            healthy_resources.append(resource)
                if not healthy_resources:
                    return None

            # 根据策略选择资源
            if strategy == “priority”:
                healthy_resources.sort(key=lambda x: x.priority)
                return healthy_resources[0]
            elif strategy == “random”:
                # 简单随机选择，可扩展为加权随机
                import random
                return random.choice(healthy_resources)
            elif strategy == “round_robin”:
                # 简单的轮询，需要记录上次选择的位置
                if not hasattr(self, ‘_rr_index’):
                    self._rr_index = 0
                selected = healthy_resources[self._rr_index % len(healthy_resources)]
                self._rr_index += 1
                return selected
            else:
                return healthy_resources[0]

    async def report_failure(self, resource: APIResource):
        """报告一次资源调用失败，用于快速熔断"""
        async with self._lock:
            resource.consecutive_failures += 1
            if resource.consecutive_failures >= resource.failure_threshold:
                resource.status = ResourceStatus.UNHEALTHY
                logger.warning(f“Resource {resource.name} marked as UNHEALTHY due to consecutive failures.”)

    async def report_success(self, resource: APIResource):
        """报告一次资源调用成功，用于恢复信用"""
        async with self._lock:
            if resource.status == ResourceStatus.UNHEALTHY:
                # 不健康资源成功一次，可以尝试恢复为UNKNOWN，等待下次健康检查确认
                resource.status = ResourceStatus.UNKNOWN
            resource.consecutive_failures = 0

    async def close(self):
        await self._client.aclose()

4.3 集成重试与故障转移的高阶客户端

最后，我们将所有组件组合起来，创建一个终极客户端。这个客户端会先尝试用主资源（带重试），如果彻底失败，则自动切换到资源池中的下一个健康资源。

class ResilientLLMClient:
    def __init__(self, resource_manager: ResourceManager):
        self.rm = resource_manager
        # 为每个资源创建其专用的、带重试的客户端（可选，这里简化处理）
        # 实际中可以复用LLMClient，但每个LLMClient绑定一个APIResource

    async def chat_completion_with_fallback(self, messages: list, **kwargs):
        """
        带故障转移的聊天补全。
        1. 获取当前最佳资源。
        2. 使用该资源进行带重试的调用。
        3. 如果彻底失败（重试耗尽且是网络/可重试错误），标记该资源失败，并获取下一个资源重试。
        4. 对客户端错误（如400, 402）不进行故障转移，直接抛出。
        """
        last_exception = None
        attempted_resources = set()

        while True:
            resource = await self.rm.get_healthy_resource(strategy=“priority”)
            if not resource:
                raise LLMAPIError(“没有可用的健康API资源”) from last_exception
            if resource.name in attempted_resources:
                # 防止在少数资源间循环
                raise LLMAPIError(“所有尝试过的资源均失败”) from last_exception

            attempted_resources.add(resource.name)
            logger.info(f“尝试使用资源: {resource.name}”)

            # 为当前资源创建临时客户端（实际项目可缓存）
            client = LLMClient(api_key=resource.api_key, base_url=resource.base_url)
            try:
                result = await client.chat_completion(messages, **kwargs)
                # 成功，报告并返回结果
                await self.rm.report_success(resource)
                await client.close()
                return result
            except (httpx.TimeoutException, httpx.NetworkError, httpx.HTTPStatusError) as e:
                # 这些是可能通过重试或切换资源解决的错误
                await self.rm.report_failure(resource)
                last_exception = e
                logger.warning(f“资源 {resource.name} 调用失败: {e}，尝试下一个资源。”)
                await client.close()
                continue # 继续循环，尝试下一个资源
            except (InsufficientBalanceError, ContentLengthError, LLMAPIError) as e:
                # 客户端错误，故障转移通常无效（除非是负载均衡下的不同实例）
                # 例如，余额不足，换一个同供应商的key可能有用，但这里我们简单处理为失败
                await self.rm.report_failure(resource) # 这个key可能暂时不可用
                await client.close()
                raise e # 直接抛出，让业务层决定是否换Key重试
            except Exception as e:
                await client.close()
                raise e

# 使用示例
async def main():
    # 1. 初始化资源管理器并添加资源
    rm = ResourceManager()
    rm.add_resource(APIResource(name=“free_source_1”, api_key=“key1”, base_url=“https://api.source1.com/v1”, priority=1))
    rm.add_resource(APIResource(name=“free_source_2”, api_key=“key2”, base_url=“https://api.source2.com/v1”, priority=2))
    # 可以添加一个付费源作为兜底
    rm.add_resource(APIResource(name=“paid_backup”, api_key=“paid_key”, base_url=“https://api.openai.com/v1”, priority=3))

    # 2. 创建韧性客户端
    resilient_client = ResilientLLMClient(rm)

    try:
        messages = [{“role”: “user”, “content”: “你好，请介绍一下你自己。”}]
        response = await resilient_client.chat_completion_with_fallback(messages, model=“gpt-3.5-turbo”)
        print(response[‘choices’][0][‘message’][‘content’])
    except LLMAPIError as e:
        print(f“所有尝试均失败: {e}”)
    finally:
        await rm.close()

# asyncio.run(main())

注意事项：

1. 成本与礼貌 ：频繁切换并重试免费资源可能对服务提供方造成压力。务必遵守其服务条款，合理设置重试次数和退避时间。对于付费资源，故障转移是保障服务高可用的有效手段。
2. 上下文一致性 ：在故障转移时，如果对话有状态（多轮对话），需要确保新的API端点支持相同的上下文或能处理你的消息历史。有些免费API可能有功能限制。
3. 资源池更新 ：资源池应该是可动态更新的，允许在运行时添加或移除资源（如检测到某个免费Key失效）。

5. 高级话题与优化方向

实现基础的重试和故障转移后，还可以从以下几个方向进行优化，构建更鲁棒的系统。

5.1 针对特定错误的适应性重试

对于 ContentLengthError （上下文超长），我们可以实现一个更智能的重试策略，自动调整参数。

from tenacity import retry, stop_after_attempt, wait_fixed, retry_if_exception, before_sleep_log
import logging

logger = logging.getLogger(__name__)

def is_content_length_error(exception):
    return isinstance(exception, ContentLengthError)

@retry(
    stop=stop_after_attempt(2), # 对于长度错误，只重试一次（调整参数后）
    wait=wait_fixed(0.5), # 短暂等待
    retry=retry_if_exception(is_content_length_error),
    before_sleep=before_sleep_log(logger, logging.INFO)
)
async def smart_chat_completion(client: LLMClient, messages: list, model: str, max_retoken_attempts: int = 1, **kwargs):
    """
    智能聊天补全，能自动处理上下文长度错误。
    """
    attempt = 0
    current_messages = messages
    current_max_tokens = kwargs.get(‘max_tokens’, 1000)

    while attempt <= max_retoken_attempts:
        try:
            return await client.chat_completion(current_messages, model=model, max_tokens=current_max_tokens, **kwargs)
        except ContentLengthError as e:
            attempt += 1
            logger.info(f“触发内容长度错误，尝试第{attempt}次调整。原始错误: {e}”)
            if attempt > max_retoken_attempts:
                raise
            # 调整策略：1. 减少max_tokens； 2. 截断最旧的消息（这里简化处理，仅减少max_tokens）
            current_max_tokens = int(current_max_tokens * 0.7) # 减少30%
            kwargs[‘max_tokens’] = current_max_tokens
            logger.info(f“调整max_tokens至: {current_max_tokens}”)
            # 更复杂的策略可以在这里截断或总结messages
            continue

5.2 监控、度量与告警

一个生产级的系统离不开监控。

• 记录指标 ：记录每个API调用的耗时、状态码、使用的资源、重试次数。可以使用 prometheus-client 或 statsd 等库。
• 设置告警 ：当某个资源的失败率连续超过阈值（如5分钟内失败率>20%），或平均响应时间显著上升时，触发告警（如发送邮件、Slack消息）。
• 日志聚合 ：将详细的请求日志、错误日志收集到如ELK、Loki等系统中，便于排查问题。

5.3 配置化管理

不应将API密钥、重试参数、资源列表等硬编码在代码中。应使用配置文件（如YAML、JSON）或环境变量来管理。

# config.yaml
retry_policy:
  max_attempts: 3
  base_delay: 1.0
  max_delay: 30.0

resources:
  - name: “source_a”
    type: “openai”
    api_key: ${SOURCE_A_KEY}
    base_url: “https://api.source-a.com/v1”
    priority: 1
    enabled: true
  - name: “source_b”
    type: “anthropic”
    api_key: ${SOURCE_B_KEY}
    base_url: “https://api.source-b.com/v1”
    priority: 2
    enabled: true

然后在代码中加载配置，动态构建资源池和重试策略。

5.4 测试策略

为你的重试和故障转移逻辑编写单元测试和集成测试至关重要。

• 模拟网络错误 ：使用 pytest 和 pytest-asyncio ，配合 httpx 的 MockTransport 来模拟超时、429、503等错误，验证重试逻辑是否按预期工作。
• 测试故障转移 ：模拟主资源持续失败，验证客户端是否能正确切换到备用资源。
• 测试熔断器 ：模拟短时间内大量失败，验证资源是否会被正确标记为不健康并暂时排除。

6. 常见问题与排查技巧实录

在实际部署和运行中，你肯定会遇到各种问题。以下是我总结的一些常见坑点和解决思路。

Q1: 重试导致重复消费或重复执行怎么办？ A: 这是重试策略中最危险的问题之一，特别是对于非幂等的操作（如创建订单、发送消息）。对于LLM API调用，虽然生成内容通常是幂等的（相同输入得到相同输出），但计费是按请求次数来的。 解决方案 ：

• 请求去重 ：为每个请求生成一个唯一ID（如UUID），并在客户端记录。如果收到重试请求，先检查该ID是否已处理过。这需要服务端配合或客户端有持久化存储。
• 幂等性令牌 ：部分API支持幂等性令牌（Idempotency Key）。你可以在请求头中携带一个唯一的令牌，服务端会保证对于同一个令牌，多次请求只有一次生效。 这是最佳实践，如果API支持，务必使用。
• 业务层保证 ：在调用LLM的上层业务逻辑中实现幂等性，例如，根据业务ID来确保同一任务只成功执行一次。

Q2: 日志太多，难以定位问题。 A: 无节制的重试日志会淹没真正有用的信息。 技巧 ：

• 结构化日志 ：使用 structlog 或 json-logging ，为每条日志附加请求ID、资源名称、重试次数等关键字段。
• 分级记录 ：将“开始重试”、“重试等待”等日志级别设为 DEBUG 或 INFO ，而将“重试耗尽最终失败”设为 ERROR 或 WARNING 。
• 采样记录 ：对于高频请求，可以采样记录重试详情，例如每100次重试记录一次完整链路。

Q3: 故障转移时，不同API的响应格式不一致。 A: 不同的LLM提供商（OpenAI格式 vs Anthropic格式）返回的JSON结构不同。 解决方案 ：

• 适配器模式 ：为每个资源类型（或每个API提供商）编写一个适配器（Adapter）类。这个类的职责是将统一的内部请求格式转换为特定API的格式，并将特定API的响应转换回统一的内部格式。这样，核心业务逻辑只处理统一格式。
• 配置化映射 ：将请求和响应的字段映射关系写在配置里，提高灵活性。

Q4: 如何设置合理的重试次数和退避时间？ A: 没有绝对标准，但可以遵循以下原则：

• 免费API ：重试次数宜少（2-3次），退避时间宜长（基础延迟2-5秒），避免被判定为滥用。
• 付费API ：可以稍激进一些（3-5次），基础延迟1-2秒。
• 实时交互场景 ：总超时时间要短（如10-15秒），重试次数不宜多，优先保证快速失败，给用户反馈。
• 异步批处理场景 ：可以设置更多重试次数（5-10次）和更长的总超时（几分钟），以追求成功率。
• 动态调整 ：更高级的系统可以根据历史成功率动态调整重试参数。例如，最近失败率高，则自动增加退避时间。

Q5: 遇到 402 Insufficient Balance 错误，除了换Key还有什么办法？ A: 这是硬性限制。在资源管理器中，一旦某个资源因402错误被标记失败，可以将其冷却时间设置得非常长（例如几小时或一天），或者直接禁用，等待人工处理。同时，系统应触发高优先级告警，通知管理员充值或更换Key。

Q6: 异步（Async）环境下的并发控制。 A: 当你有数百个并发请求同时触发重试和故障转移时，可能会对下游服务造成巨大压力，也容易触发客户端的连接数限制。 技巧 ：

• 使用信号量（Semaphore） ：限制同时向同一个API端点发起的请求数量。
• 分布式环境下的协同 ：如果你的服务是分布式的，多个实例共享同一批免费资源，那么需要一个中心化的协调者（如Redis）来管理全局速率限制和熔断状态，避免单个实例的行为影响整体。

构建一个健壮的 free-llm-api-resources 调用体系，重试和故障转移策略只是骨架，血肉则来自于对每一个错误码的细致处理、对每一次超时的耐心等待、以及对整个系统状态的持续观察和调整。它没有一劳永逸的银弹，需要你根据实际使用的API特性和业务需求，不断地打磨和优化。从最简单的 try...except 加 sleep 开始，逐步演进到如今带有退避、熔断、故障转移的复杂策略，这个过程本身，就是对分布式系统容错能力的一次深刻实践。