0
# Reranking
1

2
Document relevance scoring and reordering for improved search and retrieval results. Uses specialized reranking models to optimize document ordering based on query relevance, enhancing search quality for information retrieval systems.
3

4
## Capabilities
5

6
### Document Reranking
7

8
Reorder documents based on relevance to a query using specialized reranking models.
9

10
```python { .api }
11
def create(
12
    model: str,
13
    query: str,
14
    documents: Union[List[str], List[Dict[str, Any]]],
15
    top_n: Optional[int] = None,
16
    return_documents: bool = False,
17
    rank_fields: Optional[List[str]] = None,
18
    **kwargs
19
) -> RerankResponse:
20
    """
21
    Rerank documents based on query relevance.
22

23
    Args:
24
        model: Reranking model identifier
25
        query: Search query for relevance comparison
26
        documents: List of documents to rerank (strings or objects)
27
        top_n: Number of top documents to return
28
        return_documents: Include original documents in response
29
        rank_fields: Fields to rank when documents are objects
30

31
    Returns:
32
        RerankResponse with relevance scores and rankings
33
    """
34
```
35

36
### Async Reranking
37

38
Asynchronous document reranking for concurrent processing.
39

40
```python { .api }
41
async def create(
42
    model: str,
43
    query: str,
44
    documents: Union[List[str], List[Dict[str, Any]]],
45
    **kwargs
46
) -> RerankResponse:
47
    """
48
    Asynchronously rerank documents.
49

50
    Returns:
51
        RerankResponse with relevance scores and rankings
52
    """
53
```
54

55
## Usage Examples
56

57
### Basic Document Reranking
58

59
```python
60
from together import Together
61

62
client = Together()
63

64
query = "What is the capital of the United States?"
65
documents = [
66
    "New York is the most populous city in the United States.",
67
    "Washington, D.C. is the capital of the United States.",
68
    "Los Angeles is known for its entertainment industry.",
69
    "The United States has 50 states and a federal district.",
70
    "Chicago is the third-largest city in the United States."
71
]
72

73
response = client.rerank.create(
74
    model="Salesforce/Llama-Rank-V1",
75
    query=query,
76
    documents=documents,
77
    top_n=3
78
)
79

80
print("Reranked documents by relevance:")
81
for result in response.results:
82
    print(f"Rank {result.index + 1}: {documents[result.index]}")
83
    print(f"Relevance score: {result.relevance_score:.4f}")
84
    print("---")
85
```
86

87
### Advanced Reranking with Structured Documents
88

89
```python
90
# Documents with metadata
91
documents = [
92
    {
93
        "title": "Python Programming Basics",
94
        "content": "Python is a high-level programming language known for its simplicity.",
95
        "category": "programming"
96
    },
97
    {
98
        "title": "Machine Learning Introduction", 
99
        "content": "Machine learning is a subset of artificial intelligence.",
100
        "category": "ai"
101
    },
102
    {
103
        "title": "Data Science with Python",
104
        "content": "Python is widely used in data science for analysis and visualization.",
105
        "category": "data-science"
106
    }
107
]
108

109
query = "Python programming for beginners"
110

111
response = client.rerank.create(
112
    model="Salesforce/Llama-Rank-V1",
113
    query=query,
114
    documents=documents,
115
    top_n=2,
116
    return_documents=True,
117
    rank_fields=["title", "content"]
118
)
119

120
print("Top relevant documents:")
121
for result in response.results:
122
    doc = documents[result.index]
123
    print(f"Title: {doc['title']}")
124
    print(f"Relevance: {result.relevance_score:.4f}")
125
    print(f"Content: {doc['content'][:100]}...")
126
    print("---")
127
```
128

129
## Types
130

131
### Request Types
132

133
```python { .api }
134
class RerankRequest:
135
    model: str
136
    query: str
137
    documents: Union[List[str], List[Dict[str, Any]]]
138
    top_n: Optional[int] = None
139
    return_documents: bool = False
140
    rank_fields: Optional[List[str]] = None
141
```
142

143
### Response Types
144

145
```python { .api }
146
class RerankResponse:
147
    id: str
148
    results: List[RerankResult]
149
    meta: RerankMeta
150

151
class RerankResult:
152
    index: int
153
    relevance_score: float
154
    document: Optional[Dict[str, Any]] = None
155

156
class RerankMeta:
157
    api_version: Dict[str, str]
158
    billed_units: Dict[str, int]
159
```
160

161
## Supported Models
162

163
- `Salesforce/Llama-Rank-V1` - High-quality reranking model
164
- `BAAI/bge-reranker-large` - BGE reranking model
165
- `BAAI/bge-reranker-base` - Efficient reranking model