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 工作負載設計，提供靈活的嵌入後端、混合搜尋以及自訂儲存或排序的擴充性。