Démarrage rapide : embarqué
Dans ce démarrage rapide, vous ajoutez Barrel à une application Erlang et construisez une petite base de connaissances de support : trois articles, comme kb-142 « Reset a locked account ». Vous les stockez sous forme de documents JSON, vous les sélectionnez avec une requête, puis vous retrouvez le bon article à partir d’une question formulée autrement, comme « I cannot log in ». Suivez ce parcours quand Barrel tournera dans votre propre release OTP, sans serveur entre les deux : la base est une bibliothèque que votre code appelle directement, sans saut réseau ni processus séparé à déployer.
Ce que vous allez faire10 minutes
- Créer une release OTP qui dépend de barrel
- Écrire et lire des documents JSON
- Sélectionner des documents avec une requête BQL
- Rechercher les articles par leur sens avec des embeddings locaux
Avant de commencer
- Erlang/OTP 26 ou plus récent, et rebar3, pour compiler et lancer la release.
- CMake et un compilateur C++ : le stockage vectoriel compile une bibliothèque native.
- Pour l’étape 5 seulement : Ollama en marche en
local avec le modèle
nomic-embed-text(ollama pull nomic-embed-text). Ollama transforme un texte en embedding, une liste de nombres qui place près les uns des autres les textes de sens voisin.
1. Créer le projet
Vous partez d’une release OTP vide : Barrel tourne ainsi dans votre propre application, comme il le fera en production.
rebar3 new release kb
cd kb
Ajoutez barrel aux dépendances, et indiquez-lui où garder ses fichiers.
data_dir est le répertoire où le stockage de documents écrit sur
disque.
{deps, [{barrel, "~> 1.14"}]}. [{barrel_docdb, [{data_dir, "data/docdb"}]}]. 2. Ouvrir une base
Une base est un stockage nommé de documents. L’ouvrir vous donne un
descripteur que vous passez à chaque appel suivant. Lancez un shell avec rebar3 shell. vectordb => none n’ouvre que le
stockage de documents, donc aucun modèle n’est encore nécessaire.
{ok, _} = application:ensure_all_started(barrel),
{ok, Db} = barrel:open(<<"kb">>, #{vectordb => none}). 3. Écrire des documents
Chaque article est un document JSON, écrit en Erlang sous forme de map à
clés binaires. Le champ id nomme le document ; c’est par cet id que vous
le relisez. Ici, vous écrivez les trois articles, puis vous relisez
kb-207.
Articles = [
#{<<"id">> => <<"kb-142">>, <<"product">> => <<"console">>,
<<"title">> => <<"Reset a locked account">>},
#{<<"id">> => <<"kb-207">>, <<"product">> => <<"console">>,
<<"title">> => <<"Rotate an API key">>},
#{<<"id">> => <<"kb-311">>, <<"product">> => <<"mobile">>,
<<"title">> => <<"Sign in with a passkey">>}],
[{ok, _} = barrel:put_doc(Db, A) || A <- Articles],
barrel:get_doc(Db, <<"kb-207">>). {ok,#{<<"_rev">> =>
<<"000001a1ba3fd05d00000000@w4f0cb98700ad5ffc">>,
<<"id">> => <<"kb-207">>,<<"product">> => <<"console">>,
<<"title">> => <<"Rotate an API key">>}} Barrel a stocké le document tel que vous l’avez écrit et a ajouté _rev,
le jeton de révision de cette
écriture. La partie avant @ est une valeur d’horloge, celle d’après
désigne l’auteur de l’écriture. Pour mettre le document à jour, renvoyez
_rev avec votre modification : Barrel sait alors quelle version vous
avez modifiée, et une modification faite sur une copie périmée ne peut pas
écraser en silence une version plus récente. Voir
L’enregistrement.
4. Interroger avec BQL
BQL est le langage de requête de Barrel, proche de SQL. Chaque champ est indexé : vous pouvez filtrer et trier sur n’importe quel champ sans déclarer d’index au préalable. Cette requête sélectionne les articles de la console.
{ok, Rows, _Meta} = barrel:query(Db,
<<"SELECT id, title FROM kb "
"WHERE product = 'console' ORDER BY id">>). {ok,[#{<<"id">> => <<"kb-142">>,
<<"title">> => <<"Reset a locked account">>},
#{<<"id">> => <<"kb-207">>,
<<"title">> => <<"Rotate an API key">>}],
#{count => 2, ...}} Le résultat est une liste de lignes, une map par document, qui ne
contient que les champs sélectionnés, dans l’ordre des id. kb-311
manque, car son product vaut mobile. La dernière map contient des
métadonnées sur la réponse ; count est le nombre de lignes.
5. Rechercher par le sens
Un filtre BQL trouve « console », mais pas « I cannot log in » : aucun titre ne contient ces mots. La recherche par le sens compare des embeddings : une question retrouve ainsi l’article qui y répond.
Ouvrez une deuxième base en mode
enregistrement. Dans ce mode,
Barrel calcule l’embedding des champs que vous nommez (ici title) pour
chaque document écrit, et garde l’index vectoriel en phase avec les
modifications et suppressions suivantes : vous ne gérez jamais les
vecteurs vous-même. mode => sync calcule l’embedding avant que
l’écriture ne rende la main, si bien qu’une recherche juste après la
trouve. Le mode enregistrement ne traite que les documents écrits
après son activation : vous réécrivez donc les articles dans cette
nouvelle base.
{ok, Kb} = barrel:open(<<"kb_search">>, #{
embedding => #{
fields => [<<"title">>],
mode => sync,
embedder => {ollama,
#{model => <<"nomic-embed-text">>}}},
vectordb => #{db_path => "data/vectors/kb_search"}}),
[{ok, _} = barrel:put_doc(Kb, A) || A <- Articles],
barrel:search(Kb, <<"I cannot log in">>, #{k => 2}). {ok,[#{text => <<"Sign in with a passkey">>,
metadata =>
#{<<"product">> => <<"mobile">>,
<<"title">> => <<"Sign in with a passkey">>},
key => <<"kb-311">>,score => 0.5656703092487099},
#{text => <<"Reset a locked account">>,
metadata =>
#{<<"product">> => <<"console">>,
<<"title">> => <<"Reset a locked account">>},
key => <<"kb-142">>,score => 0.5460874853125287}]} Vous avez demandé les 2 articles les plus proches (k => 2). Chaque
résultat donne l’id du document dans key, le texte calculé dans
text, les autres champs dans metadata, et un score de similarité,
le plus haut en premier. Aucun titre ne contient « log in », et pourtant
les deux articles de connexion reviennent, pas celui sur la clé d’API.
La même recherche s’exécute depuis BQL, jointe aux documents : vous pouvez donc sélectionner des champs du document à côté du score :
barrel:query(Kb,
<<"SELECT v.id, v._score, title "
"FROM vector_top_k('lost my credentials', k => 2) AS v">>). {ok,[#{<<"_score">> => 0.5919581721812395,
<<"id">> => <<"kb-142">>,
<<"title">> => <<"Reset a locked account">>},
#{<<"_score">> => 0.47384916313011594,
<<"id">> => <<"kb-311">>,
<<"title">> => <<"Sign in with a passkey">>}],
#{count => 2, ...}} vector_top_k est une fonction de table : elle renvoie les documents les
plus proches sous forme de lignes, avec l’alias v, leur id et leur
_score. title vient du document lui-même. Avec une autre question,
« lost my credentials », kb-142 passe en tête.
Le mode enregistrement traite ce que vous écrivez après son activation ; il n’indexe pas les documents déjà présents dans une base ouverte sans lui. Pas d’Ollama ? N’importe quel fournisseur fonctionne ici : un modèle local via un virtualenv Python, ou une API cloud avec une clé. Voir Choisir un fournisseur d’embeddings.
Définissez db_path comme ci-dessus pour choisir où vit le stockage
vectoriel. Sans lui, le stockage va à côté des documents, dans
<data_dir>/kb_search.vectordb.
6. Fermer
Fermer une base libère son descripteur. Les données restent sur disque,
et le prochain barrel:open/2 avec le même nom les retrouve.
ok = barrel:close(Db),
ok = barrel:close(Kb).