Модель поменяли — стало ли лучше, где и почему? ranklens отвечает на это из таблиц pandas одной строкой: разница с интервалом, p- и q-value, минимальный заметный эффект (MDE), разбивка по сегментам с поправкой на множественные сравнения. Метрики совпадают с trec_eval до 1e-9.

import ranklens as rl

rl.compare(current, new, qrels, ["ndcg@10"], by="device")

Типичные задачи

Примеры — на синтетическом каталоге из docs/examples/catalog.py: запросы, товары и оценки выдуманы, но устроены как в настоящем поиске. На главной странице документации они выполняются при каждой сборке.

    query                            product  grade history  base_s0  new_s0
0  молоко            Молоко Луговое 3,2% 1 л      3     нет     0.92    1.08
1  молоко  Молоко Северная ферма 2,5% 930 мл      2     нет     0.97    1.04

Эффект виден только в сегменте. Новая модель знает, покупал ли пользователь товар раньше, — такой признак есть только у пользователей с историей покупок (около 9% запросов). У каждой модели два сида: они усредняются по запросу.

rl.compare([base_s0, base_s1], [new_s0, new_s1], qrels, ["ndcg@10"], by="history")

                 n_queries   delta  ci_low  ci_high     mde  q_value
metric  history
ndcg@10 есть            29  0.0387  0.0190   0.0616  0.0308   0.0006
        нет            291 -0.0010 -0.0034   0.0015  0.0035   0.4194

В среднем по всем запросам прирост +0.0026 не отличим от нуля и меньше MDE (0.0046) — минимального эффекта, который эти запросы способны показать. Разбивка находит, где он.

Две версии выдачи размечены разными партиями асессоров.

rl.agreement(batch_cur, batch_new)
# Agreement(2495 common pairs: exact 88.8%, mean grade A 1.801, B 1.913, shift +0.112)
qrels = rl.merge_qrels(batch_cur, batch_new)  # одна разметка для обеих сторон
rl.compare(current, new_version, qrels, ["ndcg@5", "ndcg@10", "err@10"])

         n_queries   delta  ci_low  ci_high     mde  q_value
metric
ndcg@5         320 -0.0019 -0.0039   0.0000  0.0028   0.0801
ndcg@10        320  0.0629  0.0559   0.0699  0.0099   0.0003
err@10         320  0.0019 -0.0016   0.0054  0.0051   0.2966

Вторая партия мягче, поэтому сравниваем на общей разметке. NDCG@10 значимо выше, а метрики верха выдачи — нет: новая версия улучшает позиции 6–10.

Почему: вклад признаков в метрику. Модель — CatBoost, LightGBM, XGBoost, scikit-learn, PyTorch, ONNX или любая функция скоринга.

ex = rl.explainer(model, df, query="query", doc="product", relevance="grade")
ex.importance("ndcg@10")  # насколько падает метрика, если перемешать признак
ex.worst(20)  # худшие запросы и признаки, которые их подвели

               drop of ndcg@10
feature
text_match              0.1548
bought_before           0.0066
popularity              0.0046
price_rank              0.0006

Установка

pip install "ranklens[viz]"

Extras: viz (графики и HTML-отчёты), arrow (parquet, Feather), models (CatBoost, LightGBM, XGBoost, scikit-learn), neural (ONNX). PyTorch ставится по инструкции pytorch.org. Свежий main — pip install "ranklens @ git+https://github.com/AlexandrBaranov7/ranklens".

Данные и командная строка

rl.run и rl.qrels берут таблицу pandas, polars или pyarrow с одной строкой на пару «запрос — документ»; порядок — по скору модели (score=), по позиции (rank=) или порядку строк. Несколько выдач на запрос (по магазинам, сессиям) — list_id=.

qrels = rl.qrels(labels, query="qid", doc="sku", relevance="grade")
current = rl.run(df_a, query="qid", doc="sku", rank="pos", segments="device")
new = rl.run(df_b, query="qid", doc="sku", rank="pos", segments="device")

Те же сравнения из терминала — для файлов и CI:

ranklens eval --run run.trec --qrels qrels.trec --metrics ndcg@10 mrr@10
ranklens compare --baseline a.csv --candidate b.csv --qrels qrels.csv \
    --metrics ndcg@10 mrr@10 --segments device locale --report compare.html
ranklens explain --model model.cbm --features features.csv --top-worst 20

metric   device   locale  queries  mean A  mean B  delta    95% CI              p       q
ndcg@10  desktop  ru      60       0.5352  0.5352  +0.0000  [+0.0000, +0.0000]  1.0000  1.0000
ndcg@10  mobile   en      60       0.6490  0.6329  -0.0161  [-0.0302, -0.0038]  0.0655  0.0982
ndcg@10  mobile   ru      60       0.6137  0.6926  +0.0789  [+0.0409, +0.1234]  0.0005  0.0015  *

--report compare.html пишет один файл со всеми графиками, который открывается без интернета: таблица, покрытие разметкой, разница по сегментам с интервалами (значимые после поправки — синим), распределение поразапросных разниц, метрика по cutoff, перемещения документов из топ-10.

