# Vector Retriever Microservice


<div class="component_card_widget">
  <a class="icon_github" href="https://github.com/open-edge-platform/edge-ai-libraries/tree/release-2026.2.0/microservices/vector-retriever/vector-retriever">
     GitHub
  </a>
  <a class="icon_document" href="https://github.com/open-edge-platform/edge-ai-libraries/blob/release-2026.2.0/microservices/vector-retriever/vector-retriever/README.md">
     Readme
  </a>
</div>


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

- [How It Works](./how-it-works.md)
- [System Requirements](./get-started/system-requirements.md)
- [Get Started](./get-started.md)
- [How to Build from Source](./get-started/build-from-source.md)
- [How To Add New Retriever Backend](./add-new-retriever-backend.md)
- [API Reference](./api-reference.md)
- [Filter Grammar Reference](./filter-grammar.md)
- [Release Notes](./release-notes.md)


:::{toctree}
:hidden:

Get Started <./get-started.md>
How It Works <./how-it-works.md>
How To Add New Backend <./add-new-retriever-backend.md>
API Reference <./api-reference.md>
Filter Grammar Reference <./filter-grammar.md>
Release Notes <./release-notes.md>

:::