Barrel
EN GitHub

barrel_faiss

Des bindings Erlang vers la bibliothèque C++ FAISS, et le backend d’index faiss, optionnel, de barrel_vectordb.

Ce qu’elle résout

Certaines charges veulent les types d’index de FAISS (IVF, PQ, flat, HNSW de FAISS) plutôt que le HNSW en Erlang pur. barrel_faiss enveloppe FAISS dans un NIF pour que barrel_vectordb puisse s’en servir, et vous pouvez aussi l’appeler directement.

Quand l’utiliser

  • Vous dépendez déjà des types d’index FAISS ou de leurs compromis entre mémoire et vitesse.
  • Vous pouvez installer la bibliothèque FAISS sur chaque nœud qui ouvre le magasin.

Quand ne pas l’utiliser

  • Vous voulez un build sans bibliothèque système : le backend HNSW par défaut est en Erlang pur.
  • Vous compilez sous Windows : il n’y a pas de hooks de build pour cette plateforme.

Sa place dans Barrel

Repose sur
Aucune autre bibliothèque Barrel
Utilisée par
Aucune autre bibliothèque Barrel n’en dépend
Optionnelle dans
barrel_vectordb
Autres dépendances
bibliothèque et en-têtes FAISS, CMake 3.14 ou plus récent, C++17, OpenMP, BLAS
Seule
Oui, comme bindings NIF sans dépendance Erlang. Il faut FAISS installé sur le système.

Installation

dépendances rebar.config
{barrel_faiss, "~> 1.0"}

Dans l’umbrella, il ne fait pas partie du build par défaut : utilisez rebar3 as faiss compile.

Configuration

Configuration d’un magasin barrel_vectordb

CléDéfautRôle
backend hnsw Mettez faiss
faiss.index_type <<"HNSW32">> Une chaîne de fabrique FAISS
faiss.nprobe aucun Pour les index IVF

Seulement les clés les plus utilisées. Pour toutes les options, voyez la référence de configuration et la référence de l’API.

L’API par tâche

Index

TâcheAppelRenvoie
Créer barrel_faiss:new/1,2, index_factory/2,3 {ok, Index} ; métrique l2 ou inner_product
Entraîner (IVF, PQ) barrel_faiss:train/2, is_trained/1 ok, booléen
Ajouter barrel_faiss:add/2, add_with_ids/3 ok ; float32 et int64, boutisme natif
Chercher barrel_faiss:search/3 {ok, Distances, Labels}
Retirer barrel_faiss:remove_ids/2 {ok, N} ; pas sur HNSW
Enregistrer, charger serialize/1, deserialize/1, write_index/2, read_index/1 binaire ou fichier
Inspecter, fermer dimension/1, ntotal/1, close/1 entiers, ok

Appels directs

D’après une exécution vérifiée sur un build CMake neuf, avec FAISS installé par MacPorts. L’exécution a affiché les valeurs ci-dessous ; les instructions d’affichage sont omises du code.

Erlang
{ok, Idx} = barrel_faiss:new(4),
Vecs = << <<X:32/float-native>> || X <-
          [1.0,0.0,0.0,0.0, 0.0,1.0,0.0,0.0,
           0.0,0.0,1.0,0.0] >>,
ok = barrel_faiss:add(Idx, Vecs),
Q = << <<X:32/float-native>> || X <- [0.9,0.1,0.0,0.0] >>,
{ok, D, L} = barrel_faiss:search(Idx, Q, 2),
{ok, Bin} = barrel_faiss:serialize(Idx),
{ok, H} = barrel_faiss:index_factory(4, <<"IDMap,Flat">>,
                                     inner_product),
ok = barrel_faiss:add_with_ids(H, Vecs,
    << <<I:64/signed-native>> || I <- [100, 200, 300] >>),
{ok, _, L2} = barrel_faiss:search(H, Q, 1),
barrel_faiss:remove_ids(H, <<100:64/signed-native>>),
ok = barrel_faiss:close(Idx).
Affiché par l’exécution, barrel_faiss 1.0.1
ntotal=3 dim=4 trained=true
distances=[0.020000005140900612,1.619999885559082] labels=[0,1]
deserialized ntotal=3 (93 bytes)
IDMap top label=[100]
remove_ids={ok,1} ntotal=2
after close: {error,"index_closed"}

Comme backend d’un magasin de vecteurs barrel

La même exécution, à travers barrel. La dernière ligne est la même ouverture sur un build sans le NIF.

Erlang
{ok, Db} = barrel:open(fdb, #{
    docdb => #{data_dir => Dir},
    vectordb => #{dimension => 3, backend => faiss,
                  db_path => Dir ++ "/fdb_vec"}}),
ok = barrel:vector_add(Db, <<"a">>, <<"alpha">>, #{},
                       [1.0, 0.0, 0.0]),
ok = barrel:vector_add(Db, <<"b">>, <<"beta">>, #{},
                       [0.0, 1.0, 0.0]),
{ok, Hits} = barrel:search_vector(Db, [0.9, 0.1, 0.0],
                                  #{k => 1}).
Affiché par l’exécution
faiss-backed hit: [<<"a">>]
without NIF: {error,{index_init_failed,faiss_not_available}}

Limites à connaître

  • Demande un FAISS installé sur le système ; le build cherche dans FAISS_ROOT, /opt/local, /usr/local, /opt/homebrew et /usr.
  • S’exécute sur des dirty schedulers. remove_ids/2 n’est pas pris en charge sur les index HNSW.
  • Une recherche sur un index fermé renvoie {error, "index_closed"}, une chaîne plutôt qu’un atome.

Haut et bas pour se déplacerEntrée pour ouvrir