rryam/VecturaKit

VecturaKit – Swift 应用的设备端向量数据库

是什么 – VecturaKit 是一个 Swift 库，允许 iOS、macOS、watchOS、tvOS 和 visionOS 应用将文本文档以向量嵌入的形式本地存储在设备上。它提供常规的向量数据库功能（添加、更新、删除、搜索），并支持混合 BM25 + 向量搜索，且完全在设备端运行，确保数据不会离开用户的硬件。

核心功能

• 可插拔嵌入器 – 您可以插入任何符合 VecturaEmbedder 协议的嵌入器。该包自带：
  • NLContextualEmbedder – 使用 Apple 的 NaturalLanguage 框架（零外部依赖）。
  • OpenAICompatibleEmbedder – 与任何 /v1/embeddings API 通信（例如 OpenAI、Ollama、LM Studio）。
  • SwiftEmbedder（通过独立的 VecturaEmbeddingsKit）– 运行 swift-embeddings 模型，如 Model2Vec、BERT、RoBERTa 等。
  • MLXEmbedder（通过 VecturaMLXKit）– 在 Apple MLX 上实现 GPU 加速嵌入。
• 混合搜索 – 将向量的余弦相似度与 BM25 文本评分结合；两者之间的权重可配置。
• 自定义存储与搜索 – 您可以通过遵循 VecturaStorage 协议提供自己的存储后端（SQLite、Core Data、云等），并通过遵循 VecturaSearchEngine 协议替换搜索算法。
• 内存策略 – 支持自动、全内存或按需加载文档的索引模式，适用于从几百到数百万条记录的场景。
• CLI 工具 – vectura-cli（NaturalLanguage）和 vectura-oai-cli（OpenAI 兼容）让您可以通过命令行进行实验。

典型使用流程

1. 配置 一个 VecturaConfig（名称、可选自定义目录、搜索选项、内存策略）。
2. 创建嵌入器 – 例如：let embedder = try await NLContextualEmbedder(language: .english)。
3. 实例化数据库 – let db = try await VecturaKit(config: config, embedder: embedder)。
4. 添加文档 – await db.addDocuments(texts: [...])（批量处理是并行化的）。
5. 搜索 – await db.search(query: "some query", numResults: 5) 返回一个 VecturaSearchResult 数组，包含 id、文本、相似度分数和时间戳。
6. 管理文档 – 更新、删除、按 id 获取，或重置整个数据库。

为何重要

• 隐私优先：所有嵌入和索引都在本地完成；适用于需要语义搜索但不希望将用户数据发送到云端的应用。
• Swift 原生：除非您选择 OpenAI 兼容嵌入器，否则无需桥接到 Python 或外部服务。
• 可扩展：插件架构允许您在不修改应用其他部分的情况下，替换为新的嵌入模型或自定义排序逻辑。

快速开始 通过 Swift Package Manager 添加包：

.dependencies: [
    .package(url: "https://github.com/rryam/VecturaKit.git", from: "6.3.0"),
]

然后导入 VecturaKit（以及可选的 VecturaNLKit 或 VecturaOAIKit），并按照 README 中的快速入门代码示例操作。

文档与社区

• 详细指南位于 Docs/ 目录中（索引存储、性能基准）。
• 嵌入模型专用包（VecturaEmbeddingsKit）和 MLX 加速包（VecturaMLXKit）。
• 提供开源许可证（MIT）和贡献指南。

---

总结 – VecturaKit 是一个真正的、可投入生产的 Swift 向量数据库，专为设备端 AI/ML 工作负载设计，提供灵活的嵌入后端、混合搜索以及自定义存储或排序的可扩展性。