Crate faiss 

This crate provides high-level bindings to Faiss, the vector similarity search engine.

Preparing

This crate has two modes of linking.

Dynamic linking

By default, Faiss is dynamically linked, so it requires Faiss and the C API to be built beforehand by the developer. Please follow the instructions here, and build the dynamic library with the C API (additional instructions here)

This will result in the dynamic library faiss_c (“libfaiss_c.so” in Linux), which needs to be installed in a place where your system will pick up. In Linux, try somewhere in the LD_LIBRARY_PATH environment variable, such as “/usr/lib”, or try adding a new path to this variable.

Static linking

Alternatively to the above, enable the static Cargo feature to let Rust build Faiss for you. You will still need the dependencies required to build and run Faiss as described in their INSTALL.md, namely a compatible C++ compiler and a BLAS implementation.

GPU support

Enable the cargo feature gpu for GPU support. If you are using dynamic linking, the Faiss library needs to be built with GPU capabilities.

Examples

The Index trait is one of the center-pieces of this library. Index implementations can be requested using the index_factory function:

use faiss::{Index, index_factory, MetricType};
let mut index = index_factory(8, "Flat", MetricType::L2)?;
index.add(my_data)?;
let result = index.search(my_query, 5)?;
for (i, (l, d)) in result.labels.iter()
    .zip(result.distances.iter())
    .enumerate()
{
    println!("#{}: {} (D={})", i + 1, *l, *d);
}

With GPU support, create a StandardGpuResources and use the into_gpu and into_cpu methods to move an index to and from the GPU.

use faiss::{GpuResources, StandardGpuResources, Index, index_factory, MetricType};

let index = index_factory(8, "Flat", MetricType::L2)?;
let gpu_res = StandardGpuResources::new()?;
let index = index.into_gpu(&gpu_res, 0)?;

Unless otherwise indicated, vectors are added and retrieved from the library under the form of contiguous column-first slices of f32 elements.

Details from the official Faiss APIs still apply. Please visit the Faiss wiki for additional guidance.

Re-exports

pub use index::flat::FlatIndex;

pub use index::id_map::IdMap;

pub use index::io::read_index;

pub use index::io::write_index;

pub use index::io::read_index_binary;

pub use index::io::write_index_binary;

pub use index::lsh::LshIndex;

pub use index::index_factory;

pub use index::index_binary_factory;

pub use index::ConcurrentIndex;

pub use index::Idx;

pub use index::Index;

pub use metric::MetricType;

pub use gpu::GpuResources;

pub use gpu::StandardGpuResources;

pub use index::gpu::GpuIndexImpl;

Modules

cluster

Vector clustering interface and implementation.

error

Error handling module

gpu

Contents for GPU support

index

Index interface and native implementations.

metric

Module containing the metric type.

search_params

selector

Abstract Faiss ID selector

utils

vector_transform

Vector transformation implementation