Pydantic AI 与 Gemini API 交互时的 JSON Schema 兼容性问题分析

问题背景

Pydantic AI 是一个基于 Pydantic 的 AI 交互框架，它允许开发者使用 Python 类型注解来定义 AI 模型的输入输出结构。在最新版本（0.0.53及以上）中，用户报告了与 Google Gemini API 交互时出现的 JSON Schema 兼容性问题。

问题现象

当开发者使用 Pydantic AI 的 structured outputs 功能，并设置 instrument=True 参数创建 Gemini Agent 时，系统会生成不符合 Gemini API 要求的 JSON Schema。具体表现为：

1. Gemini API 拒绝接受包含 $defs 和 $ref 字段的 Schema
2. 同样拒绝接受包含 additionalProperties 字段的 Schema
3. 错误信息明确指出这些字段在 Gemini API 的 Schema 定义中不存在

技术分析

Schema 生成机制变化

在 Pydantic AI 0.0.52 及以下版本中，Schema 生成机制与 Gemini API 完全兼容。但从 0.0.53 版本开始，Schema 生成方式发生了变化：

1. 开始使用更标准的 JSON Schema 结构
2. 引入了 $defs 和 $ref 来实现 Schema 的复用和引用
3. 显式添加了 additionalProperties 控制字段

Gemini API 的限制

Gemini API 对工具函数声明中的参数 Schema 有严格要求：

1. 不支持 JSON Schema 的高级特性如 $defs 和 $ref
2. 不接受 additionalProperties 这样的元数据字段
3. 需要更扁平化的 Schema 结构

影响范围

该问题影响所有使用以下配置的用户：

1. 使用 Pydantic AI 0.0.53 及以上版本
2. 与 Gemini 系列模型交互（包括 gemini-2.0-flash 和 gemini-2.5-pro-exp-03-25）
3. 启用了结构化输出和工具函数（instrument=True）

临时解决方案

目前可行的临时解决方案是：

1. 降级到 Pydantic AI 0.0.52 版本
2. 等待官方修复并发布新版本

开发者建议

对于需要继续开发的用户，建议：

1. 在 requirements 中明确指定 pydantic-ai-slim[vertexai]==0.0.52
2. 避免在 Gemini 集成中使用 instrument=True 参数
3. 考虑使用其他兼容性更好的模型作为临时替代方案

未来展望

这个问题凸显了 AI 工具链中 Schema 兼容性的重要性。期待 Pydantic AI 团队能够：

1. 提供模型特定的 Schema 适配器
2. 增加对不同 API 规范的自动检测和适配
3. 完善文档中关于各模型兼容性的说明

该问题的解决将进一步提升 Pydantic AI 在多模型环境下的稳定性和可用性。