pydantic-ai项目中Gemini函数调用与字典字段处理的优化实践

在Python生态系统中，pydantic-ai作为连接Pydantic模型与大型语言模型(LLM)的重要桥梁，其功能调用能力为开发者提供了极大便利。本文将深入探讨pydantic-ai在处理Gemini函数调用时遇到的字典字段转换问题及其解决方案。

问题背景

当开发者尝试使用pydantic-ai与Gemini的函数调用功能时，会遇到一个典型问题：Gemini对JSON Schema有着严格要求，特别是明确禁止使用additionalProperties关键字。而Pydantic模型中常见的Dict[K, V]类型字段会自动生成包含additionalProperties的JSON Schema，这直接导致Gemini拒绝接受此类模式。

技术挑战

开发者最初采用的解决方案是创建一个动态模型适配器(GeminiModelAdapter)，该适配器执行以下关键操作：

1. 识别所有标注为Dict[K, V]的字段
2. 将这些字段类型替换为List[KeyValuePair]结构
3. 通过json_schema_extra强制指定正确的数组模式
4. 使用ConfigDict(extra="forbid")配置动态模型

虽然这种方案在Pydantic层面生成的JSON Schema看起来完全正确——字段类型被正确表示为数组，且不包含additionalProperties——但当通过pydantic-ai传递给Gemini时，系统仍会报错提示不支持JSON Schema中的附加属性。

问题本质分析

深入研究发现，问题并非出在Pydantic的模型转换或Schema生成上，而是pydantic-ai内部在处理动态创建的模型时，会对Schema进行二次处理。这个内部处理过程会错误地重新引入additionalProperties属性，即使原始Schema中已经明确移除了这些属性。

值得注意的是，当使用静态定义的Pydantic模型时，即使包含List[KeyValuePair]结构，系统也能正常工作。这表明问题特定于动态创建的模型处理流程。

官方解决方案

pydantic-ai开发团队已经意识到这一问题，并在最新版本中实现了自动化的JSON Schema转换功能。新版本能够智能地将Schema转换为Gemini兼容的格式，开发者不再需要手动实现复杂的模型适配逻辑。

这一改进意味着：

1. 开发者可以直接使用标准的Pydantic模型，包括Dict[K, V]字段
2. 无需编写额外的适配器代码或进行复杂的字段类型转换
3. pydantic-ai会在内部自动处理所有Schema兼容性问题
4. 系统稳定性得到提升，减少了因Schema处理不当导致的错误

实践建议

对于正在使用或计划使用pydantic-ai与Gemini集成的开发者，建议：

1. 升级到最新版本的pydantic-ai以获取自动Schema转换功能
2. 简化模型定义，避免不必要的动态模型创建
3. 对于复杂的数据结构，优先考虑使用Pydantic的标准模型定义方式
4. 在遇到Schema相关问题时，首先检查pydantic-ai版本是否为最新

这一改进显著降低了使用门槛，使开发者能够更专注于业务逻辑的实现，而非底层Schema兼容性问题。