Ranqueamento

Cerca de 45 minutos min de leitura, com 14 exemplos em 12 seções.

Edição 2026.11.10 Exemplos aprovados em 19 de nov de 2026 132 de 132 exemplos passam O que mudou

Traduzido com IA. Verificado por pessoas em inglês. Como fazemos os livros

Traduzido do livro em inglês, edição 2026.11.10. Leia o original

Ao final deste capítulo, você consegue descrever cada produto que a recuperação retorna com seus atributos (features), treinar um modelo de learning-to-rank com LightGBM a partir dos seus próprios julgamentos, reordenar o topo da lista com um cross-encoder ou com um LLM, medir o viés posicional de um reranqueador baseado em LLM, definir a profundidade da reordenação contando os seus custos e destilar um reranqueador lento em um rápido. Você também consegue decidir, com uma comparação planejada sobre as consultas de teste, se algum deles supera a sua recuperação.

A recuperação semântica sozinha ainda é o ranqueador a ser superado na loja, onde cada busca é ordenada por um único escore de embeddings e mais nada. Ela ranqueia os produtos por embeddings de Snowflake/snowflake-arctic-embed-m-v1.5, e obtém 0.830 em nDCG@10 nas 30 consultas de teste. Nenhuma mudança nos capítulos 5 a 8 a superou por uma margem estabelecida. Este capítulo pergunta se um segundo estágio consegue: um modelo treinado com os julgamentos próprios da loja, um reranqueador que lê a consulta e o produto em conjunto, ou um LLM. O cross-encoder do capítulo 1 reordenou a execução híbrida, e não a recuperação semântica, e nunca viu os julgamentos da loja.

Assim, este capítulo testa os três sobre os resultados do topo da recuperação semântica, cada um pontuado contra os julgamentos da loja. Reranqueamento reordena o topo da lista da recuperação com um modelo mais lento. Os reranqueadores da loja são gravados: cada um rodou uma vez e salvou suas saídas, que os exemplos leem.

O LLM da loja é o modelo aberto gemma4:12b-it-q4_K_M, com licença Apache-2.0. Ele rodou localmente com as configurações do capítulo 4, que fazem com que ele sempre escolha a palavra seguinte mais provável, com o modo de raciocínio desligado, de modo que responde sem escrever o raciocínio, e com um JSON schema, que é uma descrição legível por máquina do formato da resposta. recordings/llm_rerank.py reordenou os 20 primeiros resultados da recuperação semântica apenas para as consultas de teste, de modo que nada sobre os reranqueadores baseados em LLM pôde ser ajustado. Todas as pontuações usam os julgamentos humanos, porque em um estudo juízes LLM classificaram reranqueadores LLM alto demais (O que dá errado em produção). Estes resultados descrevem um modelo e dois prompts, então trate-os como resultados da loja, e não como um veredito sobre reranqueadores LLM.

O capítulo fixou suas 5 comparações planejadas sobre as consultas de teste antes de ler qualquer resultado de teste. Cada uma coloca um método contra a execução da recuperação semântica em nDCG@10:

  1. LambdaMART, um ranqueador aprendido treinado com os julgamentos das consultas de treino, ordenando os produtos candidatos de cada consulta
  2. o cross-encoder reordenando os 20 primeiros da recuperação semântica
  3. o LLM pontuando cada um dos 20 primeiros por conta própria
  4. o LLM ordenando os 20 primeiros em um único prompt
  5. um pequeno ranqueador destilado treinado com as pontuações do cross-encoder

O critério é a regra do livro: 5 comparações planejadas dividem os seus 0.05, então cada uma precisa de um p-valor de teste de permutação pareado abaixo de 0.01. O teste t pareado e um intervalo de bootstrap de 99% ficam ao lado dele.

Descreva cada candidato com features

Última alteração na edição 2026.11.10

A primeira das comparações planejadas do capítulo é um ranqueador aprendido, que não lê texto. Um ranqueador aprendido pontua cada par de consulta e produto a partir de uma lista de números, suas features, e aprende com os julgamentos como ponderá-las. Uma feature dependente da consulta descreve a consulta e o produto juntos, como uma pontuação BM25. Uma feature independente da consulta descreve somente o produto, como quantos compradores o avaliaram. Conjuntos de features para busca na web misturam os dois: o LETOR 4.0, um benchmark para aprendizado para ranqueamento, tem 46 features, entre elas "BM25 do título", "PageRank" e "Número de barras na URL" (Qin e Liu, 2013). Um ranqueador pontua apenas candidatos, os produtos que uma etapa de recuperação mais barata devolve, então suas features podem ser caras.

Os candidatos para cada consulta da loja são os produtos que a gravação do cross-encoder pontuou: a união dos 100 primeiros do BM25 e dos 100 primeiros da recuperação semântica. lib.ranking.feature_table atribui a cada candidato 8 features:

  • bm25: a pontuação BM25 de lib.lexical, a linha de base sem stemming do livro, e 0 para um produto que não compartilha nenhum termo com a consulta
  • similarity: a similaridade do cosseno entre os embeddings da consulta e do produto
  • cross_encoder: a pontuação gravada do cross-encoder
  • name_match e attribute_match: a parcela dos termos da consulta, tokenizados como faz o capítulo 5, encontrada no nome do produto e nos seus atributos
  • rating_count, average_rating e review_count, que os dados da loja atribuem a cada produto

2632 dos produtos do catálogo não têm avaliação, e suas três features de avaliação permanecem ausentes. A tabela também traz a nota humana de cada candidato, ou uma lacuna quando ninguém o julgou. Construa a tabela para as consultas de treino, observe uma consulta e depois compare cada feature entre as notas:

ranking-features-by-grade.py Python 3.12.15 · bm25s 0.3.16 · lightgbm 4.7.0 · numpy 2.5.5 · pandas 3.1.1 · pystemmer 3.1.0 · scikit-learn 1.9.1 · scipy 1.18.1 Aprovado
"""Builds the feature table for the train queries, shows one query's candidates, and compares each feature's mean acrossthe human grades. The prose's point rests on the mean cross_encoder line for each grade and the mean of each feature by grade."""import pandas as pdfrom lib.ranking import FEATURES, feature_tablefrom lib.store import load_products, load_queriesproducts, queries = load_products(), load_queries("train")      # train queries: features are design worktable = feature_table(products, queries)print(f"features: {len(FEATURES)}")print(f"train candidates: {len(table)}")print(f"train candidates per query, median: {table.groupby('query_id').size().median():.0f}")print(f"share of train candidates nobody judged: {table['grade'].isna().mean():.3f}")query_id = queries.index[queries["query"] == "laundry basket with wheels"][0]one = table[table["query_id"] == query_id].sort_values("cross_encoder", ascending=False)one = one.assign(name=products.loc[one["product_id"], "name"].str[:38].to_numpy())pd.set_option("display.width", 200)print(f"\ncandidates for laundry basket with wheels: {len(one)}")print(one[["name", "bm25", "similarity", "cross_encoder", "name_match", "attribute_match", "rating_count", "grade"]]      .head(6).round(3).to_string(index=False))print(f"top 6 by cross-encoder, exact: {(one['grade'].head(6) == 2).sum()}")# grades 2, 1 and 0 are exact, partial and irrelevant; a missing grade means nobody judged the pairlabel = table["grade"].map({2: "exact", 1: "partial", 0: "irrelevant"}).fillna("unjudged")means = table[FEATURES].groupby(label).mean().loc[["exact", "partial", "irrelevant", "unjudged"]]print("\nmean of each feature by grade, train candidates:")print(means.round(3).to_string())for grade in means.index:    print(f"mean cross_encoder, {grade}: {means.at[grade, 'cross_encoder']:.3f}")relevance = ["bm25", "similarity", "cross_encoder", "name_match"]nearer = [name for name in relevance if abs(means.at["unjudged", name] - means.at["irrelevant", name])          < abs(means.at["unjudged", name] - means.at["partial", name])]print(f"relevance features where unjudged sits nearer irrelevant than partial: {len(nearer)} of {len(relevance)}")medians = table[["rating_count", "review_count"]].groupby(label).median().loc[means.index]  # counts are skewedfor grade in ["exact", "partial", "irrelevant"]:    print(f"rating_count, {grade}, mean: {means.at[grade, 'rating_count']:.3f}")    print(f"rating_count, {grade}, median: {medians.at[grade, 'rating_count']:.1f}")print(f"products with no rating: {products['rating_count'].isna().sum()}")
Saídapython ranking-features-by-grade.py
features: 8
train candidates: 6896
train candidates per query, median: 131
share of train candidates nobody judged: 0.286

candidates for laundry basket with wheels: 125
                                  name  bm25  similarity  cross_encoder  name_match  attribute_match  rating_count  grade
       laundry sorter basket on wheels 8.229       0.597          3.433       1.000              0.0           NaN    2.0
                vintage laundry basket 6.270       0.572          2.995       0.667              0.0         638.0    2.0
         rolling wicker laundry basket 5.494       0.588          2.974       0.667              0.0         110.0    2.0
aluminum frame laundry basket can be f 4.739       0.524          2.941       0.667              0.0          14.0    2.0
    rebrilliant rolling laundry hamper 5.537       0.558          2.804       0.333              0.0          17.0    2.0
4-bag laundry hamper sorter cart baske 6.012       0.543          2.739       0.667              0.0           NaN    2.0
top 6 by cross-encoder, exact: 6

mean of each feature by grade, train candidates:
             bm25  similarity  cross_encoder  name_match  attribute_match  rating_count  average_rating  review_count
grade
exact       4.317       0.517          2.191       0.562            0.024       466.879           4.537       333.589
partial     3.936       0.454          1.513       0.461            0.030       385.454           4.539       288.779
irrelevant  2.760       0.360          1.159       0.404            0.006       246.781           4.552       159.052
unjudged    2.323       0.369          1.050       0.140            0.018       339.904           4.520       237.027
mean cross_encoder, exact: 2.191
mean cross_encoder, partial: 1.513
mean cross_encoder, irrelevant: 1.159
mean cross_encoder, unjudged: 1.050
relevance features where unjudged sits nearer irrelevant than partial: 4 of 4
rating_count, exact, mean: 466.879
rating_count, exact, median: 43.0
rating_count, partial, mean: 385.454
rating_count, partial, median: 31.0
rating_count, irrelevant, mean: 246.781
rating_count, irrelevant, median: 35.5
products with no rating: 2632

As consultas de treino têm 6896 candidatos, uma mediana de 131 por consulta, e ninguém julgou uma parcela de 0.286 deles.

laundry basket with wheels tem 125 candidatos. Os seis primeiros pela pontuação do cross-encoder incluem 6 produtos exatos. Seu attribute_match é 0, porque os atributos trazem cores, materiais e tamanhos, não palavras como wheels.

Entre os candidatos de treino, a pontuação média do cross-encoder cai de 2.191 para os produtos exatos, para 1.513 para os parciais e para 1.159 para os irrelevantes, e bm25, similarity e name_match caem da mesma forma. average_rating e attribute_match quase não se movem.

As médias de rating_count caem com a nota, mas as medianas não: poucos produtos muito avaliados puxam as médias.

Nota Contagem média de avaliações Contagem mediana de avaliações
exato 466.879 43.0
parcial 385.454 31.0
irrelevante 246.781 35.5

Candidatos não julgados têm pontuação média de cross-encoder de 1.050, e, em 4 of 4 features que caem com a nota, sua média fica mais perto da dos produtos irrelevantes do que da dos parciais. Isso importa para o que um candidato não julgado deve ensinar a um modelo.

Regra prática: Comece pelas features que você já calcula: a pontuação de cada recuperador, a pontuação de um reranqueador, se você tiver um, as correspondências em campos como o nome, e os sinais de popularidade. Compare cada feature por nota nas consultas de treino antes de treinar, com médias para pontuações e medianas para contagens assimétricas. Uma feature que não se move com a nota tem pouco a ensinar ao modelo. Calcule as features com o mesmo código ao treinar e ao servir.

Aprenda um ranking a partir de pares de produtos

