Spring AI 项目中整合 Vertex AI 模型与 JDBC 存储时的问题分析与解决方案

问题背景

在使用 Spring AI 1.0.0 版本与 Spring Boot 3.4.6 构建聊天应用时，开发者尝试将 Vertex AI 的 Gemini 模型与 MySQL 数据库存储结合使用时，遇到了应用启动失败的问题。核心错误表现为 NoClassDefFoundError: com/google/protobuf/GeneratedMessageV3，这表明系统在运行时无法找到 Protobuf 相关的关键类。

错误现象深度分析

当开发者配置了基于 JDBC 的聊天记忆存储库(JdbcChatMemoryRepository)并尝试启动应用时，控制台输出了详细的错误堆栈。从技术角度来看，这个问题的根源不在于 JDBC 存储配置本身，而是与 Vertex AI 模型依赖的 Protobuf 库版本冲突有关。

错误堆栈显示，系统在初始化 VertexAiGeminiChatModel 时失败，具体是在尝试加载 Protobuf 的 GeneratedMessageV3 类时发生了类找不到异常。这种情况通常发生在：

1. 依赖项中缺少必要的 Protobuf 库
2. 项目中存在多个版本的 Protobuf 库导致冲突
3. 类加载器无法正确加载所需的类

根本原因

经过对示例项目的依赖分析，发现项目中同时引入了两个不同版本的 Protobuf 库：

• protobuf-java 4.26.1
• protobuf-java 3.25.5

这种版本冲突导致了运行时类加载失败。Protobuf 的不同主版本间存在二进制不兼容性，特别是 GeneratedMessageV3 类在不同版本中的实现可能有显著差异。

解决方案

方案一：统一 Protobuf 版本

最彻底的解决方案是统一项目中的 Protobuf 依赖版本。可以通过以下步骤实现：

1. 在 build.gradle 中显式声明 Protobuf 版本：

configurations.all {
    resolutionStrategy {
        force 'com.google.protobuf:protobuf-java:4.26.1'
    }
}

2. 运行 ./gradlew dependencies 命令验证所有依赖是否使用了统一的 Protobuf 版本

方案二：升级 Spring Boot 版本

根据开发者反馈，该问题在 Spring Boot 3.5.0 中已不复存在。这是因为新版本的 Spring Boot 可能已经更新了相关依赖，解决了版本冲突问题。

升级 Spring Boot 版本的步骤：

1. 修改 build.gradle 中的 Spring Boot 版本号
2. 重新同步项目依赖
3. 清理并重建项目

方案三：排除冲突依赖

如果无法立即升级 Spring Boot，可以尝试排除冲突的依赖：

implementation('org.springframework.ai:spring-ai-vertex-ai-gemini') {
    exclude group: 'com.google.protobuf', module: 'protobuf-java'
}

最佳实践建议

1. 依赖管理：在大型项目中，始终使用 dependencyManagement 或 BOM 文件来统一管理依赖版本
2. 冲突检测：定期使用 gradle dependencies 或 mvn dependency:tree 检查依赖冲突
3. 版本兼容性：在选择 Spring AI 和 Spring Boot 版本时，参考官方文档的兼容性矩阵
4. 环境一致性：确保开发、测试和生产环境使用相同的依赖版本

技术原理延伸

Protobuf (Protocol Buffers) 是 Google 开发的一种高效的数据序列化格式。在 Spring AI 与 Vertex AI 集成时，Protobuf 用于：

1. 模型配置的序列化与反序列化
2. 客户端与服务器间的通信协议
3. 模型参数的内部表示

当不同版本的 Protobuf 库共存时，由于序列化格式和内部API的变化，可能导致运行时错误。特别是 GeneratedMessageV3 作为核心基类，其变化会影响所有生成的 Protobuf 消息类。

总结

在 Spring AI 项目中整合 Vertex AI 模型与 JDBC 存储时遇到的启动问题，本质上是依赖管理问题而非功能实现问题。通过统一 Protobuf 版本或升级 Spring Boot 版本可以有效解决。这也提醒我们在引入多个AI相关依赖时，需要特别注意底层库的版本兼容性。良好的依赖管理实践是构建稳定AI应用的基础。