请求与响应处理

相关源文件

• src/openai/_base_client.py
• src/openai/_constants.py
• src/openai/_legacy_response.py
• src/openai/_response.py
• src/openai/_streaming.py
• tests/test_client.py
• tests/test_legacy_response.py
• tests/test_response.py
• tests/test_streaming.py

本文档解释了 OpenAI Python 客户端库如何处理对 OpenAI API 的请求并处理相应的响应。理解此系统对于有效使用该库和在出现问题时进行故障排除至关重要。有关流式响应的具体信息，请参阅流式响应。

请求-响应流程概述

OpenAI Python 客户端中的请求-响应周期虽然复杂，但遵循逻辑流程

来源: src/openai/_base_client.py476-549 src/openai/_response.py129-193

请求构建

请求选项

每个 API 请求都始于 FinalRequestOptions，它封装了构建 HTTP 请求所需的所有参数

来源: src/openai/_base_client.py434-455 src/openai/_models.py

请求头构建

请求头通过 _build_headers 方法以分层方式构建

来源: src/openai/_base_client.py433-458

URL 和参数处理

客户端通过以下几个步骤处理 URL 和查询参数

1. 针对基础 URL 解析相对 URL
2. 将默认查询参数与请求特定参数合并
3. 处理参数名称和值中的特殊字符
4. 创建带有正确编码参数的最终 URL

来源: src/openai/_base_client.py460-471 src/openai/_qs.py

请求体处理

对于请求体，该库处理

1. JSON 数据序列化
2. 文件上传和 multipart/form-data 编码
3. 将基本 JSON 数据与额外 JSON 数据合并

来源: src/openai/_base_client.py487-494 src/openai/_files.py

响应处理

响应类层级结构

该库使用复杂的响应类层级结构来处理不同类型的响应

来源: src/openai/_response.py48-193 src/openai/_response.py274-380 src/openai/_response.py383-487

响应解析

响应处理的核心是 _parse 方法，它负责处理

1. 识别响应类型（文本、JSON、二进制、流）
2. 将原始响应内容转换为适当的 Python 类型
3. 根据预期类型验证响应数据
4. 处理解析过程中的错误

来源: src/openai/_response.py128-271

缓存解析后的响应

响应对象根据目标类型缓存解析结果，以避免重复解析

来源: src/openai/_response.py285-331 src/openai/_response.py394-438

错误处理与重试

客户端包含强大的错误处理和重试逻辑

重试决策逻辑

客户端根据以下因素决定是否重试请求

1. HTTP 状态码（408, 409, 429, 500+）
2. 来自 API 的 x-should-retry 请求头
3. 网络和超时错误
4. 最大重试次数配置
5. Retry-After 请求头值

来源: src/openai/_base_client.py741-774 src/openai/_base_client.py683-739

退避策略

重试超时时间根据以下方式计算

1. 带初始延迟的指数退避
2. 最大延迟上限
3. 随机抖动以防止请求风暴
4. 遵守 Retry-After 请求头

来源: src/openai/_base_client.py717-739 src/openai/_constants.py13-14

类型转换系统

该库在 Python 对象和 API 格式之间进行转换

类型转换使用以下几种机制

1. 严格验证以强制类型安全
2. 非严格构建以实现更灵活的响应处理
3. 对联合类型、泛型和可选类型的特殊处理

来源: src/openai/_base_client.py607-624 src/openai/_utils.py src/openai/_models.py

请求和响应上下文

该库提供上下文管理器来处理流式响应

这些上下文管理器通过在上下文退出时自动关闭响应来确保正确的资源清理，防止资源泄漏。

来源: src/openai/_response.py615-660

请求-响应周期示例

一个完整的聊天补全请求-响应周期示例

来源: src/openai/_base_client.py935-1050

结论

OpenAI Python 客户端中的请求-响应处理系统是一个复杂的架构，它处理

1. Python 对象和 API 格式之间的转换
2. 管理 HTTP 请求和响应
3. 处理错误并实现重试逻辑
4. 支持流式响应
5. 通过验证确保类型安全

理解此系统有助于有效使用该库，并解决在 API 交互过程中可能出现的问题。