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):
| Id | Needs | Default model | Dims | Tested |
|---|---|---|---|---|
local | Python 3, sentence-transformers | BAAI/bge-base-en-v1.5 | 768 | yes |
ollama | Ollama with the model pulled | nomic-embed-text | 768 | yes |
fastembed | Python 3, fastembed | BAAI/bge-small-en-v1.5 | 384 | no |
splade | Python 3, transformers, torch | prithivida/Splade_PP_en_v1 | sparse | no |
colbert | Python 3, transformers, torch | colbert-ir/colbertv2.0 | 128 per token | no |
clip | Python 3, transformers, torch, pillow | openai/clip-vit-base-patch32 | 512 | no |
| your module | the barrel_embed_provider behaviour | yours | yours | yes |
Cloud providers send your text to the vendor's API:
| Id | Needs | Default model | Dims | Tested |
|---|---|---|---|---|
openai | OPENAI_API_KEY | text-embedding-3-small | 1536 | no |
cohere | COHERE_API_KEY | embed-english-v3.0 | 1024 | no |
voyage | VOYAGE_API_KEY | voyage-3 | 1024 | no |
jina | JINA_API_KEY | jina-embeddings-v3 | 1024 | no |
mistral | MISTRAL_API_KEY | mistral-embed | 1024 | no |
azure | AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT, a deployment | your deployment | 1536 | no |
bedrock | BEDROCK_API_KEY or AWS keys | amazon.titan-embed-text-v2:0 | 1024 | no |
vertex | GOOGLE_CLOUD_PROJECT and a token or key | text-embedding-004 | 768 | no |
"Tested" means we ran it for these docs. The others are described from their source.
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.
#{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.
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.