https://github.com/mbari-org/fastapi-vss
RESTful API for vector similarity search. It uses the Python web framework FastAPI. This accelerates machine learning workflows that require vector similarity search using foundational models.
https://github.com/mbari-org/fastapi-vss
fastapi foundation-models image-classification vision-transformer
Last synced: 4 months ago
JSON representation
RESTful API for vector similarity search. It uses the Python web framework FastAPI. This accelerates machine learning workflows that require vector similarity search using foundational models.
- Host: GitHub
- URL: https://github.com/mbari-org/fastapi-vss
- Owner: mbari-org
- License: apache-2.0
- Created: 2024-07-10T22:48:24.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-01-30T19:47:29.000Z (over 1 year ago)
- Last Synced: 2025-04-13T12:12:39.354Z (about 1 year ago)
- Topics: fastapi, foundation-models, image-classification, vision-transformer
- Language: Python
- Homepage:
- Size: 20.5 MB
- Stars: 2
- Watchers: 5
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
[](http://www.mbari.org)
[](https://github.com/semantic-release/semantic-release)
[](https://opensource.org/licenses/Apache-2.0)
[](https://www.python.org/downloads/)
**fastapi-vss** is a RESTful API for vector similarity search 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](https://github.com/danellecline)
---
## Architecture
Built on **Redis Stack** (vector store + job queue)—the fastest option 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
```mermaid
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]
```
**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:
```yaml
# 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.
```yaml
# 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.
---
## Related
- Train your own ViTS model using the Huggingface trainer: https://github.com/mbari-org/vitstrain