3.0 KiB
Qdrant Index Contract
M6 embedding-space identity
New ModelForge shadow collections and payloads carry the exact embedding_space_id; dimensions
alone never establish compatibility. The current production collection remains legacy-observed and
unchanged. Evaluation-only shadow reads name a server-owned profile and never mutate the alias.
Collecties
Collecties worden per indexprofiel/embeddingruimte gemaakt, niet per project:
rag_dense_<profile>_<version>
rag_code_<profile>_<version>
Een alias verwijst naar de actieve build. Verschillende dimensies of modeldigests worden nooit gemengd.
Named vectors
dense: semantische embedding;sparse: lexicale/tokenrepresentatie;- latere multivector alleen via nieuw profiel en evaluatie.
Verplichte payload
workspace_id, space_id, document_id, document_version_id, chunk_id, parent_chunk_id, source_id, status, content_type, language, trust_level, location, profile versions en tekst/excerpt.
Payload indexes
Minimaal: workspace, space, document, version, status, content_type, language en trust_level. Voeg geen index toe zonder gemeten filtergebruik.
Query invariant
Iedere query bevat server-side workspace/space/statusfilters. Raw clientfilters worden nooit rechtstreeks doorgestuurd; toegestane filters worden gecompileerd uit typed requestvelden.
Rebuild
Qdrant is afgeleid. Rebuild maakt een shadow collection, controleert counts/samples/golden queries, activeert alias en houdt de vorige build voor rollback.
Elke build-, rollback- en reconcile-aanroep wordt per alias geserialiseerd door een PostgreSQL-backed lease lock (indexes.index_build_operations), niet door een proceslokale lock, zodat meerdere app-/workerreplicas nooit dezelfde aliasmigratie gelijktijdig uitvoeren. Acquisitie is begrensd (timeout + backoff) en een gecrashte houder laat geen permanent vastgelopen lock achter: een verlopen lease wordt bij de volgende poging gereclaimed en als needs_repair gemarkeerd zodat de eerdere afbraak zichtbaar blijft.
Elke stap van een operatie wordt in dezelfde rij gelogd (saga log) zodat een gedeeltelijk mislukte build gecompenseerd kan worden: vóór activatie wordt de shadow collection verwijderd; na (een poging tot) activatie wordt de alias geforceerd teruggezet naar de vorige collectie en geverifieerd. Een compensatie die zelf niet bevestigd kan worden resulteert in needs_repair en een IndexRepairError, nooit in een stilzwijgend geslaagde melding.
Malformed of legacy points blokkeren reconciliatie niet: ze worden gedetecteerd, uitgesloten van gebruik en vervolgens hersteld (deterministisch herbouwd vanuit de authoritative bron) wanneer hun ID bij een verwachte chunk hoort, of gequarantained (verwijderd op exact opgeslagen ID) wanneer dat niet zo is.
Batchquota voor Qdrant-schrijfoperaties tellen de werkelijke UTF-8-geserialiseerde bytes van het volledige payload, de sparse-vectoren en de fingerprintvelden, niet alleen tekst/excerpt-lengte; een build kent daarnaast een cumulatieve bytequota over alle batches heen.