Umwandlung von RAG-Embedding-Modellen ohne Neindekxisierung: Wie rebasis funktioniert

Das Aufrüsten des Embedding-Modells hinter einem retrieval-augmented generation System klingt nach einer Routineaufgabe – bis der vorhandene Vektorindex im Weg steht. Ein Open-Source-Python-Tool namens rebasis befasst sich genau mit diesem Problem. Es trainiert einen kleinen Adapter, der Abfragenvektoren aus einem neuen Embedding-Modell in den Raum überträgt, den der alte Index bereits versteht. Dadurch kann eine vollständige Neindeckung verzögert werden oder langsam und unter Überwachung durchgeführt werden.

Das Tool prüft verschiedene Arten der Abbildung (zentriertes orthogonales Procrustes, affine, niedrig-rangige sowie Netzwerke mit kleinen Restfehlern) unter einem gemeinsamen Bewertungsprotokoll. Es gibt nicht nur Informationen zur Qualität der Ausrichtung, sondern schätzt auch ab, wie viel besser das neue Modell tatsächlich auf dem jeweiligen Korpus ist, und ob das angepasste System vorteilhafter ist als das Beibehalten des Alten. Konfidenzintervalle aus einem gepaarten Bootstrap-Verfahren, mehrere Suchmetriken, Fingerabdrücke der Kodierungs-Einstellungen, reproduzierbare Prüfprotokolle sowie ein fehlerresistenter Migrationsmechanismus sorgen dafür, dass ein Upgrade zu einer messbaren Entscheidung statt zu einem Glaubensakt wird.

Die Themen sind RAG, Embedding-Drift, Vektordatenbanken, Rückwärtskompatibilität, Modellmigration, Suchbewertung sowie annähernde Suche nach dem nächsten Nachbarn.

Warum das Embedding-Modell „eingefroren“ bleibt

Beim Aufbau eines RAG-Systems ist man nicht nur auf ein Sprachmodell und eine Vektordatenbank angewiesen. Man ist auch vom Koordinatensystem des Embedding-Modells abhängig, das zum Zeitpunkt der Indizierung im Einsatz war. Dokumente – egal ob Tausende oder Millionen – werden in Blöcke aufgeteilt, kodiert und in einen Index geschrieben. Früher oder später taucht ein schnelleres, besseres oder besser passendes Embedding-Modell auf, und genau da beginnen die Probleme: Ein Abfragenvektor des neuen Modells bedeutet nichts für einen mit dem alten Modell erstellten Index.

„Indexieren Sie einfach alles erneut“ ist der gängige Ratschlag. Technisch gesehen ist das richtig, doch oft kostspielig. Eine umfangreiche persönliche Wissensdatenbank, ein internes Dokumentationsset, eine Codebasis oder das langfristige Gedächtnis eines Agenten müssen erneut in Blöcke aufgeteilt und neu eingebettet werden – was Zeit, Rechenleistung, API-Ressourcen erfordert und operative Risiken mit sich bringt. Deshalb bleiben viele Systeme lange Zeit bei einem veralteten Modell, obwohl bereits ein besseres verfügbar ist.

rebasis wurde entwickelt, um diese Bindung zu durchbrechen. Sein ausgesprochenes Ziel ist es, es einem lokalen RAG-System zu ermöglichen, sein Embedding-Modell zu ändern, ohne den bereits vorhandenen Vektorindex löschen zu müssen.

Die Abfrage transformieren, nicht den Index

Zwei Embedding-Modelle erzeugen keine vergleichbaren Räume. Wenn man einen Satz mit jedem Modell kodiert, kann die Dimensionalität unterschiedlich sein, doch die Unterschiede gehen tiefer: Was jede Achse bedeutet, wo sich der Raum befindet, wie er skaliert wird und wie semantische Nachbarn angeordnet sind, all das kann sich ändern. Ein Abfravektor des neuen Modells, der direkt an den herkömmlichen Index gesendet wird, liefert größtenteils sinnlose Ergebnisse. Einige Vektordatenbanken lehnen die Abfrage ganz ab, weil die Dimension nicht zur Sammlung passt.

Die Antwort des Tools ist ein kleiner, gelernter Adapter. Er nimmt einen Abfragevektor vom neuen Modell und überträgt ihn in den Raum, in dem der bestehende Index kommuniziert. Um die Zuordnung zu lernen, werden dieselben Texte sowohl vom alten als auch vom neuen Modell kodiert, wodurch paarweise Vektoren entstehen. Wenn die Beziehung zwischen den beiden Räumen ausreichend lernbar ist, kann ein neuer Abfragevektor in etwas Umsetzbares für den alten Index umgewandelt werden.

