OpenAI SDK v3.37.0发布：Decisions类型迎破坏性变更

OpenAI SDK v3.37.0 的核心变更

OpenAI 官方 SDK 仓库（openai-sdks）发布了 v3.37.0 版本。尽管版本号只是一个小版本递增，但这次发布被明确标记为包含破坏性变更（Breaking Change），影响范围集中在 Live API 的 Decisions 类型上。

从变更日志看，本次发布包含 1 项功能更新和 4 项维护性工作：功能层面扩展了 Decisions 的输入与问题类型；维护层面则涉及文件/视频轮询辅助方法、上传辅助方法、Live 连接默认值，以及 astral-sh/setup-uv 依赖的版本升级。

破坏性变更具体改了什么

根据发布说明，在 Live 响应模型中，问题（question）的 instructions 字段现在可以是字符串，也可以是结构化文本、图片或 JSON 片段组成的列表。这意味着此前直接对 instructions 做字符串操作（如拼接、切片、正则匹配）的代码，在新版本下可能遇到类型错误。官方建议的做法是：在使用字符串操作前，先通过 isinstance(question.instructions, str) 判断类型，并对结构化形式单独处理。

这一变更反映了多模态交互正在成为 Live 场景的常态——用户指令不再只是纯文本，而可能携带图片、结构化 JSON 等内容。SDK 的类型系统需要相应放宽，以承载更丰富的输入形态。

结构化文本、图片或 JSON 片段在 SDK 类型系统中通常以“内容块（content block）”的形式建模：每个块带有 type 字段（如 text、image、json），图片块则携带 base64 数据或 URL，文本块携带纯文本。这种设计源自多模态模型的消息格式惯例，目的是让一条指令可以混合多种模态，而不必拆成多条消息。对开发者而言，关键区别在于：字符串是不可变的连续序列，可以直接切片和正则；而块列表是结构化对象，需要遍历、按 type 分派处理，序列化与日志打印的行为也不同。因此类型判断必须先于任何字符串操作。

**工具历史项（tool-history items）**指模型在对话中调用工具（函数调用、检索等）后产生的调用记录与返回结果，它们会作为输入消息的一部分回传给模型，以维持多轮工具调用的上下文。新增历史项类型意味着模型可接收更丰富的工具交互轨迹（例如并行调用、带结构化参数的结果），但也要求开发者在做角色/类型穷举判断时补全新分支，否则新项会被静默忽略或落入默认分支。

输入类型扩展的连带影响

除了 instructions 字段，Decisions 的请求输入类型也新增了额外的消息角色和工具历史项（tool-history items）。这意味着开发者在编写穷举式类型检查（例如对消息角色做 switch/if-else 分支）时，需要同步更新分支逻辑，否则可能遗漏新角色或新历史项，导致运行时行为不符合预期。

好消息是兼容性并未完全打破：现有的字符串形式 instructions，以及 DecisionInputMessageParam 中的用户消息输入，仍然保持支持。对于没有使用结构化指令的存量项目，升级风险相对可控。

维护性改动与依赖升级

本次发布的 chore 项主要是「保留」既有能力：保留文件与视频轮询辅助方法、保留上传辅助方法及 Live 连接默认值。这类改动通常出现在重构或类型调整过程中，目的是确保辅助工具在核心类型变更后仍然可用。

依赖方面，astral-sh/setup-uv 从 10.2.0 升级至 10.3.0，属于常规的 CI 工具链更新，对业务代码没有直接影响。

升级建议

对于正在使用 Live API 和 Decisions 类型的项目，建议在升级前做三件事：一是全局搜索对 question.instructions 的字符串操作；二是检查所有对 Decisions 输入消息角色的穷举判断；三是补充针对结构化指令的测试用例。如果项目暂时不涉及多模态指令，也可以先锁定当前版本，待官方补充更多迁移文档后再跟进。

要点总结

• v3.37.0 是带破坏性变更的小版本，影响 Live 响应模型的 Decisions 类型
• question.instructions 由纯字符串扩展为字符串或结构化片段列表
• Decisions 输入新增消息角色与工具历史项，穷举类型检查需同步更新
• 字符串指令与 DecisionInputMessageParam 用户消息输入保持向后兼容
• 依赖升级为 CI 工具链常规维护，对业务代码无直接影响