Skip to content

add documentation for rerank unified route #655

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
narengogi wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

add documentation for rerank unified route #655

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
db3216c
add documentation for rerank unified route
narengogi Jan 15, 2026
261f623
update documentation
narengogi Jan 15, 2026
a708d6d
Update rerank.mdx
narengogi Jan 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -318,6 +318,7 @@
"integrations/llms/bedrock/fine-tuning",
"integrations/llms/bedrock/prompt-caching",
"integrations/llms/bedrock/embeddings",
"integrations/llms/bedrock/rerank",
"integrations/llms/bedrock/bedrock-knowledgebase"
]
},
Expand Down Expand Up @@ -369,6 +370,7 @@
"integrations/llms/openrouter",
"integrations/llms/ovhcloud",
"integrations/llms/perplexity-ai",
"integrations/llms/pinecone",
"integrations/llms/predibase",
"integrations/llms/reka-ai",
"integrations/llms/recraft-ai",
Expand Down
64 changes: 64 additions & 0 deletions integrations/llms/bedrock/rerank.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
---
title: "Rerank"
description: "Rerank documents with Amazon Bedrock"
---

Amazon Bedrock supports reranking documents using the Amazon Rerank model. Portkey provides a standardized interface for reranking through the unified `/v1/rerank` endpoint.

## Reranking Documents

```sh
curl https://api.portkey.ai/v1/rerank \
-H "Content-Type: application/json" \
-H "x-portkey-api-key: $PORTKEY_API_KEY" \
-d '{
"model": "@bedrock-prod/arn:aws:bedrock:us-east-1::foundation-model/cohere.rerank-v3-5:0",
"query": "What is the capital of the United States?",
"documents": [
"Carson City is the capital city of the American state of Nevada.",
"The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean. Its capital is Saipan.",
"Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) is the capital of the United States. It is a federal district.",
"Capital punishment (the death penalty) has existed in the United States since beforethe United States was a country. As of 2017, capital punishment is legal in 30 of the 50 states."
],
"top_n": 3
}'
```

## Supported Models

| Model | Model ID |
|-------|----------|
| Amazon Rerank | `amazon.rerank-v1:0` |

## Request Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `model` | string | Yes | The reranking model to use |
| `query` | string | Yes | The query to use for reranking |
| `documents` | array | Yes | List of documents to rerank |
| `top_n` | integer | No | Number of top results to return |

## Response Format

The response follows the unified Portkey rerank response format:

```json
{
"object": "list",
"model": "arn:aws:bedrock:us-east-1::foundation-model/cohere.rerank-v3-5:0",
"results": [
{
"index": 2,
"relevance_score": 0.95
},
{
"index": 0,
"relevance_score": 0.45
}
],
"usage": {
"total_tokens": 150
}
}
```
62 changes: 23 additions & 39 deletions integrations/llms/cohere.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,47 +108,31 @@ console.log(embedding);

### Re-ranking