Última alteração na edição 2026.11.10

Aprendizado de ranking treina um modelo com consultas avaliadas para ordenar os candidatos pelas suas características. Seus métodos se dividem em três famílias: pontual, par a par e listwise (Liu, 2009). Um modelo pontual prevê o grau de cada produto isoladamente, como uma regressão. Um modelo par a par aprende qual de dois produtos deve ficar acima no ranking. Um modelo listwise avalia um ranking inteiro. A comparação de Liu de 2009 no benchmark LETOR favoreceu a abordagem listwise, embora de forma cautelosa. O obstáculo para as três é a métrica: o nDCG só muda quando dois produtos trocam de posição, e por isso as métricas de ranking "estão em toda parte descontínuas ou planas, de modo que a descida do gradiente parece problemática" (Burges, 2010).

RankNet, um método par a par, contorna esse problema com uma função de perda suave sobre os pares. Para dois produtos em que i deve ficar acima de j, seu gradiente é grande quando o modelo os pontua na ordem errada ou quase empatados, e pequeno quando ele já os separa bem. LambdaRank mantém esse gradiente e o multiplica pelo quanto o nDCG mudaria se os dois produtos trocassem de posição (Burges, 2010, seção 4.1). Burges escreve o gradiente com sinal de menos, como a inclinação de um custo; aqui, um λ positivo empurra i para cima:

λ_ij    = σ / (1 + exp(σ · (s_i − s_j))) · |ΔnDCG_ij|      s: the model's scores, σ = 1
ΔnDCG_ij = (g_i − g_j) · (1 / log2(1 + r_i) − 1 / log2(1 + r_j)) / ideal DCG      g: grades, r: positions

O total de um produto é a soma dos seus λ nos pares em que ele deve ficar acima, menos os dos pares em que deve ficar abaixo. Burges (2010) também interpreta os λ como forças que empurram os produtos para cima e para baixo na lista.

LambdaMART usa o λ do LambdaRank como gradiente para as árvores com gradient boosting, que somam pequenas árvores de decisão uma de cada vez, cada uma ajustada aos gradientes das árvores anteriores: "LambdaMART é a versão com árvores boosted do LambdaRank, que se baseia no RankNet". Um conjunto de rankers LambdaMART venceu a Track 1 do Learning to Rank Challenge que o Yahoo promoveu em 2010 (Burges, 2010).

Uma consulta de treino, outdoor waterproof chest, mostra a aritmética. Tome a similaridade semântica como os escores que o modelo tem até aqui, calcule à mão o λ de cada par nos 10 primeiros, verifique cada |ΔnDCG| trocando o par e recalculando o nDCG com lib.metrics, e some as forças:

lambdas-for-one-query.py Python 3.12.15 · numpy 2.5.5 · pandas 3.1.1 Aprovado
"""Works out LambdaRank's λ for every pair in one train query's top 10 by hand, and checks each pair's |ΔnDCG| againstswapping the pair in the metric. The prose's point rests on the strongest push up and down, and on the count of pairswhose formula matches swapping."""import mathfrom itertools import combinationsfrom lib.metrics import dcg_at_k, ndcg_at_kfrom lib.semantic import SemanticSearchfrom lib.store import load_queries, qrelsqueries, judgments = load_queries("train"), qrels("train")query_id = queries.index[queries["query"] == "outdoor waterproof chest"][0]judged = judgments[query_id]scores = SemanticSearch().search(query_id, k=10)       # the model so far: semantic similarityranking, similarity = list(scores.index), scores.to_numpy()# an unjudged product counts as grade 0, as it does in the metricgrades = [judged.get(product_id, 0) for product_id in ranking]# the ideal DCG takes every judged product, as lib.metrics does; sigma is 1, LightGBM's default sigmoidideal, sigma = dcg_at_k(sorted(judged.values(), reverse=True), 10), 1.0print("grades from the top:", " ".join(map(str, grades)))force, checks, pulls = [0.0] * len(ranking), [], []for i, j in combinations(range(len(ranking)), 2):      # i is above j    if grades[i] == grades[j]:        continue    better, worse = (i, j) if grades[i] > grades[j] else (j, i)    ranknet = 1 / (1 + math.exp(sigma * (similarity[better] - similarity[worse])))      # RankNet's pull    # i and j count from 0, so position p is i + 1 and its discount is 1 / log2(p + 1), which is 1 / log2(i + 2)    delta = abs((grades[i] - grades[j]) * (1 / math.log2(i + 2) - 1 / math.log2(j + 2))) / ideal    swapped = ranking.copy()    swapped[i], swapped[j] = swapped[j], swapped[i]    checks.append(math.isclose(delta, abs(ndcg_at_k(swapped, judged, 10) - ndcg_at_k(ranking, judged, 10))))    pulls.append(ranknet)    pair_lambda = sigma * ranknet * delta                         # LambdaRank: scaled by |delta nDCG|    force[better], force[worse] = force[better] + pair_lambda, force[worse] - pair_lambdaprint(f"pairs with different grades: {len(checks)}")print(f"pairs where delta ndcg by formula matches swapping the pair: {sum(checks)}")for position, push in enumerate(force, start=1):    print(f"force at position {position}: {push:+.3f}")# list indexes count from 0 and positions from 1, hence the + 1print(f"strongest push up, position: {force.index(max(force)) + 1}")print(f"strongest push down, position: {force.index(min(force)) + 1}")print(f"ranknet's pull, lowest: {min(pulls):.3f}\nranknet's pull, highest: {max(pulls):.3f}")
Saídapython lambdas-for-one-query.py
grades from the top: 1 2 2 0 1 2 0 2 0 0
pairs with different grades: 32
pairs where delta ndcg by formula matches swapping the pair: 32
force at position 1: +0.013
force at position 2: +0.159
force at position 3: +0.104
force at position 4: -0.083
force at position 5: -0.010
force at position 6: +0.063
force at position 7: -0.092
force at position 8: +0.063
force at position 9: -0.105
force at position 10: -0.111
strongest push up, position: 2
strongest push down, position: 10
ranknet's pull, lowest: 0.472
ranknet's pull, highest: 0.525

A |ΔnDCG| da fórmula coincide com a variação causada pela troca do par em 32 dos 32 pares com graus diferentes nos 10 primeiros. Os graus dos 10 primeiros, do topo para baixo, são 1 2 2 0 1 2 0 2 0 0; um produto não avaliado conta como 0, como acontece na métrica.

O maior empurrão para cima vai para a posição 2, um produto exato, com +0.159; o maior empurrão para baixo vai para a posição 10, um produto irrelevante, com -0.111. O produto parcial na posição 1 recebe um empurrão líquido de +0.013: os produtos irrelevantes abaixo dele o empurram para cima, e os exatos o empurram para baixo.

O fator do RankNet em λ permanece entre 0.472 e 0.525, porque as similaridades ficam próximas umas das outras, de modo que a |ΔnDCG| decide quase tudo.

Esse exemplo é simplificado. Ele usa o DCG ideal de todos os produtos avaliados, como faz lib.metrics, e considera apenas dez produtos. O LightGBM toma o ideal a partir das linhas de treino da consulta e, na versão 4.7.0, dois valores padrão alteram o λ. lambdarank_truncation_level vale 30, o que limita o treino aos 30 primeiros resultados: somente pares com um produto no top 30 atual recebem um λ. lambdarank_norm vale true, o que normaliza os lambdas entre consultas; defina-o como false para obter o algoritmo lambdarank original (Parameters). A normalização, como o código-fonte do LightGBM a faz, divide a |ΔnDCG| de cada par pela distância entre seus escores mais 0.01 e, em seguida, redimensiona o λ de cada consulta (rank_objective.hpp).

Para conferir a fórmula contra a biblioteca, escreva-a como um objetivo personalizado do LightGBM, treine cinco árvores pequenas sobre os candidatos desta consulta e treine-as de novo com o lambdarank do LightGBM, com e sem esses valores padrão:

lambdas-match-lightgbm.py Python 3.12.15 · bm25s 0.3.16 · lightgbm 4.7.0 · numpy 2.5.5 · pandas 3.1.1 · pystemmer 3.1.0 · scikit-learn 1.9.1 · scipy 1.18.1 Aprovado
"""Writes LambdaRank's gradients by hand as a custom LightGBM objective, then checks them against LightGBM's own lambdarankon one query, with and without its defaults. The prose's point rests on the two printed differences: a rounding-sized gapwithout the defaults, and a large one at them."""import numpy as npfrom lightgbm import LGBMRankerfrom lib.ranking import DETERMINISTIC, FEATURES, feature_tablefrom lib.store import load_products, load_queriesqueries = load_queries("train")one = queries[queries["query"] == "outdoor waterproof chest"]rows = feature_table(load_products(), one)                  # one query's candidates, in product_id order# unjudged candidates count as grade 0, as in the metricgrades = rows["grade"].fillna(0).astype(int).to_numpy()SIGMA = 1.0                                                   # LightGBM's default sigmoiddef lambdas(y_true, y_pred, weight, group):    """The chapter's lambda for every pair with different grades, as gradients and second derivatives."""    rank = np.empty(len(y_pred), dtype=int)    rank[np.argsort(-y_pred, kind="stable")] = np.arange(len(y_pred))   # LightGBM's stable sort on score    # rank counts from 0, so the product at position rank + 1 has the discount 1 / log2(rank + 2)    discount, ideal = 1 / np.log2(rank + 2), np.sum(np.sort(y_true)[::-1] / np.log2(np.arange(len(y_true)) + 2))    gradient, hessian = np.zeros(len(y_pred)), np.zeros(len(y_pred))    for i in range(len(y_true)):        for j in np.flatnonzero(y_true < y_true[i]):                      # i should rank above j            delta = (y_true[i] - y_true[j]) * abs(discount[i] - discount[j]) / ideal            pull = 1 / (1 + np.exp(SIGMA * (y_pred[i] - y_pred[j])))            gradient[i], gradient[j] = gradient[i] - SIGMA * pull * delta, gradient[j] + SIGMA * pull * delta            hessian[[i, j]] += SIGMA ** 2 * pull * (1 - pull) * delta    return gradient, hessian# five small trees; min_child_samples is 5 where LightGBM's default is 20, so the trees can split this query's candidatestree = {"n_estimators": 5, "num_leaves": 3, "min_child_samples": 5, **DETERMINISTIC}# turns off normalization and sets truncation to every candidate, so every pair gets a λ, as the formula has itplain = {"lambdarank_norm": False, "lambdarank_truncation_level": len(rows)}   # LightGBM's lambdas, untouchedmodels = {"by hand": LGBMRanker(objective=lambdas, **tree),          "lightgbm, no normalization or truncation": LGBMRanker(objective="lambdarank", label_gain=[0, 1, 2], **plain, **tree),          "lightgbm at its defaults": LGBMRanker(objective="lambdarank", label_gain=[0, 1, 2], **tree)}# raw scores: the values the gradients act on, before any sigmoidscores = {name: model.fit(rows[FEATURES], grades, group=[len(rows)]).predict(rows[FEATURES], raw_score=True)          for name, model in models.items()}print(f"candidates: {len(rows)}")for name in list(models)[1:]:    difference = np.abs(scores[name] - scores["by hand"]).max()    print(f"{name}, largest difference from the lambdas by hand after 5 trees: {difference:.6f}")
Saídapython lambdas-match-lightgbm.py
candidates: 180
lightgbm, no normalization or truncation, largest difference from the lambdas by hand after 5 trees: 0.000006
lightgbm at its defaults, largest difference from the lambdas by hand after 5 trees: 0.595667

Sobre os 180 candidatos da consulta, o LightGBM sem normalização nem truncamento pontua cada produto a menos de 0.000006 dos escores do objetivo personalizado. A diferença é arredondamento, já que o LightGBM lê sua sigmoide de uma tabela pré-calculada (rank_objective.hpp). Com os valores padrão, os escores diferem em até 0.595667.

