A vector index is only a candidate retrieval layer. To make results reproducible, fix the embedding model, preprocessing rules, distance metric, and index parameters, and store them in index metadata.
Core concepts
Vectors from the same model can be compared directly. Store the model identifier, dimension, normalization method, and build time in the index. Changing any of these requires a new index version rather than mixing data in place.
import math
def cosine(a: list[float], b: list[float]) -> float:
dot = sum(x * y for x, y in zip(a, b))
na = math.sqrt(sum(x * x for x in a))
nb = math.sqrt(sum(y * y for y in b))
return dot / (na * nb) if na and nb else 0.0
assert round(cosine([1, 0], [1, 0]), 3) == 1.0
Steps
- Fix cleaning, chunking, and embedding model versions and write them into the index manifest.
- Use a small data set to verify dimensions, empty vectors, and duplicate-document handling.
- Choose distance and retrieval count, recording build parameters and failed batches.
- Compare recall and latency with an offline question set before introducing an approximate index.
When to use it
This workflow suits small and medium knowledge bases and production pipelines that need versioned rebuilds.
Common questions
Do I need a vector database? Not always. SQLite or an in-memory index can validate the workflow at small scale.
Can I reuse an old index after changing the embedding model? Usually not. Build a new version and evaluate it again.
Is a larger retrieval count always better? Too many candidates add noise and context cost. Let an evaluation set decide.
Official references
OpenAI Embeddings; Qdrant documentation.
Last checked: 2026-11-16. Use the linked documentation for current model and index behavior.
