ResponseFunctionWebSearch doesn’t match returned payload

问题场景

用户通过 OpenAI Python SDK 解析一次包含多次 web search 的响应。代码遍历 response.raw_responses 中的输出条目，筛选 type == "web_search_call" 的项，并直接访问 item.action.type == "search"，用于统计搜索次数。报错发生在库的类型定义与服务器实际返回的 JSON 载荷不一致时：类型上 action 被定义为存在，但实际 payload 中出现了 action=None。

报错原文

ResponseFunctionWebSearch doesn't match returned payload

相关载荷示例：

ResponseFunctionWebSearch(
    id='ws_...264', 
    action=None, 
    status='completed', 
    type='web_search_call'
)

以及触发属性访问失败的代码：

search_count = sum(
    1
    for raw_response in response.raw_responses
    for item in raw_response.output
    if item.type == "web_search_call" and item.action.type == "search"
)

原因分析

可能原因是：openai-python 生成的类型定义承诺 ResponseFunctionWebSearch.action 存在，但实际 API 返回的载荷中该字段可能为 None，导致按类型安全假设直接访问 .type 时失败。Issue 评论指出，Python 侧的类型表示无法区分“字段被省略”和“JSON 中显式为 null”，这一区分被跟踪到 openai/openai-openapi#572。因此这更可能是上游 OpenAPI 规范与 Python 类型生成之间的契约不一致，而不是单纯的本地脚本写法问题。

环境排查

• 确认使用的 OpenAI Python SDK 版本是否为 Issue 中提到的 2.32；不同版本的类型定义可能不同。
• 确认 Python 版本；Issue 中报告为 3.14。
• 确认操作系统；Issue 中为 Windows 11。
• 确认调用路径：是否通过 Agents SDK 使用，还是直接使用 openai-python 客户端；Issue 中报错来自 Agents SDK 场景。
• 确认返回载荷中 web_search_call 条目的 action 字段是否存在、是否为 None，以及是否为省略或显式 null。
• Issue 未提供 CUDA、显卡、PyTorch 或依赖版本信息，这些项无法从当前讨论链确认，不应作为必查项。

解决步骤

1. 在遍历 raw_response.output 时，不要直接访问 item.action.type。
2. 可优先尝试的缓解写法：先判断 item.action is not None，再访问 item.action.type。
3. 如果业务上需要区分“字段省略”与“显式为 null”，需要等待上游 openai/openai-openapi#572 的规范澄清；当前 Python 类型表示可能无法单独完成区分。
4. 关注 openai/openai-python#3179 中提到的后续修复进展；Issue 已关闭并合并到 openai/openai-openapi#572 继续跟踪。

验证方法

在对 action 增加空值判断后，重新运行原先的统计代码。如果不再因为 item.action.type 抛出属性错误，说明本地规避生效。若要确认类型契约是否已修复，应检查 openai/openai-openapi#572 的进展，并确认后续版本的 openai-python 中 ResponseFunctionWebSearch.action 的类型定义是否已反映省略或 null 的实际行为。

参考来源

openai/openai-python #3179

openai/openai-openapi #572

AI 工具推荐

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

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

了解 GamsGo AI

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