Periplus

Periplus

配x警告：Periplus在Alpha

Periplus目前在Alpha，尚未準備就緒。該項目正在積極開發中，並且不建議用於生產系統。

介紹

Periplus是建立在Meta的Vector相似性搜索庫Faiss上的開源內存矢量數據庫緩存。該項目最好被視為“ vector數據庫的重複”。它旨在將大型矢量集合的動態更新子集存儲在內存中，同時在查詢時，而無需在查詢時間與其他任何節點進行交互。當Periplus收到查詢時，它首先評估它是否具有索引居住的相關部分。如果確實如此，它將通過適當的響應解析查詢。如果沒有，它將返回緩存失誤，並讓Querier從數據庫中獲取數據。 Periplus並非設計用於隔離功能。取而代之的是，它旨在形成一個模塊化和靈活的緩存層，用於形成持久層的單獨矢量數據庫。這樣做的目的是使較低的延遲和易於水平縮放量表以增加吞吐量。有關Periplus背後的靈感及其工作方式的更詳細說明，您可以閱讀公告博客：介紹Periplus：矢量數據庫緩存的新方法。

它如何工作

Periplus使用倒文件索引（IVF）作為緩存管理的基礎。倒文件索引將矢量空間劃分為由一組質心向量定義的連續單元，其中每個單元被定義為接近其質心的區域，而不是其他任何質心。然後通過首先計算從查詢矢量到質心集的距離來解決查詢，然後僅搜索由N_probe （搜索超參數）最接近的質心定義的細胞。 Periplus通過在任何給定時間將這些單元的子集保留在居住中，而僅解決與該子集相關的查詢，同時拒絕與不像Cache失誤相關的居民，則利用了這一點。 Periplus一次載荷並驅逐整個IVF單元，以維持索引的完整性，並確保（在高速緩存命中）對標準IVF指數（在緩存命中）上進行等效召回。通過通過代理查詢矢量數據庫，其中periplus維護以跟踪哪些向量佔據了哪些細胞，從而加載了IVF單元。這些操作可以由用戶使用加載，搜索和驅逐命令來調用。有關詳細信息，請參見下面的“ Periplus命令”部分。

運行Periplus

Periplus可以作為Docker容器運行，也可以從源構建並作為可執行文件運行。目前沒有官方二進製文件。推薦的方法是運行Periplus作為容器，但兩者都是可行的選擇。

？作為容器運行Periplus

當前，Docker映像僅支持AMD64架構。這種約束源於基本圖像，但在不久的將來將支持更多的架構。有兩種將Periplus作為容器運行的方法：從Dockerhub（推薦）下載官方Docker映像或自己構建圖像。在任何一種情況下，第一步都是安裝Docker，如果您還沒有。這樣做的說明可以在這裡找到。

使用官方圖像

1. 通過運行下載圖像： docker image pull qdl123/periplus:latest 。
2. 運行容器： docker run -p 3000:3000 qdl123/periplus:latest

構建圖像

1. 克隆存儲庫： git clone https://github.com/QDL123/Periplus.git
2. CD到存儲庫根： cd <path-to-periplus-repo>/Periplus
3. 構建圖像： docker build -t periplus-image .
4. 運行容器： docker run -p 3000:3000 periplus-image .

從來源建造Periplus

Periplus使用CMAKE進行其構建系統。它預計所有依賴性都將通過自製的二進製文件進行預編譯。如果您在Windows上，則由MacOS，Ubuntu和WSL支持Homebrew。 Periplus已建立在MacOS/ARM64和Ubuntu/AMD64上。所有其他操作系統和架構組合都未經測試。要從源建立Periplus，請按照以下步驟：

1. 安裝自製：訪問官方自製網站以獲取安裝說明。
2. 安裝Periplus的依賴關係。要立即安裝它們，請運行： brew install faiss curl cpr rapidjson libomp catch2 cmake
3. 克隆存儲庫： git clone https://github.com/QDL123/Periplus.git
4. CD到存儲庫根： cd <path-to-periplus-repo>/Periplus
5. 生成makefile： cmake -S . -B build
6. 編譯可執行文件： cmake --build build
7. 運行periplus（在端口3000上聽）： ./build/periplus -p 3000

使用Periplus

使用Periplus的任何系統都將由4個組件組成：矢量數據庫，一個數據庫代理，該數據庫代理允許Periplus從數據庫，Periplus實例和客戶端應用程序中加載數據。

使用Periplus的應用程序的示例體系結構。

向量數據庫

任何允許通過唯一標識符（幾乎全部）查找數據的矢量數據庫都將起作用。 Periplus的設計是在與真正的大型矢量集合（十億個尺度）合作時最有益的，該指數必須在文件系統上而不是RAM，儘管這不是必需的。

向量數據庫代理

向量數據庫代理的目的是為Periplus提供與矢量數據庫通過的一致接口。代理必須實現一個REST接口，該接口接受以下表格的發布請求：

URL：這是靈活的，可以由Periplus客戶端指定。

標題： "Content-Type": "application/json

身體:

{
    "ids" : [ " id-1 " , " id-2 " , " id-3 " ]
}

回覆:

{
    "results" : [
        {
            "id" : " String " ,
            "embedding" : [ 0.1 , 0.2 , 0.3 ],
            "document" : " String " ,
            "metdata" : " String "
        }
    ]
}

為了使實現此端點更容易，您可以使用Periplus-Proxy Python軟件包，該軟件包使用FastApi來設置所有內容。用戶所要做的就是實現以下功能，並將其作為參數傳遞：

