Embedding-API-Migration: Vektoren neu aufbauen und zurückrollen

Ein anderes Embedding-Modell braucht einen neuen Suchindex

Bei der Migration von text-embedding-3-small zu text-embedding-3-large erstellen Sie aus den ursprünglichen Dokumenttexten einen separaten Index und erzeugen Suchanfragen mit der dazu passenden Embedding-Konfiguration. Füllen Sie alte Vektoren nicht mit Nullen auf, damit ihre Länge passt. Gleiche Vektorlängen belegen auch nicht, dass zwei Modelle dasselbe Koordinatensystem verwenden. Halten Sie den bisherigen Index verfügbar, bis der neue Dokument- und Abfragepfad Ihre eigene Retrieval-Evaluation bestanden hat.

Für ein Dokumentationsteam, das seine Produkthilfe-Suche umstellt, gehören dazu die Kosten einer erneuten Einbettung des gesamten Korpus, vorübergehender Speicher für beide Indizes und eine umkehrbare Konfigurationsänderung. Das ausführbare Python-Beispiel zeigt, warum eine reine Dimensionsprüfung nicht genügt, weist sechs ungültige Testfälle zurück und berechnet ein konkretes Budget für den Neuaufbau. Es läuft vollständig offline: Seine zweidimensionalen Vektoren sind von Hand definierte Geometrie, keine Ausgaben eines der beiden OpenAI-Modelle.

Innerhalb jedes Raums liefern die von Hand definierten Vektoren das richtige Ergebnis. Eine vermischte Abfrage-Index-Kombination liefert trotz identischer Vektorlänge B. Das Diagramm beruht auf dem tatsächlich ausgeführten lokalen Beispiel.

Modelldimensionen und die derzeitige Orux-Unterstützung

OpenAIs Embedding-Leitfaden nennt Standardlängen von 1.536 für text-embedding-3-small und 3.072 für text-embedding-3-large. Er beschreibt außerdem den nativen Parameter dimensions, mit dem sich Embeddings der dritten Generation verkürzen lassen. Die Ausgabe eines unterstützten Modells zu verkürzen ist eine Konfigurationsentscheidung; dadurch wird das Modell nicht zu einem anderen Modell.

Beide exakten Aliase sind derzeit bei Orux gelistet. Die Modellseite für text-embedding-3-small und die Modellseite für text-embedding-3-large bieten Texteingaben und Vektoren im Float-Format. Ihre gespeicherten öffentlichen Beispiele nennen 1.536 beziehungsweise 3.072 Dimensionen. Diese Beispiele belegen die angegebene Ausgabeform, keine allgemeine Genauigkeitsrangfolge der Modelle.

Die am 3. November 2026 geprüften Formulare enthalten keine Einstellung für die Dimensionen. Planen Sie deshalb keinen verkürzten Orux-Index allein deshalb, weil die native OpenAI-Dokumentation diese Möglichkeit beschreibt. Prüfen Sie den genauen Integrationsvertrag, bevor Sie sich darauf verlassen. Dieser Artikel sendet weder eine kostenpflichtige Embedding-Anfrage noch demonstriert er die Weiterleitung des Dimensionsparameters durch Orux. Die aktuelle Integrationsoberfläche finden Sie in der Orux-API-Dokumentation.

Speichern Sie Modellalias, zurückgegebene Dimensionszahl, Version der Textvorverarbeitung und Distanzmetrik gemeinsam. Ein Hilfeartikel aus title + body sollte beispielsweise eine andere Vorverarbeitungsversion erhalten als eine Einbettung ausschließlich aus body. Bewahren Sie neben den Chunk-Kennungen auch Hashes der Dokumentrevisionen auf, damit ein späterer Neuaufbau veraltete Texte erkennen kann. Eine übereinstimmende Dimensionszahl kann offensichtliche Formfehler erkennen; die übrigen Vertragsfelder erfassen Konfigurationsfehler, die allein an der Form nicht sichtbar werden.

Ein zweidimensionales Beispiel macht den verborgenen Fehler sichtbar

