Image Similarity Search

Installation

1. Install dependencies:

1.1. Create and activate a virtual environment bash python -m venv venv source venv/bin/activate # On Windows use `venv\Scripts\activate`

1.2. Install the required packages using pip:

pip install -r requirements.txt

2. Download data-images

2.1. Move data-images folder from https://github.com/msikyna/MetricLearningExperiment2 to the root directory of the project.

2.2. Into the data-images folder, add the 561.txt file from https://drive.google.com/drive/folders/1sFfDmAFW5OcI3wNIEdYVQsZnUoxp-N-5?usp=sharing directly into the data-images folder.

2.3. The final structure should look like this:

/sim-search
├── data-images
│   ├── 561
│   │    ├── 000.jpg
│   │    ├── 001.jpg
│   │    ├── 002.jpg
│   │    └── ...
│   └── 561.txt
├── requirements.txt
├── README.md
├── manage.py 
├── djangoProject
├── base
└── ...

3. Run the server:

1.

python manage.py makemigrations

2.

python manage.py migrate

In Bash:

python manage.py runserver

OR

In PyCharm:

1. Open Run Configuration Settings:

   • Click the "Add Configuration" button in the top-right toolbar
   • Or go to Run → Edit Configurations...

2. Add Django Server Configuration:

   • Click the + button
   • Select Django Server from the list

3. Configure Settings:

   • Name: Django Server
   • Host: 127.0.0.1
   • Port: 8000
   • Python interpreter: Ensure your project's Python interpreter is selected
   • Working directory: Should point to your project root (where manage.py is located)
   • Environment variables: Leave blank unless needed

4. Apply and Run:

   • Click Apply and OK
   • Click the green play button (▶) in the toolbar to start the server

4. Access the application:

Open your web browser and navigate to http://127.0.0.1:8000/ to use the image similarity search application.

Usage

1. Select a base image from selection or search by text

For caller-supplied metric-matrix searches, see MAHALANOBIS_SEARCH_API.md.

Docker Deployment (Server)

This setup is prepared so you can pull the repo and run with Docker directly.

1. Prepare environment

cp .env.example .env
mkdir -p runtime user_matrices cache/L2 cache/IP

2. Build and run

docker compose up -d --build

If the project was moved and the new ./cache bind mount is empty or root-owned, seed FAISS mapping files from the old deployment cache:

SIMSEARCH_SEED_CACHE_ROOT=/home/xsikyna/sim-search/cache \
  docker compose -f docker-compose.yml -f docker-compose.seed-cache.yml up -d --build

3. Check logs

docker compose logs -f sim-search

4. Update after code changes

git pull
docker compose up -d --build

Final URL target

The app is configured for URL prefix:

http://disa.fi.muni.cz/demos/personalized-similarity-search

through:

DJANGO_FORCE_SCRIPT_NAME=/demos/personalized-similarity-search

Reverse proxy (Apache) example

ProxyPreserveHost On
ProxyPass        /demos/personalized-similarity-search/  http://cybela14.fi.muni.cz:8942/
ProxyPassReverse /demos/personalized-similarity-search/  http://cybela14.fi.muni.cz:8942/
RequestHeader set X-Forwarded-Proto "https"

Container/network notes

• Gunicorn inside container binds 0.0.0.0:8942.
• Published port is ${SIMSEARCH_BIND_IP}:${SIMSEARCH_PORT} (default 0.0.0.0:8942).

Concurrency tuning for ~20 simultaneous users

The repo defaults are tuned for a modest multi-user deployment:

• GUNICORN_WORKERS=8
• FAISS_NUM_THREADS=1
• file-based Django sessions in /app/runtime/sessions
• SQLite WAL + busy timeout enabled
• SIMSEARCH_QUERY_LOG_EXPAND_RESULTS=0 to avoid a second search only for logging
• in-process user matrix cache enabled (SIMSEARCH_MATRIX_CACHE_SIZE=32)

Recommended next step on the server:

1. Keep only the index you really use enabled.
2. Serve /images/... outside Gunicorn if possible.

Why step 2 matters:

• the search backend can handle concurrency reasonably with multiple workers
• image streaming from shared storage through Gunicorn will still consume workers quickly

If your reverse proxy supports it, prefer one of these:

• Apache/Nginx direct file serving for /images/
• or enable SIMSEARCH_IMAGE_X_SENDFILE=1 / SIMSEARCH_IMAGE_X_ACCEL_REDIRECT_PREFIX=...

That change usually helps concurrency more than just increasing Gunicorn workers.

Load Testing

There is a standalone HTTP load test script at:

python scripts/loadtest_sim_search.py --help

It exercises the real personalization flow over HTTP:

1. login
2. text search
3. save positive and negative feedback
4. apply feedback to learn/update the matrix
5. rerun the query
6. optionally fetch the progressive full rerun

Example: 20 concurrent users

python scripts/loadtest_sim_search.py \
  --base-url http://disa.fi.muni.cz/demos/personalized-similarity-search/ \
  --users 20 \
  --rounds 5 \
  --num-results 20 \
  --metric cosine \
  --output-json runtime/loadtest_20_users.json

Notes:

• By default the script prepares test users named loadtest_user_001, loadtest_user_002, ...
• The first version uses the text-search path because it covers the full search + feedback + matrix-learning flow without needing extra image-anchor fixtures.
• If you want to reuse pre-created users, add --no-prepare-users.