Rerank Example

Document reranking example demonstrating various features of Lexilux Rerank API.

Lexilux supports two rerank modes:

  1. OpenAI-compatible mode (mode="openai"): Standard rerank API format (default)

  2. DashScope mode (mode="dashscope"): Alibaba Cloud DashScope rerank API

For a detailed comparison of both modes, see Rerank Modes Comparison.

Full Example

  1#!/usr/bin/env python
  2"""
  321 Document Reranking - Sort by Relevance
  4
  5Learn how to rerank documents based on their relevance to a query.
  6This is useful for search results and recommendation systems.
  7
  8Level: Other APIs
  9"""
 10
 11from config_loader import get_chat_config, parse_args
 12
 13from lexilux import Rerank
 14
 15
 16def main():
 17    """Demonstrate document reranking."""
 18    args = parse_args()
 19
 20    try:
 21        config = get_chat_config(config_path=args.config)
 22        print(
 23            "Note: Using chat config for rerank. "
 24            "Configure 'reranker' section for better results."
 25        )
 26    except (FileNotFoundError, KeyError) as e:
 27        print(f"Configuration error: {e}")
 28        print("\nUsing placeholder values. Please configure test_endpoints.json")
 29        config = {
 30            "base_url": "https://api.example.com/v1",
 31            "api_key": "your-api-key",
 32            "model": "rerank-model",
 33        }
 34
 35    rerank = Rerank(**config)
 36
 37    # Example 1: Basic reranking
 38    print("=" * 50)
 39    print("Example 1: Basic Reranking")
 40    print("=" * 50)
 41
 42    query = "python programming tutorial"
 43    documents = [
 44        "Learn Python from scratch",
 45        "Python for data science",
 46        "Introduction to machine learning",
 47        "Python web development with Flask",
 48        "JavaScript basics for beginners",
 49    ]
 50
 51    result = rerank(query, documents)
 52
 53    print(f"Query: {query}\n")
 54    print("Reranked results:")
 55    for idx, score in result.results:
 56        print(f"  {idx}. [{score:.2f}] {documents[idx]}")
 57    print()
 58
 59    # Example 2: Top-k filtering
 60    print("=" * 50)
 61    print("Example 2: Top-K Filtering (get top 3)")
 62    print("=" * 50)
 63
 64    result = rerank(query, documents, top_k=3)
 65
 66    print(f"Query: {query}\n")
 67    print("Top 3 results:")
 68    for idx, score in result.results:
 69        print(f"  {idx}. [{score:.2f}] {documents[idx]}")
 70    print()
 71
 72    # Example 3: Include documents in results
 73    print("=" * 50)
 74    print("Example 3: Include Documents in Results")
 75    print("=" * 50)
 76
 77    result = rerank(query, documents, top_k=3, include_docs=True)
 78
 79    print(f"Query: {query}\n")
 80    print("Results with documents:")
 81    for idx, score, doc in result.results:
 82        print(f"  [{score:.2f}] {doc}")
 83    print()
 84
 85    # Example 4: Search use case
 86    print("=" * 50)
 87    print("Example 4: Search Result Reranking")
 88    print("=" * 50)
 89
 90    search_query = "how to install python"
 91    search_results = [
 92        "Download Python from python.org",
 93        "Python installation guide for Windows",
 94        "Best Python IDEs for development",
 95        "Install Python using package managers",
 96        "Python vs JavaScript comparison",
 97    ]
 98
 99    result = rerank(search_query, search_results, include_docs=True)
100
101    print(f"User searched for: {search_query}\n")
102    print("Original order vs Reranked order:\n")
103
104    print("Original:")
105    for i, doc in enumerate(search_results):
106        print(f"  {i + 1}. {doc}")
107
108    print("\nReranked (most relevant first):")
109    for rank, (idx, score, doc) in enumerate(result.results, 1):
110        print(f"  {rank}. [{score:.2f}] {doc}")
111
112
113if __name__ == "__main__":
114    main()

Mode Selection

You can specify the mode when initializing the Rerank client:

# OpenAI-compatible mode
rerank = Rerank(
    base_url="https://api.example.com/v1",
    api_key="your-api-key",
    model="rerank-model",
    mode="openai"  # Use OpenAI-compatible format
)

# DashScope mode
rerank = Rerank(
    base_url="https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank",
    api_key="your-api-key",
    model="qwen3-rerank",
    mode="dashscope"  # Use DashScope format
)

You can also override the mode for individual calls:

# Use OpenAI mode for this call only
result = rerank("query", docs, mode="openai")

Score Sorting Rules

Lexilux automatically handles different score formats returned by rerank APIs:

Positive Scores (e.g., 0.95, 0.80, 0.70):

  • Higher score = Better relevance

  • Sorted in descending order: 0.95 > 0.80 > 0.70

Negative Scores (e.g., -3.0, -4.0, -5.0):

  • Less negative = Better relevance

  • Sorted in descending order: -3.0 > -4.0 > -5.0

  • Note: -3.0 is mathematically greater than -4.0

The library automatically detects which format is used and applies the correct sorting order.

OpenAI-Compatible Mode

When using mode="openai", Lexilux uses the standard OpenAI-compatible rerank API format:

Request Format:

  • Endpoint: POST /rerank

  • Payload:

    {
  "model": "rerank-model",
  "query": "search query",
  "documents": ["doc1", "doc2", "doc3"],
  "top_n": 3,
  "return_documents": true
}

Response Format:

  • Expected response:

    {
  "results": [
    {
      "index": 0,
      "relevance_score": 0.95,
      "document": {"text": "doc1"}
    },
    {
      "index": 1,
      "relevance_score": 0.80,
      "document": {"text": "doc2"}
    }
  ],
  "usage": {"total_tokens": 100}
}

Key Differences: - Uses top_n instead of top_k - Uses return_documents instead of include_docs - Uses relevance_score instead of score - Document is wrapped in {"text": "..."} object

DashScope Mode

When using mode="dashscope", Lexilux uses the Alibaba Cloud DashScope rerank API format:

Request Format:

  • Endpoint: POST /text-rerank/text-rerank

  • Payload:

    {
  "model": "qwen3-rerank",
  "input": {
    "query": "search query",
    "documents": ["doc1", "doc2", "doc3"]
  },
  "parameters": {
    "top_n": 3,
    "return_documents": true
  }
}

Response Format:

  • Expected response:

    {
  "output": {
    "results": [
      {
        "index": 0,
        "relevance_score": 0.95,
        "document": {"text": "doc1"}
      }
    ]
  },
  "usage": {"total_tokens": 100}
}

Key Features: - Query and documents wrapped in input object - Additional parameters in parameters object - Results wrapped in output.results

Response Formats

Lexilux supports multiple response formats from rerank APIs:

  1. Dictionary format with results:

    {
  "results": [
    {"index": 0, "score": 0.95},
    {"index": 1, "score": 0.80}
  ]
}

  2. Dictionary format with data:

    {
  "data": [
    {"index": 0, "score": 0.95},
    {"index": 1, "score": 0.80}
  ]
}

  3. Direct list format with document text:

    [
  ["doc1", 0.95],
  ["doc2", 0.80]
]

  4. Direct list format with index:

    [
  [0, 0.95],
  [1, 0.80]
]

The library automatically detects and parses all these formats.