Stellen Sie sich zwei Dokumentvektoren in einem vereinfachten alten Raum vor: A ist (1, 0) und B ist (0, 1). Die alte Abfrage (1, 0) findet A. Drehen Sie nun den gesamten Raum um 90 Grad. A wird zu (0, 1), B zu (-1, 0) und dieselbe inhaltliche Abfrage zu (0, 1). Eine konsistente Suche innerhalb des jeweiligen Raums findet weiterhin A.

Vergleichen Sie die gedrehte Abfrage dagegen mit den alten Dokumenten, gewinnt B. Jeder Vektor hat nach wie vor zwei Koordinaten. Die Berechnung läuft erfolgreich durch, während sich die Bedeutung des Suchergebnisses ändert. Dies ist ein mathematisches Gegenbeispiel zur Annahme, gleiche Dimensionen belegten Kompatibilität. Es simuliert weder das erlernte Verhalten eines Modells noch schätzt es reale Fehlerraten bei Migrationen.

Das Auffüllen eines alten Vektors mit Nullen ändert seine Länge, liefert aber keine Abbildung in die erlernte Repräsentation eines neuen Modells. Auch Abschneiden stellt keine modellübergreifende Kompatibilität her. Selbst bei der Verkürzung innerhalb eines unterstützten Modells müssen Dokumente und Abfragen dieselbe Dimensionsregel verwenden; evaluieren Sie außerdem das resultierende Retrieval-Verhalten. Native Unterstützung für verkürzte Embeddings erlaubt keine beliebige Vermischung alter und neuer Repräsentationen.

Die Schutzprüfung des Beispiels vergleicht vor der Kosinusberechnung die vollständige Konfiguration. Das funktioniert nur bei korrekten Metadaten: Wer eine neue Abfrage absichtlich als alte kennzeichnet, umgeht die Prüfung. Das Ergebnis unsafe_mixed_top unten zeigt genau diese Grenze. In Produktion muss die Herkunft aus der Encoder-Konfiguration und dem Speicherpfad abgeleitet werden, nicht aus einer ungeprüften Behauptung des Aufrufers.

Kosten des Neuaufbaus: den Korpus kalkulieren, nicht die Vektoranzahl

Die folgenden Preise wurden am 3. November 2026 geprüft. Die Orux-Tarife stammen aus den beiden öffentlichen Modelldatensätzen. Die direkten OpenAI-Standardtarife für Eingaben stammen aus den Preisangaben zum kleinen Modell und zum großen Modell. Es handelt sich um getrennte Bezugsoptionen; damit wird keine Gleichheit von Kontobedingungen oder Betriebsverhalten behauptet.

Die derzeit konfigurierte Umrechnung lautet 1 Credit = USD 0.005. Die USD-Werte sind rechnerische Entsprechungen; Orux rechnet in Credits ab. Sämtliche Tarife gelten pro eine Million Eingabe-Tokens, nicht pro Million Dokumente. Die Tabelle enthält keine separaten Kosten für Speicher, Indexhosting und Entwicklungsarbeit und setzt weder Batch-Rabatte noch einen kostenlosen Neuaufbau voraus.

Horizontal wischen, um die ganze Tabelle zu sehen.

Ein Planungskorpus mit 10.000 Chunks und durchschnittlich 500 Eingabe-Tokens umfasst insgesamt fünf Millionen Tokens. Wer diesen gesamten Korpus auf large umstellt, muss daher den Neuaufbau mit large budgetieren, nicht nur die Differenz zwischen beiden Tabellenzeilen. Bereits für small ausgegebenes Geld kauft keine large-Vektoren. Der Orux-Tarif für large ist in dieser Momentaufnahme ungefähr 6,5-mal so hoch wie der für small; dieses Verhältnis sagt nichts über die Retrieval-Verbesserung bei Ihren Dokumenten aus.

Die Summen sind Schätzungen auf Basis einer angenommenen Tokenzahl und einer aggregierten Berechnung. Tatsächliche Chunk-Längen, Suchverkehr, Wiederholungen und die Abrechnungsgranularität können die Kosten verändern. Ermitteln Sie die Korpus-Tokens mit dem passenden Tokenizer, bevor Sie einen echten Lauf freigeben. Der ausführbare Code verwendet ganzzahlige Micro-Credits für die Tarifberechnung und Decimal für die Anzeige; binäre Gleitkommarechnung für Geldbeträge wird so vermieden.