Die praktischen Vorteile sind erheblich: Das neue Modell kann sofort für Abfragen genutzt werden, und die Dokumentvektoren im Index bleiben unverändert. Die Integration in eine Anwendung wird absichtlich auf ein Minimum beschränkt. Zuerst der Import:

from rebasis import Bridge

Dann wird der Adapter geladen und auf den Abfragenpfad gesetzt:

bridge = Bridge.load("adapters/minilm-to-bge.rbs")query_vector = new_model.encode(["how do I deploy to production?"])
query_vector = bridge.to_index_space(query_vector)
results = collection.query(query_embeddings=query_vector, n_results=10)

Bridge ist die dünne Schicht, die auf dem Hot Path der RAG-Anwendung liegt. Wenn der Adapter geladen wird, überprüft er die Identitäten der Modelle, die Kodierungsprofile, die Dimensionen sowie die Integrität der Adapter-Datei. Danach kostet jede Abfrage nur die Matrixoperation. Logging, das Erstellen von Wörterbüchern sowie wiederholte Überprüfungen werden absichtlich außer Acht gelassen, da eine kleine Bequemlichkeit nicht zu einem Kostenfaktor bei jeder Anfrage werden sollte. Ebenso ist kein GPU erforderlich, denn bei dieser Skala kostet das Übertragen von Daten zwischen Geräten in der Regel mehr als die Multiplikation.

Die Mathematik hinter dem Standardadapter

Nennen wir das alte Embedding-Modell f_old und das neue f_new, und nehmen wir n Dokumente, die von beiden kodiert wurden. Dadurch entstehen zwei Datenträgermatrizen, eine in jedem Raum. Ziel ist es, eine Funktion zu lernen, die den neuen Raum in den alten abbildet, wobei das Trainingsziel in seiner allgemeinen Form die Frobenius-Norm-Distanz zwischen den abgebildeten neuen Vektoren und den alten minimiert.

Die Standardmethode ist das zentrierte orthogonale Procrustes-Verfahren. Zunächst werden den beiden Matrizen ihre Spaltenmittelwerte abgezogen. Für Räume gleicher Dimension besteht die Einschränkung, dass die Transformation eine rotationssimile orthogonale Matrix sein muss. Durch die Singulärwertzerlegung des Produkts der zentrierten Matrizen erhält man eine orthogonale Matrix mit geschlossener Formel, die aus den linken und rechten Singulärvektoren gebildet wird. Eine Abfrage wird anschließend durch Zentrieren am Mittelwert des neuen Raums, Drehen sowie Wiederhinzufügen des Mittelwerts des alten Raums transformiert. Dies ist das klassische Procrustes-Problem, das seit den 1960er Jahren untersucht wird.

In dieser Lösung kommt es nicht zu iterativer Optimierung, sodass weder eine Lernrate noch eine Auswahl von Epochen erforderlich sind. Dasselbe Eingabedatenmuster ergibt stets dieselbe Transformation.

Vektoren werden vor dem Anpassen sowie erneut nach Anwendung des Adapters längennormalisiert, wodurch die Kosinusähnlichkeit auf ein Skalarprodukt reduziert wird. Das Zentrieren ist wichtig, da Embeddingsräume anisotrop sind und eine gemeinsame Mittelkomponente aufweisen. Durch das Entfernen dieser Komponente muss die Transformation keine Translation darstellen, die eine einfache Rotation nicht ausdrücken kann. Falls ein Paar von Modellen mehr Freiheit benötigt, kommen affine, niedrig-rangige oder residuale Alternativen zum Einsatz.

Eine operationell wichtige Eigenschaft ergibt sich daraus: Die Trainingskosten hängen von der Anzahl der abgeglichenen Paare ab und nicht von der Größe des Korpus. Selbst wenn der Index Hunderttausende von Datensätzen enthält, kann ein Adapter anhand von einigen tausend repräsentativen Paaren angepasst werden. Eine Vollmatrixumwandlung kostet im Größenordnung des Produkts der beiden Dimensionen pro Abfrage und benötigt einen Parameter-Speicher im gleichen Größenordnung. Eine Rank-r-Faktorisierung senkt die Abfragekosten auf etwa r-mal die Summe der Dimensionen. Als konkrete Zahl nimmt eine 768 mal 768 große float32-Matrix etwa 2,36 MB in Anspruch – was im Vergleich zu den Kosten für den Neuaufbau des Indexes vernachlässigbar ist.

Warum eine einzige Umwandlungsmethode nicht ausreicht

