Barrel
EN GitHub

Trouvez par le sens, par le mot, ou par la chaîne exacte.

Barrel garde un document et son vecteur sous un même identifiant : une seule requête peut classer par le sens, par mots-clés, ou les deux, et renvoyer des lignes avec les champs du document. Pour les identifiants et les messages d’erreur que le sens manque, un index de trigrammes trouve le texte exact.

La recherche s’exécute là où tourne la base : dans votre nœud Erlang, derrière le serveur REST et MCP, ou sur des vecteurs synchronisés dans un navigateur.

Vectorielle, par mots-clés et hybrideSous-chaîne et expression régulière

Six façons de trouver un enregistrement

Chacune est un index ou une étape distincte que vous activez. La marque indique si elle fonctionne sans installation.

  • Vectorielle

    Les plus proches voisins par le sens. HNSW par défaut, DiskANN, ou FAISS via barrel_faiss. Les requêtes en texte demandent un embedder ; vous pouvez aussi passer vous-même le vecteur de la requête.

  • Par mots-clés (BM25)

    Recherche par mots-clés classée. Désactivée sur une base simple tant que vous ne fixez pas bm25_backend à memory ou disk ; le mode enregistrement l’active avec disk.

  • Hybride

    Vecteurs et BM25 fusionnés en un seul classement : fusion par rang réciproque par défaut (rrf_k 60), ou un mélange linéaire avec bm25_weight et vector_weight. Demande que BM25 soit activé.

  • Sous-chaîne et expression régulière

    Chaînes exactes et motifs PCRE sur les documents avec barrel_ngram, un index de trigrammes alimenté par le flux des changements. Chaque résultat est confirmé sur le texte et porte ses plages d’octets.

  • Reclassement

    Une seconde passe avec un cross-encoder dans barrel_rerank : vous lui donnez la requête et les textes de vos meilleurs résultats, il les renvoie réordonnés, chacun avec un score.

  • Fonctions de table BQL

    vector_top_k, bm25_top_k et hybrid_top_k comme FROM d’une requête : les résultats sont joints à leurs documents, puis WHERE, ORDER BY et les projections s’appliquent.

Comment s’exécute une requête hybride

Les deux index répondent au même texte ; leurs rangs sont fusionnés, et une fonction de table BQL joint chaque résultat à son document avant que WHERE ne s’applique. Les fonctions de table récupèrent 3 fois k (1000 au plus) pour qu’un WHERE ait encore des lignes à garder.

  1. Texte de la requête ou un vecteur de requête

    embedding par le fournisseur du magasin

  2. Index vectoriel HNSW, DiskANN ou FAISS
    Index BM25 mémoire ou disque

    fusion des rangs (RRF, k 60)

  3. Résultats hybrides id, score, texte, métadonnées

    BQL : jointure aux documents, puis WHERE

  4. Lignes champs, _score
La boîte BM25 est en pointillés : elle n’existe que si bm25_backend est fixé, ou en mode enregistrement.

Comment s’exécute la recherche par sous-chaîne et par expression régulière

  1. barrel_docdb documents

    flux des changements

  2. Segments de trigrammes immuables, avec somme de contrôle

    candidats tirés des listes

  3. Confirmation sur le texte écarte les faux positifs

    résultats

  4. id et plages décalage en octets, longueur

Ce qui tient, et ce qui le teste

Des propriétés sur lesquelles vous pouvez compter, avec le test du dépôt qui vérifie chacune.

Exact veut dire exact

La recherche par sous-chaîne et par expression régulière confirme chaque candidat sur le texte stocké : les collisions de trigrammes n’apparaissent jamais comme résultats.

Vérifié par oracle_equivalence dans barrel_ngram_SUITE, qui compare chaque réponse à un parcours exhaustif.

Le vecteur suit le document

En mode enregistrement, une modification recalcule l’embedding, une suppression retire le vecteur, et le marqueur destiné à l’indexeur est écrit dans le même lot que le document.

