Pydantic and JSON schemas need upgrade

快速结论：报错 “Pydantic and JSON schemas need upgrade” 通常出现在把 Pydantic 生成的 JSON Schema 与 OpenAI Python SDK / Responses API 的 Structured Outputs 对接时，尤其在 schema 嵌套较深、需要存储到数据库再发送给 API 的场景下。优先排查 Pydantic 导出的 schema 是否包含额外的 title、$defs/$ref 是否被目标接口接受，以及是否缺少 extra=”forbid”、strict 等约束。

适用环境：Issue 中已确认使用 OpenAI Python SDK 与 Pydantic；用户示例使用 MathResponse.model_json_schema() 导出 JSON Schema，并尝试保存到数据库。Issue 未提供确认的操作系统、Python 版本、CUDA、显卡或具体依赖版本，因此这些项目不要臆测。

最快修复方案：暂无确认的一步修复方案。可优先尝试在 Pydantic 模型上设置 model_config = ConfigDict(extra="forbid")，保持字段为必填，再用 json.dumps() 序列化 model_json_schema() 的结果，并通过 responses.create() 的 text.format 传入 type="json_schema"、name 与 strict=True。

注意事项：该方案来自 Issue 维护者的收尾回复，能处理提问中的嵌套示例，但并未提供可复现的最小验证日志。Issue 中另有用户指出 openai.resources.responses.responses._type_to_text_format_param 能生成更适合 Responses API 的 schema，但这属于内部实现，不是官方公开接口，存在随版本变化的风险，不建议作为长期稳定方案。

问题场景

用户在 OpenAI Python SDK 中为每个用户单独准备 JSON Schema，并希望用 Pydantic 模型来生成、管理和存储这些 schema。由于 schema 约有 350 个键且嵌套层级较深，手写 JSON 难以阅读和编辑，因此用户尝试用 Schema.model_json_schema() 把 Pydantic 模型转换为 JSON Schema，再保存到数据库，并在请求 Responses API 时使用 Structured Outputs。过程中出现了 Pydantic 与 JSON Schema 需要升级/适配的问题。

报错原文

Pydantic and JSON schemas need upgrade

原因分析

最可能的原因是 Pydantic 默认导出的 JSON Schema 与 OpenAI Structured Outputs 所需的 schema 约束不完全一致。例如：Pydantic 默认会为字段生成 title，嵌套模型会被拆到 $defs 并通过 $ref 引用；而 Structured Outputs 虽然支持 $defs 和 $ref，但对对象是否允许额外属性、字段是否必填、以及 strict 模式有额外要求。

Issue 中的用户还提到，把 Pydantic 对象直接存数据库不现实，因此必须先转成 JSON。如果导出的 schema 没有设置 extra="forbid"，或者没有按 text.format 的 json_schema 结构包装，就可能在发送给 API 时被拒绝或无法得到预期结构化输出。

环境排查

确认 OpenAI Python SDK 版本，确保使用的 responses.create() 与 text.format 参数在当前版本中可用。
确认 Pydantic 版本，并确认 model_json_schema() 的导出行为；Issue 中未给出具体版本号，因此不要照搬未经验证的版本。
确认模型字段是否全部为必填，或是否符合 Structured Outputs 对 required 的要求。
确认嵌套模型是否设置 extra="forbid"，避免导出后包含 additionalProperties: true 或缺少该约束。
确认最终传给 API 的 schema 是否放在 text.format 中，并带有 type="json_schema"、name、strict=True。
如果使用 Issue 中提到的内部函数 _type_to_text_format_param，需确认当前 SDK 版本中该路径是否存在，并接受其非公开接口带来的升级风险。

解决步骤

在 Pydantic 模型上增加配置，禁止额外字段。Issue 维护者建议对示例中的两个模型都设置 model_config = ConfigDict(extra="forbid")。
保持模型字段 required，避免导出的 schema 中出现可选字段与 Structured Outputs 的严格模式冲突。
使用 MathResponse.model_json_schema() 导出 schema，并用 json.dumps() 序列化，以便保存到数据库或作为请求参数传递。
调用 responses.create() 时，通过 text.format 传入结构化输出配置：type="json_schema"、name、strict=True，并把上一步得到的 schema 放入对应字段。
如果上述公开接口方式仍失败，可优先尝试 Issue 中用户提到的 _type_to_text_format_param 生成 schema；但该函数位于 openai.resources.responses.responses 内部，不是稳定公开接口，升级 SDK 后可能失效，仅建议作为排错对照。
不要手动为每个用户逐字编写 350 个键的 JSON Schema；用 Pydantic 模型生成并存储 JSON 字符串，再在请求时读取该 JSON 字符串作为 schema。

验证方法

用一个最小嵌套模型（例如 Issue 中的 MathResponse）导出 schema，检查 JSON 中是否包含 $defs、$ref，并确认对象层没有允许额外属性。然后调用 responses.create()，观察是否仍返回 Pydantic/JSON schema 升级相关报错，以及返回内容是否符合 steps、final_answer 的结构。Issue 中维护者以该示例可通过公开接口处理为由关闭，但未附实际运行日志，因此验证时应以你自己的最小示例为准。