Regra prática: treine rankers com um gradiente que pondere cada par pela métrica que você reporta, como faz o LambdaMART, em vez de regredir sobre os graus. Saiba quais padrões da sua biblioteca alteram esse gradiente e verifique, em consultas de treino, que ele supera um modelo pontual nos seus dados, porque a ordem das famílias em um benchmark não se transfere sozinha.

Treinar LambdaMART com LightGBM

Última alteração na edição 2026.11.8

O LightGBM treina o LambdaMART com LGBMRanker e objective="lambdarank". Quatro configurações exigem cuidado, e cada uma está documentada para o lightgbm na versão 4.7.0:

  • As linhas são agrupadas por consulta. “data should be ordered by the query”, e group guarda o número de linhas de cada consulta nessa ordem, e não os IDs das consultas, de modo que seus tamanhos somam o número de linhas (sum(group) = n_samples; Parâmetros; LGBMRanker).
  • Os ganhos são exponenciais por padrão. label_gain tem como padrão 0,1,3,7,15,31,63,..., de modo que “o ganho do rótulo 2 é 3”, e todo rótulo deve ser menor que o número de ganhos (Parâmetros). Trata-se do DCG de Burges, com ganho 2^grau − 1. O nDCG do livro usa ganhos lineares, então defina label_gain=[0, 1, 2].
  • Por padrão, o nDCG é avaliado nas posições 1 a 5. Defina eval_at=[10] para parar no nDCG@10, e registre a pontuação final com lib.metrics de qualquer forma.
  • Os dados de validação vão em eval_X e eval_y. Na versão 4.7.0, eval_set está “obsoleto desde a versão 4.7.0”, e eval_X e eval_y o substituem (LGBMRanker; notas de versão). Os exemplos passam eval_X, eval_y e eval_group.

Parada antecipada pontua consultas de treino reservadas após cada árvore, e mantém as árvores até a melhor pontuação quando outras 30 não trazem ganho. Para que o treinamento se repita exatamente, os exemplos usam uma única thread, uma semente fixa e deterministic=True, o que “deve garantir resultados estáveis ao usar os mesmos dados” (Parâmetros), junto com force_row_wise=True, recomendado na mesma entrada, para evitar possível instabilidade causada por problemas numéricos. lib.ranking guarda essas configurações, e seu fit aplica o agrupamento e a parada antecipada.

A ordem das linhas também importa. Antes da primeira árvore, todas as pontuações são 0, então o LightGBM toma a ordem das linhas como ranking inicial para o primeiro λ, e pontuações iguais exigem um desempate. O registro do cross-encoder lista os candidatos de cada consulta do melhor para o pior, o que entregaria ao modelo o ranking do cross-encoder antes que ele tivesse aprendido qualquer coisa. Por isso, feature_table ordena os candidatos por product_id, e lib.ranking.ranked desfaz empates por product_id.

Escolha o tamanho da árvore por validação cruzada nas consultas de treino: divida-as em cinco dobras, ranqueie cada dobra com um modelo ajustado nas outras três e interrompido antecipadamente na quinta, e pontue cada consulta uma vez. Teste oito configurações, de 3 a 31 folhas em duas taxas de aprendizado, contando candidatos não julgados como grau 0, como faz a métrica:

lambdamart-tree-size-on-train.py Python 3.12.15 · bm25s 0.3.16 · lightgbm 4.7.0 · numpy 2.5.5 · pandas 3.1.1 · pystemmer 3.1.0 · scikit-learn 1.9.1 · scipy 1.18.1 Aprovado
"""Cross-validates LambdaMART on the train queries over eight tree sizes and learning rates, and names the best. The prose'spoint rests on the best setting's score, and on the score beside it for LightGBM's default of 31 leaves at 0.1."""from lightgbm import LGBMRankerfrom lib.metrics import evaluatefrom lib.ranking import DETERMINISTIC, FEATURES, LAMBDARANK, TREE_GRID, TREES, cross_validate, feature_tablefrom lib.semantic import SemanticSearchfrom lib.store import load_products, load_queries, qrelsqueries, judgments = load_queries("train"), qrels("train")          # tuning: train queries onlycandidates = feature_table(load_products(), queries)candidates["grade or 0"] = candidates["grade"].fillna(0).astype(int)  # unjudged counts as irrelevant, as in nDCGprint(f"train queries: {len(queries)}")print(f"semantic, train ndcg@10: {evaluate(SemanticSearch().run(queries, k=100), judgments)['ndcg@10'].mean():.3f}")results = {}for setting in TREE_GRID:                                            # LightGBM's default is 31 leaves at 0.1    name = f"{setting['num_leaves']} leaves, learning rate {setting['learning_rate']}"    # up to 500 trees; early stopping inside cross_validate keeps fewer    model = lambda: LGBMRanker(**LAMBDARANK, n_estimators=500, **setting, **DETERMINISTIC)    # one nDCG@10 per train query, each ranked by a model that never saw that query    results[name] = cross_validate(model, candidates, candidates, "grade or 0", FEATURES, judgments)    print(f"{name}, cross-validated ndcg@10: {results[name].mean():.3f}")    # the trees early stopping kept in each fold    print(f"{name}, trees kept per fold: {', '.join(map(str, results[name].attrs['trees']))}")best = max(results, key=lambda name: results[name].mean())print(f"settings tried: {len(results)}")print(f"best setting: {best}")print(f"lib.ranking.TREES holds it: {'yes' if best == f'{TREES['num_leaves']} leaves, learning rate {TREES['learning_rate']}' else 'no'}")
Saídapython lambdamart-tree-size-on-train.py
train queries: 50
semantic, train ndcg@10: 0.772
3 leaves, learning rate 0.05, cross-validated ndcg@10: 0.780
3 leaves, learning rate 0.05, trees kept per fold: 18, 27, 52, 20, 85
3 leaves, learning rate 0.1, cross-validated ndcg@10: 0.798
3 leaves, learning rate 0.1, trees kept per fold: 99, 20, 8, 43, 38
7 leaves, learning rate 0.05, cross-validated ndcg@10: 0.744
7 leaves, learning rate 0.05, trees kept per fold: 2, 28, 30, 39, 55
7 leaves, learning rate 0.1, cross-validated ndcg@10: 0.772
7 leaves, learning rate 0.1, trees kept per fold: 80, 12, 13, 7, 20
15 leaves, learning rate 0.05, cross-validated ndcg@10: 0.720
15 leaves, learning rate 0.05, trees kept per fold: 4, 37, 175, 44, 120
15 leaves, learning rate 0.1, cross-validated ndcg@10: 0.728
15 leaves, learning rate 0.1, trees kept per fold: 19, 68, 136, 48, 53
31 leaves, learning rate 0.05, cross-validated ndcg@10: 0.679
31 leaves, learning rate 0.05, trees kept per fold: 15, 8, 91, 8, 22
31 leaves, learning rate 0.1, cross-validated ndcg@10: 0.737
31 leaves, learning rate 0.1, trees kept per fold: 11, 75, 166, 96, 58
settings tried: 8
best setting: 3 leaves, learning rate 0.1
lib.ranking.TREES holds it: yes

Entre 8 configurações, a melhor é 3 leaves, learning rate 0.1, com 0.798; o padrão do LightGBM de 31 folhas com taxa 0.1 (LGBMRanker) pontua 0.737. A melhor de todas as configurações se superestima, então espere menos em consultas reservadas.

Uma escolha depende dos julgamentos da loja. Ninguém julgou uma parcela de 0.286 dos candidatos de treino. Um modelo pode contá-los como grau 0, ou aprender apenas com os candidatos julgados; não julgado não é irrelevante, mas o modelo os ranqueará em tempo de consulta de qualquer forma. Compare as duas opções por validação cruzada no tamanho de árvore escolhido, com uma regressão pontual sobre os graus ao lado:

lambdamart-choices-on-train.py Python 3.12.15 · bm25s 0.3.16 · lightgbm 4.7.0 · numpy 2.5.5 · pandas 3.1.1 · pystemmer 3.1.0 · scikit-learn 1.9.1 · scipy 1.18.1 Aprovado
"""Compares three ways of training on the train queries, each by cross-validation: LambdaRank with unjudged candidates as 0,LambdaRank on judged candidates only, and pointwise regression. The prose's point rests on the differences and thepermutation p-values printed under each setup."""from lightgbm import LGBMRanker, LGBMRegressorfrom lib.metrics import evaluatefrom lib.ranking import DETERMINISTIC, FEATURES, LAMBDARANK, TREES, cross_validate, feature_tablefrom lib.semantic import SemanticSearchfrom lib.significance import comparefrom lib.store import load_products, load_queries, qrelsqueries, judgments = load_queries("train"), qrels("train")          # tuning: train queries onlycandidates = feature_table(load_products(), queries)candidates["grade or 0"] = candidates["grade"].fillna(0).astype(int)  # unjudged counts as irrelevant# the rows the model learns from when unjudged candidates are left out; it still ranks every candidate at query timejudged_only = candidates.dropna(subset=["grade"]).astype({"grade": int})setups = {                                                          # (model, rows it learns from, label)    "lambdarank, unjudged as 0": (lambda: LGBMRanker(**LAMBDARANK, **TREES, **DETERMINISTIC), candidates, "grade or 0"),    "lambdarank, unjudged left out": (lambda: LGBMRanker(**LAMBDARANK, **TREES, **DETERMINISTIC), judged_only, "grade"),    "pointwise regression, unjudged as 0": (lambda: LGBMRegressor(**TREES, **DETERMINISTIC), candidates, "grade or 0"),}semantic = evaluate(SemanticSearch().run(queries, k=100), judgments)["ndcg@10"]print(f"semantic, train ndcg@10: {semantic.mean():.3f}")scores = {name: cross_validate(model, rows, candidates, label, FEATURES, judgments)          for name, (model, rows, label) in setups.items()}chosen = scores["lambdarank, unjudged as 0"]for name, per_query in scores.items():    print(f"{name}, cross-validated ndcg@10: {per_query.mean():.3f}")    if name != "lambdarank, unjudged as 0":        # the mean difference is the first argument minus the second, tested by permutation over the queries        result = compare(per_query, chosen)        print(f"{name}, minus the first: {result['mean difference']:.3f}")        print(f"{name}, minus the first, permutation p: {result['permutation p']:.3f}")result = compare(chosen, semantic)print(f"first setup minus semantic: {result['mean difference']:.3f}")print(f"first setup minus semantic, permutation p: {result['permutation p']:.3f}")
Saídapython lambdamart-choices-on-train.py
semantic, train ndcg@10: 0.772
lambdarank, unjudged as 0, cross-validated ndcg@10: 0.798
lambdarank, unjudged left out, cross-validated ndcg@10: 0.733
lambdarank, unjudged left out, minus the first: -0.064
lambdarank, unjudged left out, minus the first, permutation p: 0.005
pointwise regression, unjudged as 0, cross-validated ndcg@10: 0.769
pointwise regression, unjudged as 0, minus the first: -0.029
pointwise regression, unjudged as 0, minus the first, permutation p: 0.007
first setup minus semantic: 0.026
first setup minus semantic, permutation p: 0.242

Contar candidatos não julgados como 0 pontua mais do que deixá-los de fora, 0.798 contra 0.733, uma diferença de -0.064 com valor-p de permutação de 0.005. Um modelo que nunca vê um candidato não julgado no treino ainda precisa ranqueá-lo, e as features dizem que eles se parecem com produtos irrelevantes.

A regressão pontual pontua 0.769, uma diferença de -0.029 (p = 0.007), então, nas consultas de treino da loja, uma verificação de ajuste contra um modelo pontual favorece o LambdaMART.

Em relação ao 0.772 da recuperação semântica, a configuração escolhida difere por 0.026, com valor-p de permutação de 0.242: mesmo nas consultas que a escolheram, ela não mostra nenhum ganho que as consultas de treino consigam distinguir do acaso.