Für den Speicher ist eine eigene Schätzung nötig. Bei float32 benötigen 10.000 Vektoren mit 1.536 Dimensionen 61.440.000 Bytes, mit 3.072 Dimensionen 122.880.000 Bytes: ungefähr 58,59 MiB beziehungsweise 117,19 MiB. Das sind ausschließlich die rohen Koordinatenarrays. Metadaten, Kennungen, Suchgraphen, Replikate und Serialisierung verursachen zusätzlichen Aufwand. Bei einer umkehrbaren Migration brauchen beide rohen Arrays zusammen bereits 184.320.000 Bytes, noch ohne diesen Zusatzaufwand.

Kompatibilitäts- und Budgetbeispiel ausführen

Speichern Sie den folgenden Code als migration_demo.py und führen Sie python3 migration_demo.py mit Python 3.9 oder neuer aus. Er verwendet ausschließlich die Standardbibliothek und sendet keine Netzwerkanfragen. Die Tarife bilden einen datierten Stand ab, damit die Rechnung reproduzierbar ist. Ersetzen Sie sie bei einer späteren Migrationsplanung durch geprüfte aktuelle Tarife.

import json
import math
from dataclasses import asdict, dataclass
from decimal import Decimal

@dataclass(frozen=True)
class Contract:
    model: str
    dimensions: int
    preprocessing: str
    metric: str = 'cosine'

def validate(vector, contract):
    if len(vector) != contract.dimensions:
        raise ValueError('dimension mismatch')
    if any(isinstance(x, bool) or not isinstance(x, (int, float))
           or not math.isfinite(x) for x in vector):
        raise ValueError('non-finite or non-numeric vector')
    if math.hypot(*vector) == 0:
        raise ValueError('zero vector')

def search(query, query_contract, documents, index_contract):
    if query_contract != index_contract:
        raise ValueError('embedding contract mismatch')
    validate(query, query_contract)
    scores = []
    for doc_id, vector in documents.items():
        validate(vector, index_contract)
        score = sum(a*b for a, b in zip(query, vector)) / (
            math.hypot(*query) * math.hypot(*vector))
        scores.append((doc_id, score))
    return sorted(scores, key=lambda row: (-row[1], row[0]))

def budget(rate_micro_credits, total_tokens):
    micro = (rate_micro_credits * total_tokens + 999999) // 1000000
    credits = Decimal(micro) / 1000000
    return {'credits': str(credits), 'usd': str(credits * Decimal('0.005'))}

def main():
    # Handwritten two-dimensional geometry, NOT model outputs.
    old = Contract('toy-old', 2, 'title-body-v1')
    new = Contract('toy-new', 2, 'title-body-v1')
    old_docs = {'A': [1, 0], 'B': [0, 1]}
    new_docs = {'A': [0, 1], 'B': [-1, 0]}
    old_top = search([1, 0], old, old_docs, old)[0][0]
    new_top = search([0, 1], new, new_docs, new)[0][0]
    unsafe_top = search([0, 1], old, old_docs, old)[0][0]
    assert (old_top, new_top, unsafe_top) == ('A', 'A', 'B')
    failures = [
        lambda: search([0, 1], new, old_docs, old),
        lambda: validate([1], old),
        lambda: validate([0, 0], old),
        lambda: validate([float('nan'), 1], old),
        lambda: validate([True, 1], old),
        lambda: search([1, 0], Contract('toy-old', 2, 'title-body-v2'), old_docs, old),
    ]
    rejected = 0
    for test in failures:
        try:
            test()
        except ValueError:
            rejected += 1
        else:
            raise AssertionError('invalid fixture was accepted')
    chunks, tokens_per_chunk = 10000, 500
    tokens = chunks * tokens_per_chunk
    result = {
        'toy_results': {'old_top': old_top, 'new_top': new_top,
                        'unsafe_mixed_top': unsafe_top},
        'rejected_fixtures': rejected,
        'planning_tokens': tokens,
        'orux_small': budget(1533360, tokens),
        'orux_large': budget(9966720, tokens),
        'raw_float32_bytes': {'small_1536': chunks * 1536 * 4,
                             'large_3072': chunks * 3072 * 4},
        'new_contract': asdict(new),
    }
    print(json.dumps(result, indent=2))

