A useful vector collection is the least complex option when product-content questions need semantic matching and every answer must point back to approved fintech copy. The operational requirement is stricter than "store some embeddings": each collection needs one fixed dimension because distance is defined between equal-length vectors, and the embedding model determines that length. Treat the dimension, model identity, preprocessing rules, and source metadata as one versioned ingestion contract.
TL;DR: reject a vector at the write boundary when its length differs from the collection dimension; never pad, truncate, or silently mix it with vectors from another embedding configuration. During a model change, build and validate a new collection, then switch retrieval traffic deliberately. That preserves comparable scores and, just as important for regulated product content, keeps retrieval results tied to citations that can be checked.
The page usually arrives later: "grounded-answer rate below objective." On-call sees successful request counts, ordinary latency, and an answer with no qualifying citation among its retrieved passages. The service is up. The evidence path is not.
Why does a vector collection need a fixed dimension?
A vector is an ordered list of numbers produced by an embedding process. Its dimension is simply the number of positions in that list. A collection groups vectors under a shared schema so an index can compare a query vector with stored vectors using a declared similarity rule. Euclidean distance, for example, compares corresponding coordinates; cosine similarity uses a dot product and vector magnitudes. Those operations require equal-length inputs. A 768-value query and a 1,536-value stored item do not describe two compatible points in one coordinate space.
Equal length is necessary, but it is not sufficient. Two models can emit the same number of values while assigning unrelated meanings to their coordinates. Even two revisions of one pipeline may differ because tokenization, normalization, or input prefixes changed. Dimension is therefore the cheap structural guardrail, not proof of semantic compatibility. The full contract needs a stable encoder identifier and preprocessing version as well. This distinction matters during an incident because a shape check can be green while retrieval quality quietly changes: the records fit the index, yet their coordinates no longer mean what the query encoder assumes. Diagnose that case with version labels and a labeled retrieval set, not by relaxing the dimension check.
The earlier signal should be a rejected-vector counter grouped by expected dimension, observed dimension, and ingestion version, paired with an age gauge for the newest successfully indexed approved document. Page on user-visible grounding failure; ticket or alert earlier on sustained contract rejection or citation-freshness risk. This ordering catches the broken supply line before the answer SLO spends its error budget.
For fintech product content, the stored record also needs evidence fields outside the vector: a stable document ID, source URL, effective version, approval state, and the exact passage used for retrieval. Embeddings help rank candidates.
They are not citations.
An embedding cannot reconstruct the source text. RAG joins retrieval with generation, but the generator still needs the retrieved evidence and provenance if an answer is expected to support its claims.
Instrument the contract at ingestion
Validate before the index write, while the producer still has enough context to identify the bad batch. A small Go boundary makes the policy unambiguous:
package vectors
import (
"errors"
"fmt"
)
type Contract struct {
Dimension int
EncoderID string
PreprocessingVersion string
}
type Record struct {
DocumentID string
SourceURL string
EncoderID string
PreprocessingVersion string
Values []float32
}
func Validate(c Contract, r Record) error {
if c.Dimension <= 0 {
return errors.New("collection dimension must be positive")
}
if len(r.Values) != c.Dimension {
return fmt.Errorf("dimension mismatch: expected %d, got %d", c.Dimension, len(r.Values))
}
if r.EncoderID != c.EncoderID {
return fmt.Errorf("encoder mismatch: expected %q, got %q", c.EncoderID, r.EncoderID)
}
if r.PreprocessingVersion != c.PreprocessingVersion {
return fmt.Errorf("preprocessing mismatch: expected %q, got %q", c.PreprocessingVersion, r.PreprocessingVersion)
}
if r.DocumentID == "" || r.SourceURL == "" {
return errors.New("retrievable records require document ID and source URL")
}
return nil
}
Do not repair it.
Padding invents coordinates the encoder never produced; truncation discards part of its output. Either operation creates a different representation without an evaluation showing that its rankings remain useful. Rejecting the record is noisier at ingestion and far quieter during an incident.
The query path must use the same contract. Emit the collection version, encoder ID, retrieved document IDs, citation eligibility, retrieval duration, and outcome, but avoid logging raw customer queries or sensitive passage text by default. The useful unit for an alert is a rate or distribution, not a single malformed request. One rejection can be a canary. A sustained increase can mean a deployment boundary has split.
Capacity planning is part of the schema decision
Dimension changes resource demand even before index overhead is counted. With float32, the raw vector payload is record_count * dimension * 4 bytes. One million 768-dimensional vectors therefore contain 3,072,000,000 bytes of raw numeric data, about 2.86 GiB. That is not a memory forecast: index structures, metadata, replicas, allocator behavior, and temporary rebuild space add their own load. Measure those components on the implementation and dataset that will actually run.
This is where an infrastructure roadmap gets honest. A managed service can move index operations and parts of capacity management away from the team, while self-hosting can give tighter control over deployment and data placement; neither choice removes the need to version the embedding contract or evaluate citations. The decision belongs in an SLO and staffing discussion, not in a feature checklist.
| Decision area | Managed operation | Self-hosted operation | Evidence to collect |
|---|---|---|---|
| Rebuild capacity | Confirm quotas, concurrency, and isolation behavior | Reserve compute, memory, and temporary storage | Full rebuild duration and impact on live queries |
| On-call ownership | Define provider and application escalation boundaries | Own index, storage, upgrades, and recovery | Failure drills and paging history |
| Lock-in | Inspect export format and index-specific semantics | Inspect component and format portability | Timed export, restore, and reindex test |
| Grounding | Application still owns source eligibility and citation checks | Application still owns source eligibility and citation checks | Labeled retrieval and citation evaluation set |
A useful capacity plan includes normal ingestion, a full parallel rebuild, rollback retention, and peak query load. If the plan only fits steady state, an encoder migration will compete with production or become an indefinitely deferred risk.
Change the encoder without mixing coordinate spaces
Create a new collection with a new contract. Re-embed the approved corpus into it, preserve source IDs and version metadata, and run the same labeled query set against old and new retrieval paths. Evaluate retrieval separately from generation: did the expected passage appear, was it eligible at the query time, and did the answer cite that passage accurately? Aggregate relevance can hide failures on disclosures, fee explanations, eligibility rules, or other small but consequential slices.
Then shadow queries or send a controlled traffic fraction to the new path. Compare latency distributions, empty-result rate, citation coverage, and the labeled retrieval measures chosen before the migration. Keep the old collection available for a bounded rollback window, switch the read alias or application configuration, and retire old data only after the observation window completes.
No in-place mixing.
This parallel approach costs temporary storage and compute, yet it gives the team a comprehensible rollback boundary. An in-place rewrite may appear cheaper on a diagram, but readers can encounter a partially migrated corpus, and score distributions may change while thresholds still reflect the old encoder. A fixed-dimension collection turns that dangerous ambiguity into a visible incompatibility. The encoder and preprocessing checks close the remaining same-shape loophole.
The limitation is duplication: parallel migration needs temporary capacity and keeps two retrieval paths operational. For a tiny, rebuildable corpus with no availability objective, an offline rebuild and an explicit maintenance window may be the better trade-off. For continuously served product content with citation commitments, the extra capacity buys a rollback boundary that an in-place conversion cannot provide.
Close the page with evidence, then tune the alert
The incident is resolved when approved product passages are being embedded under the intended contract, retrieval returns eligible sources, and generated claims carry citations that resolve to those passages. A falling error counter alone is weak closure; replay the affected query class and record which contract and corpus versions served it.
Alert thresholds need restraint. Paging on every rejected write creates noise during harmless client mistakes and teaches responders to ignore the signal. Waiting for answer-level grounding failures burns the user-facing error budget. Start with two layers: a low-urgency signal for any contract rejection, and a page for a sustained rejection rate, stalled freshness, or measured grounding SLO breach. Set the exact windows from observed ingestion cadence and error-budget policy rather than copying a universal number.
False positives have a real capacity cost. They interrupt the same people needed to operate migrations and evaluate retrieval quality, so threshold reviews should examine pages that produced no action, low-volume batches, planned rebuilds, and delayed source approvals. Suppress known maintenance through explicit deployment metadata, not by weakening the invariant. The fixed dimension should never be negotiable; the urgency of its alert can be.
A collection is ultimately a compatibility boundary with an index behind it. Keep the boundary narrow, version the meaning as well as the shape, and judge the system by whether it retrieves current evidence that a reader can verify.
Top comments (0)