Semantic Kernel 中向量数据库批量插入操作的API设计思考

在开发 Semantic Kernel 项目的向量数据库抽象层时，团队针对批量插入操作(UpsertBatchAsync)的API设计进行了深入讨论。本文将全面剖析这一技术决策背后的思考过程，帮助开发者理解现代.NET应用中数据库抽象层的设计考量。

背景与问题

在构建向量数据库抽象层时，批量插入操作是一个核心功能。最初的设计采用了IAsyncEnumerable作为返回值类型，这主要是为了支持数据库自动生成ID的场景。然而，这种设计在实际使用中暴露出了一些问题：

1. 开发者体验不够友好 - 即使不关心返回的ID，也必须显式消费返回的IAsyncEnumerable
2. 需要额外依赖System.Linq.Async包才能方便地处理返回值
3. 可能导致开发者忽略等待操作完成，类似忘记await的问题

技术调研发现

通过对多种数据库系统的调研，团队发现：

• 支持自动生成ID的数据库包括：MongoDB、CosmosDB、Milvus、Weaviate等非关系型数据库，以及PostgreSQL、SQL Server等关系型数据库
• 不支持自动生成ID的数据库包括：Azure AI Search、Chroma、Qdrant等
• 内存数据库(InMemory)和部分专用向量数据库要求必须提供ID

这一发现改变了最初"只有关系型数据库支持自动ID生成"的假设，证明了该功能在多种数据库中的普遍性。

API设计权衡

团队考虑了多种设计方案：

1. 保持IAsyncEnumerable：保持现有设计，但改善开发者体验

   • 优点：保持灵活性，支持流式返回
   • 缺点：使用复杂，可能被误用

2. 改为IReadOnlyList：

   • 优点：简化使用，更符合大多数场景
   • 缺点：失去流式处理能力

3. 完全不支持自动ID生成：

   • 优点：简化API，避免复杂性
   • 缺点：限制功能，未来难以扩展

经过讨论，团队决定采用IReadOnlyList方案，因为：

• 自动生成的ID通常数量不大，流式处理价值有限
• 大多数情况下开发者更关注操作完成而非逐个获取ID
• 简化API能显著改善开发者体验

幂等性问题

自动ID生成带来了一个重要的幂等性问题：在非原子性操作的数据库中，重试批量插入可能导致重复记录。团队决定：

• 不限制功能，但明确文档说明风险
• 让开发者根据具体数据库特性决定是否使用该功能
• 对于需要严格幂等性的场景，建议使用单条插入而非批量

实现建议

基于这些讨论，团队确定了以下实现方向：

1. 修改UpsertBatchAsync返回类型为IReadOnlyList
2. 在记录定义中添加AutoGenerated标志
3. 各数据库连接器按需实现自动ID生成
4. 提供清晰的文档说明幂等性限制

总结

在Semantic Kernel的向量数据库抽象层设计中，批量插入操作的API演变展示了现代.NET开发中的典型权衡过程。通过深入分析实际需求和技术限制，团队找到了既保持功能完整性又优化开发者体验的平衡点。这一决策不仅解决了眼前的问题，也为未来的扩展奠定了基础。

对于.NET开发者而言，这一案例也提供了有价值的启示：API设计不仅要考虑技术可能性，更要关注实际使用场景和开发者体验，在灵活性和易用性之间找到最佳平衡。