架构概述

相关源文件

• src/openai/__init__.py
• src/openai/_base_client.py
• src/openai/_client.py
• src/openai/_constants.py
• src/openai/_module_client.py
• src/openai/_streaming.py
• src/openai/_utils/_resources_proxy.py
• src/openai/resources/__init__.py
• tests/test_client.py
• tests/test_module_client.py
• tests/test_streaming.py

本文档描述了 OpenAI Python 库的高层架构，包括客户端层次结构、组件关系和关键设计模式。它涵盖了核心客户端类、API 资源组织、HTTP 基础设施以及基于实例和模块级别的使用模式。

有关特定 API 端点及其用法的信息，请参阅API 资源。有关类型系统和数据模型的详细信息，请参阅数据类型和模型。有关开发和构建系统的信息，请参阅开发与贡献。

系统概览

OpenAI Python 库采用分层架构，清晰地分离了 HTTP 传输、客户端接口、API 资源和数据类型。

高层架构

来源：src/openai/_client.py76-376 src/openai/_base_client.py361-778 src/openai/__init__.py148-347

客户端层次结构和继承

客户端架构采用分层设计，其中专门的客户端类继承自提供 HTTP 处理、重试逻辑和请求/响应处理的基础实现。

客户端类层次结构

来源：src/openai/_base_client.py361-378 src/openai/_base_client.py810-859 src/openai/_client.py76-156 src/openai/_client.py377-456

关键客户端组件

组件	职责	关键方法
BaseClient	HTTP 传输、重试、请求构建	_build_request(), _should_retry(), _make_status_error()
SyncAPIClient	同步请求执行	request(), close(), __enter__/__exit__
AsyncAPIClient	异步请求执行	request(), aclose(), __aenter__/__aexit__
OpenAI/AsyncOpenAI	用户面对的 API、身份验证、资源访问	API 资源的属性访问器

来源：src/openai/_base_client.py433-457 src/openai/_base_client.py931-1078

API 资源组织

API 资源被组织成逻辑分组，并为同步和异步操作提供了统一的模式。

资源结构

来源：src/openai/resources/__init__.py1-216 src/openai/_client.py159-253

请求与响应流程

该库通过一个多层管道处理请求，该管道负责身份验证、重试、流式传输和类型转换。

请求处理管道

来源：src/openai/_base_client.py931-1078 src/openai/_base_client.py600-623 src/openai/_base_client.py475-548

流式传输架构

流式处理系统处理服务器发送事件 (SSE) 和 WebSocket 连接，以实现实时 API 交互。

流式传输组件

来源：src/openai/_streaming.py22-121 src/openai/_streaming.py123-223 src/openai/_streaming.py266-380

模块级客户端模式

该库通过惰性加载模式支持基于实例和模块级别的用法，该模式会自动检测 API 凭据和配置。

模块客户端实现

来源：src/openai/__init__.py283-347 src/openai/_module_client.py30-142 src/openai/__init__.py264-278

配置优先级

模块客户端遵循以下配置优先级顺序

1. 显式模块级变量（openai.api_key、openai.base_url 等）
2. 环境变量（OPENAI_API_KEY、AZURE_OPENAI_ENDPOINT 等）
3. 默认值和自动检测逻辑

来源：src/openai/__init__.py117-147 src/openai/__init__.py298-315

错误处理与重试

基础客户端实现了全面的错误处理，具有可配置的重试逻辑和针对不同 HTTP 状态码的特定异常类型。

重试策略

条件	操作
超时错误 (408)	使用指数退避重试
速率限制错误 (429)	使用服务器指定的延迟重试
锁冲突 (409)	使用指数退避重试
服务器错误 (≥500)	使用指数退避重试
客户端错误（4xx，以上除外）	不重试，立即失败

来源：src/openai/_base_client.py740-773 src/openai/_base_client.py716-738 src/openai/_client.py342-374

类型安全和验证

该库使用 Pydantic 模型进行请求/响应验证，可配置的严格程度由 _strict_response_validation 参数控制。

来源：src/openai/_base_client.py614-622 src/openai/_client.py114 src/openai/_client.py415