模型转换系统

相关源文件

• src/openai/_utils/_transform.py
• src/openai/lib/_parsing/_responses.py
• src/openai/types/responses/parsed_response.py
• tests/test_transform.py

模型转换系统负责将 Python 数据结构转换为 API 兼容的格式，反之亦然。它根据类型注解和元数据处理属性别名、数据格式化、类型强制转换和结构转换。该系统弥合了 Python 命名约定与 API 要求之间的差距，同时提供了类型安全的数据转换功能。

有关底层类型系统架构的信息，请参阅类型系统架构。有关 Pydantic 模型和数据结构的详细信息，请参阅数据类型和模型。

核心架构

该转换系统围绕 PropertyInfo 注解类和一组转换函数构建，这些函数根据类型提示递归处理数据结构。

来源：src/openai/_utils/_transform.py76-448

PropertyInfo 注解系统

PropertyInfo 类用作字段转换指令的元数据容器。它支持属性别名、数据格式化以及联合类型的判别字段。

来源：src/openai/_utils/_transform.py42-74 tests/test_transform.py40-42 src/openai/types/responses/parsed_response.py42-45

转换管道

转换过程遵循递归模式，该模式分析类型注解并根据发现的元数据和类型结构应用转换。

来源：src/openai/_utils/_transform.py152-227 src/openai/_utils/_transform.py314-389

关键转换功能

属性别名

该系统使用 PropertyInfo 中的 alias 属性将 Python 字段名转换为 API 兼容的名称。

Python 字段	PropertyInfo 别名	API 字段
foo_bar	"fooBar"	fooBar
account_holder_name	"accountHolderName"	accountHolderName
required_prop	"prop"	prop

来源：src/openai/_utils/_transform.py129-145 tests/test_transform.py40-48

数据格式化

该系统提供了多种内置格式化程序，以满足常见数据转换需求

来源：src/openai/_utils/_transform.py230-254 src/openai/_utils/_transform.py392-416 tests/test_transform.py164-269

复杂类型处理

转换系统处理嵌套和复杂数据结构

• TypedDict 结构：带别名映射的递归字段转换
• 列表和可迭代对象：在保留集合结构的同时进行元素级转换
• 联合类型：对所有联合成员应用转换
• Pydantic 模型：自动序列化为字典并进行适当的排除
• 嵌套组合：支持复杂嵌套结构，例如 List[Union[TypedDict, OtherType]]

来源：src/openai/_utils/_transform.py175-212 tests/test_transform.py63-133

与请求/响应处理的集成

转换系统通过几个关键集成点与更广泛的 OpenAI 客户端架构集成

来源：src/openai/lib/_parsing/_responses.py53-129 src/openai/types/responses/parsed_response.py42-78

性能优化

转换系统包括多项性能优化

• LRU 缓存：类型内省结果使用 @lru_cache(maxsize=8096) 装饰器进行缓存
• 跳过转换：当不需要更改时，像 int 和 float 这样的简单类型会绕过转换
• 惰性处理：NotGiven 值会提前过滤掉，以避免不必要的处理
• 类型特定快速路径：对列表保留等常见场景进行特殊处理

来源：src/openai/_utils/_transform.py113 src/openai/_utils/_transform.py148-149 src/openai/_utils/_transform.py194-201 src/openai/_utils/_transform.py440-447

异步支持

该系统通过并行实现路径提供完整的 async/await 支持

• async_transform() 和 async_maybe_transform() 入口点
• 用于递归处理的 _async_transform_recursive()
• 用于文件读取等 I/O 操作的 _async_format_data()
• 使用 anyio.Path 进行异步文件操作

来源：src/openai/_utils/_transform.py278-437