Description
Voyage Cross-Encoder Reranking takes a query and an existing document candidate set, then returns relevance scores keyed to the original document indices. It is designed for the precision stage after cheaper retrieval has already narrowed the corpus. The adapter defaults to Voyage rerank-2.5, supports optional top-K and provider-side truncation settings, and reports the model and prompt-token usage with every result.
The implementation is BYOK and failure-aware. It validates credentials at construction, enforces a 1,000-document request cap, applies request timeouts and bounded retries, honors the provider's Retry-After header, and preserves typed rate-limit and authentication errors. Exact-model cost estimation is separate from embedding pricing so rerank rates cannot accidentally become a default embedding rate.
Selling Points
- Improves the ordering of a manageable candidate set using joint query-document scoring rather than independent embeddings.
- Returns original input indices, making it straightforward to reassemble rich application results after ranking plain document text.
- Provider token usage and exact-model pricing support honest per-call metering.
- Retry hints expose the provider's requested backoff rather than hiding it behind a generic timeout.
- A clear batch ceiling prevents callers from turning an expensive precision stage into an unbounded corpus scan.
User Story
Universal Search retrieves a fused shortlist with BM25 and vector similarity, then sends its candidate text to the reranker. The adapter returns new relevance scores, and the search stage reorders the hits within its timeout budget. If the provider is unavailable, the search engine keeps the fused ordering rather than losing the query.
Extension Surface
Pluggable is the first true rung because packages/embedding-providers/src/internal/voyage-rerank.ts implements the public VoyageRerankProvider seam, while packages/embedding-providers/src/internal/rerank-provider-registry.ts catalogs shipped and deferred rerank providers behind a common provider vocabulary. The search engine consumes its own structural RerankerLike contract, allowing the adapter to be substituted at composition.
Capabilities & Limits
- Reranks up to 1,000 documents with optional top-K selection and truncation control.
- Reports relevance scores, source indices, model ID, token usage, and exact-model cost.
- Retries transient failures and surfaces structured authentication and rate-limit conditions.
- Limits: reranking does not retrieve documents; callers must supply a bounded candidate set.
- Limits: the adapter performs network I/O and can time out, so production consumers need a graceful fallback order.
Implementation Map
packages/embedding-providers/src/internal/voyage-rerank.tspackages/embedding-providers/src/internal/rerank-provider-registry.tspackages/embedding-providers/src/internal/cost.tspackages/search/src/internal/stages/rerank.tsapps/web/src/composition/rerank-metering.ts