async def fetch_ids(request: Query) -> QueryResult

有關如何執行此操作的詳細信息，您可以查看Periplus-Proxy軟件包readme.md。

Periplus

請按照上述說明啟動Periplus實例。

客戶端應用程序

要與您的Periplus實例進行交互，請使用Periplus客戶端庫。目前僅支持Python。有關客戶端庫的詳細信息，您可以查看其readme.md。

Periplus命令

1. 初始化：這是Periplus的設置命令。必須在任何其他命令和任何後續初始化調用之前擦除所有數據並重置Periplus實例。有2個必需的參數：d（矢量集合的維度）和db_url（數據庫代理端點的URL用於加載數據）。還有一個可選的選項對象參數，其中有2個可用選項： ntotal和use_flat 。第一個， NTOTAL ，是對藏品中向量總數的估計。這用於優化要使用的IVF單元的數量。如果未指定，Periplus將選擇可能導致次優性能的中間立場。第二個是Use_flat ，是一個布爾值，它指示Periplus使用平面索引，而不是應用任何產品量化（PQ）。默認情況下，此值是錯誤的，在這種情況下，如果向量足夠大且易於將其分解為子向量，則將應用產品量化。如果設置為true，則將使用平坦的IVF索引。
2. 火車：此命令設置了構成緩存基礎的IVF索引中質心的位置。一旦設置了質心位置，就無法完全擦拭緩存，就無法重置它們。它將向量嵌入的列表作為參數，應該是您的向量集合的代表性示例。建議最多使用總收集的10％，但是對於真正的大數據集來說，可以使用少於10％的Periplus實例。
3. 補充：此命令使Periplus意識到數據，而無需實際填充緩存，因此可以從數據庫中加載它。 Periplus應該首先加載的任何向量都需要通過Add命令註冊。該命令採用兩個參數ID和嵌入，它們是具有向量ID和相應向量嵌入的相等長度的列表。
4. 加載：此命令指示Periplus從數據庫中加載IVF單元格（S）（請參閱其工作方式）。它具有一個必需的參數，一個向量告訴它要靶向的單元格，以及一個可選的選項對象，其中一個可用的選項n_load ，它告訴它加載了多少個單元格。 Periplus將從數據庫加載最近的N_load單元格到向量（如果未指定的話，N_load默認值為1）。這確保了具有相同向量的後續搜索命令將產生緩存命中（假設尚未事先驅逐單元格，並且N_load參數與搜索中給出的N_probe參數匹配）。
5. 搜索：此命令針對Periplus中存儲的數據運行一組查詢。它需要2個必需的參數： k指定返回最近鄰居的數量， xq是查詢向量列表。它可以選擇採用一個選項對象，其中有兩個可用的選項： N_Probe和require_all 。第一個指定要搜索多少IVF單元。較大的值導致延遲增加，但也增加了回憶（使用recure_all時，緩存率較低）。如果未指定，則默認值為1。第二個選項require_all是一個布爾值，它決定了緩存命中/錯過行為。如果設置為true，則所有N_probe最近的單元格必須在駐留式中才能使查詢成為緩存。如果是錯誤的，則只有最近的IVF單元才能在駐留式中是緩存的命中率，而Periplus將搜索IVF細胞在最接近的IVF細胞的N_probe始終存在的。默認值是正確的。搜索命令返回文檔列表的列表，其中每個列表對應於該索引上提供的相應查詢向量的K結果。緩存誤差將具有長度為0的列表。在極少數情況下，如果長度為> 0和<k，則表明最近的N_probe細胞中的向量總數為<k。每個文檔元組都有4個字段：ID，嵌入，元數據和文檔，它們將在加載數據時對數據庫代理提供的值。
6. 驅逐：此命令的工作原理與負載完全相同，但如果它們從Periplus出現而不是加載它們，則驅逐IVF單元格。它具有一個必需的灌溉，一個矢量告訴它要靶向的單元格，並且具有可用選項的可選選項對象n_evict whch告訴它要驅逐多少個單元。 Periplus將從Periplus驅逐與最接近的N_EVICT質心相對應的單元格（N_EVICT默認為1個未指定）。

例子

 from periplus_client import Periplus

# host, port
client = Periplus ( "localhost" , 13 )

# vector dimensionality, database proxy url, options: (nTotal)
await client . initialize ( d = d , db_url = url , options = { "nTotal" : 50000 })

training_data = [[ 0.43456 , ..., 0.38759 ], ...]
await client . train ( training_data )

ids = [ "0" , ..., "n" ]
embeddings = [[ 0.43456 , ..., 0.38759 ], ...]
await client . add ( ids = ids , embeddings = embeddings )

load_options = { "n_load" : 2 }
# query_vector, optional: options object
await client . load ([ embeddings [ 0 ]] load_options )

# k, query_vector
response = await client . search ( 5 , [ embeddings [ 0 ]])
print ( response )
'''
[ // Results for each of the n query vectors in xq
    [ // K nearest neighbors to this corresponding index in the xq list
        (
            id="n",
            embedding=[0.43456, ..., 0.38759],
            document="",
            metadata="{}"
        ),
        ...
    ],
    ...
]
'''

# query_vector
await client . evict ( embeddings [ 0 ])

基準測試

即將推出！

貢獻

我們歡迎對Periplus的貢獻！要了解如何入門，請查看貢獻指南。

執照

該項目是根據MIT許可證獲得許可的 - 有關詳細信息，請參見許可證文件。