Barrel
EN GitHub

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.

rebar.config
{deps, [{barrel, "~> 1.14"}]}.
config/sys.config
[{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.

Shell Erlang
{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.

Shell Erlang
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">>).
Sortie d’une exécution sur barrel 1.12.0
{ok,#{<<"_rev">> =>
        <<"000001a1ba3fd05d00000000@w4f0cb98700ad5ffc">>,
    <<"id">> => <<"kb-207">>,<<"product">> => <<"console">>,
    <<"title">> => <<"Rotate an API key">>}}
Ce qui vient de se passer

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.

Shell Erlang
{ok, Rows, _Meta} = barrel:query(Db,
  <<"SELECT id, title FROM kb "
    "WHERE product = 'console' ORDER BY id">>).
Sortie d’une exécution sur barrel 1.12.0
{ok,[#{<<"id">> => <<"kb-142">>,
     <<"title">> => <<"Reset a locked account">>},
   #{<<"id">> => <<"kb-207">>,
     <<"title">> => <<"Rotate an API key">>}],
      #{count => 2, ...}}
Ce qui vient de se passer

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.

Shell Erlang
{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}).
Sortie d’une exécution sur barrel 1.12.0 avec Ollama nomic-embed-text
{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}]}
Ce qui vient de se passer

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 :

Shell Erlang
barrel:query(Kb,
  <<"SELECT v.id, v._score, title "
    "FROM vector_top_k('lost my credentials', k => 2) AS v">>).
Sortie d’une exécution sur barrel 1.12.0 avec Ollama nomic-embed-text
{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, ...}}
Ce qui vient de se passer

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.

Note

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.

Shell Erlang
ok = barrel:close(Db),
ok = barrel:close(Kb).

Traduit de la page anglaise: /docs/start/quickstart-embedded/ Modifier cette page Voir en Markdown

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