# facebookresearch/faiss architecture

> Architecture diagram of the GitHub repository facebookresearch/faiss, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/facebookresearch/faiss
- Repository: https://github.com/facebookresearch/faiss

## Overview

Faiss is a C++ similarity-search and clustering library with Python and C interfaces, CPU indexes, and optional GPU indexes. The main workflow is to create or train an index, add identified vectors, then search with L2 or dot-product similarity; index choice trades search time, quality, memory, and training/addition cost. The graph also shows quantization, inverted-list storage, wrappers, and distributed search. Some connections are documented in the README; distributed relationships follow the shown demo and server excerpts, while unsampled implementation details are omitted.

Main entry points: [`faiss/Index.cpp`](https://github.com/facebookresearch/faiss/blob/main/faiss/Index.cpp) (Index API), [`faiss/IndexIVF.cpp`](https://github.com/facebookresearch/faiss/blob/main/faiss/IndexIVF.cpp) (IVF Search), [`benchs/distributed_ondisk/distributed_query_demo.py`](https://github.com/facebookresearch/faiss/blob/main/benchs/distributed_ondisk/distributed_query_demo.py) (Distributed Query Demo), [`benchs/distributed_ondisk/search_server.py`](https://github.com/facebookresearch/faiss/blob/main/benchs/distributed_ondisk/search_server.py) (Distributed Search Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_indexing["Indexing and Search"]
  node_index_base["Index API<br/>[Index.cpp]"]
  node_factory["Index Factory<br/>[index_factory.cpp]"]
  node_flat["Exact Flat Search<br/>[IndexFlat.cpp]"]
  node_ivf["IVF Search<br/>[IndexIVF.cpp]"]
  node_graphs["Graph Indexes<br/>[IndexHNSW.cpp]"]
  node_binary["Binary Indexes<br/>[IndexBinary.cpp]"]
  node_gpu["GPU Indexes<br/>[GpuIndex.h]"]
end

subgraph group_models["Training and Compression"]
  node_clustering["Clustering<br/>[Clustering.cpp]"]
  node_pq["Product Quantization<br/>[IndexPQ.cpp]"]
  node_scalar["Scalar Quantization"]
  node_quantizer["E-means Quantizers<br/>[quantizer.py]"]
  node_triton["Triton Assignment"]
  node_bench_index["Benchmark Index Framework<br/>[index.py]"]
  node_bench_descriptors["Benchmark Descriptors<br/>[descriptors.py]"]
  node_paper_bench["E-means Paper Runs<br/>[paper_bench.py]"]
  node_paper_data["Paper Datasets<br/>[paper_data.py]"]
  node_paper_xb["Paper Experiment Runner<br/>[paper_xb.py]"]
end

subgraph group_storage["Index Storage and IO"]
  node_invlists[("Inverted Lists<br/>[InvertedLists.cpp]")]
  node_ondisk[("On-disk Lists")]
end

subgraph group_interfaces["Language Interfaces"]
  node_python["Python Wrappers<br/>[class_wrappers.py]"]
  node_capi["C API<br/>[IndexIVF_c.h]"]
end

subgraph group_distributed["Distributed Search"]
  node_rpc["RPC Transport<br/>[rpc.py]"]
  node_server["Distributed Search Server<br/>[search_server.py]"]
  node_combined["Combined IVF Index<br/>[combined_index.py]"]
  node_demo["Distributed Query Demo"]
end

node_user(("Application"))

node_user -->|"adds and searches"| node_index_base
node_factory -->|"creates indexes"| node_index_base
node_index_base -->|"supports exact search"| node_flat
node_index_base -->|"supports approximate search"| node_ivf
node_index_base -->|"supports graph search"| node_graphs
node_index_base -->|"supports binary search"| node_binary
node_clustering -.->|"trains quantizers"| node_ivf
node_pq -.->|"compresses vectors"| node_ivf
node_scalar -.->|"compresses vectors"| node_ivf
node_ivf -.->|"stores vectors"| node_invlists
node_ondisk -.->|"implements storage"| node_invlists
node_quantizer -->|"supports assignment"| node_triton
node_python -->|"wraps indexes"| node_index_base
node_capi -->|"exposes index API"| node_index_base
node_gpu -->|"provides GPU alternative"| node_index_base
node_bench_descriptors -->|"supplies descriptors"| node_bench_index
node_paper_bench -->|"loads datasets"| node_paper_data
node_paper_bench -->|"runs experiments"| node_paper_xb
node_demo -->|"connects clients"| node_rpc
node_demo -->|"loads local index"| node_combined
node_demo -->|"builds split search"| node_server
node_server -->|"serves requests"| node_rpc
node_server -.->|"uses combined index"| node_combined

click node_index_base "https://github.com/facebookresearch/faiss/blob/main/faiss/Index.cpp"
click node_factory "https://github.com/facebookresearch/faiss/blob/main/faiss/index_factory.cpp"
click node_flat "https://github.com/facebookresearch/faiss/blob/main/faiss/IndexFlat.cpp"
click node_ivf "https://github.com/facebookresearch/faiss/blob/main/faiss/IndexIVF.cpp"
click node_graphs "https://github.com/facebookresearch/faiss/blob/main/faiss/IndexHNSW.cpp"
click node_binary "https://github.com/facebookresearch/faiss/blob/main/faiss/IndexBinary.cpp"
click node_clustering "https://github.com/facebookresearch/faiss/blob/main/faiss/Clustering.cpp"
click node_pq "https://github.com/facebookresearch/faiss/blob/main/faiss/IndexPQ.cpp"
click node_scalar "https://github.com/facebookresearch/faiss/blob/main/faiss/IndexScalarQuantizer.cpp"
click node_quantizer "https://github.com/facebookresearch/faiss/blob/main/contrib/e_means/quantizer.py"
click node_triton "https://github.com/facebookresearch/faiss/blob/main/contrib/e_means/triton_assignment.py"
click node_invlists "https://github.com/facebookresearch/faiss/blob/main/faiss/invlists/InvertedLists.cpp"
click node_ondisk "https://github.com/facebookresearch/faiss/blob/main/faiss/invlists/OnDiskInvertedLists.cpp"
click node_python "https://github.com/facebookresearch/faiss/blob/main/faiss/python/class_wrappers.py"
click node_capi "https://github.com/facebookresearch/faiss/blob/main/c_api/IndexIVF_c.h"
click node_gpu "https://github.com/facebookresearch/faiss/blob/main/faiss/gpu/GpuIndex.h"
click node_bench_index "https://github.com/facebookresearch/faiss/blob/main/benchs/bench_fw/index.py"
click node_bench_descriptors "https://github.com/facebookresearch/faiss/blob/main/benchs/bench_fw/descriptors.py"
click node_paper_bench "https://github.com/facebookresearch/faiss/blob/main/benchs/e_means/paper_bench.py"
click node_paper_data "https://github.com/facebookresearch/faiss/blob/main/benchs/e_means/paper_data.py"
click node_paper_xb "https://github.com/facebookresearch/faiss/blob/main/benchs/e_means/paper_xb.py"
click node_rpc "https://github.com/facebookresearch/faiss/blob/main/contrib/rpc.py"
click node_server "https://github.com/facebookresearch/faiss/blob/main/benchs/distributed_ondisk/search_server.py"
click node_combined "https://github.com/facebookresearch/faiss/blob/main/benchs/distributed_ondisk/combined_index.py"
click node_demo "https://github.com/facebookresearch/faiss/blob/main/benchs/distributed_ondisk/distributed_query_demo.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_index_base,node_factory,node_flat,node_ivf,node_graphs,node_binary,node_gpu toneBlue
class node_clustering,node_pq,node_scalar,node_quantizer,node_triton,node_bench_index,node_bench_descriptors,node_paper_bench,node_paper_data,node_paper_xb toneAmber
class node_invlists,node_ondisk toneMint
class node_python,node_capi toneRose
class node_rpc,node_server,node_combined,node_demo,node_user toneIndigo
```

## Components

### Indexing and Search

- [Index API](https://github.com/facebookresearch/faiss/blob/main/faiss/Index.cpp): `faiss/Index.cpp`
- [Index Factory](https://github.com/facebookresearch/faiss/blob/main/faiss/index_factory.cpp): `faiss/index_factory.cpp`
- [Exact Flat Search](https://github.com/facebookresearch/faiss/blob/main/faiss/IndexFlat.cpp): `faiss/IndexFlat.cpp`
- [IVF Search](https://github.com/facebookresearch/faiss/blob/main/faiss/IndexIVF.cpp): `faiss/IndexIVF.cpp`
- [Graph Indexes](https://github.com/facebookresearch/faiss/blob/main/faiss/IndexHNSW.cpp): `faiss/IndexHNSW.cpp`
- [Binary Indexes](https://github.com/facebookresearch/faiss/blob/main/faiss/IndexBinary.cpp): `faiss/IndexBinary.cpp`
- [GPU Indexes](https://github.com/facebookresearch/faiss/blob/main/faiss/gpu/GpuIndex.h): `faiss/gpu/GpuIndex.h`

### Training and Compression

- [Clustering](https://github.com/facebookresearch/faiss/blob/main/faiss/Clustering.cpp): `faiss/Clustering.cpp`
- [Product Quantization](https://github.com/facebookresearch/faiss/blob/main/faiss/IndexPQ.cpp): `faiss/IndexPQ.cpp`
- [Scalar Quantization](https://github.com/facebookresearch/faiss/blob/main/faiss/IndexScalarQuantizer.cpp): `faiss/IndexScalarQuantizer.cpp`
- [E-means Quantizers](https://github.com/facebookresearch/faiss/blob/main/contrib/e_means/quantizer.py): `contrib/e_means/quantizer.py`
- [Triton Assignment](https://github.com/facebookresearch/faiss/blob/main/contrib/e_means/triton_assignment.py): `contrib/e_means/triton_assignment.py`
- [Benchmark Index Framework](https://github.com/facebookresearch/faiss/blob/main/benchs/bench_fw/index.py): `benchs/bench_fw/index.py`
- [Benchmark Descriptors](https://github.com/facebookresearch/faiss/blob/main/benchs/bench_fw/descriptors.py): `benchs/bench_fw/descriptors.py`
- [E-means Paper Runs](https://github.com/facebookresearch/faiss/blob/main/benchs/e_means/paper_bench.py): `benchs/e_means/paper_bench.py`
- [Paper Datasets](https://github.com/facebookresearch/faiss/blob/main/benchs/e_means/paper_data.py): `benchs/e_means/paper_data.py`
- [Paper Experiment Runner](https://github.com/facebookresearch/faiss/blob/main/benchs/e_means/paper_xb.py): `benchs/e_means/paper_xb.py`

### Index Storage and IO

- [Inverted Lists](https://github.com/facebookresearch/faiss/blob/main/faiss/invlists/InvertedLists.cpp): `faiss/invlists/InvertedLists.cpp`
- [On-disk Lists](https://github.com/facebookresearch/faiss/blob/main/faiss/invlists/OnDiskInvertedLists.cpp): `faiss/invlists/OnDiskInvertedLists.cpp`

### Language Interfaces

- [Python Wrappers](https://github.com/facebookresearch/faiss/blob/main/faiss/python/class_wrappers.py): `faiss/python/class_wrappers.py`
- [C API](https://github.com/facebookresearch/faiss/blob/main/c_api/IndexIVF_c.h): `c_api/IndexIVF_c.h`

### Distributed Search

- [RPC Transport](https://github.com/facebookresearch/faiss/blob/main/contrib/rpc.py): `contrib/rpc.py`
- [Distributed Search Server](https://github.com/facebookresearch/faiss/blob/main/benchs/distributed_ondisk/search_server.py): `benchs/distributed_ondisk/search_server.py`
- [Combined IVF Index](https://github.com/facebookresearch/faiss/blob/main/benchs/distributed_ondisk/combined_index.py): `benchs/distributed_ondisk/combined_index.py`
- [Distributed Query Demo](https://github.com/facebookresearch/faiss/blob/main/benchs/distributed_ondisk/distributed_query_demo.py): `benchs/distributed_ondisk/distributed_query_demo.py`

### Other components

- **Application**

## Connections

- Application → Index API: adds and searches (evidence: `README.md`)
- Index Factory → Index API: creates indexes (evidence: `README.md`)
- Index API → Exact Flat Search: supports exact search (evidence: `README.md`)
- Index API → IVF Search: supports approximate search (evidence: `README.md`)
- Index API → Graph Indexes: supports graph search (evidence: `README.md`)
- Index API → Binary Indexes: supports binary search (evidence: `README.md`)
- Clustering → IVF Search: trains quantizers
- Product Quantization → IVF Search: compresses vectors
- Scalar Quantization → IVF Search: compresses vectors
- IVF Search → Inverted Lists: stores vectors
- On-disk Lists → Inverted Lists: implements storage
- E-means Quantizers → Triton Assignment: supports assignment (evidence: `contrib/e_means/triton_assignment.py`)
- Python Wrappers → Index API: wraps indexes (evidence: `README.md`)
- C API → Index API: exposes index API (evidence: `c_api/IndexIVF_c.h`)
- GPU Indexes → Index API: provides GPU alternative (evidence: `README.md`)
- Benchmark Descriptors → Benchmark Index Framework: supplies descriptors (evidence: `benchs/bench_fw/descriptors.py`)
- E-means Paper Runs → Paper Datasets: loads datasets (evidence: `benchs/e_means/paper_bench.py`)
- E-means Paper Runs → Paper Experiment Runner: runs experiments (evidence: `benchs/e_means/paper_bench.py`)
- Distributed Query Demo → RPC Transport: connects clients (evidence: `benchs/distributed_ondisk/distributed_query_demo.py`)
- Distributed Query Demo → Combined IVF Index: loads local index (evidence: `benchs/distributed_ondisk/distributed_query_demo.py`)
- Distributed Query Demo → Distributed Search Server: builds split search (evidence: `benchs/distributed_ondisk/distributed_query_demo.py`)
- Distributed Search Server → RPC Transport: serves requests (evidence: `benchs/distributed_ondisk/search_server.py`)
- Distributed Search Server → Combined IVF Index: uses combined index (evidence: `benchs/distributed_ondisk/search_server.py`)
