turbovec ist ein Open-Source-In-Process-Vektorindex, der in Rust mit Python-Bindungen geschrieben wurde. Es implementiert den TurboQuant-Ansatz von Google Research, um dichte Vektoren ohne eine separate Codebuch-Trainingsphase zu komprimieren, und durchsucht dann die gepackten Codes mit architekturspezifischen SIMD-Kerneln. Sein praktischer Reiz ist eine Kombination aus Online-Ingest, 2-Bit- oder 4-Bit-Speicher, Persistenz, stabilen externen IDs, Löschunterstützung, durch Zulassungslisten gefilterter Suche und Adaptern für gängige RAG-Frameworks.
Es ist wichtig, es richtig zu klassifizieren. turbovec ist eine Indexbibliothek, keine gehostete Vektordatenbank oder ein vollständiger Abrufdienst. Es allein bietet keine verteilte Replikation, Multi-Node-Sharding, Backups, Authentifizierung, Mandantenverwaltung, Netzwerk-APIs, hybride lexikalische Suche, Beobachtbarkeit oder eine Kontrollebene. Teams gewinnen lokale Kontrolle und Gedächtniseffizienz im Gegenzug dafür, dass sie sich die umliegenden Anliegen zu eigen machen.
So funktioniert die TurboQuant-Komprimierung
Die zugrunde liegende Erkenntnis ist, dass eine zufällige orthogonale Rotation dazu führt, dass die Koordinaten hochdimensionaler Einheitsvektoren einer vorhersagbaren Verteilung folgen. turbovec trennt zunächst die Norm jedes Vektors von seiner Richtung. Es wendet eine gemeinsame Zufallsdrehung an und quantisiert dann die gedrehten Koordinaten mithilfe vorberechneter Lloyd–Max-Buckets. Zwei Bits liefern vier Werte pro Koordinate; Vier Bits ergeben sechzehn. Codes sind bitgepackt und eine Korrektur pro Vektor beseitigt die durch Quantisierung verursachte systematische Schrumpfung des Innenprodukts.
Das Projekt fügt die Kalibrierung TQ+ hinzu: Beim ersten Hinzufügen schätzt es mithilfe empirischer Quantile eine Verschiebung und Skalierung für jede Koordinate und friert diese Werte dann für spätere Aufnahmen ein. Dies ist nicht dasselbe wie ein herkömmliches Produktquantisierungstraining, aber die erste Charge beeinflusst die Kalibrierung. Eine winzige oder nicht repräsentative erste Hinzufügung kann daher auf eine schlechte Produktionsinitialisierung hinweisen. Setzen Sie den Index mit einer repräsentativen Stichprobe und testen Sie die Verteilungsdrift.
| Bühne | Gespeichert oder berechnet | Operative Konsequenz |
|---|---|---|
| Normalisieren | Einheitsrichtung plus Originalnorm | Behält die Größe bei, während die Winkelstruktur quantisiert wird |
| Zufällige Rotation | Gemeinsame orthogonale Transformation | Macht Koordinatenverteilungen über beliebige Eingabedaten vorhersehbar |
| TQ+ Kalibrierung | Beim ersten Hinzufügen gelernte Verschiebung und Skalierung pro Koordinaten | Verbessert endliches/niedrigdimensionales Verhalten; erfordert eine repräsentative Initialisierung |
| Lloyd–Max Quantisierung | 2-Bit- oder 4-Bit-Koordinatencodes | Große Speicherreduzierung mit datensatzabhängigem Erinnerungsverlust |
| Längenkorrektur | Ein Skalar pro Vektor | Korrigiert nach unten gerichtete Schätzungen des Innenprodukts |
| SIMD Suche | Rotierte Abfrage- und Nachschlagetabellenbewertung über gepackte Codes | Vermeidet eine vollständige Dekompression; Die Leistung hängt von der CPU-Architektur ab |
Gedächtnismathematik ohne Marketing-Abkürzung
Ein 1.536-dimensionaler Float32-Vektor verwendet 6.144 Bytes für Rohkoordinaten. Seine Koordinatencodes erfordern vor den Metadaten 384 Bytes bei 2 Bit oder 768 Bytes bei 4 Bit. Das ist eine theoretische Reduzierung der Koordinatennutzlast um das 16-fache oder 8-fache. In der Überschrift des Repositorys heißt es, dass ein Float32-Korpus mit 10 Millionen Dokumenten, der etwa 31 GB benötigt, in etwa 4 GB passen kann; Dieses Beispiel spiegelt eine bestimmte Dimension und Darstellung wider und sollte nicht auf jedes Korpus verallgemeinert werden.
Bei der Kapazitätsplanung müssen externe IDs, Korrektur-/Normwerte pro Vektor, Kalibrierungsdaten, Ausrichtung, Allokator-Overhead, gelöschte Slots, Anwendungsmetadaten, Abfragepuffer und der Originaldokumentspeicher hinzugefügt werden. Einbettungen machen selten die gesamte RAG-Speicherrechnung aus. Messen Sie die Größe des residenten Satzes, nachdem Sie den echten persistenten Index geladen und gleichzeitige Abfragen bedient haben.
Was der API unterstützt
numpy als np importieren
aus turbovec Import IdMapIndex
index = IdMapIndex(dim=1536, bit_width=4)
index.add_with_ids(vectors.astype(np.float32), ids.astype(np.uint64))
Ergebnisse, result_ids = index.search(query.astype(np.float32), k=10)
index.remove(document_id)
index.write("corpus.tvim")
restauriert = IdMapIndex.load("corpus.tvim")Der Python API lehnt Nicht-Float32-Vektoren bewusst ab, anstatt sie stillschweigend zu konvertieren. Stabile IDs sind wichtig, da sich interne Steckplätze nach Löschungen und Wartungsarbeiten ändern können. Persistenz macht einen lokalen Neustart praktisch, aber Anwendungen benötigen weiterhin atomare Veröffentlichung, Prüfsummen, Sicherungs-/Versionsrichtlinien und Kompatibilitätstests bei Bibliotheksaktualisierungen.
Der gefilterte Abruf ist ein sinnvolles Unterscheidungsmerkmal
Für den mandantenfähigen, zeitfenster- oder berechtigungsbewussten Abruf kann die Anwendung zunächst einen zulässigen ID-Satz aus SQL, BM25, einem ACL-Dienst oder einem anderen System erstellen und dann turbovec auffordern, nur diese Kandidaten zu bewerten. Die Filterung erfolgt innerhalb des Pfads SIMD mit einer Blockgranularität von 32 Vektoren. Leere Blöcke können übersprungen werden und unzulässige Slots werden vor der Heap-Einfügung zurückgewiesen, sodass selektive Filter einen Großteil der Dense-Scoring-Arbeit vermeiden können.
Dies ist besser, als einen globalen Top-K abzurufen und nicht autorisierte Ergebnisse zu verwerfen, was dazu führen kann, dass zu wenige gültige Dokumente zurückgegeben werden und Ranking-Informationen verloren gehen. Es liegt weiterhin in der Verantwortung des Anrufers, die Zulassungsliste korrekt zu erstellen, sie an den authentifizierten Mandanten zu binden und leere, kleine, große und sich schnell ändernde Mengen zu testen. Verwenden Sie die Metadatenfilterung niemals als einzige Berechtigungsprüfung beim endgültigen Dokumentabruf.
So lesen Sie die veröffentlichten Benchmarks
| Anspruch | Veröffentlichte Testgrenze | Was bleibt unbewiesen |
|---|---|---|
| Rückruf konkurrenzfähig mit FAISS PQ | 100.000 Vektoren, k=64; OpenAI Dimension 1536/3072 und GloVe Dimension 200; angepasste Bitrate | Ihr Einbettungsmodell, Korpusverteilung, k-, Metrik- und Relevanzbezeichnungen |
| 10–19 % schneller auf ARM | Apple M3 Max gegen FAISS IndexPQFastScan in Repository-Konfigurationen | Andere Apple-Chips, Parallelität, thermischer Zustand und Produktionsfilter |
| Wettbewerbsfähige x86-Geschwindigkeit | Xeon Platinum 8481C; Gewinne wurden für 4-Bit gemeldet, in einigen 2-Bit-Fällen waren geringfügige Verluste zu verzeichnen | Ihre CPU-Generation, AVX-Pfad, Kerne, NUMA und Abfragebatch |
| Kein Training/Umbau | Bekannter Verteilungsquantisierer mit First-Add-TQ+-Kalibrierung und Online-Additionen | Auswirkungen einer nicht repräsentativen ersten Charge oder einer großen Vertriebsverschiebung |
| Durch die gefilterte Suche wird ein übermäßiger Abruf vermieden | Die Zulassungsliste wird innerhalb der Blockbewertung und Heap-Einfügung behandelt | End-to-End-SQL/ACL-Kosten und nicht selektive Worst-Case-Filter |
Die Vergleichsbasislinie ist FAISS IndexPQ/IndexPQFastScan, nicht jeder Indextyp FAISS. Flache exakte Suche, HNSW, IVF-PQ, GPU-Indizes und verwaltete Datenbanken lösen verschiedene Punkte auf der Rückruf-, Latenz-, Speicher- und Betriebskurve. Reproduzieren Sie zunächst die Repository-Benchmarks und ersetzen Sie dann Ihre Daten und Ihr Akzeptanzziel durch einen Faktor nach dem anderen.
Ein nützliches RAG-Bewertungsprotokoll
- Einbettungen einfrieren. Verwenden Sie das genaue Modell, die Normalisierung, die Bemaßung und die Abstandskonvention, die für die Produktion geplant sind.
- Erstellen Sie eine fundierte Wahrheit. Berechnen Sie genaue Top-K-Nachbarn mit einer vertrauenswürdigen flachen Implementierung und verwalten Sie die Beurteilung der Aufgabenrelevanz separat.
- Testen Sie beide Bitbreiten. Vergleichen Sie 2-Bit und 4-Bit mit Float32 oder exakter Suche, nicht nur miteinander.
- Stratifizieren Sie Abfragen. Berücksichtigen Sie häufige, seltene, mehrsprachige, kurze, lange, doppelte und domänenfremde Fälle.
- Sportliche Einnahme. Mit einem repräsentativen Stapel initialisieren, spätere Verteilungen anhängen, IDs löschen, beibehalten, neu laden und deterministisches Verhalten überprüfen.
- Benchmark-Filter. Messen Sie keine Filter und Zulassungslisten bei 0 %, 0,1 %, 1 %, 10 %, 50 % und 100 % Abdeckung, einschließlich gegnerischer Blocklayouts.
- Belastungstest. Zeichnen Sie p50/p95/p99-Latenz, Durchsatz, CPU-Auslastung, residenten Speicher und Tail-Verhalten bei echter Parallelität auf.
- Bewerten Sie die Antwort. Messen Sie die Retrieval-Erinnerung, die Reranker-Qualität, die Zitierkorrektheit und den Erfolg der endgültigen Antwort. Schnellere ungefähre Nachbarn sind nur dann wertvoll, wenn das Anwendungsergebnis erhalten bleibt.
Entscheidungsmetriken
| Metrisch | Definition | Empfohlene Berichterstattung |
|---|---|---|
| Rückruf@k | Exakte Top-K-Nachbarn, die durch eine ungefähre Suche ermittelt wurden | Nach Datensatz-Slice, Bitbreite und Filterselektivität |
| Aufgabenerinnerung | Abfragen, deren erforderliches Belegdokument abgerufen wird | Aussagekräftiger als die Vektor-Nachbarn-Überlappung allein |
| Speicher pro Vektor | Verarbeiten Sie RSS-Delta / geladene durchsuchbare Vektoren | Beziehen Sie IDs, gelöschte Slots und Metadaten-Overhead ein |
| Schwanzlatenz | p95/p99 End-to-End-Abfragezeit | Bei realistischer Parallelität und Zulassungslistenmischung |
| Aktualisierungskosten | Zeit- und Spitzenspeicher für Hinzufügungen, Löschungen, Speichern und Neuladen | Beinhaltet First-Add-Kalibrierung und Crash-Recovery |
| Kosten pro akzeptierter Anfrage | Infrastruktur und technischer Betrieb / korrekte Aufgabenergebnisse | Vergleichen Sie mit FAISS und verwalteten Alternativen |
Framework-Integrationen
Das Repository dokumentiert Adapter für LangChain, LlamaIndex, Haystack und Agno, die ihre In-Memory-Referenzspeicher ersetzen und gleichzeitig vertraute Schnittstellen beibehalten. Dies kann einen schnellen Machbarkeitsnachweis ermöglichen, aber „Drop-in“ bezieht sich auf eine öffentliche Softwareoberfläche – nicht auf identische Bewertung, Filterung, Löschung, Persistenz, Threading oder Fehlersemantik. Führen Sie vor der Bereitstellung die Abruftests und Pin-kompatiblen Versionen jedes Frameworks durch.
Alternativen
| Option | Bevorzugen Sie es, wenn | Kompromiss |
|---|---|---|
| turbovec | Lokale In-Process-Suche, extreme Komprimierung, Online-Hinzufügen und Filtern auf Zulassungslisten passen sich der Arbeitslast an | Sie besitzen Service-, Replikations- und Betriebskontrollen |
| FAISS | Sie benötigen ausgereifte Optionen für die exakte Indizierung, IVF, PQ, HNSW oder GPU | Konfiguration und Schulung können aufwändiger sein; Der Speicher variiert je nach Index |
| hnswlib | Hoher Rückruf und Diagrammsuche mit geringer Latenz sind wichtiger als kompakter Speicher | Der Diagramm-Overhead kann wesentlich mehr Speicher verbrauchen |
| Qdrant, Weaviate oder Milvus | Netzwerkdienst, Metadatenfilter, Replikation und Vorgänge sind erforderlich | Mehr Infrastruktur und Speicher als eine kleine eingebettete Bibliothek |
| Verwaltete Vektordatenbank | Das Team möchte gehostete Skalierung, Backups, Authentifizierung und Support | Wiederkehrende Kosten, Datenresidenz und Anbieterabhängigkeit |
| PostgreSQL mit pgvector | Vektoren müssen nah an relationalen Daten und vorhandenen Operationen bleiben | Stimmt möglicherweise nicht mit einem speziellen komprimierten Index im großen Maßstab überein |
Grenzen und Produktionsrisiken
- Eine ungefähre Komprimierung kann die Reihenfolge der nächsten Nachbarn ändern, insbesondere bei aggressiver Bitbreite oder geringer Dimension.
- CPU-spezifische Kernel bedeuten, dass Benchmark-Ergebnisse nicht zwischen ARM-, AVX2- und AVX-512-Hardware übertragen werden sollten.
- First-Add-Kalibrierung, sich ändernde Einbettungsmodelle und Korpusdrift erfordern explizite Migrationstests.
- Die lokale Bereitstellung behält die Kontrolle über die Vektoren, fügt jedoch nicht automatisch Verschlüsselung, Zugriffskontrolle oder sichere Backups hinzu.
- Ein prozessinterner Absturz wirkt sich auf die Hostanwendung aus, es sei denn, die Dienstgrenze und die Wiederherstellungsstrategie sind bewusst festgelegt.
- Das Projekt entwickelt sich weiter; Pin-Releases, überprüfen Sie Änderungsprotokolle/Sicherheitsrichtlinien und validieren Sie die Kompatibilität persistenter Indizes.
Häufig gestellte Fragen
Ist turbovec eine Vektordatenbank?
Nein. Es handelt sich um eine Vektorindexbibliothek. Anwendungen müssen nach Bedarf Dokumentenspeicher, Netzwerk, Autorisierung, Replikation, Überwachung und Lebenszyklusvorgänge bereitstellen.
Ist ein Offline-Schulungsschritt erforderlich?
Es vermeidet das herkömmliche Codebuch-Training und unterstützt Online-Hinzufügungen. TQ+ kalibriert beim ersten Hinzufügen Werte pro Koordinaten, sodass der Initialisierungsstapel weiterhin sorgfältig behandelt werden muss.
Soll ich 2-Bit oder 4-Bit wählen?
Verwenden Sie 2-Bit, wenn der Speicher die bindende Einschränkung darstellt und Ihr gemessener Aufgabenrückruf akzeptabel bleibt. Vier-Bit bietet normalerweise mehr Genauigkeit bei etwa doppelt so viel Speicherplatz für den Koordinatencode. Vergleichen Sie beides.
Erzwingt die gefilterte Suche die Mietersicherheit?
Es kann das Ranking effizient auf eine Zulassungsliste beschränken. Die Anwendung muss die richtige Liste erstellen und die Autorisierung erneut prüfen, bevor sie Quellinhalte zurückgibt.
Sind die FAISS Geschwindigkeitsangaben universell?
Nein. Die veröffentlichten Ergebnisse umfassen benannte Hardware, Datensätze, Abmessungen, Bitbreiten und FAISS PQ/FastScan Konfigurationen. x86-2-Bit-Ergebnisse umfassen Fälle, in denen FAISS schneller ist.
Kann es einen Luftspalt haben?
Der Index wird lokal ausgeführt und erfordert keinen verwalteten Dienst. Ein vollständiger Air-Gap-RAG-Stack benötigt außerdem lokale Einbettungen, Dokumente, Paket-/Modellherkunft und kontrollierte Aktualisierungen.
Primärquellen
- turbovec offizielles Repository und Benchmark-Dokumentation
- turbovec API Referenz
- Reproduzierbare Benchmark-Skripte und Ergebnisse
- TurboQuant Forschungspapier
- RaBitQ Artikel zur Längenkorrektur zitiert
- FAISS FastScan technische Referenz
- turbovec Python Paket
- turbovec Rust Kiste
Zuletzt überprüft am 25. Juli 2026. Leistungsaussagen beziehen sich auf das veröffentlichte Setup des Repositorys, sofern nicht anders angegeben. Reproduzieren Sie Ihr Korpus, Einbettungsmodell, Hardware und Filterverteilung vor der Einführung.
