Barrel
FR GitHub

Choose an embedding provider

An embedding provider turns text into the vectors Barrel searches. Pick one by where your data may go and what you can run: a model on the same machine, a local server such as Ollama, or a cloud API. Providers come from barrel_embed 2.6.1; you name one in a record-mode policy or a vector store config, and Barrel calls it on every write and every text query.

Quick choice

  • Data must not leave the machine, and you can run Python: local.
  • You already run Ollama: ollama, the simplest setup.
  • You use a cloud model already: the matching cloud provider, with its API key.
  • None fits: write your own provider module.

Every provider

Local providers run on your machine (Ollama as a local server):

IdNeedsDefault modelDimsTested
localPython 3, sentence-transformersBAAI/bge-base-en-v1.5768yes
ollamaOllama with the model pullednomic-embed-text768yes
fastembedPython 3, fastembedBAAI/bge-small-en-v1.5384no
spladePython 3, transformers, torchprithivida/Splade_PP_en_v1sparseno
colbertPython 3, transformers, torchcolbert-ir/colbertv2.0128 per tokenno
clipPython 3, transformers, torch, pillowopenai/clip-vit-base-patch32512no
your modulethe barrel_embed_provider behaviouryoursyoursyes

Cloud providers send your text to the vendor's API:

IdNeedsDefault modelDimsTested
openaiOPENAI_API_KEYtext-embedding-3-small1536no
cohereCOHERE_API_KEYembed-english-v3.01024no
voyageVOYAGE_API_KEYvoyage-31024no
jinaJINA_API_KEYjina-embeddings-v31024no
mistralMISTRAL_API_KEYmistral-embed1024no
azureAZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT, a deploymentyour deployment1536no
bedrockBEDROCK_API_KEY or AWS keysamazon.titan-embed-text-v2:01024no
vertexGOOGLE_CLOUD_PROJECT and a token or keytext-embedding-004768no

"Tested" means we ran it for these docs. The others are described from their source.

Set dimensions

Barrel uses the dimensions you configure, 768 by default, not the model's own size. Set it to match the model, for example 384 for bge-small.

Configure one

Pass embedder => {Id, Options} in a record-mode policy:

{ok, Db} = barrel:open(<<"kb">>, #{
    embedding => #{
        fields     => [<<"title">>, <<"body">>],
        embedder   => {ollama,
                       #{model => <<"nomic-embed-text">>}},
        dimensions => 768},
    vectordb => #{db_path => "data/vectors/kb"}}).

Options per provider: model, timeout (30000 ms for HTTP providers, 120000 ms for Python ones), url for ollama (default http://localhost:11434), api_key for openai, deployment and api_version for azure, region for bedrock and vertex.

barrel:embedder_info(Db) returns the provider, model, dimensions and a fingerprint. Two databases with the same fingerprint embed alike.

Output from a run on barrel 1.12.0 with Ollama
#{provider => ollama,dimensions => 768,
model => <<"nomic-embed-text:latest">>,
fingerprint => <<"sha256:865b329a1672b35dba7c9c87afcc38db...">>}

The fingerprint is trimmed above.

Fall back when one is down

Pass a list: Barrel tries each provider in order and uses the first that answers. Keep the same model and dimensions in every entry, or the vectors will not be comparable.

embedder => [{ollama, #{model => <<"nomic-embed-text">>}},
             {my_provider, #{}}]

Running offline

Python providers install their packages into a managed virtualenv (priv/.venv of barrel_embed) and download the model the first time. Run once with network access, then set HF_HUB_OFFLINE=1 and TRANSFORMERS_OFFLINE=1. To use your own Python instead, set {barrel_embed, managed_venv, false}, or move the virtualenv with {barrel_embed, venv_dir, Dir}.

The Python packages are not pinned to versions.

Write your own

Any module that implements barrel_embed_provider works as an embedder: embed/2, embed_batch/2, dimension/1 and name/0, with optional init/1, available/1 and model_info/1. Pass it as {my_provider, Opts}.

-module(my_provider).
-behaviour(barrel_embed_provider).
-export([embed/2, embed_batch/2, dimension/1, name/0]).

embed(Text, _Opts) ->
    <<A:8, B:8, C:8, D:8, _/binary>> =
        crypto:hash(sha256, Text),
    {ok, [A / 255, B / 255, C / 255, D / 255]}.

embed_batch(Texts, Opts) ->
    {ok, [V || T <- Texts, {ok, V} <- [embed(T, Opts)]]}.

dimension(_Opts) -> 4.
name() -> my_provider.

This one hashes text, so it is only good for tests: it matches identical strings, not meaning. A real provider calls a model.

Cost

Cloud providers check that they are reachable before each call, which adds one request per embed.

Without a provider

You can also bring your own vectors: pass vector => [...] to put_doc/3 in record mode, or use vector_add/5 in a plain database. The dimension must match the store.

Written for the site Edit this page View as Markdown

Up and down to moveEnter to open