大模型应用开发 / 知识点

OpenAI API 开发速查手册

手册条目

CODE
client = OpenAI(max_retries=0, timeout=<SECONDS>)
except openai.APIStatusError as exc:   # 408 / 409 / 429 / 5xx 指数退避 + 抖动,优先读 retry-after

识别限流响应并使用指数退避、抖动和并发控制进行重试。

处理限流与重试

遇到 429、连接中断、超时或服务端 5xx 时,用“有限次数重试 + 指数退避 + 随机抖动 + 并发上限”恢复瞬时故障;参数、认证、权限和额度耗尽错误应立即失败,不要盲目重试。OpenAI Python SDK 默认会对连接错误、408、409、429 和 5xx 自动重试 2 次;自行实现重试时应关闭 SDK 内置重试,避免尝试次数相乘。:contentReference[oaicite:0]{index=0}

重试判定

可重试:408、409、普通 429、5xx、APIConnectionError 和 APITimeoutError。不可重试:400、401、403、404、422,以及 429 中表示额度或账单问题的 insufficient_quota。

指数退避可写为 min(上限, 基础等待 × 2^attempt) + 随机抖动。若响应包含 Retry-After,优先按该值等待;同时记录 x-ratelimit-remaining-* 和 x-ratelimit-reset-*,可在触发 429 前主动降速。:contentReference[oaicite:1]{index=1}

限流重试决策流程

可运行示例

脚本关闭 SDK 内置重试,由应用统一控制总尝试次数;BoundedSemaphore 限制同时在途请求数。它只限制并发,不等同于完整的 RPM/TPM 限速器。

python
import os
import random
import threading
import time

import openai
from openai import OpenAI

MAX_ATTEMPTS = 6
MAX_IN_FLIGHT = 4
MAX_DELAY_SECONDS = 30.0

client = OpenAI(max_retries=0, timeout=30.0)
gate = threading.BoundedSemaphore(MAX_IN_FLIGHT)

def retry_delay(exc: Exception, attempt: int) -> float:
    response = getattr(exc, "response", None)
    retry_after = response.headers.get("retry-after") if response else None
    if retry_after:
        try:
            return min(float(retry_after), MAX_DELAY_SECONDS)
        except ValueError:
            pass

    exponential = min(0.5 * (2**attempt), MAX_DELAY_SECONDS)
    return exponential + random.uniform(0.0, 0.5)

def create_response(prompt: str):
    with gate:
        for attempt in range(MAX_ATTEMPTS):
            try:
                return client.responses.create(
                    model=os.environ["OPENAI_MODEL"],
                    input=prompt,
                )
            except openai.APIStatusError as exc:
                # 配额耗尽和其他确定性 4xx 不会因等待而恢复。
                if exc.status_code == 429 and exc.code == "insufficient_quota":
                    raise
                retriable = exc.status_code in {408, 409, 429} or exc.status_code >= 500
                if not retriable or attempt == MAX_ATTEMPTS - 1:
                    raise
                delay = retry_delay(exc, attempt)
                print(
                    f"retry attempt={attempt + 1} "
                    f"wait={delay:.2f}s status={exc.status_code}"
                )
                time.sleep(delay)
            except openai.APIConnectionError as exc:
                if attempt == MAX_ATTEMPTS - 1:
                    raise
                delay = retry_delay(exc, attempt)
                print(
                    f"retry attempt={attempt + 1} "
                    f"wait={delay:.2f}s status=network"
                )
                time.sleep(delay)

    raise RuntimeError("unreachable")

if __name__ == "__main__":
    response = create_response("只输出 OK,不要添加标点。")
    print(f"success request_id={response._request_id}")
    print(response.output_text)

运行前设置有效密钥和当前项目可用的模型:

bash
export OPENAI_API_KEY="<API_KEY>"
export OPENAI_MODEL="<MODEL_ID>"
python retry_openai.py

预期输出;请求 ID 和等待时间以实际值为准:

text
success request_id=<REQUEST_ID>
OK

发生瞬时限流时,成功行之前会出现一至多行 retry attempt=...。

并发与容量控制

并发上限要按共享的项目级限制设置,而不是每个进程各自设置相同上限。多实例部署应使用集中式队列或令牌桶协调 RPM/TPM;仅靠进程内信号量会让总并发随实例数增长。

请求较大时,TPM 往往先耗尽。可通过缩短输入、限制输出、平滑队列消费和减少突发并发降低 429。失败请求也可能计入限额,因此无上限的快速重试会进一步放大限流。

风险与边界

  • 触发条件:SDK 内置重试和业务重试同时开启。后果:实际请求次数成倍增加,延迟和费用失控。替代方案:只保留一层重试,并设置总尝试次数与总耗时上限。
  • 触发条件:对 401、403、参数错误或 insufficient_quota 重试。后果:持续失败并挤占线程。替代方案:立即失败,修正密钥、权限、参数或账单。
  • 触发条件:超时后请求可能已被服务端接收。后果:重复生成、重复计费,工具调用还可能产生重复业务动作。替代方案:记录请求 ID,并在应用侧为写操作增加业务幂等键和去重。
  • 触发条件:大量客户端在同一时刻按固定间隔重试。后果:形成重试风暴。替代方案:加入随机抖动,并通过队列平滑流量。

速查:重试只处理“暂时不可用”,并发控制负责“不要同时压上去”,额度、权限和参数问题必须直接修复。

目录与阅读设置

记录一个想法

OpenAI API 开发速查手册

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通