ankane/neighbor

Neighbor – Ruby on Rails 用的最近鄰搜尋

是什麼

• 一個 Ruby gem，為 ActiveRecord 模型加入基於向量的相似性搜尋功能。它讓您能在資料庫中儲存嵌入（或任何類型的數值向量），並使用常見的距離度量查詢 k 個最相近的記錄。

主要功能

• 即時支援多種資料庫：PostgreSQL（透過 pgvector 或 cube 擴充）、MariaDB、MySQL（HeatWave）、SQLite，以及 Redis 和 S3 向量的適配器。
• 支援多種距離函數：歐幾里得、餘弦、內積、曼哈頓、漢明、傑卡德等，依後端而定。
• 支援廣泛的向量類型：全精度（vector）、半精度（halfvec）、二進位（bit/bigint）、稀疏（sparsevec），以及 SQLite 的 int8 向量。
• 提供精確與近似索引（HNSW、IVFFlat），以加速大規模搜尋。
• 簡單的模型 API — 在 ActiveRecord 模型中加入 has_neighbors :embedding，然後在記錄或類別上直接呼叫 nearest_neighbors。
• 內建助手支援混合搜尋（關鍵字 + 語意）、稀疏搜尋，以及使用 Disco 庫的線上推薦。

如何使用

1. 新增 gem 到您的 Gemfile 並執行 bundle install。
2. 在遷移中建立向量欄位（:vector、:cube、:binary 等），與您使用的資料庫相符。
3. 在模型中宣告鄰居關係，使用 has_neighbors :embedding（可選地指定維度、類型或正規化）。
4. 填入嵌入 — 可透過外部 API（OpenAI、Cohere）或本地模型（Informers、Transformers.rb）完成。
5. 查詢：

   item.nearest_neighbors(:embedding, distance: "euclidean").first(5)
   # 或者
   Item.nearest_neighbors(:embedding, [0.9, 1.3, 1.1], distance: "cosine").first(5)
   

   結果包含 neighbor_distance 屬性。

為何重要

• 無需額外的向量資料庫，即可在 Rails 應用中直接實作語意搜尋、推薦與基於相似性的功能。
• 借由底層 SQL 引擎的原生索引能力，將資料與搜尋保留在同一系統中。
• 既適合研究（稀疏向量、半精度），也適合生產環境（近似索引、MySQL 的 HeatWave）。

典型使用情境

• 基於嵌入的文件或產品搜尋。
• 實時項目推薦。
• 混合關鍵字 + 語意檢索。
• 任何需要快速相似性查找的 Rails 服務。

資源

• 完整文件在 README 中，各支援後端皆有獨立章節。
• OpenAI、Cohere、Informers、混合搜尋、稀疏搜尋與 Disco 推薦的範例程式碼。
• 獨立適配器：neighbor-redis 與 neighbor-s3 用於非 SQL 儲存。

---

以上所有細節皆直接取自專案的 README。