Google Generative AI Python SDK 中 Pydantic 模型 JSON Schema 问题的分析与解决

问题现象

在使用 Google Generative AI Python SDK 时，开发者尝试将 Pydantic 的 BaseModel 或 typing_extensions 的 TypedDict 作为 response_schema 传递给 model.generate_content_async 方法时，会遇到错误提示："type object 'dummy' has no attribute 'model_json_schema'"。

问题分析

这个错误表明 SDK 在尝试访问模型类的 model_json_schema 属性时失败。经过深入分析，我们发现这主要与以下几个因素有关：

1. Pydantic 版本兼容性问题：不同版本的 Pydantic 在 JSON Schema 生成方式上有显著差异。特别是从 Pydantic 1.x 升级到 2.x 版本后，许多内部接口发生了变化。

2. 环境依赖冲突：在某些开发环境中，可能存在多个 Python 包的版本冲突，导致 Pydantic 无法正确暴露其 JSON Schema 生成功能。

3. 异步上下文问题：在 Jupyter Notebook 或 Google Colab 等环境中，异步函数的执行可能会遇到特殊限制。

解决方案

方案一：升级 Pydantic 版本

将 Pydantic 升级到 2.x 版本可以解决大多数兼容性问题：

pip install --upgrade pydantic

方案二：检查环境依赖

创建一个干净的虚拟环境并重新安装依赖：

python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate  # Windows
pip install google-generativeai pydantic

方案三：使用替代执行环境

如果在 Colab 中遇到问题，可以尝试：

1. 使用 Kaggle Notebook
2. 在本地 Python 环境中运行
3. 将异步调用改为同步调用测试

最佳实践建议

1. 明确指定 Pydantic 版本：在 requirements.txt 或 pyproject.toml 中固定 Pydantic 版本。

2. 验证环境配置：在代码中添加环境检查：

import pydantic
print(f"Pydantic version: {pydantic.__version__}")

3. 逐步排查：先使用简单的 Pydantic 模型测试，确认功能正常后再引入复杂模型。

4. 错误处理：在调用 generate_content_async 时添加适当的异常捕获和处理逻辑。

技术背景

Pydantic 2.0 对 JSON Schema 生成进行了重大改进，采用了更标准化的实现方式。Google Generative AI Python SDK 依赖于这些标准化接口来验证和转换响应数据结构。当这些接口不可用时，SDK 就无法正确解析开发者提供的模型类。

理解这一机制有助于开发者更好地诊断和解决类似的结构化输出问题，特别是在使用现代 Python 类型提示和验证库与 AI 服务集成时。