Barrel
EN GitHub

barrel_vectordb

Un magasin de vecteurs intégré. Les vecteurs, leur texte et leurs métadonnées sont dans RocksDB, avec un index de plus proches voisins approché, BM25 en option et une fusion hybride.

Ce qu’elle résout

La recherche pour les agents demande des plus proches voisins, une recherche par mots-clés pour les termes exacts et un moyen de combiner les deux, sans faire tourner un service de recherche à part. barrel_vectordb vous donne HNSW (en Erlang pur, par défaut), DiskANN ou FAISS, BM25 en mémoire ou sur disque, une fusion RRF ou linéaire, la quantification, le chiffrement et un index persistant.

Quand l’utiliser

  • Vous avez besoin de recherche vectorielle ou par mots-clés sans documents autour, par exemple pour la mémoire d’un agent.
  • Vous fournissez vos propres vecteurs, ou voulez que le texte soit transformé en embedding par un fournisseur barrel_embed.
  • Vous voulez une recherche hybride aux poids réglables.

Quand ne pas l’utiliser

  • Vos vecteurs appartiennent à des documents : utilisez barrel, qui garde les deux sous un même identifiant.
  • Il vous faut des correspondances exactes par sous-chaîne ou expression régulière : utilisez barrel_ngram.

Sa place dans Barrel

Fonctionne avec, si présente
barrel_faiss : backend => faiss ; barrel_rerank : reclasse les résultats
Utilisée par
barrel
Autres dépendances
rocksdb, hackney, iommap ; un NIF en C compilé avec CMake ; OTP 26 ou plus récent
Seule
Oui. barrel_embed est toujours inclus, même si vous fournissez tous les vecteurs.

Installation

dépendances rebar.config
{barrel_vectordb, "~> 2.5"}

Configuration

Configuration du magasin

CléDéfautRôle
name obligatoire Nom du magasin, utilisé par chaque appel
path / db_path "priv/barrel_vectordb_<name>" Relatif au répertoire courant. Fixez-le.
dimensions 768 Taille des vecteurs ; une différence renvoie {dimension_mismatch, _, _}
embedder aucun Sans embedder, les appels sur du texte renvoient embedder_not_configured
backend hnsw hnsw, diskann ou faiss
hnsw.m, hnsw.ef_construction 16, 200 Degré du graphe et effort de construction
hnsw.quantization scalar turboquant, subspace_turboquant ou none
bm25_backend aucun memory ou disk pour activer la recherche par mots-clés
read_only false Les écritures renvoient {error, read_only}

Options de recherche

CléDéfautRôle
k 5 en vectoriel, 10 en BM25 et hybride Nombre de résultats
filter aucun fun(Metadata) -> boolean(), appliqué après la recherche
fusion rrf linear utilise bm25_weight et vector_weight (0,5 chacun)
ef_search max(k, 50) Effort de recherche

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

Cycle de vie

TâcheAppelRenvoie
Démarrer un magasin barrel_vectordb:start_link/1, start_supervised/1 {ok, Pid}
Arrêter, supprimer barrel_vectordb:stop/1, destroy/1 ok
Persister l’index barrel_vectordb:persist_index/1, checkpoint/1 ok

Écrire et lire

TâcheAppelRenvoie
Ajouter du texte (embedding calculé) barrel_vectordb:add/4,5, add_batch/2 ok
Ajouter avec un vecteur barrel_vectordb:add_vector/5, add_vector_batch/2 ok, {ok, #{inserted}}
Remplacer le texte barrel_vectordb:update/4, upsert/4 ok ; recalcule l’embedding du texte
Supprimer barrel_vectordb:delete/2 ok
Lire barrel_vectordb:get/2, peek/2, count/1, stats/1 {ok, #{key, text, metadata, vector}} ou not_found

Recherche

TâcheAppelRenvoie
Par texte barrel_vectordb:search/3 {ok, [#{key, score, text, metadata}]}
Par vecteur barrel_vectordb:search_vector/3 même forme
Par mots-clés barrel_vectordb:search_bm25/3 {ok, [{Id, Score}]}
Hybride barrel_vectordb:search_hybrid/3 {ok, [Hit]}

Une petite mémoire d’agent avec vos propres vecteurs

D’après une exécution vérifiée. Aucun embedder n’est configuré, donc la recherche par texte le signale.

Shell Erlang
{ok, _} = application:ensure_all_started(barrel_vectordb).
Cfg = #{name => <<"agent_mem">>, path => Path,
        dimensions => 4, bm25_backend => disk,
        hnsw => #{m => 8, ef_construction => 100}}.
{ok, _} = barrel_vectordb:start_link(Cfg).
ok = barrel_vectordb:add_vector(<<"agent_mem">>, <<"m1">>,
    <<"User prefers metric units in reports">>,
    #{kind => preference}, [0.9, 0.1, 0.0, 0.0]).
barrel_vectordb:add_vector_batch(<<"agent_mem">>, [
  {<<"m2">>, <<"Quarterly report is due on the 15th">>,
   #{kind => fact}, [0.7, 0.3, 0.1, 0.0]},
  {<<"m3">>, <<"Customer Acme renewed for two years">>,
   #{kind => fact}, [0.0, 0.1, 0.9, 0.2]}]).
barrel_vectordb:search_vector(<<"agent_mem">>,
    [0.8, 0.2, 0.0, 0.0],
    #{k => 2,
      filter => fun(M) -> maps:get(kind, M) =:= fact end}).
barrel_vectordb:search_bm25(<<"agent_mem">>, <<"report">>,
                            #{k => 5}).
barrel_vectordb:search(<<"agent_mem">>, <<"report">>, #{}).
Sortie d’une exécution sur barrel_vectordb 2.5.1
{ok,#{inserted => 2}}

{ok,[#{metadata => #{kind => fact},
       text => <<"Quarterly report is due on the 15th">>,
       key => <<"m2">>,score => 0.9788330406946226}]}

{ok,[{<<"m2">>,0.9403363021993156}]}

{error,embedder_not_configured}

Limites à connaître

  • Le filtre sur les métadonnées s’applique après la recherche : un filtre très sélectif peut renvoyer moins de k résultats (une recherche avec k => 2 en a renvoyé 1).
  • BM25 est désactivé tant que bm25_backend n’est pas fixé. Un index BM25 en mémoire se reconstruit à partir du texte stocké à chaque ouverture.
  • Il n’y a pas de mise à jour avec un vecteur explicite : update/4 et upsert/4 recalculent l’embedding du texte. Si le calcul échoue, l’ancienne entrée reste et l’appel renvoie l’erreur (avant la 2.5.3, l’entrée était perdue).
  • Ouvrir en lecture seule un magasin qui demande une mise à niveau échoue avec read_only_upgrade_needed.
  • Les clés d’environnement de barrel_vectordb.app.src (default_dimensions, hnsw_m...) ne sont jamais lues ; les valeurs par défaut viennent du code.
Lacune connue

Un magasin démarré avec barrel_vectordb:start_link/1 sans chemin se retrouve dans ./priv/barrel_vectordb_<name> sous le répertoire courant. Via barrel, il va plutôt à côté des documents.

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