jeffhajewski/latticedb

LatticeDB – 嵌入式圖＋向量資料庫

是什麼 – LatticeDB 是一個單檔案嵌入式屬性圖資料庫，同時儲存密集向量與全文索引。它讓本地程式能使用單一 Cypher 風格的查詢語言，透過關係遍歷、向量相似性或 BM25 文字搜尋來查詢相同資料。

對 AI 為何重要 – 現代 AI 應用（RAG 流程、代理記憶、本地知識庫）通常需要三樣東西：

1. 圖結構 用來建模實體及其關係。
2. 語意嵌入 用於相似性搜尋。
3. 關鍵字搜尋 用於精確文字匹配。 LatticeDB 在一個引擎中提供全部三項功能，無需再拼接獨立的圖資料庫、向量資料庫與搜尋服務。

主要特色（來自 README）

• 單檔案儲存 – 整個資料庫位於可攜式檔案中；無需伺服器，無需設定。
• 統一查詢層 – Cypher 支援 MATCH、WHERE、RETURN，並新增兩個運算子：
  • <=> 用於向量屬性上的餘弦距離。
  • @@ 用於 BM25 全文搜尋。
• 原生 HNSW ANN – 可設定參數的近似最近鄰搜尋，可在 100 萬向量上實現 10-NN 查詢，延遲低於 1 毫秒，召回率達 100%。
• BM25 倒排索引 – 快速詞法搜尋（100 筆文件約 19 µs），支援模糊匹配。
• ACID 交易 – 預寫日誌、崩潰復原、提交/回滾。
• 耐久性事件串流 – 命名變更流共享相同 WAL，適用於反應式代理。
• 綁定 – 提供 Python、TypeScript/Node、Go 與 Java（JDK 21+）的乾淨 C API 包裝。
• 零設定、單寫者模型 – 適合僅有一個程序寫入的本地優先應用。

效能亮點（提供基準測試）

操作	延遲	吞吐量
節點查找	0.13 µs	7.9 M ops/s
10-NN 向量搜尋（100 萬向量）	0.83 ms（平均）	1.2 k queries/s
2 跳圖遍歷（10 萬個節點）	39 µs	–
BM25 全文搜尋（100 筆文件）	19 µs	53 k ops/s
這些數字在相同工作負載下與 FAISS、Weaviate、SQLite-FTS5、Neo4j 等流行替代方案相當或更優，且完全嵌入式。

安裝

• CLI – curl …/install.sh | bash
• Python – pip install latticedb
• Node – npm install @hajewski/latticedb
• Java – 透過 Maven/Gradle 使用 bindings/java 模組（需 JDK 21）
• Go – go get 後參閱 bindings/go/README.md

快速範例（Python）

from latticedb import Database
from latticedb.embedding import hash_embed

with Database('knowledge.db', create=True, enable_vectors=True, vector_dimensions=128) as db:
    db.create_node_fts_index('Chunk', 'text')
    with db.write() as txn:
        alice = txn.create_node(labels=['Person'], properties={'name':'Alice'})
        doc   = txn.create_node(labels=['Document'], properties={'title':'Attention Is All You Need'})
        chunk = txn.create_node(labels=['Chunk'], properties={'text':'The transformer architecture uses self‑attention...'})
        txn.set_vector(chunk.id, 'embedding', hash_embed('transformer self‑attention', 128))
        txn.create_edge(chunk.id, doc.id, 'PART_OF')
        txn.create_edge(doc.id, alice.id, 'AUTHORED_BY')
        txn.commit()

    results = db.query(
        """MATCH (c:Chunk)-[:PART_OF]->(d:Document)-[:AUTHORED_BY]->(a:Person)
           WHERE c.embedding <=> $q < 0.5
           RETURN d.title, c.text, a.name
           ORDER BY c.embedding <=> $q LIMIT 5""",
        parameters={'q': hash_embed('attention mechanism', 128)}
    )
    for row in results:
        print(row['d.title'], 'by', row['a.name'])

相同模式在 TypeScript、Go 和 Java 中也適用，使用語言特定的綁定。

典型使用情境

• 本地知識圖譜 – 記事、研究論文、引用網絡，同時需要語意搜尋。
• 代理記憶 / RAG – 儲存帶嵌入的文本片段；代理可透過單一查詢取得相關內容。
• 原型開發 – 單機開發時，可取代重型客戶端-伺服器架構（Neo4j + Weaviate）。
• 嵌入式應用 – 無需伺服器的桌面或行動工具，需要圖結構資料。

應考慮其他方案的情況

• 需要 多寫者 或網路服務 – LatticeDB 僅支援單寫者。
• 工作負載主要為 表格型 – 關係型資料庫（SQLite、PostgreSQL）更簡單。
• 必須 跨多台機器擴展 – LatticeDB 設計為單程序、單機場景。

結論 – LatticeDB 是一個真正的開源專案，將圖、向量與全文搜尋整合為超輕量嵌入式引擎，是本地 AI 增強應用的實用建構模組。