Regra prática: Ordene as linhas por consulta e passe group, defina label_gain com os ganhos que sua métrica usa, pare cedo em consultas de treino reservadas por meio de eval_X e eval_y, e fixe a semente e o número de threads. Ordene os candidatos de cada consulta por ID de produto, como o capítulo 3 recomenda, e desfaça empates de pontuação da mesma forma. Conte candidatos não julgados como grau 0, a menos que a validação cruzada nas consultas de treino indique o contrário. Com poucas consultas julgadas, teste árvores pequenas.

Relatório do LambdaMART nas consultas de teste

Última alteração na edição 2026.11.10

Um modelo ajustado nas consultas de treino é relatado uma única vez nas consultas de teste, por meio de uma comparação planejada antes de se olhar os resultados. Importância de atributos mostra o que um modelo aprendeu: a importância "gain" do LightGBM é o "total de ganhos das divisões que usam o atributo" (Booster), então um atributo sem ganho não tem papel algum na pontuação.

A primeira comparação planejada usa a configuração escolhida no treino: LambdaMART com todos os atributos, com 3 folhas e taxa de aprendizado de 0.1, candidatos não avaliados como nota 0 e candidatos na ordem de product_id. Ele se ajusta a 40 consultas de treino, interrompe o treino antecipadamente em 10 outras e ordena os candidatos de cada consulta de teste. Um ganho precisa de um valor-p de permutação abaixo de 0.01:

lambdamart-on-test.py Python 3.12.15 · bm25s 0.3.16 · lightgbm 4.7.0 · numpy 2.5.5 · pandas 3.1.1 · pystemmer 3.1.0 · scikit-learn 1.9.1 · scipy 1.18.1 Aprovado
"""Fits LambdaMART on the train queries with the chosen setup, reports its early stopping and gain shares, then reports itsplanned comparison on the test queries against semantic retrieval. The prose's point rests on that comparison's permutationp-value, printed last, against the threshold printed first."""from lightgbm import LGBMRankerfrom lib.metrics import evaluatefrom lib.ranking import (DETERMINISTIC, FEATURES, LAMBDARANK, PLANNED_TEST_COMPARISONS, THRESHOLD, TREES, feature_table,                         fit, ranked, report_planned, stopping_split)from lib.semantic import SemanticSearchfrom lib.store import load_products, load_queries, qrelsproducts, train, test = load_products(), load_queries("train"), load_queries("test")print(f"planned test comparisons: {len(PLANNED_TEST_COMPARISONS)}")print(f"p-value threshold: {THRESHOLD:.2f}")table = feature_table(products, train)table["grade or 0"] = table["grade"].fillna(0).astype(int)            # the setup chosen on train# 10 train queries are held out, at random with a fixed seed, to stop onfit_ids, stop_ids = stopping_split(train.index)model = fit(LGBMRanker(**LAMBDARANK, **TREES, **DETERMINISTIC), table, "grade or 0", FEATURES, fit_ids, stop_ids)print(f"queries fitted: {len(fit_ids)}\nqueries held out for stopping: {len(stop_ids)}")curve = model.evals_result_["valid_0"]["ndcg@10"]                     # LightGBM's nDCG@10, one value per treeprint(f"trees tried: {len(curve)}\ntrees kept by early stopping: {model.best_iteration_}")print(f"stopping queries' ndcg@10, first tree: {curve[0]:.3f}")# best_iteration_ counts trees from 1 and the curve from 0, so the last tree kept is at index best_iteration_ - 1print(f"stopping queries' ndcg@10, trees kept: {curve[model.best_iteration_ - 1]:.3f}")gain = model.booster_.feature_importance(importance_type="gain")      # total gain of the splits on each feature# a feature with no gain was never split on, so it plays no part in the scoreprint(f"features the trees use: {(gain > 0).sum()} of {len(FEATURES)}")for name, share in sorted(zip(FEATURES, gain / gain.sum()), key=lambda pair: -pair[1]):    print(f"share of gain, {name}: {share:.3f}")candidates, judgments = feature_table(products, test), qrels("test")   # test queries: read once, to reportafter = evaluate(ranked(candidates, model.predict(candidates[FEATURES])), judgments)before = evaluate(SemanticSearch().run(test, k=100), judgments)for name, frame in [("semantic", before), ("lambdamart", after)]:    print(f"{name}, test ndcg@10: {frame['ndcg@10'].mean():.3f}")    print(f"{name}, test judged@10: {frame['judged@10'].mean():.3f}")    # each query's top 10 is 10 places, so (1 - judged@10) times 10 counts its unjudged places    print(f"{name}, unjudged places in the test top 10s: {round((1 - frame['judged@10']).sum() * 10)}")report_planned("lambdamart", after["ndcg@10"], before["ndcg@10"])
Saídapython lambdamart-on-test.py
planned test comparisons: 5
p-value threshold: 0.01
queries fitted: 40
queries held out for stopping: 10
trees tried: 243
trees kept by early stopping: 213
stopping queries' ndcg@10, first tree: 0.568
stopping queries' ndcg@10, trees kept: 0.794
features the trees use: 8 of 8
share of gain, cross_encoder: 0.641
share of gain, similarity: 0.172
share of gain, name_match: 0.097
share of gain, bm25: 0.043
share of gain, review_count: 0.021
share of gain, rating_count: 0.021
share of gain, attribute_match: 0.002
share of gain, average_rating: 0.001
semantic, test ndcg@10: 0.830
semantic, test judged@10: 0.990
semantic, unjudged places in the test top 10s: 3
lambdamart, test ndcg@10: 0.817
lambdamart, test judged@10: 0.990
lambdamart, unjudged places in the test top 10s: 3
lambdamart, mean difference: -0.012
lambdamart, wins, losses, ties: 14, 12, 4
lambdamart, permutation p: 0.260
lambdamart, established at 0.01: no
lambdamart, t-test p: 0.278
lambdamart, t-test agrees: yes
lambdamart, 99% interval: -0.044 to 0.011
lambdamart, interval agrees: yes

De 243 árvores testadas, a parada antecipada mantém 213. Nas consultas reservadas para a parada, o nDCG@10 próprio do LightGBM, cujo ideal vem apenas dos candidatos dessas consultas, sobe de 0.568 após a primeira árvore para 0.794 nas árvores mantidas.

As árvores usam 8 of 8 atributos, mas se apoiam no cross-encoder, que responde por 0.641 do ganho, à frente de similarity com 0.172, name_match com 0.097 e bm25 com 0.043. Portanto, colocar o modelo em produção significa uma chamada ao cross-encoder para cada candidato.

O LambdaMART não estabelece ganho nas consultas de teste: ele obtém nDCG@10 de 0.817, contra 0.830 da recuperação semântica, com valor-p de permutação de 0.260 (todas as cinco comparações). Judged@10 é 0.990 para o LambdaMART e 0.990 para a recuperação semântica.

Regra prática: Adote um ranqueador aprendido somente quando sua comparação planejada no teste estiver estabelecida. Leia sua importância por ganho antes de confiar nele, porque os atributos dos quais ele depende são os que você pagará no momento da consulta. A parada antecipada em poucas consultas reservadas faz com que números de árvores muito diferentes sejam mantidos de uma divisão para outra, de 99, 20, 8, 43, 38 entre as dobras da validação cruzada a 213 aqui. Uma regra prática, não uma medida: com tão poucas consultas, avalie mais consultas antes de ajustar mais, e trate qualquer ponto de parada isolado como ruído.

Reordene a recuperação semântica com um cross-encoder

Última alteração na edição 2026.11.10

A recuperação semântica usa um modelo de embeddings, também chamado de bi-encoder, que lê a consulta e cada produto separadamente, de modo que os embeddings dos produtos são calculados antecipadamente. Um cross-encoder lê a consulta e um produto juntos e produz uma pontuação (Nogueira e Cho, 2019). Ele pode relacionar cada palavra da consulta com cada palavra do produto, e isso tem um custo. Ele costuma ser mais lento do que um modelo Sentence Transformer, porque calcula para cada par e não para cada texto, e por isso "Cross Encoders costumam ser usados para reordenar os resultados top-k" (Sentence Transformers). O cross-encoder da loja (veja a abertura) é pequeno para um modelo de linguagem, com 149M de parâmetros (ficha do modelo). Trata-se do modelo aberto Alibaba-NLP/gte-reranker-modernbert-base, cujo manifesto, o arquivo salvo com sua gravação, indica a licença como Apache-2.0. Escolhemos esse modelo porque qualquer pessoa pode baixá-lo e executar novamente a gravação. recordings/cross_encoder.py pontuou a união dos 100 primeiros resultados do BM25 e da recuperação semântica para cada consulta (em duas consultas, sua lista semântica difere da de lib.semantic por um quase empate na 100ª posição).

O capítulo 1 reordenou a execução híbrida. Aqui o cross-encoder reordena o ranqueador a ser superado, o top 20 da recuperação semântica: os mesmos produtos que os rerankers de LLM leram, de modo que os três rerankers do capítulo partem de listas idênticas. O capítulo fixou essa profundidade antes de qualquer resultado de teste e não a ajusta. Reordene os 20 primeiros pelas pontuações registradas e mantenha o restante no lugar. Essa é a segunda comparação planejada, que exige um p-valor abaixo de 0.01:

cross-encoder-on-semantic.py Python 3.12.15 · bm25s 0.3.16 · lightgbm 4.7.0 · numpy 2.5.5 · pandas 3.1.1 · pystemmer 3.1.0 · scikit-learn 1.9.1 · scipy 1.18.1 Aprovado
"""Reranks semantic retrieval's top 20 with the recorded cross-encoder scores, and compares the two on the test queries.The prose's point rests on the planned comparison's permutation p-value, and on the judged@10 lines, which show what thererank does to the judgments it can score."""from lib.metrics import evaluatefrom lib.ranking import DEPTH, rerank, report_plannedfrom lib.recorded import cross_encoder_scores, llm_listwise, manifestfrom lib.semantic import SemanticSearchfrom lib.store import load_queries, qrelsqueries, judgments = load_queries("test"), qrels("test")       # scored on the human judgmentssemantic = SemanticSearch().run(queries, k=100)recorded = cross_encoder_scores()# the recorded score of each (query, product) pairscore = dict(zip(zip(recorded["query_id"], recorded["product_id"]), recorded["score"]))print("cross-encoder model:", manifest("cross-encoder")["model"])print("licence in the manifest:", manifest("cross-encoder")["model_licence"])# the set of products the LLM was shown for each query, from the listwise recordingshown = llm_listwise().groupby("query_id")["product_id"].apply(set)  # what the LLM rerankers sawsame = sum(set(semantic[query_id][:DEPTH]) == shown[query_id] for query_id in queries.index)print(f"rerank depth: {DEPTH}")print(f"queries whose top {DEPTH} holds the products the llm rerankers saw: {same} of {len(queries)}")reranked = rerank(semantic, score, DEPTH)                       # top 20 reordered, the rest in placebefore, after = evaluate(semantic, judgments), evaluate(reranked, judgments)for name, frame in [("semantic", before), ("cross-encoder", after)]:    print(f"{name}, test ndcg@10: {frame['ndcg@10'].mean():.3f}")    print(f"{name}, test judged@10: {frame['judged@10'].mean():.3f}")    print(f"{name}, unjudged places in the test top 10s: {round((1 - frame['judged@10']).sum() * 10)}")# index 0 is the first placemoved = sum(reranked[query_id][0] != semantic[query_id][0] for query_id in queries.index)print(f"queries whose first product changes: {moved}")report_planned("cross-encoder", after["ndcg@10"], before["ndcg@10"])
Saídapython cross-encoder-on-semantic.py
cross-encoder model: Alibaba-NLP/gte-reranker-modernbert-base
licence in the manifest: Apache-2.0
rerank depth: 20
queries whose top 20 holds the products the llm rerankers saw: 30 of 30
semantic, test ndcg@10: 0.830
semantic, test judged@10: 0.990
semantic, unjudged places in the test top 10s: 3
cross-encoder, test ndcg@10: 0.813
cross-encoder, test judged@10: 0.983
cross-encoder, unjudged places in the test top 10s: 5
queries whose first product changes: 23
cross-encoder, mean difference: -0.016
cross-encoder, wins, losses, ties: 11, 12, 7
cross-encoder, permutation p: 0.178
cross-encoder, established at 0.01: no
cross-encoder, t-test p: 0.171
cross-encoder, t-test agrees: yes
cross-encoder, 99% interval: -0.058 to 0.006
cross-encoder, interval agrees: yes

