Pydantic AI项目中Gemini模型与JSON Schema兼容性问题解析

在Pydantic AI项目中，开发者在使用Gemini 2.5模型与MCP服务器交互时遇到了一个典型的JSON Schema兼容性问题。这个问题揭示了大型语言模型对JSON Schema规范支持程度的差异，值得开发者关注。

问题本质

当MCP服务器返回包含$schema字段的完整JSON Schema定义时，Gemini 2.5模型会拒绝处理并返回400错误。这是因为Gemini API仅支持OpenAPI Schema的一个子集，而$schema字段不在其支持范围内。

技术背景

JSON Schema规范允许通过$schema字段指定使用的schema版本，这是标准JSON Schema文档的常见做法。然而，许多AI模型API（包括Gemini）为了简化实现，往往只支持核心的JSON Schema特性，而忽略元数据字段。

解决方案

开发者可以通过以下方式解决此兼容性问题：

1. Schema后处理方案：继承MCP服务器类并重写工具列表获取方法，在返回前移除$schema字段。这种方案保持了原始MCP服务器的功能完整性，仅在最后一步进行适配。

2. 框架层修复：Pydantic AI项目已在内部实现了修复方案，通过预处理工具定义来确保与Gemini API的兼容性。

影响范围

值得注意的是，这个问题不仅限于Gemini 2.5模型，所有使用GoogleGLAProvider的模型在特定版本中都存在相同的限制。这提示我们在集成不同AI模型时，需要特别注意它们对JSON Schema的支持程度。

最佳实践建议

1. 当集成新的AI模型时，应首先测试其对JSON Schema各种特性的支持情况
2. 考虑在框架层面实现Schema转换层，自动适配不同模型的Schema要求
3. 对于关键业务场景，建议实现Schema验证和降级机制

这个问题展示了AI应用开发中一个常见挑战：不同组件对标准协议实现程度的差异。通过理解底层机制并采用适当的适配策略，开发者可以构建更加健壮的AI集成方案。