Die Beziehung zwischen zwei Embedding-Räumen ist häufig einer Rotation nahe, gilt jedoch nicht für jedes Paar von Modellen. rebasis geht daher nicht davon aus, dass ein einziger Algorithmus überall funktioniert. Es startet mit dem Orthogonalen Procrustes-Verfahren, der analytisch lösbaren Methode zur optimalen Ausrichtung zweier übereinstimmender Punktmengen. Reale Räume können jedoch Mittelverschiebungen, skalenbezogene Unterschiede pro Dimension sowie nichtlineare Komponenten aufweisen.

Mit --method auto passt das Tool mehrere Kandidaten auf dieselbe Datensplit und unter denselben Vorausverarbeitungen an und vergleicht sie anschließend:

• Procrustes in zentrierten und klassischen Varianten.
• Eine durch Ränder regulierte lineare Abbildung.
• Eine niedrig-rangige affine Abbildung.
• Procrustes mit einer Skala pro Dimension.
• Falls PyTorch verfügbar ist, ein kleines residuelles MLP.

CSLS wird nicht erzwungenermaßen in die Zuordnung aufgenommen; es bewirbt sich ebenfalls als Kandidat. Der Grund dafür ist praktischer Natur. In hochdimensionalen Räumen kann es das „Hubness“-Problem bei schwachen Adaptern lindern, doch es kann eine bereits starke Ausrichtung beeinträchtigen. Ziel ist nicht eine lange Liste von Algorithmusnamen, sondern ein Gewinner, der anhand von Messungen an zurückgehaltenen Daten ausgewählt wird. Wenn mehrere Kandidaten sich in derselben Unsicherheitsregion befinden, bevorzugt das Tool denjenigen mit weniger Parametern und geringerem Aufwand.

Die Trainings- und Evaluierungsdaten bleiben stets strikt voneinander getrennt – und das ist nicht nur eine Konvention. Das Tool überprüft zur Laufzeit auf Überschneidungen. Die Bewertung eines Adapters anhand der Beispiele, die er gelernt hat, würde eine beeindruckende Zahl liefern, die jedoch nichts beweist.

Assymmetrische Embedding-Modelle werden ebenfalls ausführlich behandelt. In der E5-Familie beispielsweise bedeuten die Präfixe query: und passage:, dass derselbe Text je nach seiner Rolle unterschiedlich kodiert wird, und andere Modelle verwenden zu diesem Zweck Anweisungen für Abfragen oder Dokumente. Wenn man einen Adapter an auf Dokumente kodierte Paare anpasst und ihn anschließend auf auf Abfragen kodierte Vektoren anwendet, entsteht ein klassisches Problem der Diskrepanz zwischen Training und Einsatz. Aus diesem Grund enthält ein Kodierungsprofil in rebasis weitaus mehr Informationen als nur den Modellnamen: Dimensionalität, Normalisierung, Pooling, die Präfixe für Abfragen und Dokumente sowie alle Matryoshka-Dimensionen werden berücksichtigt. Ein Adapter, der unter dem falschen Profil erstellt wurde, wird bei der Ladung abgelehnt, anstatt stillschweigend schlechte Ergebnisse zu liefern.

Wie dies zu früheren Forschungen passt

Die Kompatibilisierung von Embeddings zwischen verschiedenen Versionen ist ein altes Problem. Bei rückwärtskompatiblem Training wird ein neues Modell während des Trainings eingeschränkt, damit seine Repräsentationen weiterhin mit denen der älteren Versionen vergleichbar bleiben. Beim vorwärtskompatiblen Training wird hingegen bereits während des Trainings des alten Modells zusätzliche Information bereitgestellt, um spätere Aktualisierungen zu erleichtern. Beide Ansätze eignen sich für große Suchsysteme, die den gesamten Lebenszyklus des Modells bereits in der Entwicklungsphase steuern.

rebasis befasst sich mit einer anderen Situation. Der Index existiert bereits, die alten und neuen Modelle wurden getrennt trainiert, und niemand kann den jeweiligen Trainingsprozess verändern. Dadurch handelt es sich um eine post-hoc-Kompatibilitätsschicht. Sie nutzt Orthogonale Procrustes-Transformationen, niederrangige Transformationen sowie die neuere Drift-Adapter-Methodik, wobei ihr eigener Beitrag in der Ingenieurskunst liegt: Sie fasst diese Ideen in ein einziges lokales Tool zusammen, das außerdem Messfunktionen, Adapterauswahl, Entscheidungstheorie, Abstraktionen für Datenquellen, sichere Migration sowie einen Workflow für reproduzierbare Audits bietet.

