AutoFaiss

2.18.0 · active · verified Fri Apr 17

AutoFaiss is a Python library that automatically selects and tunes the best Faiss index for a given dataset, optimizing for search quality and inference speed. It simplifies the process of building and evaluating vector search indexes, abstracting away much of the complexity of Faiss. The current version is 2.18.0, and it generally follows a minor release cadence driven by dependency updates and small feature enhancements.

Common errors

```
ModuleNotFoundError: No module named 'faiss_gpu'
```
cause Attempting to use GPU features (e.g., setting `use_gpu=True` implicitly or explicitly) when only `faiss-cpu` is installed, or when `autofaiss[gpu]` was not used for installation.

fix To enable GPU support, install AutoFaiss with the `[gpu]` extra: `pip install autofaiss[gpu]`. Ensure your system has a compatible NVIDIA CUDA setup. If you don't intend to use GPU, remove any GPU-related configurations.
```
TypeError: Expected np.float32 for input vectors, got np.float64.
```
cause The input data (embeddings) provided to `build_index` is in `np.float64` format, while Faiss prefers and is optimized for `np.float32`.

fix Convert your input NumPy array to `np.float32` before passing it to `build_index`. For example: `data = np.float32(your_data)`.
```
ValueError: max_ram_usage is too low to build an index for the given data. Required RAM: X.XGB, Available RAM: Y.YGB.
```
cause AutoFaiss's internal logic determined that the `max_ram_usage` specified (or default) is insufficient for the size and dimensionality of your input data.

fix Increase the `max_ram_usage` parameter in your `build_index` call to a higher value, ensuring it doesn't exceed your system's physical RAM. Example: `max_ram_usage='16GB'`.

Warnings

gotcha Building large Faiss indices, especially with `autofaiss`, can be very memory-intensive. Users frequently encounter Out-of-Memory (OOM) errors if the `max_ram_usage` parameter is not set appropriately for their system's available RAM or if it's omitted.
Fix: Always explicitly set `max_ram_usage` in `build_index` to a value comfortably below your system's physical RAM (e.g., '4GB', '16GB', etc.). Monitor memory usage during index building.
gotcha For GPU acceleration, `autofaiss` requires the `faiss-gpu` dependency. Simply installing `autofaiss` (which pulls `faiss-cpu`) will not enable GPU support. Attempting to use GPU features without `faiss-gpu` installed will result in runtime errors or fall back to CPU.
Fix: Install with `pip install autofaiss[gpu]`. Ensure you have a compatible NVIDIA CUDA toolkit and drivers installed on your system. Do not install `faiss-cpu` and `faiss-gpu` simultaneously.
gotcha Faiss, and by extension AutoFaiss, is optimized for and often expects input vectors to be of `np.float32` data type. Passing `np.float64` (the default for many NumPy operations) can significantly increase memory consumption, reduce performance, and potentially lead to Out-of-Memory errors for large datasets.
Fix: Ensure your input data is explicitly cast to `np.float32` before passing it to `build_index`. Example: `data = np.float32(your_raw_data)`.
breaking AutoFaiss requires Python >= 3.10. Attempting to install or run AutoFaiss on older Python versions will lead to dependency resolution errors, installation failures, or `SyntaxError` on import.
Fix: Upgrade your Python environment to Python 3.10 or newer. Use virtual environments to manage different Python versions if needed.

Install

pip install autofaiss Base installation (CPU)
pip install autofaiss[gpu] Installation with GPU support (requires NVIDIA CUDA)

Imports

build_index
```
from autofaiss import build_index
```
This is the primary function for automatically selecting and building a Faiss index.

Quickstart

This quickstart demonstrates how to build a Faiss index using `autofaiss.build_index` from a NumPy array. It highlights essential parameters like `index_path`, `max_ram_usage`, and `metric_type`. The `max_ram_usage` parameter is critical for preventing out-of-memory errors on large datasets.

import numpy as np
from autofaiss import build_index

# Create dummy data: 1000 vectors of 128 dimensions, float32 is recommended
data = np.float32(np.random.rand(1000, 128))

# Build the index. Specify max_ram_usage relevant to your system.
# For production, consider 'metric_type="ip"' for inner product or 'l2' for L2 distance.
index, index_infos = build_index(
    data,
    index_path="my_autofaiss_index.bin",
    index_infos_path="my_autofaiss_index_infos.json",
    max_ram_usage="4GB", # IMPORTANT: Adjust based on available RAM
    metric_type="ip" 
)

print(f"Index built and saved to my_autofaiss_index.bin with info in my_autofaiss_index_infos.json")

view raw JSON →