核心客户端类

相关源文件

• .gitignore
• README.md
• src/openai/__init__.py
• src/openai/_client.py
• src/openai/_module_client.py
• src/openai/_utils/_resources_proxy.py
• src/openai/resources/__init__.py
• tests/test_module_client.py

此页面介绍了 OpenAI Python 库中的主要客户端类，它们是与 OpenAI API 交互的主要入口点。这些类负责处理身份验证、请求构建、响应解析和错误处理。有关请求和响应处理的详细信息，请参阅请求和响应处理。

客户端类层次结构

OpenAI Python 库实现了多层客户端架构，以支持同步和异步操作，以及不同的部署环境（OpenAI API 和 Azure OpenAI）。

来源：src/openai/_base_client.py361-778 src/openai/_client.py48-278 src/openai/_client.py281-511

BaseClient 基类

BaseClient 是客户端层次结构的基石，为 API 通信提供核心功能。它是一个通用类，接受 HTTP 客户端 (_HttpxClientT) 和流响应类型 (_DefaultStreamT) 的类型参数。

主要职责包括

• 使用适当的标头和身份验证构建 HTTP 请求
• 管理失败请求的重试
• 处理错误和超时
• 处理响应

重要方法和属性

方法/属性	目的
_build_request()	根据选项构建 HTTP 请求
_build_headers()	构建包含身份验证的 HTTP 标头
auth_headers	返回身份验证标头（由子类实现）
default_headers	所有请求的默认标头
_should_retry()	确定失败的请求是否应重试
_calculate_retry_timeout()	计算重试的退避时间

The BaseClient 自动处理以下情况的重试：

• 服务器错误 (5xx 状态码)
• 速率限制 (429)
• 请求超时 (408)
• 连接问题

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

同步和异步 API 客户端

SyncAPIClient

The SyncAPIClient 扩展了 BaseClient 以提供同步实现。主要功能包括：

• 实现同步 HTTP 调用的请求方法
• 管理底层 HTTP 客户端的生命周期
• 支持用于资源清理的上下文管理器协议

AsyncAPIClient

The AsyncAPIClient 提供了一个异步实现，其接口与 SyncAPIClient 相同，但使用 async/await 模式

两种客户端类型都以相同的方式处理请求构建、身份验证、错误处理和响应处理，但执行模型不同。

来源：src/openai/_client.py90-155 src/openai/_client.py391-456

主要客户端实现

OpenAI（同步客户端）

The OpenAI 类是用于同步与 OpenAI API 交互的主要客户端。它继承自 SyncAPIClient 并提供：

• OpenAI API 身份验证
• 针对 API 响应的专门错误处理
• 通过属性访问所有 API 资源

The OpenAI 客户端会自动从环境变量中检测 API 密钥，如果未提供则会检测：

• 用于 api_key 的 OPENAI_API_KEY
• 用于 organization 的 OPENAI_ORG_ID
• 用于 project 的 OPENAI_PROJECT_ID

AsyncOpenAI（异步客户端）

AsyncOpenAI 提供与 OpenAI 相同的功能，但具有异步接口

两个客户端类都通过缓存属性公开相同的 API 资源

客户端 API 资源属性

来源：src/openai/_client.py159-253 src/openai/_client.py460-554

使用包装器客户端处理响应

OpenAI 客户端为不同的响应处理模式提供了特殊的包装器

原始响应

使用 with_raw_response 直接访问原始 HTTP 响应

流式响应

使用 with_streaming_response 更高效地处理流式响应

响应包装器类

包装器类提供与其父客户端完全相同的资源结构，确保一致的接口。

来源：src/openai/_client.py678-779 src/openai/_client.py884-1051

客户端自定义和复制

客户端提供用于创建自定义实例的方法

这允许为不同的用例创建专门的客户端实例，而无需修改原始客户端。copy() 和 with_options() 都支持与原始客户端构造函数相同的参数。

来源：src/openai/_client.py285-340 src/openai/_client.py586-641

模块级客户端

为方便起见，该库提供了一个模块级客户端接口，可根据环境变量自动在 OpenAI 和 Azure OpenAI 之间进行选择

模块级客户端架构

模块级客户端实现了自动客户端选择逻辑

环境变量	选定的客户端
仅 OPENAI_API_KEY	_ModuleClient (OpenAI)
AZURE_OPENAI_API_KEY + AZURE_OPENAI_ENDPOINT	_AzureModuleClient (Azure)
两组凭据	引发 _AmbiguousModuleClientUsageError

The _ModuleClient 类扩展了 OpenAI，其属性从模块级全局变量中读取，而资源访问则通过延迟加载的代理类实现，这些代理类将客户端实例化推迟到首次访问时。

来源：src/openai/__init__.py148-352 src/openai/_module_client.py26-141

客户端身份验证

所有客户端都通过以下方式处理 API 身份验证：

1. API 密钥身份验证

2. 多组织账户的组织 ID

3. 项目隔离的项目 ID

身份验证通过 auth_headers 属性和 default_headers 管理

对于 Azure 客户端，还提供了包括 Azure AD 令牌在内的额外身份验证方法。

来源：src/openai/_client.py269-283 src/openai/_client.py570-584

请求-响应流程

客户端堆栈中的请求/响应流

此流程展示了请求如何通过客户端层次结构进行处理，包括：

1. API 资源方法调用（例如，client.responses.create()）
2. 请求构建和身份验证标头准备
3. 通过 httpx 客户端进行 HTTP 传输
4. 使用特定的 OpenAI 异常类型处理错误
5. 响应数据处理和类型化对象返回

来源：src/openai/_client.py342-374 src/openai/_client.py643-675

客户端配置常量

客户端使用多个默认配置值

常量	值	描述
DEFAULT_TIMEOUT	600 秒	默认请求超时
DEFAULT_MAX_RETRIES	2	默认最大重试次数
INITIAL_RETRY_DELAY	0.5 秒	初始重试延迟
MAX_RETRY_DELAY	8.0 秒	最大重试延迟

这些常量控制默认客户端行为，并可在客户端初始化期间被覆盖。

来源：src/openai/_constants.py8-14