CSLS stammt aus der Literatur zur Ausrichtung von mehrsprachigen Embeddings. Es berücksichtigt die lokale Nachbarschaftsdichte der Abfrage und des Ziels und bestraft „Hub“-Vektoren, die zum nächsten Nachbarn zu vieler Abfragen werden. Im Großen und Ganzen bewertet es ein Paar mit dem Doppelten der Kosinusähnlichkeit abzüglich eines Dichteterminals für jede Seite. Laut eigenen Experimenten mit einem echten Korpus des Projekts half es schwachen Karten und schadete manchmal starken, weshalb es gemessen wird anstatt blind angewandt zu werden.

Ein Werkzeug, das manchmal sagt, man solle es nicht verwenden

Früh im Projekt stellte sich heraus, dass die Frage „Kann eine Brücke zwischen diesen beiden Räumen gebaut werden?“ für sich genommen die falsche war. Drei Fragen sind wichtiger:

1. Ist das neue Embedding-Modell tatsächlich besser für diese speziellen Daten?
2. Welchen Anteil der Qualität einer vollständigen Neindekxisierung behält der Adapter bei?
3. Ist Brückenbau besser als einfach beim aktuellen Modell zu bleiben?

Deshalb wird probe anstelle von fit als Schlüsselbefehl vorgestellt. Er vereint Sampling, Embedding, Erstellung von Referenzdaten, Anpassung von Kandidaten, Berechnung von Metriken sowie die endgültige Entscheidung in einem einzigen Messprozess und schreibt niemals in den bestehenden Index.

Eine zentrale Messgröße ist ARR, Adapted Recall Retention: Die Qualität der angepassten Suche als Anteil dessen, was eine vollständige Neindekxisierung mit dem neuen Modell liefern würde. Ein hohes ARR allein reicht nicht aus. Wenn das neue Modell nur geringfügig gegenüber dem alten verbessert, hat ein Adapter wenig praktischen Wert. Wenn das neue Modell einen großen Fortschritt darstellt, der Adapter diesen Vorteil jedoch nicht übertragen kann, könnte eine vollständige Neindekxisierung die richtige Lösung sein.

Die Entscheidung hängt daher von einem Break-Even-Maß ab:

bridge_advantage = ARR × upgrade_gain

Wenn man es schriftlich aufschreibt, wird die Logik klarer. Sei Ra die Recall@k-Wertung für das angepasste System, Rn die gleiche Wertung für ein System, das vollständig mit dem neuen Modell neu indiziert wurde, und Ro die Wertung für das aktuelle alte System. ARR ist dann der Gewinn des angepassten Systems im Vergleich zum alten geteilt durch den Gewinn der vollständigen Neuindizierung im Vergleich zum alten, und der Upgrade-Gewinn ist das Verhältnis von Rn zu Ro. Wenn man diese Werte multipliziert, heben sich die Rn-Begriffe auf, sodass nur noch Ra geteilt durch Ro übrig bleibt: das angepasste System im direkten Vergleich zur tatsächlichen Alternative des Benutzers, nichts zu tun.

Jeder Faktor beantwortet eine einfache Frage. ARR fragt, wie viel vom idealen Neindeksieren beibehalten wurde. Der Upgrade-Gain fragt, wie viel besser das neue Modell ist. Ihr Produkt fragt, ob das Übergreifen auf ein neues Modell tatsächlich Fortschritte bringt. Ein Wert über 1 bedeutet, dass das Übergreifen vorteilhaft ist; ein Wert unter 1 nicht. Wenn eine Messung zu nahe am Schwellenwert liegt, liefert das Tool keine Gewissheit. Es stuft das Ergebnis als grenzwertig ein und empfiehlt eine größere Stichprobe.

Gegeben ein echtes Abfragen-Log sowie von Menschen bewertete relevante Dokument-ID-Listen kann probe den tatsächlichen Vorteil des neuen Modells in diesem Datensatz messen. Ohne ein solches Log können als Abfragen auch ausgeschlossene Dokumente verwendet werden, und synthetische Abfragen auf Basis von Schlüsselwörtern liefern eine ungefähre Bewertung. Jedes Ergebnis gibt seinen Beweisgrad an, sodass die Ausgabe sowohl eine Punktzahl als auch die Grundlage für deren Erstellung enthält.

Ein Messwertprofil, nicht nur eine Zahl

Recall@k ist die wichtigste Entscheidungsgröße, doch die Qualität der Ergebnisabrufung lässt sich nicht in eine einzige Zahl fassen. Ein einziger Probe-Lauf liefert mehrere ergänzende Kennzahlen:

