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
- Repose sur
barrel_crypto,barrel_embed- 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
{barrel_vectordb, "~> 2.5"} Configuration
Configuration du magasin
| Clé | Défaut | Rô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éfaut | Rô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âche | Appel | Renvoie |
|---|---|---|
| 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âche | Appel | Renvoie |
|---|---|---|
| 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âche | Appel | Renvoie |
|---|---|---|
| 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.
{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">>, #{}). {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
krésultats (une recherche aveck => 2en a renvoyé 1). - BM25 est désactivé tant que
bm25_backendn’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/4etupsert/4recalculent 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.
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.