Reordenar os 20 primeiros não estabelece um ganho: a reordenação pontua 0.813 contra 0.830, com p-valor de permutação de 0.178 (veja a tabela de decisões). Os 20 primeiros contêm os produtos que os rerankers de LLM viram para 30 of 30 consultas de teste, e o reranker muda o primeiro produto em 23 delas.

Judged@10 cai de 0.990 para 0.983, e as posições não julgadas nos 10 primeiros do teste passam de 3 para 5.

Nas consultas de treino, a mesma reordenação pontua 0.802 contra 0.772 da recuperação semântica (varredura de profundidade). As consultas de treino são outra amostra, e seu veredito repete o que o capítulo 3 encontrou: a ordem de dois ranqueadores próximos pode se inverter entre conjuntos de consultas.

Regra prática: Reordene sua recuperação mais forte, com uma profundidade fixada antes de você olhar os resultados de teste, e adote o reranker somente diante de um ganho comprovado em consultas reservadas. O cross-encoder de uso geral da loja fica fora do pipeline.

Pontue cada produto com um LLM

Última alteração na edição 2026.11.10

Um LLM também pode reordenar, de três maneiras. Pontual, um LLM julga cada produto isoladamente e devolve um rótulo ou uma pontuação. Par a par, um LLM diz qual de dois produtos se adequa melhor à consulta. Por lista, um LLM ordena uma lista inteira em uma única resposta (Qin et al., 2024). Em um estudo, com oito conjuntos de dados do BEIR, uma coleção de benchmarks de recuperação usada para testar modelos em dados com os quais eles não foram treinados, prompts pontuais tiveram melhor desempenho com respostas graduadas do que com sim ou não, porque "a falta de opções intermediárias de rótulo de relevância pode levar o LLM a dar respostas ruidosas ou enviesadas" (Zhuang et al., 2024a).

O LLM da loja, o modelo aberto citado na abertura do capítulo, viu a consulta e um produto por vez: nome, classe, categoria, descrição e atributos (o que o LLM viu). O prompt pede um rótulo, exact, partial ou irrelevant, e "uma pontuação de 0 a 100 para o grau de correspondência". Reordene os 20 primeiros de recuperação semântica por essa pontuação; quando dois produtos empatam, eles mantêm a ordem da recuperação semântica, regra fixada junto com a gravação. Essa reordenação é a terceira comparação planejada, com p-valor abaixo de 0.01:

llm-pointwise-rerank.py Python 3.12.15 · bm25s 0.3.16 · lightgbm 4.7.0 · numpy 2.5.5 · pandas 3.1.1 · pystemmer 3.1.0 · scikit-learn 1.9.1 · scipy 1.18.1 Aprovado
"""Reads the pointwise LLM's answers for the test queries, one call per product, and reranks semantic retrieval's top 20 bytheir scores. The prose's point rests on the distinct-scores line, which shows how coarse the scores are, and on theplanned comparison's p-value."""from lib.metrics import evaluatefrom lib.ranking import DEPTH, rerank, report_plannedfrom lib.recorded import llm_pointwise, manifestfrom lib.semantic import SemanticSearchfrom lib.store import load_queries, qrelsqueries, judgments = load_queries("test"), qrels("test")       # scored on the human judgments, not the LLM'ssemantic = SemanticSearch().run(queries, k=100)answers = llm_pointwise()                                       # one call per product: a label and a scoreprint("llm:", manifest("llm-rerank")["model"])print("licence in the manifest:", manifest("llm-rerank")["model_licence"])print(f"calls per query: {len(answers) // answers['query_id'].nunique()}")print(f"answers without a score: {answers['score'].isna().sum()}")print(f"distinct scores per query, median: {answers.groupby('query_id')['score'].nunique().median():.0f}")print(f"share of products scored 100: {(answers['score'] == 100).mean():.3f}")# each answered product's human grade, or missing when nobody judged itpeople = answers.apply(lambda row: judgments[row["query_id"]].get(row["product_id"]), axis=1)# grades 2, 1 and 0 are exact, partial and irrelevant, the labels the LLM was asked forfor label, grade in [("exact", 2), ("partial", 1), ("irrelevant", 0)]:    print(f"products the llm labels {label}: {(answers['label'] == label).sum()}")    print(f"products people judged {label}: {(people == grade).sum()}")print(f"products nobody judged: {people.isna().sum()}")score = dict(zip(zip(answers["query_id"], answers["product_id"]), answers["score"]))reranked = rerank(semantic, score, DEPTH)                       # equal scores keep semantic retrieval's ordercounts = answers.groupby("query_id")["score"].value_counts()          # products per score, for each queryshared = {query_id: sum(counts[(query_id, score[(query_id, product_id)])] > 1 for product_id in reranked[query_id][:10])          for query_id in queries.index}                                # top-10 products that share their score# more than 5 of the top 10 share a score: most of the list is decided by the tie-breakprint(f"queries where most of the reranked top 10 shares its score: {sum(n > 5 for n in shared.values())}")before, after = evaluate(semantic, judgments), evaluate(reranked, judgments)for name, frame in [("semantic", before), ("llm pointwise", after)]:    print(f"{name}, test ndcg@10: {frame['ndcg@10'].mean():.3f}")    print(f"{name}, test judged@10: {frame['judged@10'].mean():.3f}")    print(f"{name}, unjudged places in the test top 10s: {round((1 - frame['judged@10']).sum() * 10)}")report_planned("llm pointwise", after["ndcg@10"], before["ndcg@10"])
Saídapython llm-pointwise-rerank.py
llm: gemma4:12b-it-q4_K_M
licence in the manifest: Apache-2.0
calls per query: 20
answers without a score: 0
distinct scores per query, median: 4
share of products scored 100: 0.390
products the llm labels exact: 251
products people judged exact: 310
products the llm labels partial: 345
products people judged partial: 265
products the llm labels irrelevant: 4
products people judged irrelevant: 7
products nobody judged: 18
queries where most of the reranked top 10 shares its score: 30
semantic, test ndcg@10: 0.830
semantic, test judged@10: 0.990
semantic, unjudged places in the test top 10s: 3
llm pointwise, test ndcg@10: 0.837
llm pointwise, test judged@10: 0.983
llm pointwise, unjudged places in the test top 10s: 5
llm pointwise, mean difference: 0.008
llm pointwise, wins, losses, ties: 11, 8, 11
llm pointwise, permutation p: 0.241
llm pointwise, established at 0.01: no
llm pointwise, t-test p: 0.244
llm pointwise, t-test agrees: yes
llm pointwise, 99% interval: -0.007 to 0.026
llm pointwise, interval agrees: yes

A gravação fez 20 chamadas por consulta, e 0 respostas voltaram sem pontuação. As pontuações são grosseiras. A consulta mediana recebe 4 pontuações distintas para os seus 20 produtos, e uma parcela de 0.390 de todos os produtos recebe 100. Em 30 consultas, a maioria dos 10 primeiros reordenados divide sua pontuação com outro produto, então o desempate, a ordem da recuperação semântica, decide grande parte da lista.

Com este prompt, nessas listas, o LLM classifica como exact menos produtos do que as pessoas:

Rótulo LLM Pessoas
exact 251 310
partial 345 265
irrelevant 4 7
ninguém avaliou – 18

Nessas listas isso se confirma, mas o capítulo 4 mostra que o sentido da discordância de um LLM com as pessoas muda conforme os pares avaliados e o prompt, então não leve este resultado para outros casos.

A reordenação pontual também não comprova ganho: ela pontua 0.837 contra 0.830, com p-valor de permutação de 0.241 (veja a tabela de decisões).

A ordem do LLM coloca mais produtos não avaliados nos 10 primeiros: 5 posições em vez de 3, e o judged@10 cai de 0.990 para 0.983.

Regra prática: Se você reordenar de forma pontual com um LLM, peça um rótulo graduado ou uma pontuação, conte as pontuações distintas que ele dá por consulta e decida o desempate com antecedência: a ordem da recuperação é um padrão seguro. Avalie o resultado com julgamentos humanos, nunca com as notas do mesmo LLM.

Ordene os 20 produtos com um prompt de LLM

Última alteração na edição 2026.11.8

A terceira forma, um prompt listwise, numera os candidatos e pede ao LLM que devolva os números em ordem de relevância. O RankGPT introduziu isso como geração de permutações (Sun et al., 2023). Um prompt comporta apenas certa quantidade de produtos, então uma lista longa é reordenada em uma janela deslizante: o RankGPT reordena os 100 primeiros do BM25 com "um tamanho de janela de 20 e um tamanho de passo de 10", de baixo para cima da lista (seções 3.2 e 6.1). A resposta precisa ser uma ordenação válida, e isso pode falhar: com LLMs de porte moderado de 2023, como o Flan-UL2, de 20 bilhões de parâmetros, prompts listwise quase sempre falham, por rankings ausentes, repetidos ou recusados (Qin et al., 2024).

O LLM da loja viu 20 produtos por prompt, uma janela. O prompt mostra cada produto em uma linha curta: nome, classe, atributos e os primeiros 160 caracteres da descrição. Sua última instrução diz: "Order all 20 products from the best match for the query to the worst. Return the product numbers, each exactly once, in JSON." O esquema JSON exige exatamente 20 números, mas não 20 números diferentes, então o registro corrige qualquer resposta com número repetido ou ausente e a sinaliza. Reordene os 20 primeiros da recuperação semântica pela resposta que o LLM deu quando os viu na ordem semântica. Essa reordenação é a quarta comparação planejada, com p-valor abaixo de 0.01:

llm-listwise-rerank.py Python 3.12.15 · bm25s 0.3.16 · lightgbm 4.7.0 · numpy 2.5.5 · pandas 3.1.1 · pystemmer 3.1.0 · scikit-learn 1.9.1 · scipy 1.18.1 Aprovado
"""Reads the listwise LLM's answers for the test queries, in both orders, and reranks semantic retrieval's top 20 by theanswer given in semantic order. The prose's point rests on the planned comparison's p-value, and on the repair count,which shows how many answers needed a fix."""from lib.metrics import evaluatefrom lib.ranking import DEPTH, report_plannedfrom lib.recorded import llm_listwise, manifestfrom lib.semantic import SemanticSearchfrom lib.store import load_queries, qrelsqueries, judgments = load_queries("test"), qrels("test")       # scored on the human judgments, not the LLM'ssemantic = SemanticSearch().run(queries, k=100)answers = llm_listwise()                                        # one call per query and order shown# the answers hold one row per product, so keep one row per call: one call per query and ordercalls = answers.drop_duplicates(["query_id", "order"])print(f"listwise calls, both orders: {len(calls)}")# valid is false where the recording repaired a repeated or missing numberprint(f"answers that needed repair: {(~calls['valid']).sum()}")print(f"products per call: {answers.groupby(['query_id', 'order']).size().max()}")print("prompt asks for:", manifest("llm-rerank")["prompts"]["listwise"].splitlines()[-1].replace("{n}", str(DEPTH)))shown_in_semantic_order = answers[answers["order"] == "semantic"].sort_values(["query_id", "position"])order = shown_in_semantic_order.groupby("query_id")["product_id"].apply(list)# the reranked top 20, then the rest of semantic retrieval's list in place: ranking[DEPTH:] starts at the 21st productreranked = {query_id: order[query_id] + ranking[DEPTH:] for query_id, ranking in semantic.items()}before, after = evaluate(semantic, judgments), evaluate(reranked, judgments)for name, frame in [("semantic", before), ("llm listwise", after)]:    print(f"{name}, test ndcg@10: {frame['ndcg@10'].mean():.3f}")    print(f"{name}, test judged@10: {frame['judged@10'].mean():.3f}")    print(f"{name}, unjudged places in the test top 10s: {round((1 - frame['judged@10']).sum() * 10)}")moved = sum(reranked[query_id][0] != semantic[query_id][0] for query_id in queries.index)print(f"queries whose first product changes: {moved}")report_planned("llm listwise", after["ndcg@10"], before["ndcg@10"])
Saídapython llm-listwise-rerank.py
listwise calls, both orders: 60
answers that needed repair: 0
products per call: 20
prompt asks for: Order all 20 products from the best match for the query to the worst. Return the product numbers, each exactly once, in JSON.
semantic, test ndcg@10: 0.830
semantic, test judged@10: 0.990
semantic, unjudged places in the test top 10s: 3
llm listwise, test ndcg@10: 0.819
llm listwise, test judged@10: 0.983
llm listwise, unjudged places in the test top 10s: 5
queries whose first product changes: 19
llm listwise, mean difference: -0.010
llm listwise, wins, losses, ties: 12, 12, 6
llm listwise, permutation p: 0.580
llm listwise, established at 0.01: no
llm listwise, t-test p: 0.498
llm listwise, t-test agrees: yes
llm listwise, 99% interval: -0.070 to 0.016
llm listwise, interval agrees: yes

