Embedding Vectordb

Open-source:

Dimensionality and Matryoshka

Matryoshka embeddings (OpenAI text-embedding-3, nomic-embed) allow truncating dimensions without retraining: 3072 → 1024 or 512 trades modest quality loss for faster search. Test at each dimension on your eval set before committing. Rule of thumb: 256–512 dims is enough for most retrieval; 1024+ for fine-grained similarity.

Similarity metrics

Default is cosine — most embedding models are trained with it. For unit-length embeddings, cosine equals dot product.

Vector database selection

Decision flow: prototyping → Chroma or FAISS. Already on Postgres → pgvector. Production with advanced filtering → Qdrant or Weaviate. Zero ops → Pinecone. Billions of vectors → Milvus.

Index types

HNSW is the default for most vector DBs. Key params: M (connections per node, default 16), ef_construction (build quality, default 200), ef_search (query quality, default 100). Higher M and ef = better recall, more memory, slower build. Start with defaults; tune ef_search up for recall, down for latency.

IVF clusters vectors and searches only relevant clusters. Params: nlist ≈ sqrt(N), nprobe ≈ nlist/10 to nlist/5. Faster than HNSW above ~100M vectors.

PQ (Product Quantization) compresses vectors with slight quality loss. Use when the dataset will not fit in memory. Often combined as IVF-PQ.

Hybrid search

Combine dense (semantic) and sparse (keyword/BM25) retrieval: dense catches "automobile" matching "car," sparse catches exact matches (product IDs, acronyms, proper nouns). Fuse with Reciprocal Rank Fusion: RRF = sum(1 / (k + rank_i)) with k typically 60. Hybrid almost always outperforms either method alone. Qdrant and Weaviate have built-in hybrid; for others, run BM25 (Elasticsearch/OpenSearch) and vector search separately and fuse.

Gotchas

Agent-specific failure modes — provider-neutral pause-and-self-check items:

• Choosing an embedding model based solely on MTEB leaderboard scores. MTEB benchmarks general-purpose retrieval; your domain may have different vocabulary, query patterns, or document lengths. Always benchmark candidate models on a small eval set from your own data before committing to one.
• Using L2 (Euclidean) distance with embeddings trained for cosine similarity. Most embedding models are trained with cosine similarity as the loss. Using L2 distance with them produces incorrect similarity rankings. Check the model card for the intended distance metric before configuring the vector store index.
• Embedding raw documents and chunking after the fact. An embedding represents the full input as a single vector. Embedding a 10,000-word document produces one vector that represents everything and nothing specifically. Chunk first, then embed each chunk.
• Pure dense retrieval for catalogs with exact identifiers. Dense (semantic) retrieval fails on product SKUs, proper nouns, acronyms, and precise version numbers — it is too fuzzy. Combine with sparse (BM25 / keyword) retrieval using reciprocal rank fusion for these use cases.
• No eval set to detect retrieval regressions. Without a golden set of queries with expected results, there is no way to know whether a change to chunking, embedding model, or index parameters improved or degraded retrieval quality. Build an eval set before the first production deployment.
• Single embedding model for both query and document without asymmetric fine-tuning. Queries and documents have different linguistic patterns. Some models (e.g., Voyage, e5-instruct) require instruction prefixes like "Represent this document:" for passages and "Represent this query:" for queries. Using the wrong prefix produces poorer retrieval.
• Sharing one DataLoader (or equivalent batch object) instance across search requests. Results from a cached retrieval object may belong to a different request's context. Always create per-request retrieval objects when batching or caching at the database layer.

Full reference

Metadata filtering and multi-tenancy

Store metadata alongside vectors: source, date, category, tenant_id. Pre-filter (filter before vector search) is more efficient than post-filter. For multi-tenancy, use a metadata filter on tenant_id or separate collections per tenant. Index metadata fields used in filters for performance.

Embedding pipeline best practices

• Batch processing — embed in batches of 100–500 for API efficiency
• Caching — cache by content hash to skip re-embedding unchanged content
• Normalization — normalize to unit length when using cosine
• Chunking alignment — chunk text before embedding, never embed then chunk
• Monitoring — track embedding latency, cache hit rate, and index size over time

Worked examples

• Semantic search for a docs site: text-embedding-3-small for cost-effective embedding; pgvector if already on Postgres, otherwise Qdrant. Hybrid search (BM25 + dense). Chunk by section headers at 512 tokens. Build a 50-query eval set with expected results to tune retrieval.
• Slow vector search at 5M vectors (> 500ms): If flat index, switch to HNSW. If HNSW, lower ef_search (recall vs speed). Consider Matryoshka 3072 → 1024. Enable metadata pre-filtering to shrink the search space. Benchmark each change against the eval set.
• Migrating Chroma → Qdrant: Export vectors and metadata. Create Qdrant collection with matching distance metric and dimensions. Batch-upload. Verify record count. Run the eval set against both for recall and latency. Configure Qdrant replication for HA.

Anti-patterns

• Picking a model from MTEB without benchmarking on your domain
• Using L2 distance with embeddings trained for cosine
• Embedding raw documents and chunking after the fact
• Pure dense retrieval for catalogs full of SKUs and proper nouns
• Production vector store with no eval set to detect regressions