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
{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éfaut | Rô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âche | Appel | Renvoie |
|---|---|---|
| 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.
{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). 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.
{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}). 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/2n’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.