Google Generative AI Python SDK 中 Pydantic 响应模式不一致问题解析

在 Google Generative AI Python SDK 的使用过程中，开发者发现当使用 Pydantic 模型定义响应模式时，与直接使用字典定义相比，存在明显的响应不一致问题。本文将深入分析这一现象的技术原因，并提供解决方案。

问题现象

开发者在使用 Gemini-1.5-flash 模型生成幻灯片内容时，定义了如下的 Pydantic 模型：

class SlideSchema(BaseModel):
    header: str
    subheader: str | None
    body: str | None
    image: str | None
    teachers_notes: str | None

当使用这个 Pydantic 模型作为响应模式时，成功率仅为 20% 左右。然而，当改用字典形式明确定义响应模式时，成功率提升至 100%。

技术分析

经过深入调查，发现问题的根源在于 SDK 内部对 Pydantic 模型的转换处理不够完善。具体表现为：

1. required 字段缺失：当 Pydantic 模型被转换为内部模式时，缺少了对必填字段的明确声明
2. nullable 处理不一致：虽然可空字段被正确标记为 nullable，但整体模式验证不够严格

通过检查 SDK 源码可以发现，Pydantic 模型最终被转换为如下结构：

{
    'items': {
        'properties': {
            'header': {'type': 'string'},
            'subheader': {'type': 'string', 'nullable': True},
            'body': {'type': 'string', 'nullable': True},
            'image': {'type': 'string', 'nullable': True},
            'teachers_notes': {'type': 'string', 'nullable': True}
        },
        'type': 'object'
    },
    'type': 'array'
}

而手动定义的字典模式则包含了更完整的验证信息，特别是包含了 required 字段的声明：

{
    'type': 'ARRAY',
    'items': {
        'type': 'OBJECT',
        'properties': {
            'header': {'type': 'STRING', 'nullable': False},
            'subheader': {'type': 'STRING', 'nullable': True},
            'body': {'type': 'STRING', 'nullable': True},
            'image': {'type': 'STRING', 'nullable': True},
            'teachers_notes': {'type': 'STRING', 'nullable': True}
        },
        'required': ['header', 'subheader', 'body', 'image', 'teachers_notes']
    }
}

解决方案

目前开发者可以采取以下两种解决方案：

1. 临时解决方案：继续使用字典形式明确定义响应模式，虽然代码可读性稍差，但能确保稳定性
2. 长期解决方案：等待 SDK 更新修复此问题，或者考虑迁移到新版 Gemini-2+ SDK，该版本已对此问题进行了改进

最佳实践建议

1. 在关键业务场景中，建议暂时使用字典形式定义响应模式
2. 对于复杂模式，可以先通过 Pydantic 模型定义数据结构，然后手动转换为字典形式
3. 定期检查 SDK 更新日志，关注此问题的修复进展

总结

这个问题反映了 SDK 在 Pydantic 模型支持方面的不足，特别是在模式转换过程中对字段必填性的处理不够完善。开发者需要根据实际需求选择最适合的解决方案，同时关注 SDK 的后续更新。