O registro fez 60 chamadas listwise, duas por consulta de teste, e 0 respostas precisaram de correção. A reordenação altera o primeiro produto de 19 consultas.

O ganho da reordenação listwise não está comprovado: ela obtém 0.819 contra 0.830, com p-valor de permutação de 0.580 (todas as cinco comparações).

O Judged@10 também cai aqui, de 0.990 para 0.983, com 5 posições sem julgamento, onde a recuperação semântica tem 3.

Regra prática: Verifique toda resposta listwise antes de usá-la: conte os números ausentes, repetidos e desconhecidos, e registre quantas respostas precisaram de correção. Restrinja o formato da resposta com um esquema quando seu ambiente de execução o suportar. Fixe a janela, o passo e a ordem em que você mostra os produtos antes de medir, porque a ordem altera a resposta, como mostra a próxima verificação.

Inverta a entrada para medir o viés posicional

Última alteração na edição 2026.11.10

Uma resposta listwise pode sofrer de viés posicional: a tendência de um LLM deixar que a posição de um produto no prompt afete o seu ranking, em vez de refletir o viés de posição dos cliques dos compradores. "Modelos de linguagem de grande porte (LLMs) exibem viés posicional na forma como usam o contexto, o que torna o ranking listwise especialmente difícil" (Tang et al., 2024). No TREC DL19, as consultas de 2019 da trilha de Deep Learning do TREC, um benchmark de ranking de passagens, o gpt-3.5-turbo reordenou os 100 primeiros resultados do BM25 e obteve nDCG@10 de 65.80 quando recebeu a ordem do BM25, 32.77 quando a recebeu invertida e 25.17 quando recebeu uma ordem aleatória (Sun et al., 2023, Tabela 5). A verificação direta é mostrar os mesmos produtos em duas ordens e comparar as respostas. O tau de Kendall mede o quanto duas ordenações são parecidas, de 1 para a mesma ordem a −1 para a inversa, contando os pares que elas colocam na mesma ordem relativa (capítulo 4).

A gravação enviou o prompt listwise de cada consulta de teste ao mesmo LLM duas vezes. O primeiro prompt mostrou os 20 primeiros da recuperação semântica na ordem semântica, como usava o reranqueamento listwise; o segundo os mostrou invertidos. Entre as 30 consultas de teste, com que frequência o LLM colocará o mesmo produto em primeiro lugar nas duas vezes? Anote o seu número.

listwise-position-bias.py Python 3.12.15 · bm25s 0.3.16 · lightgbm 4.7.0 · numpy 2.5.5 · pandas 3.1.1 · pystemmer 3.1.0 · scikit-learn 1.9.1 · scipy 1.18.1 Aprovado
"""Shows the listwise LLM the same test products in two orders, and measures how far its answers agree and how far eachanswer follows the order it was shown. The prose's point rests on the mean tau between the two answers, and on the twotaus between each answer and its own input order."""import numpy as npfrom scipy.stats import kendalltaufrom lib.metrics import evaluatefrom lib.ranking import DEPTHfrom lib.recorded import llm_listwisefrom lib.semantic import SemanticSearchfrom lib.store import load_queries, qrelsqueries, judgments = load_queries("test"), qrels("test")semantic = SemanticSearch().run(queries, k=DEPTH)               # the order the first prompt showedanswers = llm_listwise().sort_values(["query_id", "order", "position"])# the products in the order the LLM returned them, for each query and each order shownanswer = {key: list(group["product_id"]) for key, group in answers.groupby(["query_id", "order"])}def tau(first: list, second: list) -> float:    """Kendall's tau between two orderings of the same products."""    place = {product_id: rank for rank, product_id in enumerate(second)}    # each product's place in the second ordering    # the first ordering's positions, against where the second ordering puts each product    return kendalltau(range(len(first)), [place[product_id] for product_id in first]).statisticbetween, shown_semantic, shown_reversed, overlap, same_first = [], [], [], [], 0for query_id, shown in semantic.items():    forward, backward = answer[(query_id, "semantic")], answer[(query_id, "reversed")]    between.append(tau(forward, backward))    shown_semantic.append(tau(forward, shown))    shown_reversed.append(tau(backward, shown[::-1]))     # the reversed input, as the second prompt showed it    overlap.append(len(set(forward[:10]) & set(backward[:10])))    same_first += forward[0] == backward[0]               # index 0 is the first placeprint(f"test queries: {len(semantic)}")print(f"tau between the two answers, mean: {np.mean(between):.3f}")print(f"tau between the two answers, lowest: {min(between):.3f}\ntau between the two answers, highest: {max(between):.3f}")print(f"top-10 products in common, mean: {np.mean(overlap):.3f}")print(f"top-10 products in common, fewest: {min(overlap)}")print(f"queries with the same first product: {same_first}")print(f"share of queries with the same first product: {same_first / len(semantic):.3f}")print(f"tau between the order shown and the answer, semantic order: {np.mean(shown_semantic):.3f}")print(f"tau between the order shown and the answer, reversed order: {np.mean(shown_reversed):.3f}")# an answer that ignored the order would repeat itself, so its tau with the reversed input is minus its tau with the semantic orderprint(f"the same, if the order shown made no difference: {-np.mean(shown_semantic):.3f}")reversed_run = {query_id: answer[(query_id, "reversed")] for query_id in semantic}print(f"reversed answer, test ndcg@10, not a planned comparison: {evaluate(reversed_run, judgments)['ndcg@10'].mean():.3f}")
Saídapython listwise-position-bias.py
test queries: 30
tau between the two answers, mean: 0.311
tau between the two answers, lowest: -0.484
tau between the two answers, highest: 0.811
top-10 products in common, mean: 6.967
top-10 products in common, fewest: 3
queries with the same first product: 13
share of queries with the same first product: 0.433
tau between the order shown and the answer, semantic order: 0.414
tau between the order shown and the answer, reversed order: 0.045
the same, if the order shown made no difference: -0.414
reversed answer, test ndcg@10, not a planned comparison: 0.826

O mesmo produto fica em primeiro lugar em 13 das 30 consultas; assim, a expectativa de que um modelo capaz encontre a mesma melhor correspondência, qualquer que seja a ordem da lista, vale apenas para uma parcela de 0.433 das consultas.

As duas respostas concordam com um tau médio de 0.311, e, por consulta, o tau vai de -0.484 a 0.811. Seus top 10 compartilham, em média, 6.967 produtos, chegando a apenas 3.

As respostas também tendem para a ordem apresentada. O tau de cada resposta em relação à sua própria ordem de entrada é 0.414 para a ordem semântica e 0.045 para a invertida. Um LLM que ignorasse a ordem daria a mesma resposta nas duas vezes; assim, sua resposta invertida teria um tau de -0.414 em relação à entrada invertida. A resposta invertida fica bem mais próxima da sua própria ordem de entrada do que isso: viés posicional, para este modelo, este prompt e estas consultas. A resposta invertida obtém nDCG@10 de 0.826; não se trata de uma comparação planejada, por isso o capítulo não a testa.

Existem três remédios. O prompting de ranqueamento par a par pergunta ao LLM sobre cada par duas vezes, uma em cada ordem, e conta uma discordância como empate (Qin et al., 2024). A autoconsistência por permutação reordena o ranking a partir de várias ordens embaralhadas e agrega as respostas, o que elevou as pontuações em até 7 a 18% para o GPT-3.5 e 8 a 16% para o LLaMA v2 (70B) (Tang et al., 2024). Já os rerankers ajustados por fine-tuning para ranking listwise, como o RankZephyr, de código aberto, são relatados como "resilientes a variações na ordenação inicial dos documentos" (Pradeep et al., 2023); a loja não registrou nenhum.

Regra prática: Antes de confiar em um reranqueador listwise baseado em LLM, execute cada consulta em pelo menos duas ordens e informe o quanto as respostas concordam. Quando a concordância for baixa, agregue várias ordens ou pergunte sobre cada par nas duas ordens, e conte essas chamadas contra o seu orçamento. Em produção, mostre os produtos sempre na ordem da recuperação, para que a mesma lista receba, no mínimo, a mesma resposta.

Defina a profundidade de reranqueamento a partir de um orçamento

Última alteração na edição 2026.11.8

Um pipeline de busca roda em etapas, cada uma mais lenta e com menos candidatos que a anterior, e cada reranqueador deste capítulo acrescenta uma. Rankers de múltiplos estágios oferecem "a capacidade de equilibrar qualidade e latência controlando a admissão de candidatos em cada etapa do pipeline" (Nogueira et al., 2019). Assim, a profundidade de reranqueamento, ou seja, quantos produtos o reranqueador lê por consulta, é uma decisão de orçamento. Os tempos variam com o hardware e com as escolhas de execução (Peng et al., 2025), então esta seção conta o que os determina: chamadas ao modelo e o texto que elas leem, por consulta, multiplicados pelo tamanho do modelo. O cross-encoder da loja tem 149M de parâmetros (cartão do modelo), e o LLM dela, cerca de 12 bilhões (cartão do modelo), uns 80 vezes mais.

Na profundidade 20, conte as chamadas ao modelo de cada reranqueador e os caracteres que ele lê por consulta de teste, a partir do texto dos produtos e dos prompts registrados, somando as chamadas de dois desenhos que a loja não registrou:

reranker-prompt-sizes.py Python 3.12.15 · bm25s 0.3.16 · lightgbm 4.7.0 · numpy 2.5.5 · pandas 3.1.1 · pystemmer 3.1.0 · scikit-learn 1.9.1 · scipy 1.18.1 Aprovado
"""Counts the characters each reranker reads per test query at depth 20, from the products' text and the recorded prompts,and the model calls each design makes. The prose's point rests on the characters and calls lines, and on the two designsthe store didn't record."""import numpy as npfrom lib.agreement import as_the_llm_sawfrom lib.ranking import DEPTH, listwise_linefrom lib.recorded import manifestfrom lib.semantic import SemanticSearchfrom lib.store import load_products, load_queries, product_textproducts, queries = load_products(), load_queries("test")semantic = SemanticSearch().run(queries, k=DEPTH)                # the 20 products each reranker readsprompts, text = manifest("llm-rerank")["prompts"], product_text(products)cross_encoder, pointwise, listwise = [], [], []                  # characters read per queryfor query_id, query in queries["query"].items():    shown = products.loc[semantic[query_id]]    # one call per product, each reading the query and that product's text together    cross_encoder.append(sum(len(query) + len(text[product_id]) for product_id in semantic[query_id]))    # the pointwise prompt, filled in with the query and the product as the LLM saw it    pointwise.append(sum(len(prompts["pointwise"].format(query=query, product=as_the_llm_saw(product)))                         for _, product in shown.iterrows()))    # products numbered from 1, as the listwise prompt shows them    lines = "\n".join(f"[{number}] {listwise_line(product)}" for number, (_, product) in enumerate(shown.iterrows(), 1))    listwise.append(len(prompts["listwise"].format(query=query, products=lines, n=DEPTH)))# the cross-encoder and the pointwise LLM make one call per product; the listwise LLM makes one call per queryfor name, calls, characters in [("cross-encoder", DEPTH, cross_encoder), ("llm pointwise", DEPTH, pointwise),                                ("llm listwise", 1, listwise)]:    print(f"{name}, model calls per query: {calls}")    print(f"{name}, characters read per query, mean: {np.mean(characters):,.0f}")print(f"llm pairwise, every pair in both orders, calls per query: {DEPTH * (DEPTH - 1)}")# a sliding window of 20 products, moved 10 at a time: its starts are list positions 0, 10, ..., 80window, step, depth = 20, 10, 100                                # a sliding window over a deeper listprint(f"llm listwise over the top {depth}, window {window}, step {step}, calls per query: {(depth - window) // step + 1}")
Saídapython reranker-prompt-sizes.py
cross-encoder, model calls per query: 20
cross-encoder, characters read per query, mean: 9,911
llm pointwise, model calls per query: 20
llm pointwise, characters read per query, mean: 17,864
llm listwise, model calls per query: 1
llm listwise, characters read per query, mean: 5,973
llm pairwise, every pair in both orders, calls per query: 380
llm listwise over the top 100, window 20, step 10, calls per query: 9
Reranqueador, top 20 Chamadas ao modelo por consulta Caracteres lidos por consulta
Cross-encoder 20 9,911
LLM, pointwise 20 17,864
LLM, listwise 1 5,973