• MRR@k zeigt, wie hoch die erste relevante Trefferposition liegt.
• nDCG@k berücksichtigt sowohl die Bewertung der Relevanz als auch die Rangposition.
• Top-k Overlap gibt an, wie viel vom Ergebnissatz des Referenzsystems beibehalten wird.
• Spearman-Korrelation misst, inwieweit die interne Sortierung der gemeinsamen Ergebnisse beeinträchtigt wird.
• Kolmogorov-Smirnov-Distanz zeigt, wie stark die Kalibrierung die Verteilung der Ähnlichkeitswerte verändert.

Tail ARR bestimmt die Qualität der spärlichsten Cluster im Verhältnis zum globalen Durchschnitt, wodurch Abweichungen, die bestimmte Regionen stärker betreffen, sichtbar werden.

Die Unterschiede sind wichtig. Zwei Systeme können dieselben Dokumente in unterschiedlicher Reihenfolge zurückgeben, was Recall nicht erkennen kann, während nDCG es kann. Ebenso kann die Rangliste gut aussehen, während sich die Form der Score-Verteilung so stark verändert, dass ein Filter mit fester Schwellenwertgrenze versagt. Wenn die auf Recall und nDCG basierenden Ergebnisse nicht übereinstimmen, meldet rebasis diese Diskrepanz und ersetzt nicht heimlich eine Metrik durch die andere.

Unsicherheit gehört zu den Ergebnissen

Der auf einer Stichprobe gemessene ARR ist eine Schätzung, weshalb das Tool gemäß Efrons Methode ein 95%-Konfidenzintervall anhand von 2.000 Bootstrap-Resampling-Vorgängen berechnet. Auf der Evidenzstufe T1 ist der ARR das Verhältnis zweier Mittelwerte. Ein unabhängiges Resampling des Zählers und des Nenners würde ihre statistische Abhängigkeit zerstören, weshalb beim gepaarten Verhältnis-Bootstrap dieselben Abfrageschlüssel für beide verwendet werden. Die Grenzen bilden das 2,5%- und das 97,5%-Perzentil der resultierenden Verteilung.

Durch das Paarieren bleibt eine echte Korrelation erhalten: Eine Abfrage, die für den Adapter schwierig ist, ist in der Regel auch für den Oracle schwierig. Wenn das Intervall einen Entscheidungsschwellenwert überspannt, gilt das Ergebnis nicht als endgültig festgelegt. Anstatt Dezimalstellen fälschlich für wissenschaftliche Gewissheit zu halten, wird die Genauigkeit der Messung selbst Teil der Entscheidung. Der Seed, die Stichprobenstrategie sowie die Metrikversion werden im Prüfprotokoll festgehalten, sodass das Intervall reproduziert werden kann.

Laut dem Projekt wurde die Richtung der Messungen direkt durch diese gesteuert. In seinem veröffentlichten Bericht verglich es das alte Modell, einen naiven Modellwechsel, eine angepasste Suchfunktion sowie einen vollständigen Neindeksierungsvorgang anhand identischer Abfragesätze in 11 Korpora, 398.010 Dokumenten und 10.346 echten Benutzerabfragen. Es wurden menschliche Relevanzbeurteilungen herangezogen, und die Hauptergebnisse wurden unabhängig mithilfe von ranx bewertet, anstatt sich ausschließlich auf die eigene Metrik des Tools zu verlassen. Laut diesen Zahlen behielt ein direkter Modellwechsel etwa 12,5 % der Qualität einer vollständigen Neindeksierung bei, während ein überbrückender Ansatz etwa 71 % beibehielt – das entspricht etwa 6,4-mal mehr Wiederherstellungseffekt als beim naiven Modellwechsel.

Das aussagekräftigste Ergebnis ist, dass die Brückenschlag-Methode nicht immer richtig war. Sie lohnte sich tatsächlich nur in 12 von 62 getesteten Modell- und Korpuspaaren. Die Entscheidungsregel wies in 61 von 62 Fällen in die richtige Richtung, darunter in 32 von 33 Fällen bei Korpora, die sie vor Festlegung der Regel noch nicht gesehen hatte. Ein Tool gewinnt Vertrauen, indem es bei ehrlicher Antwort „Hier neu indizieren“ oder „Sie benötigen diesen Upgrade nicht“ sagt, sowie indem es „Verwenden Sie mich“ anbietet.

Der komplette Workflow über die Kommandozeile

rebasis ist nicht nur eine Bibliotheksfunktion. Seine Kommandozeile verwandelt eine Modelländerung in einen handhabbaren Prozess. Dabei beginnt es mit einer Überprüfung der Umgebung sowie der verfügbaren Speicher- und Embedder-Optionen:

# Inspect the environment and available store/embedder support
rebasis doctor

Danach folgen die drei Phasen des eigentlichen Prozesses: Zuerst messen und einen Weg auswählen, anschließend den Adapter einsetzen und schließlich den Index bei Bedarf in Hintergrundbatchs migrieren.

# Measure first and choose the right path
rebasis probe --store chroma:///path/to/db#notes \
  --old sentence-transformers/all-MiniLM-L6-v2 \
  --new BAAI/bge-base-en-v1.5 \
  --queries queries.jsonl --sample 10000 --report report.html# Fit the appropriate adapter
rebasis fit --store chroma:///path/to/db#notes \
  --old sentence-transformers/all-MiniLM-L6-v2 \
  --new BAAI/bge-base-en-v1.5 \
  --method auto --pairs 4000 \
  --out adapters/minilm-to-bge.rbs# When ready, migrate the index in background batches
rebasis migrate --adapter adapters/minilm-to-bge.rbs \
  --store chroma:///path/to/db#notes --priority access --limit 5000

Der resultierende .rbs-Adapter enthält mehr als nur Gewichte. Sein Manifest dokumentiert die Identitäten der alten und neuen Modelle, die Vektordimensionen, die Richtung sowie die Fingerabdrücke der Kodierungsprofile. Tensor werden im safetensors-Format gespeichert, und die Ergebnisse der Skalenkalibrierung sowie der Bewertung werden mit übertragen. Ein Adapter ist somit eine portable, überprüfbare Aufzeichnung darüber, welche Modelle und Bedingungen ihn erzeugt haben, und die Tensor-Hashes können neu berechnet werden, um die Integrität zu überprüfen.

Die Kalibrierung der Scores verdient besondere Aufmerksamkeit. Eine Transformation kann die Rangfolge beibehalten und dennoch die absoluten Ähnlichkeitswerte verschieben. Eine Anwendung mit einem festen Schwellenwert wie Ähnlichkeit > 0,7 könnte dadurch unbemerkt Ergebnisse ausschließen. Um dies zu bewältigen, passt das Tool einen monotonen isotonen Kalibrator an, der die Scores wieder in Richtung der herkömmlichen Skala verschiebt, ohne ihre Reihenfolge zu verändern, und warnt gleichzeitig Systeme, die auf feste Schwellenwerte angewiesen sind.

Berechnungs- und Speicherverhalten

Ein Tool, das theoretisch nicht das gesamte Korpus im Speicher benötigt, könnte es dennoch versehentlich laden. In rebasis strömen Korpus-Iteratoren die Datensätze, wodurch der maximale Speicherverbrauch während der Migration dem Produkt aus Größe der Batch-Größe und Dimension des Vektors entspricht. Die Laufzeit nimmt mit der Anzahl der Datensätze zu, doch das Korpus des Benutzers wird niemals in RAM materialisiert. Wenn der Speicher dem Wert von --max-memory nahekommt, kann die Größe der Batch-Gruppe verringert werden und der geparkte Job kann pausiert werden, anstatt beendet zu werden.

Die zur Suche nach Ground-Truth-Werten sowie zur Abfrage nach Ergebnissen je Stichprobengröße verwendete Ähnlichkeitsmatrix wird ebenfalls nicht vollständig erstellt. Die Abfragen werden in Blöcken verarbeitet. Jeder Block führt eine Matrixmultiplikation durch, extrahiert die top-k Ergebnisse und verwirft die Zwischenscore-Matrix. Eine vollständige Sortierung würde pro Zeile S log S Kosten verursachen. Durch die Verwendung von argpartition bleibt die erwartete Selektionskosten pro Zeile linear in S. Bei normalisierten float32-Vektoren reduziert sich die Kosinus-Suche auf eine einzige Matrixmultiplikation, wodurch sowohl der maximale Speicherverbrauch als auch plattformbedingte Unterschiede im Datentyp unter Kontrolle bleiben.

In diesem Projekt ist die CPU die numerische Referenz und nicht eine zweitrangige Alternative. Eine GPU kann die Erstellung von Embeddings erheblich beschleunigen, doch der Datentransfer zwischen Host und Gerät kann den Vorteil bei einer einzigen, kleinen Adapteroperation zunichtemachen. Bei Tests zur Geräteäquivalenz werden Schwellenwerte für die Ergebnisse sowie die abgerufenen Nachbarsatzungen verglichen – vor allem wird geprüft, ob identische Daten zu derselben Endentscheidung führen. Eine numerisch geringe Differenz, die einen ARR-Wert über einen Schwellenwert wie 0,95 bringt, gilt nicht als akzeptable Hardwarevarianz; sie wird als Defekt im Produktverhalten angesehen.

