Barrel
FR GitHub

barrel_rerank

Cross-encoder reranking: a second pass that reorders the results of vector or keyword search by reading the query and each candidate together.

What it solves

First-stage search is fast but approximate. A cross-encoder scores each query and document pair directly and puts the best answers first. barrel_rerank runs the model in a Python port and multiplexes concurrent requests over it.

When to use it

  • The top results of vector or hybrid search are close but in the wrong order.
  • You can afford a model call per query on a short list of candidates.

When not to

  • You cannot run Python with transformers and torch (about 2 GB) on the node.
  • You need scores in 0..1: the scores are raw logits.

How it fits into Barrel

Builds on
No other Barrel library
Used by
No other Barrel library depends on it
Optional in
barrel_vectordb
Other dependencies
Python 3 with transformers and torch; a HuggingFace model download on first use
On its own
Yes, it has no Erlang dependencies. It needs Python on the node.

Install

rebar.config deps
{barrel_rerank, "~> 1.0"}

Configuration

start_link/1 config

KeyDefaultWhat it does
python "python3" Use an absolute path if the venv setup fails
model cross-encoder/ms-marco-MiniLM-L-6-v2 HuggingFace model id
timeout 120000 ms Per request

App env (barrel_rerank)

KeyDefaultWhat it does
venv_path undefined (priv/.venv) Where the virtualenv lives; unset means priv/.venv of the app

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

The API by task

Rerank

TaskCallReturns
Start a model server barrel_rerank:start_link/1 {ok, Pid}; not registered, one per call
Rerank candidates barrel_rerank:rerank/3,4 {ok, [{Index, Score}]}, best first, 0-based index
Keep the best k option top_k the first k pairs
Describe, check barrel_rerank:info/1,2, available/1 {ok, #{model, type}}
Stop barrel_rerank:stop/1 ok
Venv barrel_rerank_venv:ensure_venv/0, venv_path/0, refresh/0 path, ok

Rerank three passages

From a verified run that reused an existing venv with transformers, torch and uvloop.

Erlang
%% optional: set venv_path after load and before start
ok = application:load(barrel_rerank),
ok = application:set_env(barrel_rerank, venv_path,
                         "/abs/path/to/.venv"),
{ok, _} = application:ensure_all_started(barrel_rerank),
{ok, S} = barrel_rerank:start_link(#{}),
Docs = [<<"Machine learning is a subset of AI.">>,
        <<"Python is a programming language.">>,
        <<"Deep learning uses neural networks.">>],
Q = <<"What is machine learning?">>,
io:format("rerank: ~p~n", [barrel_rerank:rerank(S, Q, Docs)]),
io:format("top_k=1: ~p~n",
          [barrel_rerank:rerank(S, Q, Docs, #{top_k => 1})]),
ok = barrel_rerank:stop(S).
Output, from a run on barrel_rerank 1.0.2
rerank: {ok,[{0,9.581769943237305},
             {2,-5.255744457244873},
             {1,-9.625640869140625}]}
top_k=1: {ok,[{0,9.581769943237305}]}

Limits to know

  • Scores are raw cross-encoder logits (9.58, -5.25 above), not values between 0 and 1.
  • If the venv setup fails, start_link/1 opens "python3" by name and fails with {error, {port_open_failed, enoent}}. Pass an absolute python or a working venv_path.
  • The model downloads from HuggingFace on first use.

Up and down to moveEnter to open