> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Rerank

> Re-score and reorder search results using cross-encoder models for higher precision

<Frame>
  <img src="https://mintcdn.com/mixpeek/TmiAqiYj-LwmWL2a/assets/retrievers/rerank.svg?fit=max&auto=format&n=TmiAqiYj-LwmWL2a&q=85&s=21889adcc72377962074d258050939f9" alt="Rerank stage showing cross-encoder model re-scoring search results" width="1000" height="400" data-path="assets/retrievers/rerank.svg" />
</Frame>

The Rerank stage uses cross-encoder models to re-score and reorder search results. Unlike bi-encoder models (used in semantic search), cross-encoders process the query and document together, enabling more accurate relevance scoring at the cost of higher latency.

<Note>
  **Stage Category**: SORT (Reorders documents)

  **Transformation**: N documents → top\_k documents (re-ranked by relevance)
</Note>

## When to Use

| Use Case                        | Description                                     |
| ------------------------------- | ----------------------------------------------- |
| **Two-stage retrieval**         | Fast recall (search) + precise ranking (rerank) |
| **High-precision requirements** | When ranking quality is critical                |
| **Top-N optimization**          | Improve quality of final displayed results      |
| **RAG applications**            | Better context selection for LLM generation     |

## When NOT to Use

| Scenario                         | Recommended Alternative       |
| -------------------------------- | ----------------------------- |
| Large result sets (1000+)        | Too slow; use `sort_by_field` |
| Real-time requirements (\< 20ms) | Use search scores directly    |
| Simple attribute sorting         | `sort_by_field`               |

## Parameters

| Parameter        | Type    | Default                    | Description                                                                                                |
| ---------------- | ------- | -------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `inference_name` | string  | `BAAI__bge_reranker_v2_m3` | Reranking inference service. List options with `GET /engine/inference`. Ignored when `feature_uri` is set. |
| `feature_uri`    | string  | `null`                     | Custom reranker plugin (`mixpeek://...`). Overrides `inference_name`.                                      |
| `top_k`          | integer | `null`                     | Number of results to keep after reranking (omit to keep all, reordered).                                   |
| `query`          | string  | `{{INPUT.query}}`          | Query for relevance scoring                                                                                |
| `document_field` | string  | `content`                  | Document field to rerank against                                                                           |

## Available Models

The built-in reranker is `BAAI__bge_reranker_v2_m3` (multilingual cross-encoder). For other models, deploy your own via a [custom extractor](/processing/custom-extractors) and reference it with `feature_uri`.

## Configuration Examples

<CodeGroup>
  ```json Basic Reranking theme={null}
  {
    "stage_name": "rerank",
    "stage_type": "sort",
    "config": {
      "stage_id": "rerank",
      "parameters": {
        "inference_name": "BAAI__bge_reranker_v2_m3",
        "top_k": 10
      }
    }
  }
  ```

  ```json High-Quality Reranking theme={null}
  {
    "stage_name": "rerank",
    "stage_type": "sort",
    "config": {
      "stage_id": "rerank",
      "parameters": {
        "inference_name": "BAAI__bge_reranker_v2_m3",
        "top_k": 5
      }
    }
  }
  ```

  ```json Custom Query theme={null}
  {
    "stage_name": "rerank",
    "stage_type": "sort",
    "config": {
      "stage_id": "rerank",
      "parameters": {
        "inference_name": "BAAI__bge_reranker_v2_m3",
        "query": "{{INPUT.question}}",
        "top_k": 20
      }
    }
  }
  ```

  ```json Large Candidate Pool theme={null}
  {
    "stage_name": "rerank",
    "stage_type": "sort",
    "config": {
      "stage_id": "rerank",
      "parameters": {
        "inference_name": "BAAI__bge_reranker_v2_m3",
        "top_k": 50
      }
    }
  }
  ```
</CodeGroup>

## How Cross-Encoders Work

| Bi-Encoder (Search)              | Cross-Encoder (Rerank)         |
| -------------------------------- | ------------------------------ |
| Query and doc encoded separately | Query + doc encoded together   |
| Pre-compute doc embeddings       | Must process each pair         |
| Fast (\< 10ms for millions)      | Slower (50-100ms for 100 docs) |
| Good approximate ranking         | Precise relevance scoring      |

Cross-encoders see the full context of both query and document together, enabling better understanding of semantic relationships.

## Two-Stage Retrieval Pattern

The recommended pattern is fast recall followed by precise reranking:

