Skip to content

FAISS search experiment

The FAISS experiment answers one question: given a query face, can the system find the same identity in the gallery? If the query is an unknown person, the nearest result should not be accepted automatically. A threshold decides whether the system rejects it.

This is different from DBSCAN. FAISS is targeted 1:N lookup with gallery, query_known, and query_unknown. DBSCAN is unlabeled grouping.

Inputs

ArcFace route:

outputs/insightface/embeddings.h5
outputs/insightface/embedding_metadata.csv

HOG baseline:

outputs/hog/embeddings.h5
outputs/hog/embedding_metadata.csv

Both routes must run. ArcFace is the main route. HOG is the baseline used for comparison.

Run

ArcFace:

python3 experiments/faiss/run_faiss_experiment.py --route insightface

HOG:

python3 experiments/faiss/run_faiss_experiment.py --route hog

The script defaults to --top-k 5. In the report, Top-K(k=5) means each query returns the five nearest gallery candidates, and the result counts as a hit if the correct identity appears anywhere in those five candidates.

For a small check, limit the query counts:

python3 experiments/faiss/run_faiss_experiment.py \
  --route insightface \
  --max-known 100 \
  --max-unknown 100 \
  --output-dir outputs/faiss_smoke/insightface

Remove smoke output after checking it.

Outputs

Each route writes:

outputs/faiss/<route>/index.faiss
outputs/faiss/<route>/known_search_results.csv
outputs/faiss/<route>/unknown_search_results.csv
outputs/faiss/<route>/threshold_report.csv
outputs/faiss/<route>/benchmark.json

known_search_results.csv measures Top-1 and Top-K(k=5) hits. unknown_search_results.csv and threshold_report.csv measure unknown rejection.

How to read the result

A valid run should have:

  • at least one gallery vector
  • known query rows with Top-1 and Top-K(k=5) results
  • unknown query rows reported separately
  • benchmark fields for embedding dimension, index type, score type, and elapsed time
  • separate output directories for ArcFace and HOG