O pointwise repete as instruções e mostra cada produto por inteiro, então lê o maior volume de texto, em chamadas independentes. O listwise lê o menos, em uma única chamada, mas precisa escrever 20 números em ordem. O prompting par a par sobre todos os pares nos dois sentidos exigiria 380 chamadas por consulta, e a janela deslizante do RankGPT sobre um top 100 exigiria 9. Em uma medição publicada no TREC DL19, reranqueando o top 100 do BM25 com Flan-T5-XL em uma GPU RTX A6000, o prompting pointwise de sim ou não atingiu 0.650 de nDCG@10 a 1.5 segundo por consulta, e o prompting par a par sobre todos os pares atingiu 0.713 em 254.9 segundos, com 9,900 chamadas ao LLM (Zhuang et al., 2024b). O LambdaMART com o cross-encoder como atributo precisa de uma pontuação do cross-encoder para cada candidato, uma mediana de 131 pares por consulta.

Para o cross-encoder, o custo cresce junto com a profundidade, então a pergunta é onde a qualidade deixa de crescer. Varie a profundidade nas consultas de treino:

rerank-depth-on-train.py Python 3.12.15 · bm25s 0.3.16 · lightgbm 4.7.0 · numpy 2.5.5 · pandas 3.1.1 · pystemmer 3.1.0 · scikit-learn 1.9.1 · scipy 1.18.1 Aprovado
"""Reranks semantic retrieval's top 5 to 75 with the recorded cross-encoder scores, on the train queries, and prints nDCG@10at each depth. The prose's point rests on the change from the depth before, which shows where the gain flattens and thenfalls."""from lib.metrics import evaluatefrom lib.ranking import rerankfrom lib.recorded import cross_encoder_scoresfrom lib.semantic import SemanticSearchfrom lib.store import load_queries, qrelsqueries, judgments = load_queries("train"), qrels("train")      # choosing a depth is tuning: train queriessemantic = SemanticSearch().run(queries, k=100)recorded = cross_encoder_scores()# the recorded cross-encoder score of each (query, product) pairscore = dict(zip(zip(recorded["query_id"], recorded["product_id"]), recorded["score"]))train_pairs = recorded[recorded["query_id"].isin(queries.index)]print(f"depth 0 (semantic alone), train ndcg@10: {evaluate(semantic, judgments)['ndcg@10'].mean():.3f}")previous = round(evaluate(semantic, judgments)["ndcg@10"].mean(), 3)     # changes between the printed valuesfor depth in [5, 10, 20, 30, 50, 75]:    mean = round(evaluate(rerank(semantic, score, depth), judgments)["ndcg@10"].mean(), 3)    print(f"depth {depth}, train ndcg@10: {mean:.3f}")    print(f"depth {depth}, change from the depth before: {mean - previous:+.3f}")    previous = mean# every candidate needs its own cross-encoder score, so this counts the recorded pairs per queryprint(f"pairs per query to score every candidate, median: {train_pairs.groupby('query_id').size().median():.0f}")
Saídapython rerank-depth-on-train.py
depth 0 (semantic alone), train ndcg@10: 0.772
depth 5, train ndcg@10: 0.782
depth 5, change from the depth before: +0.010
depth 10, train ndcg@10: 0.784
depth 10, change from the depth before: +0.002
depth 20, train ndcg@10: 0.802
depth 20, change from the depth before: +0.018
depth 30, train ndcg@10: 0.804
depth 30, change from the depth before: +0.002
depth 50, train ndcg@10: 0.793
depth 50, change from the depth before: -0.011
depth 75, train ndcg@10: 0.788
depth 75, change from the depth before: -0.005
pairs per query to score every candidate, median: 131

O ganho do cross-encoder se estabiliza entre 20 e 30, perto da profundidade fixada para coincidir com a gravação do LLM. Partindo do 0.772 da recuperação semântica sozinha, reranquear o top 5 dá 0.782, e o top 20, 0.802. O top 30 acrescenta +0.002 por metade a mais de pares. Além dele, a qualidade cai: 0.793 em 50 e 0.788 em 75.

Nas consultas de teste, o reranqueamento na profundidade 20 não comprovou ganho, então, para a loja, o reranqueador mais barato, que é nenhum, é também o que deve ser mantido.

Regra prática: Para cada reranqueador que você considerar, conte chamadas e caracteres por consulta em cada profundidade, e defina a profundidade nas consultas de treino. Trata-se de uma heurística, não de uma medição: reranqueie apenas até a profundidade em que o nDCG@10 de treino para de melhorar, porque cada produto além dela custa o mesmo e não acrescenta nada. Depois, meça essa configuração no seu próprio hardware e tráfego, e mantenha a etapa somente se ela couber no orçamento de latência.

Destile o cross-encoder em um ranqueador pequeno

Última alteração na edição 2026.11.10

Um reranqueador lento demais para o orçamento pode ensinar um rápido. Destilação treina um modelo pequeno, o aluno, para imitar um modelo grande, o professor. Hinton et al. descrevem como destilar o conhecimento de um ensemble em um único modelo (Hinton et al., 2015). Em ranqueamento, as pontuações do professor tornam-se os rótulos do aluno. Quando as pontuações dos dois modelos diferem em escala, como costuma acontecer com pontuações de arquiteturas diferentes, o aluno pode aprender a margem entre as pontuações de dois produtos, usando uma perda chamada Margin-MSE (Hofstätter et al., 2020). A destilação também vai dos LLMs para modelos menores. O RankGPT relata que um modelo de 440M destilado supera um modelo supervisionado de 3B no benchmark BEIR (Sun et al., 2023; BEIR). Em um estudo de busca de produtos sobre consultas com superlativos, modelos leves herdaram as interpretações de um LLM, onde o reranqueamento direto com o LLM tem uma latência proibitiva (Zhu et al., 2025). O professor não precisa de rótulos humanos e rotula cada candidato.

O professor é o cross-encoder. O aluno é uma regressão LightGBM sobre os 7 atributos que não exigem nenhuma chamada de modelo além da que a recuperação já faz: tudo, exceto cross_encoder. Seu rótulo é a pontuação bruta do professor, que uma regressão de árvores consegue reproduzir na escala do próprio professor. Ele ranqueia os mesmos candidatos, na ordem de product_id, com árvores do tamanho escolhido para o LambdaMART. Primeiro, compare o aluno com um modelo LambdaMART treinado com notas humanas e os mesmos atributos, por validação cruzada nas consultas de treino:

distillation-on-train.py Python 3.12.15 · bm25s 0.3.16 · lightgbm 4.7.0 · numpy 2.5.5 · pandas 3.1.1 · pystemmer 3.1.0 · scikit-learn 1.9.1 · scipy 1.18.1 Aprovado
"""Trains a student LightGBM regression on the cross-encoder's scores, and a LambdaMART model on human grades with the samefeatures, both by cross-validation on the train queries. The prose's point rests on the student's score, and on itsdifference from the human-graded ranker."""from lightgbm import LGBMRanker, LGBMRegressorfrom lib.metrics import evaluatefrom lib.ranking import CHEAP_FEATURES, DETERMINISTIC, LAMBDARANK, TREES, cross_validate, feature_table, rankedfrom lib.semantic import SemanticSearchfrom lib.significance import comparefrom lib.store import load_products, load_queries, qrelsqueries, judgments = load_queries("train"), qrels("train")          # design work: train queries onlycandidates = feature_table(load_products(), queries)# unjudged candidates count as grade 0, as in the metriccandidates["grade or 0"] = candidates["grade"].fillna(0).astype(int)student = cross_validate(lambda: LGBMRegressor(**TREES, **DETERMINISTIC), candidates, candidates,                         "cross_encoder", CHEAP_FEATURES, judgments)          # labels from the teacherhuman = cross_validate(lambda: LGBMRanker(**LAMBDARANK, **TREES, **DETERMINISTIC), candidates, candidates,                       "grade or 0", CHEAP_FEATURES, judgments)               # labels from people# the teacher's own order of the candidates, ties broken by product_idteacher = evaluate(ranked(candidates, candidates["cross_encoder"]), judgments)["ndcg@10"]semantic = evaluate(SemanticSearch().run(queries, k=100), judgments)["ndcg@10"]for name, scores in [("semantic", semantic), ("teacher", teacher), ("student, teacher's labels", student),                     ("lambdarank, human grades, same features", human)]:    print(f"{name}, train ndcg@10: {scores.mean():.3f}")# the student's score minus the human-graded ranker's, per query, tested by permutationresult = compare(student, human)print(f"student minus the human-graded ranker: {result['mean difference']:.3f}")print(f"student minus the human-graded ranker, permutation p: {result['permutation p']:.3f}")
Saídapython distillation-on-train.py
semantic, train ndcg@10: 0.772
teacher, train ndcg@10: 0.785
student, teacher's labels, train ndcg@10: 0.791
lambdarank, human grades, same features, train ndcg@10: 0.747
student minus the human-graded ranker: 0.044
student minus the human-graded ranker, permutation p: 0.002

Nessas consultas de treino, com esses atributos, os rótulos do professor em cada candidato treinaram um ranqueador melhor do que as notas das pessoas, com candidatos não julgados contados como 0. O aluno pontua 0.791, e a própria ordem dos candidatos do professor pontua 0.785.

O modelo treinado com notas humanas pontua 0.747, abaixo dos 0.772 da recuperação semântica, e o aluno menos ele é 0.044, com p-valor de permutação de 0.002. Isso é uma verificação de ajuste nas consultas de treino, não uma evidência.

Depois, ajuste o aluno nas consultas de treino, com parada antecipada nas mesmas consultas de treino reservadas do LambdaMART, e execute a última comparação planejada, no mesmo limiar de 0.01:

distilled-ranker-on-test.py Python 3.12.15 · bm25s 0.3.16 · lightgbm 4.7.0 · numpy 2.5.5 · pandas 3.1.1 · pystemmer 3.1.0 · scikit-learn 1.9.1 · scipy 1.18.1 Aprovado
"""Fits a student LightGBM regression on the teacher's scores for the train queries, then reports its gain shares, howclosely its order follows similarity and the teacher, and its planned comparison on the test queries. The prose's pointrests on that comparison and on the taus printed for each ranking."""import numpy as npfrom lightgbm import LGBMRegressorfrom scipy.stats import kendalltaufrom lib.metrics import evaluatefrom lib.ranking import CHEAP_FEATURES, DETERMINISTIC, TREES, feature_table, fit, ranked, report_planned, stopping_splitfrom lib.semantic import SemanticSearchfrom lib.store import load_products, load_queries, qrelsproducts, train, test = load_products(), load_queries("train"), load_queries("test")table = feature_table(products, train)                       # the teacher's score is the label: no human gradesprint(f"train candidates the teacher labels: {len(table)}")print(f"of them, judged by nobody: {table['grade'].isna().sum()}")print(f"student features: {len(CHEAP_FEATURES)}")# early stopping on the same 10 held-out train queries that LambdaMART stops onstudent = fit(LGBMRegressor(**TREES, **DETERMINISTIC), table, "cross_encoder", CHEAP_FEATURES, *stopping_split(train.index))print(f"trees kept by early stopping: {student.best_iteration_}")candidates, judgments = feature_table(products, test), qrels("test")       # test queries: read once, to reportpredicted = student.predict(candidates[CHEAP_FEATURES])gain = student.booster_.feature_importance(importance_type="gain")# the three features with the most gainfor name, share in sorted(zip(CHEAP_FEATURES, gain / gain.sum()), key=lambda pair: -pair[1])[:3]:    print(f"student's share of gain, {name}: {share:.3f}")for name in ["cross_encoder", "similarity"]:                   # whose order does the student follow?    # candidates has a default index, so group.index picks this query's rows out of predicted    tau = [kendalltau(group[name], predicted[group.index]).statistic for _, group in candidates.groupby("query_id")]    print(f"tau between student and {name}, mean over test queries: {np.mean(tau):.3f}")teacher = evaluate(ranked(candidates, candidates["cross_encoder"]), judgments)print(f"teacher's own order of the candidates, test ndcg@10, not a planned comparison: {teacher['ndcg@10'].mean():.3f}")after = evaluate(ranked(candidates, predicted), judgments)before = evaluate(SemanticSearch().run(test, k=100), judgments)for name, frame in [("semantic", before), ("distilled", after)]:    print(f"{name}, test ndcg@10: {frame['ndcg@10'].mean():.3f}")    print(f"{name}, test judged@10: {frame['judged@10'].mean():.3f}")    # each query's top 10 is 10 places, so (1 - judged@10) times 10 counts its unjudged places    print(f"{name}, unjudged places in the test top 10s: {round((1 - frame['judged@10']).sum() * 10)}")report_planned("distilled", after["ndcg@10"], before["ndcg@10"])
Saídapython distilled-ranker-on-test.py
train candidates the teacher labels: 6896
of them, judged by nobody: 1975
student features: 7
trees kept by early stopping: 202
student's share of gain, similarity: 0.812
student's share of gain, name_match: 0.126
student's share of gain, bm25: 0.055
tau between student and cross_encoder, mean over test queries: 0.466
tau between student and similarity, mean over test queries: 0.753
teacher's own order of the candidates, test ndcg@10, not a planned comparison: 0.782
semantic, test ndcg@10: 0.830
semantic, test judged@10: 0.990
semantic, unjudged places in the test top 10s: 3
distilled, test ndcg@10: 0.826
distilled, test judged@10: 0.987
distilled, unjudged places in the test top 10s: 4
distilled, mean difference: -0.004
distilled, wins, losses, ties: 10, 13, 7
distilled, permutation p: 0.720
distilled, established at 0.01: no
distilled, t-test p: 0.694
distilled, t-test agrees: yes
distilled, 99% interval: -0.034 to 0.017
distilled, interval agrees: yes

O professor rotula todos os 6896 candidatos de treino, dos quais 1975 não foram julgados por ninguém, e a parada antecipada mantém 202 árvores.

O aluno depende de similarity, que responde por 0.812 do ganho, à frente de name_match com 0.126 e de bm25 com 0.055. Nos candidatos de teste, suas pontuações concordam com a similaridade semântica com um tau médio de 0.753 por consulta, e com as do professor com 0.466. Assim, o aluno aprendeu sobretudo a ordem da recuperação semântica, ajustada um pouco em direção à do professor por correspondências de nome e por BM25.

O aluno não estabelece ganho: o ranqueador destilado pontua 0.826 de nDCG@10 contra 0.830 da recuperação semântica, com p-valor de permutação de 0.720 (veja a tabela de decisões). A própria ordem dos candidatos de teste pelo professor, que o capítulo não planejou testar, pontua 0.782.

Judged@10 é 0.987 para o aluno, contra 0.990 para a recuperação semântica, e os top 10 do aluno têm 4 posições não julgadas, enquanto a recuperação semântica tem 3.

Regra prática: Destile quando um reranqueador obtém um ganho comprovado, mas custa caro demais por consulta: rotule todos os candidatos das suas consultas de treino com o professor, treine o aluno com atributos que você consegue calcular sem o professor e teste o aluno contra a sua recuperação em consultas reservadas. Leia a importância de ganho do aluno: quando a pontuação da própria recuperação domina, o aluno é, na maior parte, a sua recuperação. Use margens entre pares quando o aluno não conseguir reproduzir a escala do professor. A loja ainda não tem um professor que supere a recuperação semântica, então mantém o código e não coloca o aluno em produção.

O que dá errado em produção

Última alteração na edição 2026.11.8

Um ranqueador ao vivo calcula features e chama modelos enquanto o cliente espera, com código e versões de modelos que podem divergir daqueles com que foram treinados e testados.

Features divergem entre treinamento e serving. Se o sistema ao vivo tokeniza de forma diferente, reescala o BM25 ou atualiza o modelo de embedding, os pesos aprendidos passam a operar sobre números diferentes, e nenhum erro é gerado. Calcule as features com um único caminho de código compartilhado, e registre-as com cada ranking servido.

A ordem das linhas vaza para o treinamento. O lambdarank do LightGBM parte da ordem de suas linhas de entrada, e todo ranking desempata empates de alguma forma. Um arquivo ordenado pela pontuação de um reranqueador entrega ao modelo o ranking desse reranqueador. Ordene os candidatos por um ID, ou embaralhe-os com uma semente fixa, antes de cada ajuste e de cada pontuação.

Os julgamentos vêm de um pool. O WANDS julgou apenas os produtos que seus próprios sistemas apresentaram (capítulo 2). Contar candidatos não julgados como irrelevantes ensina um modelo a rebaixar tudo o que esses sistemas não encontraram. Verifique o judged@10 de cada ranqueador que você adicionar, e faça julgar os produtos não julgados antes de confiar em qualquer ganho.

Juízes LLM favorecem reranqueadores LLM. Em um estudo, rankings construídos a partir de avaliadores LLM colocam reranqueadores baseados em LLM de 9 a 17 posições acima do que deveriam, em média (Fröbe et al., 2025). Usar LLMs tanto para ranquear quanto para julgar é circular, "ilustrando como a dependência de avaliações baseadas em LLM pode distorcer rankings de sistemas" (Clarke and Dietz, 2024). Avalie reranqueadores LLM com julgamentos humanos, como este capítulo faz.

Um reranqueador LLM pertence a uma versão de modelo e a um prompt. Um digest diferente (o hash que identifica os pesos exatos), uma quantização (a precisão com que os pesos são armazenados) ou uma redação diferente do prompt pode alterar cada resposta. E, por causa do viés de posição, uma mudança na ordem da recuperação também pode alterar as respostas. O manifesto do registro LLM registra o digest e os dois prompts literalmente; meça novamente sempre que qualquer um deles mudar.

Consultas inéditas podem ter desempenho pior. Uma comparação de 22 métodos de reranqueamento constatou que reranqueadores LLM se saem melhor em consultas familiares, enquanto "sua capacidade de generalização para consultas inéditas varia" (Abdallah et al., 2025). Observe consultas sobre produtos e estilos mais recentes que os dados de treinamento do modelo.

Cada reranqueador acrescenta uma chamada no caminho do cliente. Conte as chamadas e o texto por consulta, como em o orçamento, defina um tempo limite e recorra à ordem da recuperação quando o reranqueador não responder a tempo.

Regra prática: Registre features e versões de modelos com cada ranking, coloque os candidatos em uma ordem que não carregue informação, pontue com julgamentos humanos, verifique o judged@10, e dê a cada etapa de reranqueamento um limite de tempo e um fallback.

Decisões tomadas neste capítulo

Última alteração na edição 2026.11.8

O capítulo tomou cada decisão da lista abaixo com base nas consultas de treino, e somente uma comparação planejada estabelecida nas consultas de teste poderia alterar a busca da loja.

As 5 comparações planejadas, cada uma sobre nDCG@10 frente ao 0.830 da recuperação semântica, estabelecidas abaixo de 0.01:

Medida LambdaMART Cross-encoder LLM pointwise LLM listwise Destilado
nDCG@10 0.817 0.813 0.837 0.819 0.826
Diferença média -0.012 -0.016 0.008 -0.010 -0.004
Vitórias / derrotas / empates 14, 12, 4 11, 12, 7 11, 8, 11 12, 12, 6 10, 13, 7
p de permutação 0.260 0.178 0.241 0.580 0.720
Estabelecido no no no no no
p do teste t 0.278 0.171 0.244 0.498 0.694
Intervalo de 99% -0.044 to 0.011 -0.058 to 0.006 -0.007 to 0.026 -0.070 to 0.016 -0.034 to 0.017
Teste t concorda yes yes yes yes yes
Intervalo concorda yes yes yes yes yes
  • 5 comparações planejadas contra a recuperação semântica, com julgamentos humanos, estabelecidas abaixo de 0.01.
  • Candidatos: a união dos 100 primeiros do BM25 e da recuperação semântica, na ordem de product_id, com empates de pontuação resolvidos por product_id.
  • LambdaMART: label_gain=[0, 1, 2], candidatos não julgados como grau 0, 3 folhas com taxa de aprendizado de 0.1, escolhido por validação cruzada no treino, com parada antecipada em consultas de treino reservadas usando eval_X e eval_y. Seu ganho não está estabelecido no teste, por isso não é usado.
  • Profundidade de reranqueamento: os 20 primeiros da recuperação semântica, fixada para coincidir com a gravação das respostas do LLM; no treino, a curva do cross-encoder se achata entre 20 e 30. Nenhum ganho de reranqueador está estabelecido no teste, por isso nenhum é usado.
  • Os reranqueadores LLM são pontuados apenas com julgamentos humanos, e o listwise é verificado em duas ordens de entrada. Sua resposta depende da ordem apresentada.
  • Custos são contados, não medidos no tempo: chamadas e caracteres por consulta.
  • Destilação: um modelo aluno LightGBM sobre as pontuações do cross-encoder, sem nenhuma chamada de modelo além da recuperação. Ele aprende principalmente a ordem da recuperação semântica, não mostra ganho estabelecido e não é usado.
  • O ranqueador a ser superado continua sendo apenas a recuperação semântica, com BM25, sem stemização, como linha de base.
  • O que o capítulo mostrou: nenhuma segunda etapa mereceu seu lugar; nenhuma mostra ganho estabelecido.

Este capítulo, nesta edição

Edição 2026.11.10Exemplos aprovados em 19 de nov de 202614 de 14 exemplos exemplos deste capítulo passam

Traduzido do livro em inglês, edição 2026.11.10.

Citar esta seção

Formato

Cada formato cita o livro em inglês, que esta tradução acompanha.

Todos os formatos citam esta edição. Seu link abre a edição atual, em que o título de cada seção indica quando seu texto foi alterado pela última vez. As datas de acesso e de recuperação são o dia em que você abre esta página.

Nesta página

Capítulo 9 de 11: Ranqueamento

  1. Descreva cada candidato com features
  2. Aprenda um ranking a partir de pares de produtos
  3. Treinar LambdaMART com LightGBM
  4. Relatório do LambdaMART nas consultas de teste
  5. Reordene a recuperação semântica com um cross-encoder
  6. Pontue cada produto com um LLM
  7. Ordene os 20 produtos com um prompt de LLM
  8. Inverta a entrada para medir o viés posicional
  9. Defina a profundidade de reranqueamento a partir de um orçamento
  10. Destile o cross-encoder em um ranqueador pequeno
  11. O que dá errado em produção
  12. Decisões tomadas neste capítulo

Voltar ao topoTodos os capítulos