if __name__ == '__main__':
    main()

Der lokale Lauf ergab old_top: A, new_top: A, unsafe_mixed_top: B und rejected_fixtures: 6. Zurückgewiesen wurden ein abweichender Modellvertrag, eine falsche Vektorlänge, ein Nullvektor, eine nicht endliche Koordinate, eine boolesche Koordinate und eine geänderte Vorverarbeitungsversion. Die geplanten Gesamtkosten für small und large betragen 7.6668 beziehungsweise 49.8336 Credits und stimmen mit der Tabelle überein.

Dies ist eine ausführbare Demonstration der Kompatibilitätsregel und der Kostenrechnung, kein Datenbankadapter. Sie ruft keine Embeddings ab, erstellt keinen Index für approximative nächste Nachbarn, belegt keine Retrieval-Qualität eines Modells und implementiert keine produktive Zugriffskontrolle. Die synthetischen Koordinatenwerte sind klein; eine numerische Bibliothek für Produktion sollte außerdem den gesamten Zahlenbereich ihrer zulässigen Eingaben beherrschen.

Bereitstellungsplan: Jeder Abfrage-Encoder bleibt mit seinem passenden Index verbunden; Umschaltung und Rollback betreffen das Paar. Das Diagramm zeigt die vorgeschlagene Architektur, keine bereits bereitgestellte Migration.

Abfrage-Encoder und Index als eine Konfiguration umschalten

Erstellen Sie mit dem Zielvertrag eine neue Collection oder einen neuen Namespace. Lesen Sie die ursprünglichen Quelltexte, wenden Sie die festgehaltenen Chunking- und Vorverarbeitungsregeln an und schreiben Sie die Vektoren des Zielmodells unter stabilen Dokument- und Chunk-Kennungen. Lassen Sie die bestehende Collection unangetastet. Verfolgen Sie erwartete Chunk-IDs, abgeschlossene IDs und Quellrevisionen, statt sich auf einen einzigen Zähler verarbeiteter Zeilen zu verlassen.

Falls sich Quelldokumente während des Neuaufbaus ändern, legen Sie eine klare Konsistenzregel fest. Ein einfacher Snapshot in einem Wartungsfenster vermeidet konkurrierende Schreibvorgänge, verzögert aber Aktualisierungen. Ein Online-Neuaufbau braucht ein erneut abspielbares Änderungsprotokoll oder einen gleichwertigen Abgleich, damit Änderungen und Löschungen vor der Umschaltung im neuen Index ankommen. Gleiche Vektoranzahlen reichen nicht, wenn sich ein gelöschtes und ein fehlendes Dokument zufällig zahlenmäßig ausgleichen.

Binden Sie danach jeden Abfrage-Encoder an seinen vorgesehenen Index. Stellen Sie die Anwendung nicht auf large-Abfragen um, während sie weiterhin die small-Collection liest. Behandeln Sie das Paar als eine versionierte Anwendungskonfiguration, einschließlich Vorverarbeitung, Dimensionen und Metrik. Weisen Sie Anfragen zurück, wenn das gespeicherte Collection-Manifest nicht zur Abfragekonfiguration passt. In mandantenfähigen Systemen müssen beide Collections dieselben Mandantenfilter und Dokumentberechtigungen erhalten.

Bewahren Sie für ein Rollback die alte Abfragekonfiguration und Collection gemeinsam auf. Nur alte Vektoren zu behalten genügt nicht, wenn die Anwendung keine kompatiblen alten Abfragen mehr erzeugen kann. Beobachten Sie nach der Umschaltung Ergebnisqualität, Meldungen über fehlende Dokumente, Latenz und Abfragekosten. Nehmen Sie das alte Paar erst nach dem vereinbarten Evaluations- und Aufbewahrungszeitraum außer Betrieb, nicht schon, sobald die neue Collection Schreibvorgänge annimmt.

