Periplus

Periplus

Euen Warnung: Periplus ist in Alpha

Periplus ist derzeit in Alpha und ist nicht produktionsbereit. Das Projekt befindet sich in aktiver Entwicklung und wird noch nicht für den Einsatz in Produktionssystemen empfohlen.

Einführung

Periplus ist ein Open-Source-In-Memory-Vektor-Datenbank-Cache, das auf der Vector-Ähnlichkeitssorgungsbibliothek von Meta basiert. Das Projekt kann am besten als "Redis für Vektordatenbanken" betrachtet werden. Es wurde entwickelt, um eine dynamisch aktualisierte Teilmenge einer großen Vektorsammlung vollständig im Speicher zu speichern, während Abfragen nicht mit allen anderen Knoten zu interagieren. Wenn Periplus eine Anfrage erhält, wird zunächst bewertet, ob es den relevanten Teil des Index-In-Residence hat. Wenn dies der Fall ist, wird die Abfrage mit der entsprechenden Antwort gelöst. Wenn dies nicht der Fall ist, gibt es einen Cache -Miss zurück und lässt den Querier die Daten aus der Datenbank abrufen. Periplus ist nicht so konzipiert, dass er isoliert funktioniert. Stattdessen soll es eine modulare und flexible Caching -Schicht für eine separate Vektordatenbank bilden, die die Persistenanzschicht bildet. Der Zweck davon ist es, eine geringere Latenz und eine einfache horizontale Skalierung zur Erhöhung des Durchsatzes zu ermöglichen. Für eine detailliertere Beschreibung der Inspiration hinter Periplus und der Funktionsweise können Sie den Ankündigungsblog lesen: Einführung von Periplus: Ein neuer Ansatz zur Vektor -Datenbank -Caching.

Wie es funktioniert

Periplus verwendet einen invertierten Dateiindex (IVF) als Grundlage für die Cache -Verwaltung. Inverted File Indizes Partition Der Vektorraum in zusammenhängende Zellen, die durch eine Reihe von Zentroidvektoren definiert sind, in denen jede Zelle als die Region definiert ist, die näher an ihrem Schwerpunkt liegt als an jedem anderen Zentroid. Abfragen werden dann aufgelöst, indem zuerst die Entfernungen vom Abfragevektor zum Zentroidsatz berechnet werden und dann nur die vom N_PROBE (Suchhyperparameter) definierten Zellen am nächsten standen. Periplus nutzt dies aus, indem er zu einem bestimmten Zeitpunkt eine Untergruppe dieser Zellen im Wohnsitz aufnimmt und nur Abfragen auflöst, die für diese Teilmenge relevant sind, während sie diejenigen ablehnen, die nicht als Cache -Fehler sind. Periplus lädt und rägt ganze IVF -Zellen gleichzeitig, um die Integrität des Index aufrechtzuerhalten und einen äquivalenten Rückruf (bei Cache -Treffern) für einen Standard -IVF -Index sicherzustellen. IVF -Zellen werden durch Abfragen der Vektordatenbank über einen Proxy mit einer Liste von IDs von Vektoren geladen, die Periplus behauptet, die Vektoren zu verfolgen, welche Zellen. Diese Operationen können vom Benutzer mithilfe von Befehlen laden , such und räumen aufgerufen werden. Weitere Informationen finden Sie im Abschnitt Periplus Commands unten.

Periplus laufen

Periplus kann entweder als Docker -Container ausgeführt oder aus der Quelle erstellt und als ausführbare Datei ausgeführt werden. Derzeit sind keine offiziellen Binärdateien verfügbar. Das Ausführen von Periplus als Container ist der empfohlene Ansatz, aber beide sind praktikable Optionen.

? Periplus als Behälter ausführen

Derzeit unterstützt das Docker -Bild nur AMD64 -Architekturen. Diese Einschränkung ergibt sich aus dem Basisbild, aber in naher Zukunft werden mehr Architekturen unterstützt. Es gibt zwei Möglichkeiten, Periplus als Container auszuführen: Laden Sie das offizielle Docker -Bild von DockerHub (empfohlen) herunter oder erstellen Sie das Bild selbst. Der erste Schritt in beiden Fällen besteht darin, Docker zu installieren, wenn Sie es noch nicht getan haben. Die Anweisungen, die dies tun, finden Sie hier.

Verwenden des offiziellen Bildes

1. Laden Sie das Bild docker image pull qdl123/periplus:latest .
2. Führen Sie den Container aus: docker run -p 3000:3000 qdl123/periplus:latest

Aufbau des Bildes

1. Klon das Repository: git clone https://github.com/QDL123/Periplus.git
2. CD zum Repository Root: cd <path-to-periplus-repo>/Periplus
3. Erstellen Sie das Bild: docker build -t periplus-image .
4. Führen Sie den Container aus: docker run -p 3000:3000 periplus-image .

Bauen von Periplus aus der Quelle