Подробнее — «Первые шаги».

Почему не существующие библиотеки

• pytrec_eval — обёртка над trec_eval: быстрый эталон метрик, десятки мер. ranklens сверяется с ним golden-тестами и проигрывает ему в числе мер. Но pytrec_eval отвечает на «сколько», а не на «отличимо ли это от шума» — сравнения, интервалов и сегментов в нём нет.
• ir_measures — единый интерфейс к нескольким реализациям мер; хорош, когда нужна именно мера из конкретного инструмента. Статистику сравнения и объяснения он не делает.
• ranx умеет и метрики, и статистическое сравнение прогонов, и fusion — ближайший аналог в части сравнения. ranklens добавляет то, чего в нём нет: поправку FDR по сегментам, MDE, PPI для неточной разметки, off-policy оценку по кликам и объяснение модели по метрике.

ranklens не заменяет их в скорости и полноте набора мер — он закрывает путь от «цифра изменилась» до «вот где и почему».

Архитектура

Слои с проверяемыми границами: core (типы, результаты, протоколы, исключения — только stdlib) → io, metrics, stats, viz → aggregate, offpolicy, explain, report → api (import ranklens as rl) и cli. tests/test_architecture.py разбирает AST каждого модуля и падает, если слой импортирует то, что ему не положено, или тяжёлую библиотеку не лениво. Прогоны читаются потоком (генератор, в памяти — одна выдача), разметка — в словарь для поиска за O(1). Подробно — «Устройство».

Выбор структур данных и средств языка

Неизменяемость результатов: frozen=True, slots=True + tuple + MappingProxyType + read-only массивы numpy — frozen сам по себе запрещает только присваивание полей.

Почему Protocol, а не ABC

Метрика — любой вызываемый объект (ranked, judgements, k) -> float, в том числе обычная функция; модель для объяснений — любой объект с feature_names, score, native_importance. Это typing.Protocol: структурная типизация, реализации не наследуются от наших классов, и чужую модель или функцию не нужно встраивать в иерархию. С ABC каждую сторонюю модель пришлось бы оборачивать в подкласс. Имя метрики хранится в спецификации (ndcg@10): у функции нет атрибута name, и протокол с ним её бы не принял. Новая модель — класс-адаптер и одна строка в ADAPTERS; адаптер находится по MRO класса модели, поэтому подкласс LGBMRanker из чужого кода тоже распознаётся.

Почему ресемплинг по запросам

Единица наблюдения — запрос. Пусть 100 запросов по 10 документов. Ресемплинг строк считал бы, что наблюдений 1000, хотя документы одной выдачи зависимы — интервал вышел бы примерно в √10 ≈ 3 раза уже правды. Поэтому bootstrap берёт с возвращением запросы и усредняет поразапросные разницы M_B(q) − M_A(q); перестановочный тест меняет знак разницы целиком у запроса. Проверено симуляцией: 95%-й интервал покрывает истинную разницу в 95.3% из 1000 повторов. Вывод — в «Статистике сравнения».

Ограничения

• Вход должен быть сгруппирован по запросу (строки запроса подряд), для PairedRuns — отсортирован; иначе ошибка, а не тихая потеря запросов. Разметка грузится в память целиком.
• Неразмеченный документ считается нерелевантным (как в trec_eval): прогон, который приносит много нового, проигрывает из-за разметки. compare показывает judged@k и предупреждает о разрыве; PPI++ лечит систематическую ошибку разметки при наличии случайной gold-выборки.
• Перцентильный bootstrap-интервал на малых выборках бывает уже нужного; поэтому p-value — из перестановочного теста, а меньше 20 запросов — предупреждение.
• Off-policy: PBM с фиксированными propensity не описывает каскадное поведение; неверные propensity смещают IPS; документы, которых старая модель не показывала, не оцениваются никакими весами. SNIPS здесь — отношение (классический SNIPS на PBM-веса не переносится) и оценивает долю, а не клики.
• Объяснения: точки «наполовину A, наполовину B» и перемешанные признаки бывают нереалистичными; Шепли точен до 12 признаков, дальше — по выборке порядков; текстовые кросс-энкодеры и LLM-реранкеры (без матрицы признаков) не объясняются (#34, #35).
• Модели из pickle исполняют код при загрузке — только с --allow-pickle (SECURITY.md).

Roadmap

• Doubly Robust оценщик и Regression-EM для оценки propensity по логам; каскадные click-модели.
• PPI в сравнении по сегментам и в CLI; стратифицированная gold-выборка.
• Объяснение текстовых реранкеров (#34), смещения LLM-реранкеров (#35), GPU-бэкенд метрик (#17).

Разработка

git clone https://github.com/AlexandrBaranov7/ranklens.git
cd ranklens
poetry install --all-extras   # Poetry >= 2.4
poetry run pytest

Правила — в CONTRIBUTING.md, изменения — в CHANGELOG.md.

Лицензия

MIT