# Rerank Text Ranking

Rerank improves retrieval accuracy and relevance. This document introduces how to use the Rerank API.

## API Endpoint

`https://api-us-ca.umodelverse.ai/v1/rerank` 

## Request Parameters

| Parameter | Type | Required | Description |
| ---- | ---- | ---- | ---- |
| model      | string | Yes | Model name. Here: `bge-reranker-v2-m3` |
| query      | string | Yes | The query content. |
| documents  | array[string] | Yes | List of candidate documents to be ranked. Each element is a string. |
| top_n      | int   | No | Return the top_n ranked documents. By default, all documents are returned. If top_n is greater than the total number of documents, all documents will be returned. |

## Notes

1. **Text Length Limit**: The maximum length of a single {query + document} is `8192`

### Request Example

⚠️ If you are using Windows, it is recommended to use Postman or other API tools.
```bash
  curl -X POST https://api-us-ca.umodelverse.ai/v1/rerank \
  -H "Authorization: Bearer $MODELVERSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bge-reranker-v2-m3",
    "query": "what is panda?",
    "documents": [
      "hi",
      "The giant panda (Ailuropoda melanoleuca), sometimes called a panda bear or simply panda, is a bear species endemic to China."
    ],
    "top_n": 2
  }'
```

## Response Parameters

| Parameter | Type | Description |
| ---- | ---- | ---- |
| results    | array | Ranking results, sorted by relevance_score in descending order. |
| document   | object | Original document object. |
| document.text   | string | Original document text |
| index | int | Indicates the original index position in the input documents list. |
| relevance_score | double   | Semantic relevance score between the document and the query, ranging from 0.0 to 1.0. The higher the score, the stronger the relevance. |

## Response Example

```json
{
	"model": "BAAI/bge-reranker-v2-m3",
	"usage": {
		"total_tokens": 53
	},
	"results": [{
		"index": 1,
		"document": {
			"text": "The giant panda (Ailuropoda melanoleuca), sometimes called a panda bear or simply panda, is a bear species endemic to China.",
			"multi_modal": null
		},
		"relevance_score": 0.9948425889015198
	}, {
		"index": 0,
		"document": {
			"text": "hi",
			"multi_modal": null
		},
		"relevance_score": 0.0002801174996420741
	}]
}
```