Periplus verwendet CMake für sein Build -System. Es wird erwartet, dass alle Abhängigkeiten vorbereitete Binärdateien über Homebrew installiert haben. Homebrew wird von MacOS, Ubuntu und WSL unterstützt, wenn Sie unter Windows sind. Periplus wurde auf MacOS/ARM64 und Ubuntu/AMD64 gebaut. Alle anderen Betriebssysteme und Architekturkombinationen sind nicht getestet. Befolgen Sie die folgenden Schritte, um Periplus aus der Quelle zu erstellen:

1. Installieren Sie Homebrew: Besuchen Sie die offizielle Homebrew -Site hier, um Anweisungen für die Installation zu erhalten.
2. Installieren Sie die Abhängigkeiten von Periplus. Um sie alle auf einmal zu installieren, rennen Sie: brew install faiss curl cpr rapidjson libomp catch2 cmake
3. Klon das Repository: git clone https://github.com/QDL123/Periplus.git
4. CD zum Repository Root: cd <path-to-periplus-repo>/Periplus
5. Erzeugen Sie die Makefile: cmake -S . -B build
6. Kompilieren Sie die ausführbare Datei: cmake --build build
7. Periplus ausführen (Hören auf Port 3000): ./build/periplus -p 3000

Periplus verwenden

Jedes System, das Periplus verwendet, besteht aus 4 Komponenten: der Vektor -Datenbank, einem Datenbankproxy, mit dem Periplus Daten aus der Datenbank, eine Periplus -Instanz und eine Clientanwendung laden kann.

Beispielarchitektur einer Anwendung mit Periplus.

Die Vektordatenbank

Jede Vektor -Datenbank, die die Suche nach Daten nach einer eindeutigen Kennung (praktisch alle) ermöglicht, funktioniert. Periplus ist für die Arbeit mit wirklich großen Vektor-Sammeln (Milliarden) am vorteilhaftesten ausgelegt, wobei der Index auf dem Dateisystem im Gegensatz zu RAM leben muss, obwohl dies keine Anforderung ist.

Der Vektordatenbankproxy

Der Zweck des Vector Database Proxy ist es, eine konsistente Schnittstelle für Periplus bereitzustellen, um mit der Vektor -Datenbank durchzusetzen. Der Proxy muss eine REST -Schnittstelle implementieren, die Postanforderungen des folgenden Formulars akzeptiert:

URL: Dies ist flexibel und kann vom Periplus -Kunden angegeben werden.

Header: "Content-Type": "application/json

Körper:

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

Antwort:

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

Um diesen Endpunkt zu vereinfachen, können Sie das Python-Paket Periplus-Proxy verwenden, mit dem Fastapi alles einstellt. Der Benutzer muss nur die folgende Funktion implementieren und als Argument übergeben:

async def fetch_ids(request: Query) -> QueryResult

Weitere Informationen dazu finden Sie im Periplus-Proxy-Paket Readme.md.

Periplus

Befolgen Sie die obigen Anweisungen, um eine Periplus -Instanz zu starten.

Client -Anwendung

Verwenden Sie die Periplus -Kundenbibliothek, um mit Ihrer Periplus -Instanz zu interagieren. Derzeit wird nur Python unterstützt. Weitere Informationen in der Client -Bibliothek finden Sie in Readme.md.

Periplus -Befehle

