Apply more fixes for Pydantic schema incompatibilities with OpenAI structured outputs

当你在 openai-python 的 Structured Outputs(如 client.beta.chat.completions.parse )里使用 Pydantic 模型,且模型包含带默认值的可选字段或 datetime / 日期字段时,Pydantic 生成的 JSON Schema

快速结论:当你在 openai-python 的 Structured Outputs(如 client.beta.chat.completions.parse)里使用 Pydantic 模型,且模型包含带默认值的可选字段或 datetime / 日期字段时,Pydantic 生成的 JSON Schema 可能带有 API 不支持的 defaultformat: 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 正文示例那样手动 popdefault / 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 中是否残留 defaultformat 等不受支持字段。
  • Issue 未提供操作系统、Python、CUDA、显卡或依赖版本信息,这些项目无法从本 Issue 确认。

解决步骤

  1. 升级 openai-python 到包含 PR #1663 修复的当前发行版,以解决带 None 默认值的可选字段产生 default 字段的问题。
  2. 对于日期/时间字段,不要手动删除 format: date-time。维护者说明 Structured Outputs 现已支持日期/时间格式,应保留该约束。
  3. 对于数值边界(如 Field(ge=…, le=…)),同样保留约束,因为 Structured Outputs 现已支持受支持基础模型上的数值边界。
  4. 若升级后特定 schema 仍然失败,尤其是微调模型场景,收集完整 schema 和模型名,按维护者建议单独开一个聚焦的 Issue 排查。

验证方法

使用升级后的 openai-python,对原报错的 Pydantic 模型重新调用 client.beta.chat.completions.parse 并设置 strict: True。若请求不再因 schema 校验失败,且能用 NewsArticles.model_validate_json(...) 正常解析返回内容,则说明问题已解决。若仍失败,应按维护者要求附上完整 schema 和模型名另开 Issue。

参考来源

openai/openai-python #1659

GamsGo AI

AI 工具推荐

想把多个 AI 模型放在一个入口?

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型,适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接:通过此链接购买,我可能获得佣金,不影响你的价格。

这个方案解决了吗?

celebrityanime
celebrityanime
文章: 24505

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注