在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

openai/openai-python

菜单

HTTP 客户端基础

相关源文件

本文档涵盖了所有 OpenAI API 交互底层的 HTTP 客户端基础架构。HTTP 客户端基础提供了核心的请求/响应处理、重试逻辑、身份验证、流式传输支持和错误管理，为同步和异步 API 操作提供支持。

有关在此基础上构建的更高级客户端接口的信息，请参阅核心客户端类。有关流式传输和实时通信协议的详细信息，请参阅流式传输和实时 API。

目的与范围

HTTP 客户端基础是所有与 OpenAI API 进行 HTTP 通信的基础层。它抽象了 HTTP 传输、连接管理、重试逻辑和响应处理的复杂性，同时为同步和异步操作提供了统一的接口。该基础能够实现所有 OpenAI 服务之间可靠、弹性的 API 交互。

架构概述

HTTP 客户端基础围绕分层的类结构构建，将通用 HTTP 处理与 OpenAI 特定的客户端实现区分开来

来源： src/openai/_base_client.py361-777

核心组件

BaseClient

The BaseClient 类作为通用基类，提供了基础的 HTTP 客户端功能

组件目的关键方法
请求构建构建包含正确标头、身份验证和参数的 HTTP 请求_build_request(), _prepare_url(), _build_headers()
响应处理处理响应解析、验证和类型转换_process_response_data(), _maybe_override_cast_to()
重试逻辑实现带指数退避的智能重试策略_should_retry(), _calculate_retry_timeout()
错误处理将 HTTP 错误转换为相应的 API 异常_make_status_error_from_response()
配置管理超时、连接限制和客户端设置timeout, max_retries, _strict_response_validation

来源： src/openai/_base_client.py361-777

SyncAPIClient and AsyncAPIClient

这些具体实现扩展了 BaseClient，以提供同步和异步 HTTP 操作

来源： src/openai/_base_client.py810-1091 src/openai/_base_client.py1092-1418

请求/响应流程

HTTP 客户端基础遵循结构化的请求/响应流程，处理身份验证、重试和错误恢复

来源： src/openai/_base_client.py931-1039 src/openai/_base_client.py475-548 src/openai/_base_client.py600-622

重试机制

该基础实现了复杂的重试逻辑，具有指数退避功能并遵循服务器提供的重试指导

重试决策逻辑

_should_retry() 方法根据以下因素决定是否重试

条件操作状态码
服务器指令如果存在 x-should-retry 标头，则遵循其指令任意
请求超时始终重试408
锁超时始终重试409
速率限制始终重试429
服务器错误始终重试≥ 500
客户端错误从不重试4xx (408、409、429 除外)

来源： src/openai/_base_client.py740-773

重试时间计算

_calculate_retry_timeout() 方法实现了智能退避

  1. 服务器指定延迟：遵循 retry-after 和 retry-after-ms 标头
  2. 指数退避：INITIAL_RETRY_DELAY * pow(2.0, nb_retries) 上限为 MAX_RETRY_DELAY
  3. 抖动：应用随机方差以防止惊群效应
  4. 边界检查：将重试延迟限制在合理范围（服务器提示为 0-60 秒）

来源： src/openai/_base_client.py716-738 src/openai/_constants.py13-14

流式传输支持

该基础通过服务器发送事件 (SSE) 提供全面的流式传输支持

SSE 事件处理

流式传输系统处理各种事件类型和错误条件

  • 标准事件：event: completion, event: ping
  • 响应事件：以 response. 或 transcript. 开头的事件
  • 错误事件：包含错误信息的 event: error 事件
  • 完成标记：[DONE] 表示流终止

来源： src/openai/_streaming.py22-122 src/openai/_streaming.py266-369

错误处理

HTTP 客户端基础提供了具有特定异常类型的全面错误处理

异常类型触发器目的
APITimeoutErrorhttpx.TimeoutException请求超时处理
APIConnectionError连接失败网络连接问题
APIStatusErrorHTTP 4xx/5xx 响应服务器端 API 错误
APIResponseValidationError无效的响应数据响应解析失败

来源： src/openai/_base_client.py977-1004 src/openai/_exceptions.py

配置与常量

该基础使用集中式配置以实现可靠运行

默认设置

设置值目的
DEFAULT_TIMEOUThttpx.Timeout(timeout=600, connect=5.0)10 分钟总超时，5 秒连接超时
DEFAULT_MAX_RETRIES2适用于大多数操作的合理重试限制
DEFAULT_CONNECTION_LIMITSmax_connections=1000, max_keepalive_connections=100连接池限制
INITIAL_RETRY_DELAY0.5 秒指数退避的起点
MAX_RETRY_DELAY8.0 秒最大重试延迟上限

自定义标头

该基础自动添加操作标头

  • 身份验证：Authorization: Bearer {api_key}
  • 用户代理：{ClientName}/Python {version}
  • 重试跟踪：x-stainless-retry-count: {retries_taken}
  • 超时信息：x-stainless-read-timeout: {timeout}
  • 内容类型：application/json（默认）

来源： src/openai/_constants.py8-14 src/openai/_base_client.py433-457 src/openai/_base_client.py637-651