barrel_embed

A standalone library for generating text and image embeddings with multiple provider backends and automatic fallback support.

Features

• Multiple embedding providers with automatic fallback
• Provider chain configuration for high availability
• Batch embedding with configurable chunk size
• Python integration via async port server (no NIF dependency)
• Sparse, multi-vector, and cross-modal embeddings

Providers

Installation

Add to your rebar.config:

{deps, [
    {barrel_embed, "~> 2.3"}
]}.

Note: Local Python providers require Python 3.9+ installed on your system.

Quick Start

%% Initialize with a single provider
{ok, State} = barrel_embed:init(#{
    embedder => {ollama, #{
        url => <<"http://localhost:11434">>,
        model => <<"nomic-embed-text">>
    }}
}).

%% Generate embedding
{ok, Vector} = barrel_embed:embed(<<"Hello world">>, State).

%% Batch embedding
{ok, Vectors} = barrel_embed:embed_batch([<<"text1">>, <<" text2">>], State).

Configuration

Single Provider

%% Ollama (recommended for local deployment)
#{embedder => {ollama, #{
    url => <<"http://localhost:11434">>,
    model => <<"nomic-embed-text">>
}}}

%% Local Python (sentence-transformers)
#{embedder => {local, #{
    python => "python3",
    model => "BAAI/bge-base-en-v1.5"
}}}

%% OpenAI
#{embedder => {openai, #{
    api_key => <<"sk-...">>,  %% or set OPENAI_API_KEY env var
    model => <<"text-embedding-3-small">>
}}}

%% FastEmbed (ONNX, lighter)
#{embedder => {fastembed, #{
    model => "BAAI/bge-small-en-v1.5"
}}}

Provider Chain (Fallback)

#{embedder => [
    {ollama, #{url => <<"http://localhost:11434">>}},
    {openai, #{api_key => <<"sk-...">>}},
    {local, #{}}  %% fallback to CPU
]}

Custom Dimensions and Batch Size

#{
    embedder => {local, #{}},
    dimensions => 768,
    batch_size => 64
}

Ollama Example

First, install Ollama and pull an embedding model:

# Install Ollama (macOS)
brew install ollama

# Start Ollama server
ollama serve

# Pull embedding model
ollama pull nomic-embed-text

Then use in Erlang:

%% Start the application
application:ensure_all_started(barrel_embed).

%% Initialize with Ollama
{ok, State} = barrel_embed:init(#{
    embedder => {ollama, #{
        url => <<"http://localhost:11434">>,
        model => <<"nomic-embed-text">>
    }},
    dimensions => 768
}).

%% Generate embeddings
{ok, Vec1} = barrel_embed:embed(<<"The quick brown fox">>, State).
{ok, Vec2} = barrel_embed:embed(<<"A fast auburn canine">>, State).

%% Calculate cosine similarity
Dot = lists:sum(lists:zipwith(fun(A, B) -> A * B end, Vec1, Vec2)).
Norm1 = math:sqrt(lists:sum([X * X || X <- Vec1])).
Norm2 = math:sqrt(lists:sum([X * X || X <- Vec2])).
Similarity = Dot / (Norm1 * Norm2).
%% => ~0.85 (semantically similar)

Specialized APIs

SPLADE Sparse Embeddings

{ok, State} = barrel_embed:init(#{embedder => {splade, #{}}}).

%% Get sparse vector (indices + values)
{ok, #{indices := Indices, values := Values}} =
    barrel_embed_splade:embed_sparse(<<"query text">>, Config).

ColBERT Multi-Vector Embeddings

{ok, State} = barrel_embed:init(#{embedder => {colbert, #{}}}).

%% Get token-level vectors
{ok, TokenVectors} = barrel_embed_colbert:embed_multi(<<"document">>, Config).

%% Calculate MaxSim score
Score = barrel_embed_colbert:maxsim_score(QueryVecs, DocVecs).

CLIP Image Embeddings

{ok, State} = barrel_embed:init(#{embedder => {clip, #{}}}).

%% Embed image (base64-encoded)
{ok, ImageVec} = barrel_embed_clip:embed_image(ImageBase64, Config).

%% Embed text (same vector space as images)
{ok, TextVec} = barrel_embed_clip:embed(<<"a photo of a cat">>, Config).

%% Now ImageVec and TextVec can be compared with cosine similarity

API Reference

barrel_embed

Application Configuration

barrel_embed creates and manages its own Python virtualenv automatically on startup (default location: priv/barrel_embed/.venv). Configure a custom location in sys.config:

%% sys.config
[
    {barrel_embed, [
        {venv_dir, "/path/to/.venv"},  %% Optional: custom venv location
        {managed_venv, false}          %% Optional: skip the bootstrap
    ]}
].

Set managed_venv to false when the deployment supplies its own interpreter with the model libraries installed (each provider's python option): the venv is neither created nor checked at start, so an image without python3-venv boots silently. Installing python3-venv just to silence the warning would create an empty venv nothing uses.

Python Setup

Managed Virtualenv (Default)

No manual setup is required. barrel_embed creates the venv on application start and installs each provider's dependencies the first time it is used:

%% Venv created and configured automatically
{ok, State} = barrel_embed:init(#{
    embedder => {local, #{
        model => "BAAI/bge-base-en-v1.5"
    }}
}).

See venv-setup for the full venv management API.

Manual Installation

Install based on providers used:

# For local provider
pip install sentence-transformers

# For fastembed provider
pip install fastembed

# For splade/colbert providers
pip install transformers torch

# For clip provider
pip install transformers torch pillow

See venv-setup for detailed virtualenv instructions.

Support

License

Apache-2.0. See LICENSE for details.

Built by Enki Multimedia | barrel-db.eu