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
- Used by
barrel,barrel_vectordb- Other dependencies
- hackney; Python 3 for the local Python providers
- On its own
- Yes. Its only dependency is hackney.
Install
{barrel_embed, "~> 2.6"} Configuration
init/1 config
| Key | Default | What 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)
| Key | Default | What 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)
| Key | Default | What 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
| Task | Call | Returns |
|---|---|---|
| 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
| Task | Call | Returns |
|---|---|---|
| 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.
-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.
{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(#{})]). 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/1returns the configureddimensions(768 by default), not the provider's size. Passdimensionsexplicitly, 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.