vss is a vector similarity search service that using FastAPI and Redis—the fastest vector database available. Redis Stack's in-memory RediSearch delivers sub-millisecond KNN queries. ViT (Vision Transformer) models power image retrieval, rare event mining, anomaly detection, and labeling unlabeled data (e.g., plankton, marine imagery).

Author: Danelle Cline

---

Architecture

Built on Redis Stack (vector store + job queue)—the for vector similarity workloads. Project isolation: each project can use a dedicated Redis instance (host/port) so vector indexes and queues stay separate.

Batching: The pipeline is tuned for high-throughput batch inference. Set BATCH_SIZE (default 32) via environment variable to match GPU memory. RQ decouples the API from inference so requests enqueue and process asynchronously. Multiple workers run in parallel (one per project), and preprocessing uses a thread pool for parallel image loading.

Workflow

flowchart LR
    A[Client] -->|POST /knn| B[FastAPI]
    B -->|Enqueue| C[(Redis Queue)]
    C --> D[RQ Worker]
    D --> E[ViT: preprocess → embed]
    E --> F[KNN search]
    F --> G[(Vector Store)]
    G --> F
    F --> H[JSON result]

Loading

Flow: Client uploads images → API enqueues job, returns job_id → Client polls GET /predict/job/{job_id}/{project} → Worker runs ViT inference, searches Redis KNN → Result returned.

Features

• Redis—fastest vector database available; sub-ms KNN over embeddings
• Foundational (DINO) or fine-tuned ViT models trained with the Huggingface trainer: https://github.com/mbari-org/vitstrain
• Batch processing—configurable BATCH_SIZE (env var), async RQ, parallel workers; top-n search
• Docker, OpenAPI docs, URL-based config override

Configuration

YAML config files are loaded from the CONFIG_PATH directory. By default this is the config/ directory at the project root. Override by setting the CONFIG_PATH environment variable.

Basic example that define the redis server and a single model:

# config_testproject1.yaml
# This config references a foundational model
redis:
  host: "redis-stack-vss"
  port: 6379
vss:
  model: "google/vit-base-patch16-224"
  project: "testproject1"
  output_path: "/data/vss/outputs/testproject1"

For multiple models, add multiple config files per each project, e.g.

# config_testproject2.yaml
# This config uses a locally stored model
redis:
  host: "redis-stack-vss"
  port: 6379
vss:
  model: "/mnt/models/CFE/cfe_isiis_dino_v7-20250916/"
  project: "testproject2"
  output_path: "/data/vss/outputs/testproject2"

Add config_url: "https://..." to merge remote config (remote overrides local). Timeout 30s.

---

Development

Recipes are managed with just. Install it with:

brew install just        # macOS
cargo install just       # any platform with Rust

List all available recipes:

just list

Setup

Create the conda environment, install dependencies, and configure pre-commit hooks:

just install

This will:

1. Create (or update) the fastapi-vss conda environment from environment.yml
2. Install the pinned redis-py wheel
3. Install pre-commit hooks
4. Print the activation command when done

Activate the environment:

conda activate fastapi-vss

Regenerate the .env file and prepare local config/model paths:

just setup-env

This creates .env with Redis credentials and downloads the default ViT model to models/vit-base-patch16-224.

Running locally

Start Redis only (needed before running the FastAPI server locally):

just run-redis-dev

Start the FastAPI server + RQ worker in development mode (hot-reload enabled):

just run-server-dev

API is available at http://localhost:8000 and docs at http://localhost:8000/docs.

Testing

Run the test suite against a locally running production stack:

just test

This starts the full Docker Compose stack, waits for the server to be healthy, then runs tests/test_endpoint.py.

Run pre-commit checks before committing:

just pre-commit

Docker

Build the CPU image:

just build-docker

Build the CUDA image:

just build-docker-cuda

---

Related

• Train your own ViTS model using the Huggingface trainer: https://github.com/mbari-org/vitstrain