Crate faiss

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

Preparing

This crate 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 (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.

GPU support

In order to have GPU support, the gpufaiss_c library from the main project needs to be built instead. Then, enable the gpu Cargo feature for this crate.

[dependencies]
"faiss" = {version = "0.6.0", features = ["gpu"]}

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::lsh::LshIndex;
pub use index::index_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.
selector	Abstract Faiss ID selector
vector_transform	Vector transformation implementation