1. Initialisieren : Dies ist der Setup -Befehl für Periplus. Es muss vor einem anderen Befehl aufgerufen werden, und alle nachfolgenden Initialisierungsanrufe löschen alle Daten und setzen die Periplus -Instanz zurück. Es gibt zwei erforderliche Argumente: D (Dimensionalität der Vektorsammlung) und db_url (URL des Datenbank -Proxy -Endpunkts, der zum Laden von Daten verwendet wird). Es gibt auch ein optionales Optionsobjektargument mit 2 verfügbaren Optionen: ntotal und use_flat . Das erste, Ntotal , ist eine Schätzung der Gesamtzahl der Vektoren in der Sammlung. Dies wird verwendet, um die Anzahl der zu verwendenden IVF -Zellen zu optimieren. Wenn nicht angegeben, wählt Periplus einen Mittelweg aus, der zu einer suboptimalen Leistung führen kann. Der zweite, Use_Flat , ist ein Boolescher, der Periplus anweist, einen flachen Index zu verwenden, anstatt eine Produktquantisierung (PQ) anzuwenden. Standardmäßig ist dieser Wert falsch. In diesem Fall wird die Produktquantisierung angewendet, wenn die Vektoren groß genug und leicht in Subvektoren aufgeteilt sind. Wenn auf TRUE eingestellt wird, wird stattdessen ein flacher IVF -Index verwendet.
2. Zug : Dieser Befehl legt die Position der Schwerpunkte im IVF -Index fest, der die Grundlage des Cache bildet. Sobald die Schwerpunktpositionen festgelegt sind, können sie nicht zurückgesetzt werden, ohne den Cache vollständig abzusetzen. Es dauert eine Liste von Vektor -Einbettungen als Argument, das eine repräsentative Stichprobe Ihrer Vektorsammlung sein sollte. Es wird empfohlen, bis zu 10% Ihrer gesamten Sammlung zu verwenden, aber weniger ist in Ordnung für wirklich große Datensätze, bei denen 10% die Periplus -Instanz überwältigen.
3. Hinzufügen : Dieser Befehl macht Periplus auf die Daten aufmerksam, ohne den Cache tatsächlich zu bevölkern, damit er später aus der Datenbank geladen werden kann. Jeder Vektor, den Periplus zuerst laden sollte, muss über den Befehl hinzufügen registriert werden. Der Befehl nimmt zwei Argumente -IDs und Einbettungsdings an, bei denen es sich um Listen mit gleichen Längen mit Vektor -IDs und entsprechenden Vektoreinbettung handelt.
4. Laden : Dieser Befehl weist Periplus an, IVF -Zellen (siehe) (siehe, wie es für Details funktioniert) aus der Datenbank. Es hat ein Argument erforderlich, einen Vektor, der ihm mitteilt, welche Zellen sie abzielen sollen, und ein optionales Optionsobjekt mit einer verfügbaren Option N_LOAD , die ihm mitteilt, wie viele Zellen geladen werden sollen. Periplus lädt die nächsten N_LOAD -Zellen aus der Datenbank in den Vektor (n_load standardmäßig auf 1, wenn nicht angegeben). Dies garantiert, dass ein nachfolgender Suchbefehl mit demselben Vektor einen Cache -Treffer liefert (vorausgesetzt, die Zelle wurde vorher noch nicht vertrieben und das N_LOAD -Argument entspricht dem in der Suche angegebenen N_PROBE -Argument).
5. Suche : In diesem Befehl wird eine Reihe von Abfragen gegen die in Periplus gespeicherten Daten ausgeführt. Es dauert 2 erforderliche Argumente: k , was die Anzahl der nächsten Nachbarn angibt, die zurückkehren sollen, und XQ , der eine Liste von Abfrageberichten ist. Es wird optional ein Optionsobjekt mit zwei verfügbaren Optionen verwendet: N_PROBE und Request_all . Der erste gibt an, wie viele IVF -Zellen gesucht werden sollen. Größere Werte führen zu einer erhöhten Latenz, aber auch zu einem erhöhten Rückruf (und einer niedrigeren Cache -Trefferrate, wenn Required_all verwendet wird). Der Standardwert beträgt 1, wenn sie nicht spezifiziert sind. Die zweite Option Required_all ist ein Boolescher, der den Cache -Treffer/Miss -Verhalten vorschreibt. Wenn sie auf True gesetzt sind, müssen alle Zellen von N_PROBE in der Residenz sein, damit die Abfrage ein Cache-Treffer ist. Wenn dies falsch ist, darf nur die nächste IVF-Zelle in Residence sein, damit die Abfrage ein Cache-Treffer ist, und Periplus sucht nach IVF-Zellen, die bis zu der N_PROBE- IVF-Zelle in Residence sind. Der Standardwert ist wahr. Der Suchbefehl gibt eine Liste der Listen von Dokumenttupel zurück, in denen jede Liste den k -Ergebnissen für den entsprechenden Abfragevektor entspricht, der in diesem Index bereitgestellt wird. Cache -Misses hat eine Liste von Länge 0. In seltenen Fällen ist die Länge> 0 und <k, die anzeigt, dass die Gesamtzahl der Vektoren in den nächsten N_PROBE -Zellen <k ist. Jedes Dokument -Tupel verfügt über 4 Felder: ID, Einbettung, Metadaten und Dokument, die den vom Datenbankproxy angegebenen Werten beim Laden der Daten entsprechen.
6. REVICT : Dieser Befehl funktioniert genauso wie Last , außer dass er IVF -Zellen räumt, wenn sie aus Periplus vorhanden sind, anstatt sie zu laden. Es verfügt über eine erforderliche Weisung, einen Vektor, der ihm mitteilt, welche Zellen zielen sollen, und ein optionales Optionsobjekt mit einer verfügbaren Option N_evict Whos sagt ihm, wie viele Zellen zu räumen sollen. Periplus wird die Zellen, die den nächstgelegenen N_EVICT -Zentroiden für den Vektor von Periplus entsprechen (n_evict standardmäßig, nicht angegeben) ergeben.

Beispiel

 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 ])

Benchmarking

Bald kommen!

Beitragen

Wir begrüßen Beiträge zum Periplus! Um zu lernen, wie man anfängt, schauen Sie sich den Beitragsführer an.

Lizenz

Dieses Projekt ist unter der MIT -Lizenz lizenziert - Einzelheiten finden Sie in der Lizenzdatei.