Deployment Guide

Operations & Deployment

Overview

This is a local-only application with no cloud deployment. This section covers local setup, dependencies, and hardware requirements.

Prerequisites

Component	Requirement	Notes
Python	3.9+	Tested with 3.10/3.11/3.12
GPU (Recommended)	NVIDIA CUDA or Apple MPS	For comfortable indexing speeds
RAM	8GB minimum	16GB+ recommended for 10k+ images
VRAM	4GB+	For half-precision model inference

Setup

pip install -r requirements.txt

Dependencies:

Package	Purpose
fastapi, uvicorn	API framework and ASGI server
chromadb	Persistent vector database
transformers, accelerate	HuggingFace model loading
torch, torchvision	Deep learning runtime
Pillow, pillow-heif	Image loading and HEIF support
opencv-python	Video frame extraction
qwen-vl-utils	Vision processing utilities
tqdm	Progress bars

Running the Application

Step 1: Index the Vault

python indexer.py vault
python indexer.py vault --batch 16

Step 2: Start the API Server

python api.py
# Server starts at http://127.0.0.1:8000

Scalability

• Vault Size: Designed to handle 10k+ images.
• Database: ChromaDB uses HNSW indexing with cosine similarity for sub-100ms lookups.
• Batch Processing: Adjustable via --batch parameter (default: 8). Larger batches improve throughput but require more VRAM.
• Indexing Time: Dependent on GPU. Expect 10-30 images/sec on modern GPUs.

Maintenance

Task	Command	Notes
Re-index after vault changes	python indexer.py vault	Automatic via mtime tracking
Clear and rebuild DB	Delete .db/ folder	Full re-index required
Clear thumbnails	Delete .cache/thumbnails/	Regenerated on next run

Monitoring

• /health endpoint returns current device and status.
• Console output from indexer.py shows processing throughput.

Related Components

• Environment Configuration – All configurable constants
• Image Indexing Pipeline – Indexing workflow details
• REST API Endpoints – API server internals

---

Last Updated: 2026-06-17