```json theme={null}
[
  {
    "stage_name": "search",
    "stage_type": "filter",
    "config": {
      "stage_id": "feature_search",
      "parameters": {
        "searches": [
          {
            "feature_uri": "mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1",
            "query": { "input_mode": "text", "value": "{{INPUT.query}}" },
            "top_k": 100
          }
        ],
        "final_top_k": 100
      }
    }
  },
  {
    "stage_name": "rerank",
    "stage_type": "sort",
    "config": {
      "stage_id": "rerank",
      "parameters": {
        "inference_name": "BAAI__bge_reranker_v2_m3",
        "top_k": 10
      }
    }
  }
]
```

**Why this works:**

1. **Search stage**: Fast, retrieves 100 candidates (\< 20ms)
2. **Rerank stage**: Slower but precise, picks best 10 (50-100ms)
3. **Total**: High-quality results in 70-120ms

## Performance

| Metric                 | Value                                 |
| ---------------------- | ------------------------------------- |
| **Latency**            | 50-100ms (depends on candidate count) |
| **Optimal input size** | 50-200 documents                      |
| **Maximum practical**  | \~500 documents                       |
| **Batching**           | Automatic                             |

<Warning>
  Reranking 1000+ documents is not recommended. Use `top_k` limits in the search stage to control candidate pool size.
</Warning>

## Output

Each returned document includes:

| Field             | Type    | Description                |
| ----------------- | ------- | -------------------------- |
| `document_id`     | string  | Unique document identifier |
| `score`           | float   | Reranker relevance score   |
| `original_score`  | float   | Score from previous stage  |
| `rerank_position` | integer | Position after reranking   |

## Common Pipeline Patterns

### Search + Rerank + Limit

```json theme={null}
[
  {
    "stage_name": "search",
    "stage_type": "filter",
    "config": {
      "stage_id": "feature_search",
      "parameters": {
        "searches": [
          {
            "feature_uri": "mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1",
            "query": { "input_mode": "text", "value": "{{INPUT.query}}" },
            "top_k": 100
          }
        ],
        "final_top_k": 100
      }
    }
  },
  {
    "stage_name": "rerank",
    "stage_type": "sort",
    "config": {
      "stage_id": "rerank",
      "parameters": {
        "inference_name": "BAAI__bge_reranker_v2_m3",
        "top_k": 20
      }
    }
  },
  {
    "stage_name": "limit",
    "stage_type": "reduce",
    "config": {
      "stage_id": "limit",
      "parameters": {
        "limit": 5
      }
    }
  }
]
```

### Search + Filter + Rerank

```json theme={null}
[
  {
    "stage_name": "search",
    "stage_type": "filter",
    "config": {
      "stage_id": "feature_search",
      "parameters": {
        "searches": [
          {
            "feature_uri": "mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1",
            "query": { "input_mode": "text", "value": "{{INPUT.query}}" },
            "top_k": 200
          }
        ],
        "final_top_k": 200
      }
    }
  },
  {
    "stage_name": "category_filter",
    "stage_type": "filter",
    "config": {
      "stage_id": "attribute_filter",
      "parameters": {
        "field": "metadata.category",
        "operator": "eq",
        "value": "{{INPUT.category}}"
      }
    }
  },
  {
    "stage_name": "rerank",
    "stage_type": "sort",
    "config": {
      "stage_id": "rerank",
      "parameters": {
        "inference_name": "BAAI__bge_reranker_v2_m3",
        "top_k": 10
      }
    }
  }
]
```

## Custom Reranker (BYO Model)

Use your own reranker model deployed as a [custom extractor](/processing/custom-extractors) instead of the built-in models. Set `feature_uri` to route reranking through your extractor's inference endpoint.

### Parameters

| Parameter     | Type   | Default | Description                                                                   |
| ------------- | ------ | ------- | ----------------------------------------------------------------------------- |
| `feature_uri` | string | `null`  | Feature URI of a custom reranker plugin. Overrides `inference_name` when set. |

Your plugin must accept `{pairs: [[query, doc], ...]}` and return `{scores: [float, ...]}`.

### Configuration Example

```json theme={null}
{
  "stage_name": "my_rerank",
  "config": {
    "stage_id": "rerank",
    "parameters": {
      "feature_uri": "mixpeek://my_reranker@1.0.0/rerank",
      "top_k": 10
    }
  }
}
```

<Tip>
  Set `inference_type: "rerank"` in your plugin's manifest to declare compatibility with the rerank stage.
</Tip>

## Trade-offs

| Aspect               | Impact                     |
| -------------------- | -------------------------- |
| **Higher precision** | Better relevance scoring   |
| **Higher latency**   | 50-100ms per batch         |
| **Limited scale**    | Best for \< 500 candidates |
| **API costs**        | Per-document scoring       |

## Related

* [Feature Search](/retrieval/stages/feature-search) - Initial candidate retrieval
* [Feature Search](/retrieval/stages/feature-search) - Combined vector + text search
* [Sort Attribute](/retrieval/stages/sort-attribute) - Simple attribute sorting