快速结论:当你在 openai-python 的 Structured Outputs(如 client.beta.chat.completions.parse)里使用 Pydantic 模型,且模型包含带默认值的可选字段或 datetime / 日期字段时,Pydantic 生成的 JSON Schema 可能带有 API 不支持的 default、format: date-time 等字段,从而触发 schema 校验失败。优先排查 Pydantic 生成的 schema 中是否残留这些字段。
适用环境:Issue 中确认的工具为 OpenAI Python SDK(openai-python)及其 Structured Outputs 功能;示例模型为 gpt-4o-2024-08-06。Issue 未提供操作系统、Python、CUDA、显卡或具体依赖版本信息。
最快修复方案:Issue 中确认已修复的是“可选字段带 None 默认值生成 default 字段”的问题(PR #1663,已在当前发行版中可用)。对 format: date-time 问题,维护者明确表示当时没有自动移除的计划;现在 Structured Outputs 已支持日期/时间格式和数值边界,因此应保留这些约束,而不是删除它们。
注意事项:不要按 Issue 正文示例那样手动 pop 掉 default / format 字段来“绕过”校验:维护者指出移除 format 会破坏 .parse() “要么生成合法数据、要么不生成数据”的承诺。若在微调模型上仍遇到 schema 失败,应带完整 schema 和模型名单独开 Issue。
问题场景
用户在 openai-python 中使用 Structured Outputs,通过 client.beta.chat.completions.parse 并传入由 Pydantic 模型(经 to_strict_json_schema 转换)生成的 JSON Schema,同时设置 strict: True。当 Pydantic 模型里存在带默认值的可选字段(如 Optional[str] = Field(None, ...))或日期时间字段(如 Optional[datetime])时,生成的 schema 会含有 API 不支持的字段,导致请求在 schema 校验阶段失败。
报错原文
Apply more fixes for Pydantic schema incompatibilities with OpenAI structured outputs
原因分析
最可能的原因是 Pydantic 生成的 JSON Schema 与 OpenAI Structured Outputs 的 schema 校验要求不兼容:
- 带 Pydantic 默认值的可选字段会在 schema 中生成
default字段,而 API 不支持该字段。 - 日期字段会生成
format: date-time,在当时的 API 版本中不被支持。
维护者已确认 None 默认值的问题在 PR #1663 中修复(None defaults were fixed in #1663
环境排查
- 确认 openai-python 是否为包含 PR #1663 修复的当前发行版。
- 确认使用的模型(Issue 中为
gpt-4o-2024-08-06,微调模型可能仍有差异)。 - 确认 Pydantic 模型是否包含带默认值的可选字段、
datetime日期字段、Field(ge=…, le=…)数值边界或bool = False等字段。 - 确认最终的 JSON Schema 中是否残留
default、format等不受支持字段。 - Issue 未提供操作系统、Python、CUDA、显卡或依赖版本信息,这些项目无法从本 Issue 确认。
解决步骤
- 升级 openai-python 到包含 PR #1663 修复的当前发行版,以解决带
None默认值的可选字段产生default字段的问题。 - 对于日期/时间字段,不要手动删除
format: date-time。维护者说明 Structured Outputs 现已支持日期/时间格式,应保留该约束。 - 对于数值边界(如
Field(ge=…, le=…)),同样保留约束,因为 Structured Outputs 现已支持受支持基础模型上的数值边界。 - 若升级后特定 schema 仍然失败,尤其是微调模型场景,收集完整 schema 和模型名,按维护者建议单独开一个聚焦的 Issue 排查。
验证方法
使用升级后的 openai-python,对原报错的 Pydantic 模型重新调用 client.beta.chat.completions.parse 并设置 strict: True。若请求不再因 schema 校验失败,且能用 NewsArticles.model_validate_json(...) 正常解析返回内容,则说明问题已解决。若仍失败,应按维护者要求附上完整 schema 和模型名另开 Issue。
参考来源
AI 工具推荐
想把多个 AI 模型放在一个入口?
GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型,适合写作、绘图、视频和日常 AI 工作流。
推广链接:通过此链接购买,我可能获得佣金,不影响你的价格。
这个方案解决了吗?
可以继续搜索完整报错,或查看同一工具的其他排查指南。


