Pydantic-AI项目中的Decimal类型JSON Schema生成问题解析

在Pydantic-AI项目中，开发者在使用Gemini API进行结构化输出解析时遇到了一个典型问题：当模型字段定义为Optional[decimal.Decimal]类型时，系统无法生成符合Gemini API要求的JSON Schema，导致请求被拒绝。本文将深入分析该问题的技术背景、产生原因及解决方案。

问题现象

开发者在定义包含Optional[decimal.Decimal]字段的Pydantic模型时，Gemini API返回400错误，提示"schema didn't specify the schema type field"。具体报错指向支付里程碑金额字段的Schema定义问题。

技术背景

1. Decimal类型特性
   Python的decimal.Decimal类型用于高精度浮点运算，在金融等领域应用广泛。与普通float不同，Decimal需要特殊处理以保证精度。

2. JSON Schema规范
   JSON Schema要求明确指定字段类型。Gemini API对Schema格式有严格要求，特别是对可选(Optional)字段的处理。

3. Pydantic的类型转换
   Pydantic在生成JSON Schema时会对Python类型进行映射，Optional类型会转换为包含null的anyOf结构。

问题根源分析

通过最小化复现案例发现：

• 对于Optional[decimal.Decimal]字段，Pydantic生成的Schema包含anyOf结构，其中包含number、string和null三种类型选项
• Gemini API不接受这种复合类型定义，特别是当anyOf中包含null类型时
• 相比之下，Optional[float]生成的Schema使用更简洁的"type": "number"加"nullable": true格式，能够被Gemini接受

解决方案

1. 临时解决方案
   将字段类型改为Optional[float]可以绕过问题，但会损失Decimal的高精度特性。

2. 根本解决方案
   Pydantic-AI团队修复了JSON Schema生成逻辑，使Optional[Decimal]字段也能生成Gemini兼容的Schema格式。具体改进包括：

   • 统一Optional类型的Schema表示方式
   • 确保生成的Schema符合Gemini API的严格校验要求
   • 保持Decimal类型的精度特性不被破坏

最佳实践建议

1. 在金融等需要高精度计算的场景，优先使用Decimal类型
2. 与Gemini等严格校验的API交互时，注意测试复杂类型的Schema生成结果
3. 及时更新Pydantic-AI到最新版本以获取类型处理改进
4. 对于关键业务字段，建议编写单元测试验证Schema生成结果

总结

这个问题展示了类型系统在API交互中的重要性。Pydantic-AI通过改进Schema生成逻辑，既保持了类型的精确性，又满足了外部API的格式要求，体现了其作为类型安全工具的价值。开发者在使用时应注意类型选择与目标API的兼容性，合理平衡功能需求与技术约束。