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
{barrel_rerank, "~> 1.0"} Configuration
start_link/1 config
| Key | Default | What 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)
| Key | Default | What 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
| Task | Call | Returns |
|---|---|---|
| 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.
%% 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). 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/1opens"python3"by name and fails with{error, {port_open_failed, enoent}}. Pass an absolutepythonor a workingvenv_path. - The model downloads from HuggingFace on first use.