Barrel
FR GitHub

barrel_embed

Text and image embeddings for Erlang, from local models or cloud APIs, with a chain of providers that falls back when one is unavailable.

What it solves

Vector search needs embeddings, and the right source changes: a local model on a laptop, Ollama on a server, a cloud API in production. barrel_embed puts every source behind one call, so barrel and barrel_vectordb take an embedder config and never call a model directly.

When to use it

  • You want record mode or text search in barrel or barrel_vectordb.
  • You want a fallback: try a local model first, then another provider.
  • You have your own model and want to plug it in as a provider module.

When not to

  • You compute vectors elsewhere and pass them in: you can skip a provider (barrel_vectordb still pulls this library in).

How it fits into Barrel

Builds on
No other Barrel library
Other dependencies
hackney; Python 3 for the local Python providers
On its own
Yes. Its only dependency is hackney.

Install

rebar.config deps
{barrel_embed, "~> 2.6"}

Configuration

init/1 config

KeyDefaultWhat it does
embedder none {Provider, Opts} or a list for a fallback chain; none gives {ok, undefined}
dimensions 768 Reported by dimension/1; set it to match the model
batch_size 32 Chunk size for embed_batch

Providers (default model, dimension)

KeyDefaultWhat it does
local BAAI/bge-base-en-v1.5, 768 sentence-transformers in a managed Python venv
ollama nomic-embed-text, 768 url default http://localhost:11434
fastembed BAAI/bge-small-en-v1.5, 384 ONNX in the venv
openai text-embedding-3-small, 1536 api_key or OPENAI_API_KEY
cohere, voyage, jina, mistral 1024 each API key from the environment
azure, bedrock, vertex see the reference Cloud credentials
splade, colbert, clip sparse, multi-vector, image Specialized calls, Python venv

App env (barrel_embed)

KeyDefaultWhat it does
venv_dir <priv>/.venv Managed Python venv
managed_venv true false skips the venv bootstrap

The most used keys only. For every option, see the configuration reference and the API reference.

The API by task

Embed

TaskCallReturns
Start a provider chain barrel_embed:init/1 {ok, State}, {ok, undefined} or {error, no_providers_available}
One text barrel_embed:embed/2 {ok, [float()]} or {error, all_providers_failed}
Many texts barrel_embed:embed_batch/2,3 {ok, [[float()]]}
Describe barrel_embed:info/1, describe/2, dimension/1 #{configured, providers, dimension}
Release barrel_embed:release/1 ok

Providers and venv

TaskCallReturns
Write a provider behaviour barrel_embed_provider: name/0, dimension/1, embed/2, embed_batch/2 optional init/1, available/1, model_info/1
Python venv barrel_embed:venv_path/0, refresh_venv/0, install_provider/1 path, ok
Sparse, multi-vector, image barrel_embed_splade:embed_sparse/2, barrel_embed_colbert:embed_multi/2, barrel_embed_clip:embed_image/2 take the provider config, not the state

A provider of your own

Any module that implements the behaviour can be named as a provider.

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

embed(Text, _Config) ->
    <<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, Config) ->
    {ok, [V || T <- Texts, {ok, V} <- [embed(T, Config)]]}.
dimension(_Config) -> 4.
name() -> my_embedder.

Custom, Ollama, and a fallback chain

From a verified run, with Ollama running locally and nomic-embed-text pulled.

Erlang
{ok, _} = application:ensure_all_started(barrel_embed),
{ok, C} = barrel_embed:init(#{
    embedder => {my_embedder, #{}}, dimensions => 4}),
io:format("custom: ~p~n",
          [barrel_embed:embed(<<"hello">>, C)]),
{ok, O} = barrel_embed:init(#{
    embedder => {ollama, #{model => <<"nomic-embed-text">>}},
    dimensions => 768}),
{ok, V} = barrel_embed:embed(<<"hello">>, O),
io:format("ollama dim=~p~n", [length(V)]),
%% a chain: the first provider is down, the second answers
{ok, Ch} = barrel_embed:init(#{embedder => [
    {ollama, #{url => <<"http://127.0.0.1:1">>}},
    {my_embedder, #{}}]}),
io:format("chain: ~p~n",
          [barrel_embed:embed(<<"hello">>, Ch)]),
io:format("not configured: ~p~n",
          [barrel_embed:init(#{})]).
Output, from a run on barrel_embed 2.6.1
custom: {ok,[0.17254901960784313,0.9490196078431372,
             0.30196078431372547,0.7294117647058823]}
ollama dim=768
Provider barrel_embed_ollama not available, skipping
chain: {ok,[0.17254901960784313,0.9490196078431372,
            0.30196078431372547,0.7294117647058823]}
not configured: {ok,undefined}

Limits to know

  • dimension/1 returns the configured dimensions (768 by default), not the provider's size. Pass dimensions explicitly, for example 384 for bge-small.
  • Every embed call first runs the provider's available/1. For cloud providers that is an extra HTTP request per call.
  • The first init of a Python provider can pip-install packages and download a model. Python packages are not pinned.
  • Cloud providers are described from source; they were not run with keys. fastembed, splade, colbert and clip were not run.

Up and down to moveEnter to open