本文档介绍了 OpenAI Python 库的数据类型系统和模型架构，包括基础模型类、类型构造机制以及生成的类型定义。该系统在保持与 Pydantic 版本兼容性的同时，提供了 API 请求和响应的类型安全表示。
有关 HTTP 客户端基础和请求/响应处理的信息，请参阅 请求和响应处理。有关生成的 API 资源类的详细信息，请参阅 API 资源。
OpenAI Python 库使用基于 Pydantic 的分层数据模型架构来实现类型安全和验证。
来源： src/openai/_models.py85-89 src/openai/_models.py729-730 src/openai/_models.py784-807 src/openai/types/__init__.py1-96
BaseModel 类扩展了 Pydantic 的 BaseModel，并加入了 OpenAI 特有的增强功能。
BaseModel 类提供了增强的序列化方法，这些方法能够理解 API 字段命名约定。to_dict() 方法包含使用 API 名称或属性名称的选项，而 to_json() 则提供格式化的 JSON 输出。
来源： src/openai/_models.py85-104 src/openai/_models.py123-194 src/openai/_models.py203-258
| 方法 | 目的 | 关键参数 |
|---|---|---|
to_dict() | 字典表示 | use_api_names, exclude_unset, mode |
to_json() | JSON 字符串表示 | indent, use_api_names, exclude_unset |
model_dump() | Pydantic 兼容性 | by_alias, exclude_unset, warnings |
construct() | 无验证构造 | _fields_set, **values |
序列化方法处理 API 字段名（如 "fooBar"）和 Python 属性名（如 foo_bar）之间的区别，并根据 use_api_names 参数自动使用相应的命名约定。
来源： src/openai/_models.py123-159 src/openai/_models.py161-194 src/openai/_models.py273-327
该库提供了多种构造和验证类型的方法。
来源： src/openai/_models.py448-563 src/openai/_models.py692-697 src/openai/_models.py416-436
类型构造系统包含复杂的联合类型处理，特别是针对区分联合类型。
| 联合类型 | 处理策略 |
|---|---|
| 简单联合 | 按顺序尝试每个变体 |
| 区分联合 | 使用鉴别器字段选择变体 |
| 嵌套联合 | 递归变体选择 |
| 带有字面量的联合 | 直接值匹配 |
该系统使用元数据注解来识别区分联合，并构建从鉴别器值到具体类型的映射。
来源： src/openai/_models.py477-512 src/openai/_models.py612-668 src/openai/_models.py571-610
该库包含一套来自 OpenAPI 规范的全面生成的类型。
来源： src/openai/types/__init__.py8-23 src/openai/types/__init__.py25-47 src/openai/types/__init__.py77-95
类型系统包含全面的 API 请求参数类型。
| 参数类别 | 示例 |
|---|---|
| 创建参数 | CompletionCreateParams, ChatCompletionCreateParams |
| 列表参数 | FileListParams, BatchListParams |
| 更新参数 | EvalUpdateParams, ThreadUpdateParams |
| 专用参数 | ImageEditParams, AudioTranscriptionParams |
这些参数类型使用 TypedDict 定义，为 API 请求提供类型安全，同时保持与底层 HTTP 客户端的兼容性。
来源： src/openai/types/__init__.py41-75 api.md32 api.md83-85
转换系统使用 Pydantic 的 Field 别名系统，处理 API 字段名（通常是 camelCase）和 Python 属性名（snake_case）之间的映射。
来源： src/openai/_models.py136-146 src/openai/_models.py171-180 tests/test_models.py171-181
该系统包含对常见类型强制转换的专门处理。
| 源类型 | 目标类型 | 强制转换策略 |
|---|---|---|
| 字符串 | datetime | 通过 parse_datetime() 解析 ISO8601 |
| 字符串 | date | 通过 parse_date() 解析日期 |
整数 | 浮点数 | 安全数值转换 |
| 映射 | BaseModel | 递归构造 |
来源： src/openai/_models.py551-562 src/openai/_models.py542-549 tests/test_models.py423-441
该库在 Pydantic v1 和 v2 之间保持兼容性
来源： src/openai/_models.py86-89 src/openai/_models.py273-327 src/openai/_models.py733-767
BaseModel 类提供了向前兼容的方法，可以在两个 Pydantic 版本中工作
| 方法 | V2 实现 | V1 实现 |
|---|---|---|
model_dump() | 原生方法 | 使用 dict() 的自定义包装器 |
model_dump_json() | 原生方法 | 使用 json() 的自定义包装器 |
model_construct() | 原生方法 | 别名至 construct() |
这确保了为任一 Pydantic 版本编写的代码都能正确工作，无论安装了哪个版本。
来源： src/openai/_models.py273-327 src/openai/_models.py329-379 src/openai/_models.py260-264