Mit bewerteten Suchfragen entscheiden, nicht anhand der Vektorgröße

Stellen Sie vor dem vollständigen Neuaufbau einen kleinen, repräsentativen Evaluationssatz zusammen. Nehmen Sie für eine Produkthilfe exakte Teilenummern, ungenaue Fragen zur Fehlerbehebung, mehrsprachige Anfragen und Dokumente mit Zugriffsbeschränkungen auf. Halten Sie für jede Frage fest, welche Dokument-IDs relevant sind. Trennen Sie die Relevanzbewertung davon, ob die erzeugte Antwort flüssig klingt.

Rufen Sie für jede Konfiguration dieselbe Anzahl Ergebnisse aus demselben Dokument-Snapshot ab. Vergleichen Sie, ob relevante Dokumente unter den ersten Treffern erscheinen, und untersuchen Sie wichtige Fehltreffer. Vergleichen Sie keinen small-Index aus kurzen Textfragmenten mit einem large-Index aus angereicherten Titel-und-Text-Inhalten, um anschließend den gesamten Unterschied dem Modell zuzuschreiben. Chunking, Vorverarbeitung und Zugriffsfilter sind eigenständige Versuchsvariablen.

Dieser Artikel liefert keinen gemessenen Sieger. Wählen Sie small, wenn seine eigene Evaluation Ihre Anforderungen bei den derzeit geringeren Eingabe- und Speicherkosten erfüllt. Ziehen Sie large in Betracht, wenn gemessene Vorteile bei Ihrem Anwendungsfall den Neuaufbau, größere Vektoren und laufende Abfragekosten rechtfertigen. Ein erfolgreicher lokaler Kompatibilitätstest schafft eine Schutzregel, keinen Grund für den Kauf eines teureren Modells.

FAQ

Q.Muss ich beim Modellwechsel jeden Dokumentvektor neu erzeugen?

Ja, für die hier beschriebene Migration erzeugen Sie den durchsuchbaren Korpus im Raum des Zielmodells neu. Bewahren Sie Originaltexte und stabile Chunk-IDs auf und kodieren Sie künftige Abfragen mit derselben Zielkonfiguration. Bestehende Vektoren werden durch Umbenennen des Modellfelds nicht kompatibel.

Q.Kann ich Vektoren mit 1.536 Dimensionen auf 3.072 Dimensionen auffüllen?

Das Auffüllen kann eine Vorgabe für die Arraylänge erfüllen, stellt aber keine Abbildung zwischen Modellen her. Als Kompatibilitätsstrategie für diese Migration ist es ungeeignet. Das vereinfachte Beispiel zeigt, dass bei vermischten Räumen trotz gültiger Form das falsche Dokument gefunden werden kann.

Q.Bietet Orux den nativen OpenAI-Parameter dimensions an?

Die geprüften öffentlichen Formulare dieser beiden Orux-Aliase bieten ihn nicht an. Die native OpenAI-Dokumentation allein belegt kein entsprechendes Orux-Verhalten. Prüfen Sie den tatsächlichen Integrationsvertrag, bevor Sie sich auf verkürzte Ausgaben verlassen, und bauen und durchsuchen Sie anschließend einen konsistent konfigurierten Index.

Q.Ist text-embedding-3-large automatisch besser für meine Suche?

Dieser Artikel belegt keine Verbesserung für Ihren konkreten Anwendungsfall. Evaluieren Sie beide Konfigurationen mit Ihren eigenen bewerteten Fragen und demselben Quell-Snapshot. Mehr Dimensionen und höhere Preise ersetzen keine Messung, ob relevante Dokumente gefunden werden.

Q.Was hat das Python-Beispiel tatsächlich getestet?

Es hat die Geometrie von Hand definierter Vektoren, die Zurückweisung abweichender Verträge, sechs ungültige Testfälle sowie die datierte Budget- und Speicherrechnung getestet. Es hat keine Embedding-API aufgerufen, keine Orux Credits verbraucht und weder Modellausgaben noch eine echte Vektordatenbank einem Benchmark unterzogen.