Migration, die Unterbrechungen übersteht

Durch Brückenfunktionen muss der Index nicht sofort geändert werden; das System kann so lange wie gewünscht über den Adapter weiterlaufen. Soll der Index dauerhaft verschoben werden, überträgt migrate die Datensätze in Batches in den neuen Speicher – in diesem Fall steht die Datensicherheit vor der reinen Geschwindigkeit.

Jede Batch-Verarbeitung beginnt mit dem Lesen der aktuellen Vektoren, die vor jeder Überschreibung in einen Schatten-Speicher kopiert werden. Anschließend werden die transformierten Vektoren geschrieben, und eine Stichprobe der geschriebenen Datensätze wird zur Überprüfung erneut gelesen. Am Ende verlässt sich das Tool nicht nur auf den aktuellen Client-Handle. Es öffnet den Speicher über eine neue Verbindung erneut und nimmt erneut Stichproben, um Zuverlässigkeit zu gewährleisten – so kann das Caching auf der Client-Seite nicht verbergen, was tatsächlich im persistenten Speicher gespeichert wurde.

Der Migrationsserver basiert auf vier Invarianten:

1. Ein ursprünglicher float32-Vektor muss im Schatten-Speicher vorhanden sein, bevor sein Datensatz geändert wird.
2. Eine nach dem Schreiben erstellte Stichprobe aus jedem als abgeschlossen markierten Batch muss innerhalb der Toleranzgrenzen lesbar sein.
3. Eine abgeschlossene Aufgabe muss auch nach erneutem Öffnen des Speichers über eine neue Verbindung noch überprüft werden.

Der Rollback muss die ursprünglichen Vektoren wiederherstellen, ohne die Anzahl der Einträge oder die Payloads zu ändern.

Die Reihenfolge der Abläufe ist das Rückgrat der Argumentation bezüglich der Störsicherheit. Wenn der Prozess nach der Schatten-Speicherung, aber vor der Speicherung im Hauptspeicher abstirbt, entsteht lediglich eine harmlose zusätzliche Kopie. Wechselt man diese beiden Schritte, könnte derselbe Ausfall einen ursprünglichen Vektor endgültig zerstören.

Die Migrationswarteschlange dient gleichzeitig als Checkpoint, sodass --resume dort weitermacht, wo die letzte abgeschlossene Batch-Verarbeitung aufgehört hat. Das Tool kann den Speicherdruck sowie den Akkuzustand überwachen, und ein Zugriffsprotokoll kann die am häufigsten angeforderten Einträge an erste Stelle setzen. Sollte das Ergebnis enttäuschend sein, stellt rollback die ursprünglichen Daten aus der Schattenkopie wieder her. Verträge, die über die verschiedenen Backend-Systeme (Chroma, LanceDB, sqlite-vec, Qdrant, FAISS sowie ein In-Memory-System) geteilt werden, sorgen dafür, dass diese Operationen überall dieselbe Bedeutung haben.

Plugins für verschiedene Stack-Systeme

Local RAG basiert nicht auf einer einzigen Vektordatenbank oder Embedding-Dienstleisterin, weshalb Speicherung und Erstellung von Embeddings über pluginbasierte Registrierungen abgewickelt werden. Unterstützte Speicherlösungen sind Chroma, LanceDB, sqlite-vec, Qdrant und FAISS sowie ein im Speicher liegender Backend. Zur Erstellung von Embeddings stehen sentence-transformers, fastembed, Ollama, OpenAI-kompatible APIs, llama.cpp sowie vorberechnete Vektoren zur Verfügung.

Die Kerninstallation soll auch ohne PyTorch funktionieren. Die grundlegenden probe-Funktionen, das Procrustes-Anpassen sowie die Entscheidungslogik laufen unter Verwendung von NumPy, SciPy und scikit-learn, während aufwändige oder plattformspezifische Abhängigkeiten nur von denen installiert werden, die sie benötigen. Drittanbieter-Pakete können einen Eingangspunkt rebasis.stores oder rebasis.embedders bereitstellen, um eine Integration ohne Forking des Projekts zu ermöglichen.

Privatsphäre, Protokollierung und Reproduzierbarkeit

