Vector Retriever Microservice#

GitHub Readme

The Vector Retriever microservice provides semantic retrieval over vector stores through a single FastAPI interface. It supports batch querying, metadata filtering, and pluggable vector database backends.

This service is designed for semantic search workloads where embeddings are generated by a compatible embedding service (for example the local MME overlay) and stored in a vector store.

Overview#

The API exposes four endpoints:

  • GET /health for liveness checks

  • GET /ready for dependency readiness checks

  • POST /query for batch semantic search

  • GET /capabilities/filters for filter grammar discovery

Each query can include:

  • optional query_id

  • query text or image input (mutually exclusive)

  • primary where filters

  • compatibility aliases: tags, time_filter, filters

  • optional top_k

  • optional explain_filters

Image input supports two formats via a discriminated union: image_url (remote URL) and image_base64 (base64-encoded data). The embedding service computes the image embedding, and the retriever performs vector similarity search against stored document embeddings.

Key Capabilities#

  • Backend-agnostic retrieval flow with backend-specific adapters

  • Batch execution with partial failure isolation

  • Dynamic metadata filters with validation and operator guardrails

  • Backend-specific filter translation (VDMS, Milvus, PGVector, FAISS)

  • Runtime backend selection with RETRIEVER_BACKEND

Backend Support#

Current backends:

  • vdms

  • milvus

  • pgvector

  • faiss

Backend-specific code is organized under src/retriever/backends/<backend_name>/.

Supporting Resources#