Vérifié par barrel_record_SUITE : indexer_update_reembeds, indexer_delete_removes_vector, indexer_crash_restart.

Lire votre écriture, quand vous le demandez

Le mode enregistrement avec mode => sync calcule l’embedding avant que l’écriture ne rende la main. Si l’embedder échoue, l’écriture échoue et rien n’est stocké.

Vérifié par barrel_record_SUITE : sync_put_immediate_search, sync_embed_failure_fails_put.

Un index BM25 sur disque survit à un kill

Les écritures acquittées sont toujours dans l’index après que le processus a été tué et le magasin rouvert. Un index en mémoire se reconstruit à l’ouverture à partir du texte stocké.

Vérifié par barrel_vectordb_bm25_persistence_tests (disk: kill then reopen loses no acked write).

Les documents répliqués sont indexés

Les documents arrivés par réplication reçoivent leur embedding sur la copie qui les reçoit ; la version qui a perdu un conflit, non.

Vérifié par barrel_record_SUITE : replicated_docs_embedded, replicated_loser_not_reembedded.

Le même modèle, ou pas d’ouverture

Chaque magasin enregistre l’empreinte de son embedder : fournisseur, modèle, dimensions, distance. Un espace en mode enregistrement ouvert avec un autre modèle est refusé.

Vérifié par embedder_fingerprint dans barrel_record_SUITE.

L’utiliser

Ouvrir une base avec un magasin de vecteurs et BM25

L’exécution enregistrée ci-dessous utilisait kb_embed, un fournisseur à hachage de caractéristiques en 64 dimensions écrit pour le test : il rapproche les mots communs, il n’est pas sémantique.

