ADK-Python 项目中图像处理引发的 JSON 序列化问题解析

在 ADK-Python 项目开发过程中，开发者遇到了一个典型的 JSON 序列化问题。当尝试通过 API 发送包含图像的请求时，系统会抛出"Object of type bytes is not JSON serializable"错误。这个问题揭示了在 Python 开发中常见的数据类型转换挑战。

问题本质分析

该问题的核心在于 Python 的 JSON 序列化机制。JSON 标准仅支持有限的数据类型，包括字符串、数字、布尔值、数组、对象和 null。而 Python 中的 bytes 类型（二进制数据）并不在 JSON 可序列化的类型范围内。

在 ADK-Python 项目中，当用户尝试发送包含 PNG 图像的请求时，系统需要将这些二进制图像数据存储到数据库中。数据库会话服务尝试使用 json.dumps() 方法将包含二进制数据的消息内容序列化为 JSON 字符串，但由于 bytes 类型不可序列化，导致操作失败。

技术背景

SQLAlchemy 作为 Python 中广泛使用的 ORM 工具，在处理复杂数据类型时通常会使用类型转换器（TypeDecorator）。在 ADK-Python 的数据库会话服务中，开发团队已经实现了 process_bind_param 方法来处理数据绑定，但未完全考虑到二进制数据的特殊情况。

解决方案演进

项目维护者最初建议了两个临时解决方案：

1. 使用内存会话（in-memory session）替代数据库会话，避免序列化问题
2. 采用托管会话 Agent Engine，这是一个更完整的解决方案

在后续版本中，开发团队已经修复了这个问题。修复方案可能包括以下几种技术选择之一：

• 对二进制数据进行 Base64 编码转换，使其成为可序列化的字符串
• 在数据库模型层实现自定义的类型处理器，专门处理二进制数据
• 修改事件存储结构，将二进制数据单独存储而非直接 JSON 序列化

类似问题的扩展

值得注意的是，这类序列化问题不仅限于图像数据。如另一位开发者报告的案例所示，当尝试序列化 Protobuf 生成的 RevisionTemplate 对象时，也会遇到类似的错误。这表明在复杂系统开发中，类型序列化是一个需要统一考虑的设计问题。

最佳实践建议

对于开发者而言，处理类似问题时可考虑以下实践：

1. 在设计数据模型时，提前考虑所有可能的数据类型及其序列化需求
2. 对于二进制数据，优先考虑使用专门的存储字段或转换机制
3. 实现全面的类型检查和处理逻辑，避免运行时错误
4. 在 API 边界处进行严格的数据验证和转换

ADK-Python 项目对这个问题的解决过程展示了开源项目中典型的问题处理流程：问题报告、临时解决方案提供、最终修复发布。这也体现了良好项目维护的重要性。