[Bug]: pydantic.errors.PydanticUserError: `Message` is not fully defined

问题场景

用户使用 LiteLLM Python SDK，在直接实例化 `ModelResponse` 对象（内部会自动创建 `Choices` 与 `Message` 等嵌套模型）时，Pydantic 抛出运行时错误，导致程序崩溃。该问题也发生在调用 `litellm.completion`（其内部会构造 `ModelResponse`）的链路上。

报错原文

pydantic.errors.PydanticUserError: `Message` is not fully defined; you should define `ChatCompletionReasoningSummaryTextBlock`, then call `Message.model_rebuild()`.

原因分析

可能原因是 LiteLLM 1.97.0rc1 的数据类型模块中存在 Pydantic 模型间的循环引用。当 Pydantic 尝试实例化 `Message` 时，发现其字段引用的 `ChatCompletionReasoningSummaryTextBlock` 尚未完成定义，因此无法完成校验器构建。这类问题常见于新增了互相引用的模型、但缺少显式 `model_rebuild()` 调用，或模型定义顺序不当的候选版本中。从报错栈看，问题在 `Message()` 的初始化阶段即被触发，并非运行时的数据校验错误。

环境排查

• 确认 Python 版本：Issue 中明确复现环境为 Python 3.10。
• 确认 LiteLLM 版本：锁定为 1.97.0rc1。
• 排查 Pydantic 版本：Issue 未明确给出，但其报错信息格式与 Pydantic v2 的提示风格一致，建议确认是否使用了 Pydantic v2 及其兼容版本。
• 确认触发路径：无论是直接构造 `ModelResponse()`，还是通过 `litellm.completion` 间接触发，均会导致同样的崩溃。

解决步骤

1. 最直接的规避方式（可优先尝试）：停止使用 LiteLLM 1.97.0rc1 候选版本，降低版本至该候选版之前的稳定版（例如 1.96.x 系列），或升级到已包含此修复的更新版本。
2. 检查依赖组合：确认当前环境中的 Pydantic 主版本（v1 或 v2）。如果 Pydantic 版本与 LiteLLM 1.97.0rc1 的预期不匹配，可以尝试将 Pydantic 升级或降级到与该 LiteLLM 版本兼容的已知版本，但 Issue 中未给出具体验证过的版本号。
3. 临时绕过（未验证，谨慎使用）：如果暂时无法更换 LiteLLM 版本，可尝试在实例化 `ModelResponse` 之前，先手动导入并触发相关模型的重建。Issue 报错提示建议调用 Message.model_rebuild()，但这需要先确保其所依赖的 `ChatCompletionReasoningSummaryTextBlock` 已被定义。此操作不是 Issue 确认的解决方案，仅为报错提示中的指引。

验证方法

在更换或调整 LiteLLM 版本后，重新运行之前崩溃的代码路径：直接构造 ModelResponse 实例，或触发一次 `litellm.completion` 请求。如果实例能够成功创建且不再抛出 `PydanticUserError`，则说明问题已解决。

参考来源

BerriAI/litellm #36384

AI 工具推荐

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

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

了解 GamsGo AI

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