vai rerank

Rerank a set of documents against a query using Voyage AI's cross-encoder reranking models.

CLI

Synopsis

vai rerank --query <text> [options]

Description

vai rerank takes a query and a set of documents, then re-scores each document by relevance using a cross-attention model. Unlike embedding-based search (which encodes query and document independently), reranking reads the query and each document together for higher-precision relevance scores.

Documents can be provided via --documents, --documents-file, or piped through stdin.

Options

Flag	Description	Default
--query <text>	Search query (required)	—
--documents <docs...>	Documents to rerank (inline, space-separated)	—
--documents-file <path>	File with documents (JSON array or newline-delimited)	—
-m, --model <model>	Reranking model	rerank-2.5
-k, --top-k <n>	Return only top K results	All
--truncation	Enable truncation for long inputs	—
--no-truncation	Disable truncation	—
--return-documents	Include document text in results	—
--estimate	Show estimated tokens and cost without calling the API	—
--json	Machine-readable JSON output	—
-q, --quiet	Suppress non-essential output	—

Examples

Rerank inline documents

vai rerank --query "vector search" \
  --documents "MongoDB Atlas supports vector search" \
              "PostgreSQL is a relational database" \
              "Embeddings capture semantic meaning"

Rerank from a file

vai rerank --query "How do I deploy?" --documents-file candidates.json --top-k 3

Pipe documents from another command

cat search-results.json | vai rerank --query "deployment best practices"

Use the lite reranker for lower cost

vai rerank --query "authentication" --documents-file docs.txt --model rerank-2.5-lite

Get JSON output with document text included

vai rerank --query "scaling" --documents-file docs.json --return-documents --json

Playground

Using the Rerank Tab

The Rerank tab in vai playground provides a visual interface for reranking documents against a query.

Getting Started

1. Run vai playground to start the web app
2. Select the Rerank tab from the navigation
3. Enter your query in the query field
4. Add documents to compare (one per line, or paste a JSON array)
5. Click Rerank to see relevance scores

Features

Query input: Enter the search query that documents will be ranked against.

Document list: Add multiple documents to be reranked. Each document gets a relevance score from the cross-attention model.

Sorted results: Documents are displayed in order of relevance, with scores indicating how well each matches the query.

Model selection: Choose between rerank-2.5 (best quality) and rerank-2.5-lite (faster, cheaper).

Top-K filtering: Limit results to the top K most relevant documents.

When to Use Reranking

Reranking is most effective as a second stage after vector search. It provides higher precision by reading the query and document together rather than comparing independent embeddings. The playground lets you experiment with different queries and document sets to see how reranking changes result ordering.

Tips

• Reranking is most effective as a second stage after vector search. Use vai query to combine both stages automatically.
• The --documents-file (CLI) accepts JSON arrays, newline-delimited text, or JSONL with a text field.
• rerank-2.5 gives the best quality; rerank-2.5-lite is faster and cheaper for high-throughput use cases.

Related Commands

• vai query — Two-stage retrieval (search + rerank)
• vai search — Vector search without reranking
• vai embed — Generate embeddings