From db3216c08c78203fc14282c76f3a41c80d6541b7 Mon Sep 17 00:00:00 2001 From: Narendranath Gogineni Date: Thu, 15 Jan 2026 11:27:09 +0530 Subject: [PATCH 1/3] add documentation for rerank unified route --- docs.json | 2 + integrations/llms/bedrock/rerank.mdx | 72 +++++++++++++++++++++++ integrations/llms/cohere.mdx | 63 ++++++++------------ integrations/llms/jina-ai.mdx | 39 ++++++------ integrations/llms/pinecone.mdx | 88 ++++++++++++++++++++++++++++ integrations/llms/voyage-ai.mdx | 62 ++++++++------------ 6 files changed, 229 insertions(+), 97 deletions(-) create mode 100644 integrations/llms/bedrock/rerank.mdx create mode 100644 integrations/llms/pinecone.mdx diff --git a/docs.json b/docs.json index 2f5569b2..afba7255 100644 --- a/docs.json +++ b/docs.json @@ -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" ] }, @@ -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", diff --git a/integrations/llms/bedrock/rerank.mdx b/integrations/llms/bedrock/rerank.mdx new file mode 100644 index 00000000..762ea2a1 --- /dev/null +++ b/integrations/llms/bedrock/rerank.mdx @@ -0,0 +1,72 @@ +--- +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/amazon.rerank-v1: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, + "return_documents": true + }' +``` + +## 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 | +| `return_documents` | boolean | No | Whether to return documents in the response | + +## Response Format + +The response follows the unified Portkey rerank response format: + +```json +{ + "object": "list", + "model": "amazon.rerank-v1:0", + "results": [ + { + "index": 2, + "relevance_score": 0.95, + "document": { + "text": "Washington, D.C. ..." + } + }, + { + "index": 0, + "relevance_score": 0.45, + "document": { + "text": "Carson City is ..." + } + } + ], + "usage": { + "total_tokens": 150 + } +} +``` diff --git a/integrations/llms/cohere.mdx b/integrations/llms/cohere.mdx index 703ca095..d0118415 100644 --- a/integrations/llms/cohere.mdx +++ b/integrations/llms/cohere.mdx @@ -108,47 +108,32 @@ 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, + "return_documents": true + }' +``` - - - ```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." - ] - } - ) - ``` - - - ```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." - ] - ) - ``` - +#### Cohere-Specific Parameters - +| Parameter | Type | Description | +|-----------|------|-------------| +| `max_tokens_per_doc` | integer | Maximum number of tokens per document for processing | +| `priority` | integer | Request priority level | ## Next Steps diff --git a/integrations/llms/jina-ai.mdx b/integrations/llms/jina-ai.mdx index df755dc4..5221615a 100644 --- a/integrations/llms/jina-ai.mdx +++ b/integrations/llms/jina-ai.mdx @@ -89,28 +89,25 @@ embeddings = portkey.embeddings.create( ### Using Jina AI Reranker Models -Portkey also supports the Reranker models by Jina AI through the REST API. - - - ```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 - }' - ``` - +Portkey supports Jina 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": "@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, + "return_documents": true +}' +``` diff --git a/integrations/llms/pinecone.mdx b/integrations/llms/pinecone.mdx new file mode 100644 index 00000000..d8cb8f23 --- /dev/null +++ b/integrations/llms/pinecone.mdx @@ -0,0 +1,88 @@ +--- +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. + + +Provider Slug: **pinecone** + + +## 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. + + + + ```sh + npm install --save portkey-ai + ``` + + + ```sh + pip install portkey-ai + ``` + + + +### 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, + "return_documents": true + }' +``` + +### 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. + + + Explore the SDK documentation + + +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) diff --git a/integrations/llms/voyage-ai.mdx b/integrations/llms/voyage-ai.mdx index fcea3c42..0876c2c2 100644 --- a/integrations/llms/voyage-ai.mdx +++ b/integrations/llms/voyage-ai.mdx @@ -89,43 +89,31 @@ 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 - - - - ```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." - ] - }) - ``` - - - ```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) - ``` - - +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, + "return_documents": true + }' +``` + +#### Voyage-Specific Parameters + +| Parameter | Type | Description | +|-----------|------|-------------| +| `truncation` | boolean | Whether to truncate documents that exceed the model's context length | ## Next Steps From 261f623a34df4ee5050b76effa06379adc861646 Mon Sep 17 00:00:00 2001 From: Narendranath Gogineni Date: Thu, 15 Jan 2026 11:37:36 +0530 Subject: [PATCH 2/3] update documentation --- integrations/llms/bedrock/rerank.mdx | 14 +++----------- integrations/llms/cohere.mdx | 3 +-- integrations/llms/jina-ai.mdx | 3 +-- integrations/llms/pinecone.mdx | 3 +-- integrations/llms/voyage-ai.mdx | 3 +-- 5 files changed, 7 insertions(+), 19 deletions(-) diff --git a/integrations/llms/bedrock/rerank.mdx b/integrations/llms/bedrock/rerank.mdx index 762ea2a1..3c55220a 100644 --- a/integrations/llms/bedrock/rerank.mdx +++ b/integrations/llms/bedrock/rerank.mdx @@ -20,8 +20,7 @@ curl https://api.portkey.ai/v1/rerank \ "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, - "return_documents": true + "top_n": 3 }' ``` @@ -39,7 +38,6 @@ curl https://api.portkey.ai/v1/rerank \ | `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 | -| `return_documents` | boolean | No | Whether to return documents in the response | ## Response Format @@ -52,17 +50,11 @@ The response follows the unified Portkey rerank response format: "results": [ { "index": 2, - "relevance_score": 0.95, - "document": { - "text": "Washington, D.C. ..." - } + "relevance_score": 0.95 }, { "index": 0, - "relevance_score": 0.45, - "document": { - "text": "Carson City is ..." - } + "relevance_score": 0.45 } ], "usage": { diff --git a/integrations/llms/cohere.mdx b/integrations/llms/cohere.mdx index d0118415..61f2fd2f 100644 --- a/integrations/llms/cohere.mdx +++ b/integrations/llms/cohere.mdx @@ -123,8 +123,7 @@ curl https://api.portkey.ai/v1/rerank \ "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, - "return_documents": true + "top_n": 3 }' ``` diff --git a/integrations/llms/jina-ai.mdx b/integrations/llms/jina-ai.mdx index 5221615a..4b987a69 100644 --- a/integrations/llms/jina-ai.mdx +++ b/integrations/llms/jina-ai.mdx @@ -104,8 +104,7 @@ curl https://api.portkey.ai/v1/rerank \ "Organic cotton baby clothes for sensitive skin", "Natural organic skincare range for sensitive skin" ], - "top_n": 2, - "return_documents": true + "top_n": 2 }' ``` diff --git a/integrations/llms/pinecone.mdx b/integrations/llms/pinecone.mdx index d8cb8f23..7dca02c4 100644 --- a/integrations/llms/pinecone.mdx +++ b/integrations/llms/pinecone.mdx @@ -51,8 +51,7 @@ curl https://api.portkey.ai/v1/rerank \ "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, - "return_documents": true + "top_n": 3 }' ``` diff --git a/integrations/llms/voyage-ai.mdx b/integrations/llms/voyage-ai.mdx index 0876c2c2..aa9288ce 100644 --- a/integrations/llms/voyage-ai.mdx +++ b/integrations/llms/voyage-ai.mdx @@ -104,8 +104,7 @@ curl https://api.portkey.ai/v1/rerank \ "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, - "return_documents": true + "top_n": 3 }' ``` From a708d6d3a6ad3794fa4955c9e5f6dc43dfbe1704 Mon Sep 17 00:00:00 2001 From: Narendranath Gogineni <47327611+narengogi@users.noreply.github.com> Date: Thu, 15 Jan 2026 18:58:18 +0530 Subject: [PATCH 3/3] Update rerank.mdx --- integrations/llms/bedrock/rerank.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/integrations/llms/bedrock/rerank.mdx b/integrations/llms/bedrock/rerank.mdx index 3c55220a..b497ebe5 100644 --- a/integrations/llms/bedrock/rerank.mdx +++ b/integrations/llms/bedrock/rerank.mdx @@ -12,7 +12,7 @@ curl https://api.portkey.ai/v1/rerank \ -H "Content-Type: application/json" \ -H "x-portkey-api-key: $PORTKEY_API_KEY" \ -d '{ - "model": "@bedrock-prod/amazon.rerank-v1:0", + "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.", @@ -46,7 +46,7 @@ The response follows the unified Portkey rerank response format: ```json { "object": "list", - "model": "amazon.rerank-v1:0", + "model": "arn:aws:bedrock:us-east-1::foundation-model/cohere.rerank-v3-5:0", "results": [ { "index": 2,