You can use cohere reranking the `portkey.post` method with the body expected by [Cohere's reranking API](https://docs.cohere.com/reference/rerank-1).
Portkey supports Cohere's reranking models through a unified `/v1/rerank` endpoint.

```sh
curl https://api.portkey.ai/v1/rerank \
-H "Content-Type: application/json" \
-H "x-portkey-api-key: $PORTKEY_API_KEY" \
-d '{
"model": "@cohere-prod/rerank-v3.5",
"query": "What is the capital of the United States?",
"documents": [
"Carson City is the capital city of the American state of Nevada.",
"The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean. Its capital is Saipan.",
"Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) is the capital of the United States. It is a federal district.",
"Capital punishment (the death penalty) has existed in the United States since beforethe United States was a country. As of 2017, capital punishment is legal in 30 of the 50 states."
],
"top_n": 3
}'
```

<Tabs>
<Tab title="NodeJS SDK">
```js
const response = await portkey.post(
"/rerank",
{
"return_documents": false,
"max_chunks_per_doc": 10,
"model": "rerank-english-v2.0",
"query": "What is the capital of the United States?",
"documents": [
"Carson City is the capital city of the American state of Nevada.",
"The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean. Its capital is Saipan.",
"Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) is the capital of the United States. It is a federal district.",
"Capital punishment (the death penalty) has existed in the United States since beforethe United States was a country. As of 2017, capital punishment is legal in 30 of the 50 states."
]
}
)
```
</Tab>
<Tab title="Python SDK">
```python
response = portkey.post(
"/rerank",
return_documents=False,
max_chunks_per_doc=10,
model="rerank-english-v2.0",
query="What is the capital of the United States?",
documents=[
"Carson City is the capital city of the American state of Nevada.",
"The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean. Its capital is Saipan.",
"Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) is the capital of the United States. It is a federal district.",
"Capital punishment (the death penalty) has existed in the United States since beforethe United States was a country. As of 2017, capital punishment is legal in 30 of the 50 states."
]
)
```
</Tab>
#### Cohere-Specific Parameters

</Tabs>
| Parameter | Type | Description |
|-----------|------|-------------|
| `max_tokens_per_doc` | integer | Maximum number of tokens per document for processing |
| `priority` | integer | Request priority level |


## Next Steps
Expand Down
38 changes: 17 additions & 21 deletions integrations/llms/jina-ai.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,28 +89,24 @@ embeddings = portkey.embeddings.create(

### Using Jina AI Reranker Models

Portkey also supports the Reranker models by Jina AI through the REST API.
<Tabs>
<Tab title="cURL">
```sh
curl https://api.portkey.ai/v1/rerank \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $JINA_AI_API_KEY" \
-H "x-portkey-provider: jina" \
-d '{
"model": "jina-reranker-v1-base-en",
"query": "Organic skincare products for sensitive skin",
"documents": [
"Eco-friendly kitchenware for modern homes",
"Biodegradable cleaning supplies for eco-conscious consumers",
"Organic cotton baby clothes for sensitive skin"
],
"top_n": 2
}'
```
</Tab>
Portkey supports Jina AI's reranking models through a unified `/v1/rerank` endpoint.

</Tabs>
```sh
curl https://api.portkey.ai/v1/rerank \
-H "Content-Type: application/json" \
-H "x-portkey-api-key: $PORTKEY_API_KEY" \
-d '{
"model": "@jina-ai-prod/jina-reranker-v2-base-multilingual",
"query": "Organic skincare products for sensitive skin",
"documents": [
"Eco-friendly kitchenware for modern homes",
"Biodegradable cleaning supplies for eco-conscious consumers",
"Organic cotton baby clothes for sensitive skin",
"Natural organic skincare range for sensitive skin"
],
"top_n": 2
}'
```



Expand Down
87 changes: 87 additions & 0 deletions integrations/llms/pinecone.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
---
title: "Pinecone"
description: "Portkey provides a robust and secure gateway to facilitate the integration of Pinecone's reranking models into your applications."
---

With Portkey, you can take advantage of features like fast AI gateway access, observability, prompt management, and more, all while ensuring the secure management of your API keys through a [virtual key](/product/ai-gateway/virtual-keys) system.

<Note>
Provider Slug: **pinecone**
</Note>

## Portkey SDK Integration with Pinecone

Portkey provides a consistent API to interact with Pinecone's reranking models. To integrate Pinecone with Portkey:

### 1. Install the Portkey SDK

Add the Portkey SDK to your application to interact with Pinecone's models through Portkey's gateway.

<Tabs>
<Tab title="NodeJS">
```sh
npm install --save portkey-ai
```
</Tab>
<Tab title="Python">
```sh
pip install portkey-ai
```
</Tab>
</Tabs>

### 2. Initialize Portkey with the Virtual Key

To use Pinecone with Portkey, [get your API key from here](https://app.pinecone.io/), then add it to Portkey to create the virtual key.

### 3. Reranking with Pinecone

Portkey supports Pinecone's reranking models through a unified `/v1/rerank` endpoint.

```sh
curl https://api.portkey.ai/v1/rerank \
-H "Content-Type: application/json" \
-H "x-portkey-api-key: $PORTKEY_API_KEY" \
-d '{
"model": "@pinecone-dev/bge-reranker-v2-m3",
"query": "What is the capital of the United States?",
"documents": [
"Carson City is the capital city of the American state of Nevada.",
"The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean. Its capital is Saipan.",
"Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) is the capital of the United States. It is a federal district.",
"Capital punishment (the death penalty) has existed in the United States since beforethe United States was a country. As of 2017, capital punishment is legal in 30 of the 50 states."
],
"top_n": 3
}'
```

### Pinecone-Specific Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `rank_fields` | array | List of fields to rank by when documents are objects |
| `parameters` | object | Additional model-specific parameters |

## Supported Models

Portkey works with all the reranking models offered by Pinecone. You can browse the full list of Pinecone models [here](https://docs.pinecone.io/guides/inference/rerank).

| Model | Description |
|-------|-------------|
| `bge-reranker-v2-m3` | BGE Reranker v2 M3 model |
| `pinecone-rerank-v0` | Pinecone's native reranking model |

## Next Steps

The complete list of features supported in the SDK is available on the link below.

<Card title="SDK" icon="link" href="/api-reference/sdk">
Explore the SDK documentation
</Card>

You'll find more information in the relevant sections:

1. [Add metadata to your requests](/product/observability/metadata)
2. [Add gateway configs to your Pinecone requests](/product/ai-gateway/configs)
3. [Tracing Pinecone requests](/product/observability/traces)
4. [Setup a fallback from one reranking provider to another](/product/ai-gateway/fallbacks)
61 changes: 24 additions & 37 deletions integrations/llms/voyage-ai.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,43 +89,30 @@ Embedding endpoints are natively supported within Portkey like this:

### Re-ranking

You can use Voyage reranking the `portkey.post` method with the body expected by Voyage

<Tabs>
<Tab title="NodeJS SDK">
```javascript
const response = await portkey.post(
"/rerank",
{
"model": "rerank-2-lite",
"query": "What is the capital of the United States?",
"documents": [
"Carson City is the capital city of the American state of Nevada.",
"The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean. Its capital is Saipan.",
"Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) is the capital of the United States. It is a federal district.",
"Capital punishment (the death penalty) has existed in the United States since beforethe United States was a country. As of 2017, capital punishment is legal in 30 of the 50 states."
]
})
```
</Tab>
<Tab title="Python SDK">
```python
response = portkey.post(
"/rerank",
model="rerank-2-lite",
query="What is the capital of the United States?",
documents=[
"Carson City is the capital city of the American state of Nevada.",
"The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean. Its capital is Saipan.",
"Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) is the capital of the United States. It is a federal district.",
"Capital punishment (the death penalty) has existed in the United States since beforethe United States was a country. As of 2017, capital punishment is legal in 30 of the 50 states."
]
)

print(response)
```
</Tab>
</Tabs>
Portkey supports Voyage AI's reranking models through a unified `/v1/rerank` endpoint.

```sh
curl https://api.portkey.ai/v1/rerank \
-H "Content-Type: application/json" \
-H "x-portkey-api-key: $PORTKEY_API_KEY" \
-d '{
"model": "@voyage-ai-prod/rerank-2",
"query": "What is the capital of the United States?",
"documents": [
"Carson City is the capital city of the American state of Nevada.",
"The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean. Its capital is Saipan.",
"Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) is the capital of the United States. It is a federal district.",
"Capital punishment (the death penalty) has existed in the United States since beforethe United States was a country. As of 2017, capital punishment is legal in 30 of the 50 states."
],
"top_n": 3
}'
```

#### Voyage-Specific Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `truncation` | boolean | Whether to truncate documents that exceed the model's context length |

## Next Steps

Expand Down