LanceDB Python客户端中Ollama嵌入函数的序列化问题分析

LanceDB作为一款高效的向量数据库，在其Python客户端中提供了多种嵌入函数支持。最近在使用Ollama嵌入函数时发现了一个值得注意的技术问题，本文将深入分析问题原因并提供解决方案。

问题现象

当开发者尝试使用Ollama嵌入函数创建表时，会遇到"Client对象不可JSON序列化"的错误。具体表现为：

model = get_registry().get("ollama").create(name='Losspost/stella_en_1.5b_v5')
table = await async_db.create_table("cases", exist_ok=True, schema=Cases)

执行上述代码会抛出TypeError，提示Ollama的Client对象无法被JSON序列化。

根本原因分析

经过深入排查，发现问题源于LanceDB内部处理嵌入函数元数据的方式。当创建表时，系统会尝试将嵌入函数配置序列化为JSON格式存储为表元数据。在Ollama嵌入函数实现中，存在几个关键设计点导致了这个问题：

1. 客户端缓存机制：OllamaEmbeddings类使用@cached_property装饰器缓存_ollama_client实例
2. 提前初始化：调用model.ndims()方法会触发_ollama_client的初始化
3. 序列化包含：嵌入函数配置被完整序列化时包含了不可序列化的Client对象

相比之下，OpenAI嵌入函数实现没有这个问题，因为其_openai_client不会在ndims()调用时被初始化。

解决方案探讨

针对这个问题，我们提出了几种可能的解决方案：

1. 移除缓存装饰器：最简单的方案是将@cached_property改为@property，但这会影响性能
2. 定制序列化逻辑：修改safe_model_dump方法，自动排除以下划线开头的属性或缓存属性
3. 延迟初始化：重构ndims()实现，避免在序列化前初始化客户端

经过评估，第二种方案最为合理，因为它：

• 保持性能优化（仍然使用缓存）
• 具有更好的通用性（处理所有类似情况）
• 符合Python惯例（通常下划线前缀表示内部属性）

实现建议

在实际实现中，我们建议在EmbeddingFunction基类中重写序列化方法：

def safe_model_dump(self):
    # 排除以下划线开头的属性
    return {k: v for k, v in self.model_dump().items() if not k.startswith('_')}

这种实现方式既解决了当前问题，又为未来可能出现的类似情况提供了统一的处理机制。

总结

这个问题揭示了在设计和实现可序列化组件时需要特别注意的几个方面：

1. 缓存机制与序列化的兼容性
2. 属性初始化的时机控制
3. 内部状态与持久化状态的分离

通过这个案例，我们学习到在设计类似系统时，应该提前考虑组件的序列化需求，并建立适当的属性过滤机制。这不仅适用于LanceDB，对于任何需要将复杂对象序列化的Python项目都有参考价值。