AI Engineering Academy · 课时

错误处理与速率限制

Q: 「错误处理与速率限制」这节课中我会学到什么？

使用重试逻辑和指数退避模式，处理常见 API 错误，包括速率限制异常、身份验证错误和超时。 你通过在浏览器中直接运行的动手代码来练习 AI Engineering Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

使用重试逻辑和指数退避模式，处理常见 API 错误，包括速率限制异常、身份验证错误和超时。

错误处理与速率限制 是 CoddyKit 上的免费 AI Engineering Academy 课时。这是第 4 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 AI Engineering Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 AI Engineering Academy 课程共包含 4 节课。

API 错误为何发生

API 调用可能出现许多问题：过载、配额不足、网络中断或请求无效。把调用当作绝不会失败，必然会写出脆弱的代码，因此请先了解错误类型。

OpenAI 错误类型概览

SDK 会引发特定的异常，例如 RateLimitError 和 AuthenticationError。只有速率限制、网络中断等暂时性错误值得重试，其他错误不会自行修复。

使用 Try-Except 捕获错误

请使用 try-except 包裹每次调用，并捕获具体的异常，而不是使用空泛的 except。这样您就能针对每种失败情况采取恰当措施，而不是掩盖错误。代码展示了具体方法。

import openai

client = openai.OpenAI()

try:
    response = client.chat.completions.create(
        model='gpt-4o-mini',
        messages=[{'role': 'user', 'content': 'Hello!'}]
    )
    print(response.choices[0].message.content)
except openai.AuthenticationError as e:
    print('Bad API key. Check OPENAI_API_KEY environment variable.')
    raise  # do not retry
except openai.RateLimitError as e:
    print('Rate limited. Back off and retry.')
except openai.APIConnectionError as e:
    print('Network error:', e)
except openai.APIStatusError as e:
    print('Server error', e.status_code, e.message)

理解速率限制

OpenAI 会同时实施两种速率限制：每分钟请求数（RPM）和每分钟令牌数（TPM）。一个很大的提示可能在一次请求中就耗尽 TPM。两者都会返回 429。

指数退避：正确的重试策略

遇到速率限制了吗？请等待一段时间，然后采用指数退避重试：1 秒、2 秒、4 秒，每次加倍。加入少量抖动和最大重试次数，确保程序不会无限循环。请查看代码。

import time
import random
import openai

client = openai.OpenAI()

def call_with_backoff(messages, max_retries=5):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model='gpt-4o-mini',
                messages=messages
            )
        except openai.RateLimitError:
            if attempt == max_retries - 1:
                raise
            wait = (2 ** attempt) + random.uniform(0, 1)
            print(f'Rate limited. Waiting {wait:.1f}s (attempt {attempt+1})')
            time.sleep(wait)
        except (openai.APIConnectionError, openai.APIStatusError):
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)

使用 tenacity 库

不要手动编写重试逻辑，tenacity 库可以干净地处理这些工作。使用 @retry 装饰函数后，它会为您处理退避、抖动和重试条件。

from tenacity import retry, wait_random_exponential, stop_after_attempt
import openai

client = openai.OpenAI()

@retry(
    wait=wait_random_exponential(min=1, max=60),
    stop=stop_after_attempt(6)
)
def completion_with_backoff(**kwargs):
    return client.chat.completions.create(**kwargs)

response = completion_with_backoff(
    model='gpt-4o-mini',
    messages=[{'role': 'user', 'content': 'Tell me a joke.'}]
)
print(response.choices[0].message.content)

配置超时

挂起的请求可能会让应用永久冻结，因此请始终设置超时。SDK 支持以秒为单位设置超时，可以在客户端级别设置，也可以针对单次调用设置。请根据预期响应长度选择合适的值。

import openai

# Set a default timeout for all requests from this client
client = openai.OpenAI(timeout=30.0)

# Or override per request
try:
    response = client.chat.completions.create(
        model='gpt-4o-mini',
        messages=[{'role': 'user', 'content': 'Summarize the French Revolution.'}],
        timeout=60.0
    )
except openai.APITimeoutError:
    print('Request timed out. Try a shorter prompt or increase timeout.')

处理身份验证错误

AuthenticationError（401）表示您的密钥错误、已过期或已被撤销，重试不会有帮助。请记录错误、发送警报，并立即失败，不要消耗重试次数。

import os
import openai

api_key = os.environ.get('OPENAI_API_KEY')
if not api_key:
    raise EnvironmentError(
        'OPENAI_API_KEY not set. Export it before running.'
    )

client = openai.OpenAI(api_key=api_key)

try:
    response = client.chat.completions.create(
        model='gpt-4o-mini',
        messages=[{'role': 'user', 'content': 'Hello'}]
    )
except openai.AuthenticationError:
    # Do NOT retry - the key itself is invalid
    raise RuntimeError('Invalid API key. Check OPENAI_API_KEY.')

配额与速率限制

两者看起来都像 RateLimitError，但实际不同：速率限制是每分钟的调用限制，会自动重置；配额限制则是消费上限，需要增加额度。

记录错误以便调试

在生产环境中，请记录每个错误及其上下文：类型、模型、参数、令牌数量、时间和请求 ID。这个请求 ID 正是 OpenAI 支持团队需要的信息。请查看代码。

import logging
import openai

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

client = openai.OpenAI()

def safe_completion(model, messages):
    try:
        response = client.chat.completions.create(
            model=model, messages=messages
        )
        return response
    except openai.RateLimitError as e:
        logger.warning(
            'Rate limit hit',
            extra={'model': model, 'error': str(e)}
        )
        raise
    except openai.APIStatusError as e:
        logger.error(
            'API server error',
            extra={
                'status_code': e.status_code,
                'request_id': e.request_id,
                'model': model
            }
        )
        raise

生产应用中的错误处理

可靠的生产策略是：对无法恢复的错误立即失败，对暂时性错误采用退避策略重试，并提供平稳的备用方案。不要让一个 API 错误导致整个服务器崩溃。

快速检查

测试您对本课 AI 工程概念的理解。

课程回顾

您已经学会处理失败情况：OpenAI 会引发特定异常，速率限制需要结合抖动进行退避，而身份验证错误应当立即失败。接下来学习编写强大的提示。

常见问题解答

「错误处理与速率限制」课时是免费的吗？

是的 — 「错误处理与速率限制」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 AI Engineering Academy 课程的其余内容，请升级到 CoddyKit PRO。 AI Engineering Academy 课程共包含 4 节课。

「错误处理与速率限制」这节课中我会学到什么？

使用重试逻辑和指数退避模式，处理常见 API 错误，包括速率限制异常、身份验证错误和超时。你通过在浏览器中直接运行的动手代码来练习 AI Engineering Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 AI Engineering Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 AI Engineering Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 4 节课，共 4 节。

「错误处理与速率限制」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 AI Engineering Academy 课中编写并运行代码吗？

能。每节 AI Engineering Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 AI Engineering Academy