recallA retrieval
field guide

Vector Search with FAISS

Build this skill

Build and compare Flat, IVF and HNSW indexes with FAISS, measuring build time, memory, latency and recall.

FAISS (Facebook AI Similarity Search) is an open-source library from Meta's AI research team for searching large collections of vectors quickly. It was released in 2017, and the paper describing it showed similarity search over a billion vectors using GPUs. FAISS runs inside many products and research projects, and several vector databases use it, or ideas from it, internally.

FAISS is a library, not a database. It runs inside your Python program, keeps an index in memory, and searches it extremely fast. It knows nothing about your text. You hand it rows of numbers, and when you search it hands back row numbers. It is like a book index that lists only page numbers: turning to the page is your job. Metadata, users, permissions and keeping the index in step with your documents are also left to you, which makes FAISS a good fit for experiments, batch jobs and services you build yourself.

The basic workflow

Every FAISS program follows the same five steps.

Embeddingsfloat32 arrayCreate indexFlat, IVF, HNSWTrainonly for IVFAdd vectorsrow = IDSearchdistances + IDs

FAISS returns the IDs of the nearest vectors; your own code maps IDs back to passages.

FAISS is installed with pip install faiss-cpu, so the FAISS examples run on your own computer. The first block prepares the data and builds the simplest index.

python
import faiss
import numpy as np

d = 1024                                           # numbers in each embedding
vectors = np.load("passage_embeddings.npy").astype("float32")   # shape (n, d)
faiss.normalize_L2(vectors)                        # scale every row to length 1

flat = faiss.IndexFlatIP(d)                        # exact search, inner product
flat.add(vectors)                                  # row 0 gets ID 0, row 1 gets ID 1, ...

FAISS only accepts 32-bit floats, so the NumPy default of 64-bit must be converted. normalize_L2 scales each vector to length 1, which makes the inner product (IP) equal to cosine similarity. A vector's ID is simply its row number in the array you add.

Searching looks the same for every index type. You pass a 2-D array of queries (one row per query) and K, and get back two arrays.

python
query = np.load("query_embedding.npy").astype("float32").reshape(1, -1)
faiss.normalize_L2(query)

scores, ids = flat.search(query, 5)                # top 5
print(ids[0])                                      # e.g. [412  88 3071  19 950]
print([passages[i] for i in ids[0]])               # look the text up yourself

ids[0] holds the row numbers of the five nearest vectors, best first, and scores[0] holds their similarities. The last line is the part FAISS leaves to you: passages is your own list of texts, in the same order as the vectors.

IVF and HNSW in FAISS

The two approximate indexes are created differently, then used in exactly the same way.

python
# IVF: 1,024 clusters. It must be trained before vectors are added.
quantizer = faiss.IndexFlatIP(d)                   # used to find the nearest cluster centres
ivf = faiss.IndexIVFFlat(quantizer, d, 1024, faiss.METRIC_INNER_PRODUCT)
ivf.train(vectors)                                 # learn the cluster centres
ivf.add(vectors)
ivf.nprobe = 16                                    # clusters to search per query

# HNSW: 32 links per point. No training.
hnsw = faiss.IndexHNSWFlat(d, 32, faiss.METRIC_INNER_PRODUCT)
hnsw.hnsw.efConstruction = 200                     # care taken while building
hnsw.add(vectors)
hnsw.hnsw.efSearch = 64                            # candidates kept while searching

For IVF, train finds the 1,024 cluster centres and must run before add; adding first raises an error. nprobe can be changed at any time without rebuilding. For HNSW, the number 32 is M, the links per point. efConstruction is fixed when the graph is built, while efSearch can be changed between queries.

Comparing indexes on your data

The reason to have several index types is to measure them against each other on your own vectors. The usual comparison covers four numbers.

Measure How to get it
Build time Time the train and add calls
Memory Check the index size (faiss.serialize_index) or process memory
Query latency Time many searches; look at the average and the slowest 1 percent
Recall@K Compare each index's IDs with the Flat index's IDs for the same queries

The lab shows typical results of such a comparison on a million 1,024-number vectors. The figures are illustrative, but the pattern is realistic.

The same experiment, runnable here

FAISS cannot be installed in this page, so the program below uses two small NumPy classes that copy its interface: train, add and search. FlatIndex behaves like IndexFlatIP and IVFIndex like IndexIVFFlat. The measurement code at the bottom is what you would write around real FAISS indexes.

python · runs in your browser

Example output (your timings will differ):

text
IVF nprobe= 1: recall@10 = 0.54, 0.09 ms per query
IVF nprobe= 4: recall@10 = 0.74, 0.19 ms per query
IVF nprobe=16: recall@10 = 0.92, 0.37 ms per query
Flat:          recall@10 = 1.00, 0.77 ms per query
Part of the code What it does
IVFIndex.train Picks 128 vectors as cluster centres. Real FAISS runs k-means here to find better ones.
IVFIndex.add Records which centre each vector is most similar to.
IVFIndex.search Finds the nprobe centres nearest the query and scores only the vectors in those clusters.
truth, len(f & t) / 10 The Flat results are the reference; recall is the share of them the IVF search also returned.

Raising nprobe moves recall towards 1.0 and the time per query towards the Flat time. Picking a value means deciding how much recall you need and reading the latency off your own table.

When to choose FAISS

FAISS is a strong choice when you want maximum speed and control, your data fits in the memory of one machine (or a few GPUs), and you are willing to manage storage, metadata and updates yourself. Offline experiments, batch processing and custom-built services are typical cases. When you need metadata filters, permissions, frequent updates and many users without building that machinery, a vector database is usually the better fit.

Follow your curiosity.

↑ ↓ to explore · Enter to open · Escape to close