---

name: reranking-cross-encoder description: "Use for sentence-transformers CrossEncoder pair scoring, reranking, rank API usage, retrieve-and-rerank handoffs, multimodal reranker routing, and activation/softmax/num_labels pitfalls." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

Reranking Cross Encoder

Use this sub-skill when the task is about scoring input pairs with CrossEncoder, reranking an already-retrieved candidate list, choosing between a reranker and a bi-encoder, or debugging CrossEncoder predict/rank outputs.

Route Here For

• Pair scoring with CrossEncoder.predict, including single pair vs batch-of-pairs shape decisions.
• Reranking an existing list of candidate documents with CrossEncoder.rank, top_k, return_documents, stable corpus_id handling, batching, prompts, and device placement.
• Choosing a CrossEncoder reranker over a bi-encoder when accuracy on a limited candidate set matters more than precomputed embeddings or high-throughput first-stage retrieval.
• Regression reranker vs pair-classification setup, especially num_labels, activation_fn, and apply_softmax behavior.
• Multimodal reranker routing for text-image/audio/video-capable CrossEncoder checkpoints.

Route Elsewhere

• First-stage dense retrieval, semantic_search, hard-negative mining, quantized embeddings, and vector database orchestration belong in ../retrieval-and-utilities/SKILL.md.
• Detailed loss/evaluator/trainer selection belongs in ../evaluation-and-training/SKILL.md.
• ONNX/OpenVINO export and backend optimization belong in ../backend-export-optimization/SKILL.md.
• Dense SentenceTransformer.encode embeddings and similarity belong in ../embeddings-and-similarity/SKILL.md.

Fast Pattern

from sentence_transformers import CrossEncoder

model = CrossEncoder("cross-encoder/ms-marco-MiniLM-L6-v2")
query = "How many people live in Berlin?"
documents = [
    "Berlin had 3,520,031 registered inhabitants.",
    "Berlin is well known for its museums.",
]
results = model.rank(query, documents, top_k=2, return_documents=True)

rank returns dictionaries sorted by descending score. Each result includes corpus_id from the input documents list, score, and text when return_documents=True.

Essential References

• API details: references/api-reference.md
• Reranking workflows: references/workflows.md
• Failure diagnosis: references/troubleshooting.md
• Safe CLI smoke helper: scripts/cross_encoder_rerank_smoke.py --help

Ground Rules

• CrossEncoders score pairs jointly; they do not create reusable document embeddings.
• rank is for single-label rerankers (num_labels == 1); use predict for multi-class pair classifiers.
• Preserve stable corpus IDs by reranking the exact candidate list order and mapping corpus_id back to first-stage hits.
• For MS MARCO-style rerankers, raw logits may be unbounded; pass activation_fn=torch.nn.Sigmoid() if the downstream consumer needs 0-1 scores. Ranking order is usually unchanged by monotonic activations.
• Do not make the reranker retrieve the whole corpus. Retrieve top candidates first, then rerank only that shortlist.