{ok, Db} = barrel:open(<<"research">>, #{vectordb => #{
    db_path      => "data/research_vec",
    dimensions   => 64,
    embedder     => {kb_embed, #{}},
    bm25_backend => memory}}),
{ok, #{inserted := 4}} = barrel:vector_add_batch(Db, Notes).

Vectorielle, par mots-clés et hybride

barrel:search(Db, <<"leader election">>, #{k => 2}),
barrel:search_bm25(Db, <<"keyword search">>, #{k => 2}),
barrel:search_hybrid(Db, <<"nearest neighbor search">>,
                     #{k => 2}).
Sortie de search_bm25, enregistrée sur barrel 1.12.0
{ok,[{<<"paper:bm25">>,1.9587592623731485},
     {<<"paper:hnsw">>,0.6586049622596158}]}

Chercher dans une requête

_score vaut 1 moins la distance pour les vecteurs, le score BM25 brut, ou la valeur fusionnée pour l’hybride. Il peut être sélectionné et trié, pas filtré.

barrel:query(Db,
    <<"SELECT h.id, h._score, topic "
      "FROM hybrid_top_k($q, k => 3) AS h "
      "ORDER BY h._score DESC">>,
    #{params => #{<<"q">> => <<"replicated consensus">>}}).
Sortie de la requête Erlang hybrid_top_k, enregistrée (abrégée)
{ok,[#{<<"_score">> => 0.01639344262295082,
       <<"id">> => <<"paper:raft">>,
       <<"topic">> => <<"distributed-systems">>},
     #{<<"_score">> => 0.016001024065540194,
       <<"id">> => <<"paper:crdt">>, ...},
     #{<<"_score">> => 0.008536214242239805,
       <<"id">> => <<"paper:bm25">>, ...}], ...}

Mode enregistrement : la politique calcule les embeddings pour vous

Nommez les champs à transformer en embeddings. Avec mode => sync, l’écriture rend la main une fois le vecteur indexé ; le défaut, async, indexe en arrière-plan et se rétablit après une panne.

Embedder = {ollama, #{model => <<"nomic-embed-text">>}},
Policy = #{fields => [<<"title">>, <<"body">>],
           mode => sync, embedder => Embedder,
           dimensions => 768},
{ok, Db} = barrel:open(<<"notes">>, #{embedding => Policy,
    vectordb => #{db_path => "data/notes_vec"}}),
{ok, _} = barrel:put_doc(Db, #{<<"id">> => <<"n1">>,
    <<"title">> => <<"Raft">>,
    <<"body">> => <<"Leader election and log replication">>}),
barrel:search(Db, <<"how do replicas agree?">>, #{k => 1}).

Sous-chaînes exactes et expressions régulières

L’outil MCP ouvre l’index de la base à la première utilisation et le rafraîchit avant chaque recherche. Il n’y a pas de route REST.

ok = barrel_ngram:open(<<"rb_idx">>, #{db => <<"runbooks">>,
    fields => [<<"title">>, <<"body">>]}),
barrel_ngram:search(<<"rb_idx">>, <<"ERR_CONN_TIMEOUT">>),
barrel_ngram:search(<<"rb_idx">>, <<"redis">>,
                    #{case_sensitive => false}),
barrel_ngram:regex(<<"rb_idx">>,
                   <<"pg-(primary|replica)-\\d+">>).
Sortie des trois appels Erlang, enregistrée sur barrel_ngram 0.11.4
{ok,[#{id => <<"rb:db">>,spans => [{11,16}]}]}
{ok,[#{id => <<"rb:cache">>,spans => [{68,5}]}]}
{ok,[#{id => <<"rb:db">>,spans => [{35,13},{58,13}]}]}

Reclasser les meilleurs résultats optionnel

Ranker est un serveur barrel_rerank:start_link(#) (modèle par défaut cross-encoder/ms-marco-MiniLM-L-6-v2).

{ok, Hits} = barrel:search(Db, Q, #{k => 20}),
Texts = [maps:get(text, H) || H <- Hits],
{ok, R} = barrel_rerank:rerank(Ranker, Q, Texts,
                               #{top_k => 5}),
%% R vaut [{Index, Score}], le meilleur d’abord ; Index part de 0
Top = [lists:nth(I + 1, Hits) || {I, _Score} <- R].
Sortie de rerank/3 sur trois textes courts, enregistrée sur barrel_rerank 1.0.2
{ok,[{0,9.581769943237305},
     {2,-5.255744457244873},
     {1,-9.625640869140625}]}

Valeurs par défaut selon le point d’entrée

Point d’entréeRésultats si vous ne passez rien
barrel:search/3, search_vector/3k 5
barrel:search_bm25/3, search_hybrid/3k 10
BQL vector_top_k, bm25_top_k, hybrid_top_kk 10
REST /db/:db/search/* et l’outil MCP searchk 10 (REST le plafonne à 10000)
MCP ngram_searchlimit 50 (plafond 1000)

Limites

  • BM25 est désactivé sur une base simple, y compris les bases qu’ouvre un barrel_server par défaut (un magasin cosinus de 768 dimensions, BM25 désactivé). BM25 et l’hybride répondent alors bm25_not_enabled ou embedder_not_configured, en REST sous forme d’une erreur 500.
  • Il n’y a pas d’embedder hors ligne intégré. Apportez vos propres vecteurs, lancez Ollama en local, utilisez le fournisseur Python local, ou écrivez un module fournisseur.
  • Le filtre de métadonnées (filter => fun) s’applique après l’étape des plus proches voisins : un filtre strict peut renvoyer moins de k résultats.
  • La recherche par sous-chaîne et par expression régulière n’est ni dans l’API barrel ni dans BQL : appelez barrel_ngram ou l’outil MCP ngram_search. L’index occupe environ 34 fois la taille du texte, et ses champs sont fixés à sa création.
  • Le reclassement demande Python 3 avec transformers et torch, et télécharge son modèle à la première utilisation. Les scores sont les logits bruts du cross-encoder, pas des valeurs entre 0 et 1.
  • En mode simple, le document et son vecteur sont deux écritures que rien ne lie ; le mode enregistrement est la voie qui les garde ensemble.
  • Dans le navigateur, barrel-lite classe localement les vecteurs synchronisés par un cosinus exhaustif ; les requêtes par mots-clés et hybrides vont au serveur.

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