Durch seine Konstruktion sendet rebasis keine lokalen Daten an irgendeinen Ort. Es verfügt weder über Telemetriedaten noch über einen Nutzungszähler, und weder Texte aus Dokumenten noch Vektoren gelangen in die Protokolle. Da Informationen aus einem Embedding rekonstruiert werden können, werden Vektoren genauso sensibel behandelt wie reiner Text. Die Unterstützung für OpenTelemetry ist als Option vorhanden, standardmäßig deaktiviert und exportiert nur in den eigenen Collector des Benutzers.

Jede Entscheidung kann in einem nur zum Hinzufügen geeigneten Prüfprotokoll aufgezeichnet werden, damit sie reproduzierbar bleibt. Die Einträge enthalten Modelldaten, Profilfingerabdrücke, die Stichprobenmethode, den Startwert, Schwellenwerte, die Metrikversion, die rebasis-Version sowie Umgebungsdetails. Die Einträge sind in einer Hash-Kette miteinander verbunden, wodurch spätere Korruptionen oder teilweise vorgenommene Änderungen sichtbar werden. rebasis audit replay führt eine frühere Messung erneut aus, um herauszufinden, ob ein Unterschied auf eine Software-Rückentwicklung oder auf eine veränderte Datensammlung zurückzuführen ist.

Was die Open-Source-Verpackung beweisen soll

rebasis wird unter der Apache 2.0-Lizenz veröffentlicht, wobei das Ziel darin besteht, sowohl die darin gemachten Aussagen als auch den Code überprüfbar sowie lesbar zu machen. Im Repository finden Sie Aufzeichnungen zu den wichtigsten Architekturentscheidungen, zusammen mit idealen Szenarien, Messungen an echten Datensätzen, Leistungsrahmen, Kontrakttests für jeden Backend, CLI-Tests, die von Anfang bis Ende ausgeführt werden, sowie Dokumentationen für Mitwirkende. Die Teststrategie geht über den „happy path“ hinaus und berücksichtigt numerische Konsistenz zwischen verschiedenen Geräten, Speichergrenzen, Adaptereigenschaften, Store-Kontrakte sowie die Langlebigkeit von Migrationen und Rollbacks.

Der CI-Pipeline zielt auf Python 3.12 und 3.13 unter Linux und macOS ab – zwei Systeme mit unterschiedlichen Speichersemantiken. Mindestunterstützte Abhängigkeitsversionen werden separat geprüft, und eine weitere Aufgabe stellt sicher, dass optionale Komponenten wie PyTorch oder OpenTelemetry nicht in das Kernpaket gelangen. Für die Typüberprüfung wird mypy --strict verwendet, die Codequalität wird von Ruff überwacht, die Schichtgrenzen durch import-linter und die Dokumentationslinks im strengen Modus von MkDocs. Hinter all dem steht die Erkenntnis, dass das Vertrauen in Open-Source-Projekte weniger von kühnen Angaben in README-Dateien abhängt als davon, welche Tests und Messungen diese Unterstützung belegen.

Modelländerungen ohne das Alles-oder-Nichts-Prinzip

Das zugrundeliegende Problem ist nicht die Wahl einer Technologie, sondern die Kosten für deren Änderung. Mit dem Wachstum von RAG-Systemen werden ihre Indizes zu Infrastrukturinvestitionen, und die Auswahl eines Embedding-Modells wird zu einer Entscheidung, die viel schwieriger rückgängig zu machen ist, als es eigentlich der Fall sein sollte. Die Idee hinter Rebasing besteht darin, diese Verknüpfung zu lockern.

Wenn ein neues Modell auftaucht, sollte der erste Schritt darin bestehen, zu prüfen, ob es tatsächlich mit den eigenen Daten besser abschneidet. Falls ja, geht es darum herauszufinden, ob eine zuverlässige Brücke es mit dem aktuellen Index verbinden kann. Wenn die Brücke gut genug ist, kann das neue Modell sofort verwendet werden. Wenn im Laufe der Zeit eine vollständige Qualität gewünscht wird, kann die Migration in kontrollierten Chargen mit Überprüfungen und Garantien für einen Rückrollversuch durchgeführt werden. Und falls die Brücke unzureichend ist, sollte das vor einem teuren Produktivitätsversuch festgestellt werden, nicht währenddessen.

Das ist der Entscheidungsbereich, den das Tool bietet: Zuerst messen, anschließend eine Brücke schaffen und bei Bedarf sicher migrieren. Es handelt sich um ein offenes Tool, das dazu dient, lokale RAG-Infrastrukturen robuster zu machen, die Wahl von Embedding-Modellen weniger bindend zu gestalten und Modelloberholungen transparenter zu machen. Zudem steht es Entwicklern zur Verfügung, um es zu überprüfen, an echten Korpora auszuprobieren und bei der Weiterentwicklung zu helfen.