Skip to content

Getting Started

Installation

Add barrel_embed to your rebar.config:

{deps, [
    {barrel_embed, {git, "https://github.com/barrel-db/barrel_embed.git", {tag, "v1.0.0"}}}
]}.

Then fetch dependencies:

rebar3 get-deps

Choose Your Provider

Ollama is the easiest way to run embeddings locally without Python dependencies.

# Install Ollama
brew install ollama  # macOS
# or see https://ollama.ai for other platforms

# Start server and pull model
ollama serve &
ollama pull nomic-embed-text

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

Option 2: OpenAI (Production)

Best quality embeddings with minimal setup.

{ok, State} = barrel_embed:init(#{
    embedder => {openai, #{
        api_key => <<"sk-...">>,  % or set OPENAI_API_KEY env var
        model => <<"text-embedding-3-small">>
    }}
}).

Option 3: Local Python

Full control with sentence-transformers.

# Setup virtualenv (recommended)
./scripts/setup_venv.sh

# Or install manually
pip install sentence-transformers

%% Using venv (recommended)
{ok, State} = barrel_embed:init(#{
    embedder => {local, #{
        venv => "/absolute/path/to/.venv",
        model => "BAAI/bge-base-en-v1.5"
    }}
}).

%% Or using system Python
{ok, State} = barrel_embed:init(#{
    embedder => {local, #{
        model => "BAAI/bge-base-en-v1.5"
    }}
}).

Basic Usage

Single Text

{ok, Vector} = barrel_embed:embed(<<"The quick brown fox">>, State).
%% Vector is a list of floats, e.g., [0.123, -0.456, ...]

Batch Embedding

Texts = [<<"Document 1">>, <<"Document 2">>, <<"Document 3">>],
{ok, Vectors} = barrel_embed:embed_batch(Texts, State).
%% Vectors is a list of embedding vectors

Check Configuration

%% Get embedding dimension
Dim = barrel_embed:dimension(State).
%% => 768

%% Get provider info
Info = barrel_embed:info(State).
%% => #{configured => true, providers => [...], dimension => 768}

Provider Chain (Fallback)

Configure multiple providers for high availability:

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

If the first provider fails, barrel_embed automatically tries the next one.

Cosine Similarity

Calculate similarity between embeddings:

cosine_similarity(V1, V2) ->
    Dot = lists:sum(lists:zipwith(fun(A, B) -> A * B end, V1, V2)),
    Norm1 = math:sqrt(lists:sum([X * X || X <- V1])),
    Norm2 = math:sqrt(lists:sum([X * X || X <- V2])),
    Dot / (Norm1 * Norm2).

Next Steps