指南OneMux

用可重复且有上限的测试计划诊断 OpenAI API 故障

实用方法:区分 OpenAI 身份验证、速率限制、超时和响应格式错误,并在避免无限重试或无节制支出的前提下重新测试。

AI

摘要 · TL;DR

可重复的 OpenAI API 检查应记录每个用例的状态、错误代码、耗时和响应结构。只对暂时性故障进行有限次数的重试;身份验证、额度和请求错误应直接修复,而不是反复重试。

核心要点

  • 根据 HTTP 状态和具体错误代码判断故障,不要只看状态。
  • 在固定的尝试次数和时间预算内重试暂时性的速率限制和服务器错误;不要把身份验证错误或额度耗尽错误当作暂时问题来重试。
  • 将响应结构测试与 HTTP 请求成功和 JSON 有效性测试分开进行。
  • 保留一组规模较小、可重复的用例,并记录重现每个故障所需的条件。
文章目录 (6)

从有上限的诊断开始

OpenAI API 调用失败时,先判断问题出在访问权限、请求量、耗时,还是返回的数据。明确这一点后,才能决定是更换凭据、降低请求频率、重试,还是验证应用程序的解析逻辑。单凭 429 不足以决定如何修复:它可能表示暂时性的速率限制,也可能表示支出或额度限制,而再次重试无法解决后者。

OpenAI 的错误代码指南介绍了 API 错误代码及对应的 Python 库异常类型。解读实际观察到的响应时,可将其作为参考:OpenAI API 错误代码。

排查四类常见故障

症状首先检查后续操作
401 身份验证错误密钥是否有效且处于启用状态?是否使用了预期的组织?修正密钥或组织。适用时,检查项目权限和 IP 允许列表。
429 响应查看具体错误代码以及是否有 Retry-After 标头。如果是速率限制,降低请求频率。如果是额度耗尽或支出、用量限制,先解决相应限制再重试。
超时或连接错误区分请求超时和连接失败。记录耗时和网络状况。如适用,可短暂等待后谨慎重试;如果是连接错误,则检查代理、证书或防火墙规则。
HTTP 响应成功,但结果不可用检查响应正文能否解析,以及应用所需字段是否存在、类型是否符合预期。将字段缺失或无效视为应用层响应验证失败,不要自动归类为 API 身份验证或速率限制错误。

OpenAI 指南指出,无效凭据会导致 401,并列出了多种不同的 429 原因,包括请求速率、额度耗尽,以及组织或项目限制。对于速率限制,如果存在 Retry-After,指南建议遵循其要求。账单、支出和配额错误需要解决相应限制;反复重试不会恢复访问权限。指南还将 APITimeoutError 和 APIConnectionError 列为不同的 Python 库异常。来源:OpenAI 错误代码。

让小规模评估可重复执行

使用一组固定用例,而不是反复发送临时编写的提示。先从每次只隔离一个条件的用例开始:

  1. 基准测试: 发送一个规模较小且已知有效的输入,并确认预期响应字段存在。
  2. 身份验证检查: 使用预期的项目凭据运行相同的基准测试。不要在日志或测试报告中故意暴露真实密钥。
  3. 请求验证: 如果测试环境允许,可在受控测试中省略或拼错必需参数。记录返回的状态和消息;不要假设所有格式错误的请求都会以相同方式失败。
  4. 速率限制处理: 使用模拟的 429 响应测试重试逻辑,其中应包含 Retry-After 标头。避免通过真实流量触发限制。
  5. 超时处理: 在客户端或测试框架中模拟超时。使用响应缓慢的测试端点或反复调用生产环境,可能造成不必要的负载并导致结果难以判断。
  6. 响应验证: 分别测试有效 JSON 正文中必需字段缺失、字段类型错误以及 JSON 无效的情况。这些属于不同的解析或契约故障。

对于每个用例,记录时间戳和时区、端点或操作、模型、可用时的 HTTP 状态、错误类型和代码、尝试次数、耗时,以及经过脱敏的请求标识符或诊断上下文。不要在共享日志中保存凭据或敏感输入。如果就持续性问题联系 OpenAI 支持,其指南建议提供模型、错误及代码、请求数据和标头、时间戳和时区,以及其他相关细节;请先对机密信息和敏感数据进行脱敏。

为重试设置硬性上限

只有在故障可能自行消失时,重试才有用。应明确应用程序返回失败前允许的最大尝试次数和最长耗时。对于速率限制响应,如果提供了 Retry-After,应遵循其要求,并将重试预算设为有限值。对于服务器错误,指南建议短暂等待后重试;如果问题持续存在,应查看状态页面或升级处理。401、格式错误的请求或额度耗尽响应,都不应触发自动重试循环。

在 Python 中,官方库会区分 AuthenticationError、BadRequestError、RateLimitError、APITimeoutError 和 InternalServerError 等异常。请根据已安装的库版本处理可用的异常类,并在可用时记录状态和错误代码。以下示例仅用于说明分类方式,并不代表经过测试的配置或适用于所有情况的重试策略:

from openai import OpenAI

client = OpenAI()  # Supply credentials using your approved secret-management method.

try:
    response = client.responses.create(
        model="YOUR_SUPPORTED_MODEL",
        input="Return the word ready."
    )
    text = response.output_text
    if not isinstance(text, str) or not text.strip():
        raise ValueError("Response text is missing or empty")
    print(text)
except Exception as exc:
    # In production, classify known SDK exceptions explicitly and log
    # status/code when available. Do not log credentials or sensitive input.
    print(type(exc).__name__, str(exc))

模型占位符必须替换为项目可用的模型。此示例并不能证明特定模型、参数或提供商端点在你的环境中受支持。如果使用其他兼容的提供商,请先确认其端点和参数支持与客户端配置相符,再假定其行为完全相同。

将格式错误的响应与 API 错误区分开

HTTP 状态有效,并不保证应用程序收到了所需内容。在响应边界进行验证:检查解析是否成功、必需字段是否存在,以及值的类型是否可用。记录简明的验证失败描述,例如“缺少 output_text”或“预期类型为字符串”,而不要倾倒敏感的响应内容。

如果 API 返回结构化错误,应在诊断信息中保留其状态和代码。如果请求成功,但应用自己的解析器拒绝了响应正文,则应单独标记。这样可以明确问题应归因于 API 访问或速率限制、请求构造、传输,还是应用程序的假设。

结论

有效的 OpenAI API 评估应当规模小、可重复且有明确上限:一个基准用例、有针对性的故障用例、明确的输出检查,以及固定的重试上限。记录足够的上下文以便重现每个故障,并根据具体错误代码(而不只是 HTTP 状态)决定下一步操作。

常见问题

OpenAI 的每个 429 错误都应该重试吗?

不应该。请检查具体错误代码。暂时性的请求速率限制可能需要降低请求频率并遵循 `Retry-After`;额度耗尽或支出、用量限制则需要先解决限制,再进行重试。

如何判断是 API 故障还是响应格式错误?

分别记录 HTTP 状态和 API 错误代码,以及应用层验证结果。请求成功但响应无法解析或缺少必需字段,属于响应验证问题,不一定是 API 错误。

持续发生故障时应收集哪些信息?

记录模型、错误消息和代码、请求上下文及相关标头、带时区的时间戳、尝试次数和耗时。分享日志或支持信息前,请对 API 密钥和敏感数据进行脱敏。

如何在不影响生产环境的情况下测试速率限制?

使用模拟的 429 响应测试重试逻辑,其中包括模拟的 `Retry-After` 标头。不要为了触发速率限制而故意向生产项目发送大量请求。

相关文章