Re-ranking Operations

Improve search result quality with LLM-powered re-ranking. Use chain-of-thought reasoning to reorder documents based on relevance, recency, diversity, or custom strategies.

Why Re-ranking?

Vector search alone optimizes for semantic similarity, which may not align with actual relevance. LLM re-ranking adds contextual understanding, reasoning about which results truly answer the query.

POST

/api/v1/rerank

Basic re-ranking endpoint using LLM chain-of-thought reasoning. Supports listwise and pointwise methods with configurable relevance thresholds.

Request Parameters

Parameter	Type	Required	Description
`query`	string	Yes	Query for re-ranking context
`documents`	array	Yes	Documents to re-rank (must include id and content fields)
`method`	string	No	Re-ranking method: listwise or pointwise (default: listwise)
`top_k`	integer	No	Number of top results to return (1-50, default: 10)
`min_score`	integer	No	Minimum relevance score threshold (0-10, default: 5)

Response Fields

Field	Type	Description
`labels`	array	Sorted list of re-ranked documents with scores
`labels[].id`	integer	Original document ID (index in input array)
`labels[].cot`	string	Chain-of-thought reasoning (1-2 sentences)
`labels[].score`	integer	Relevance score (0-10)

Re-ranking Methods

Method	Description	Best For
`listwise`	Evaluates all documents together in context	Better ranking quality, optimal for <20 documents
`pointwise`	Scores each document independently	Faster processing, scales to more documents

POST

/api/v1/rerank/enhanced

Advanced re-ranking with quality filtering, deduplication, multiple strategies, and comprehensive analytics. Supports custom weighting, personalization, and batch processing.

Request Parameters

Parameter	Type	Required	Description
`query`	string	Yes	Query for re-ranking
`documents`	array	Yes	Documents to re-rank
`method`	string	No	Method: listwise, pointwise, pairwise, hybrid, ensemble (default: listwise)
`strategy`	string	No	Strategy: relevance, diversity, recency, quality, custom (default: relevance)
`top_k`	integer	No	Top results to return (1-100, default: 10)
`min_score`	number	No	Minimum relevance score threshold (0-1, default: 0.3)
`enable_quality_filtering`	boolean	No	Enable quality-based filtering (default: true)
`enable_deduplication`	boolean	No	Remove duplicate content (default: false)
`diversity_threshold`	number	No	Content diversity threshold (0-1, default: 0.8)
`boost_recent`	boolean	No	Boost recent documents (default: false)
`date_field`	string	No	Field name for document dates
`include_reasoning`	boolean	No	Include LLM reasoning (default: true)
`output_format`	string	No	Format: standard, detailed, compact (default: standard)

Re-ranking Strategies

Strategy	Description	Use Case
`relevance`	Pure semantic relevance to query	Standard search results
`diversity`	Maximize content diversity in results	Avoid redundant results, exploratory search
`recency`	Favor recent documents	News, time-sensitive content
`quality`	Prioritize high-quality sources	Research, authoritative content
`custom`	Custom weighting via score_weights parameter	Domain-specific ranking needs

Quality Features

Enhanced re-ranking includes automatic quality assessment:

Deduplication: Remove near-duplicate content using cosine similarity
Quality Filtering: Filter out low-quality or incomplete documents
Diversity Scoring: Measure content diversity in final results
Boost Functions: Amplify recent or viewed documents
Batch Processing: Efficient handling of large document sets

Custom Weighting Example

# Define custom scoring weights
result = client.reranking.enhanced_rerank(
    query="Best machine learning frameworks",
    documents=documents,
    strategy="custom",
    score_weights={
        "relevance": 0.5,
        "recency": 0.3,
        "quality": 0.2
    },
    boost_recent=True,
    enable_quality_filtering=True
)

# Results balanced between relevance, recency, and quality

Basic vs Enhanced Re-ranking

Feature	Basic	Enhanced
Re-ranking Methods	Listwise, Pointwise	Listwise, Pointwise, Pairwise, Hybrid, Ensemble
Strategies	Relevance only	Relevance, Diversity, Recency, Quality, Custom
Quality Filtering	No	Yes, configurable
Deduplication	No	Yes, with similarity threshold
Max Documents	50	100
Analytics	Basic scores	Comprehensive metrics and statistics
Personalization	No	User preferences and context
Processing Time	Faster	Slower (more features)

Best Practices

Document Structure: Ensure documents have unique IDs and meaningful content fields
Batch Size: For basic re-ranking, limit to 20 documents for best quality
Method Selection: Use listwise for smaller sets (<20), pointwise for larger
Strategy Choice: Match strategy to use case (recency for news, quality for research)
Deduplication: Enable for user-generated content or web scraping results
Score Thresholds: Tune min_score based on your quality requirements
Date Fields: Include date metadata when using recency boosting
Caching: Re-rank results can be cached for identical queries

Re-ranking adds 200-500ms latency depending on document count and method. For real-time applications, consider caching results or using pointwise method for faster processing.