# Improve the relevance of query responses with a reranker model in Amazon Bedrock
Amazon Bedrock provides access to reranker models that you can use when querying to improve the relevance of the retrieved results. A reranker model calculates the relevance of chunks to a query and reorders the results based on the scores that it calculates. By using a reranker model, you can return responses that are better suited to answering the query. Or, you can include the results in a prompt when running model inference to generate more pertinent and accurate responses. With a reranker model, you can retrieve fewer, but more relevant, results. By feeding these results to the foundation model that you use to generate a response, you can also decrease cost and latency.
Reranker models are trained to identify relevance signals based on a query and then use those signals to rank documents. Because of this, the models can provide more relevant, more accurate results.
**Note**
You can use reranking for only textual data.
For information about pricing for reranking models, see [Amazon Bedrock Pricing](https://aws.amazon.com/bedrock/pricing/).
Reranking requires the following input, at the minimum:
+ A reranker model that takes a user query and assesses the relevance of the data sources that it can access.
+ The user query.
+ A list of documents that the reranker must reorder according to their relevance to the query.
You can use reranker models in Amazon Bedrock in the following ways:
+ Call the [Rerank](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Rerank.html) operation directly through the Amazon Bedrock API. The `Rerank` operation sends the query, documents, and any additional configurations as input to a reranker model. The model then reranks the documents by relevance to the query and returns the documents in the response.
+ If you're using [Amazon Bedrock Knowledge Bases](knowledge-base.md) for building your Retrieval Augmented Generation (RAG) application, use a reranker model while calling the [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Retrieve.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Retrieve.html) or [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrieveAndGenerate.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrieveAndGenerate.html) operation or when querying your knowledge base in the AWS Management Console. The results from reranking override the default ranking that Amazon Bedrock Knowledge Bases determines.
**Topics**
+ [Supported Regions/models](rerank-supported.md)
+ [Permissions](rerank-prereq.md)
+ [Use a reranker model](rerank-use.md)
# Supported Regions and models for reranking in Amazon Bedrock
The following list provides links to general information about Regional and model support in Amazon Bedrock:
+ For a list of Region codes and endpoints supported in Amazon Bedrock, see [Amazon Bedrock endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bedrock_region).
+ For a list of Amazon Bedrock model IDs to use when calling Amazon Bedrock API operations, see [Supported foundation models in Amazon Bedrock](models-supported.md).
The following table shows the reranker models you can use and the Regions in which they are supported:
**Note**
The Amazon Rerank 1.0 model is not supported in the US East (N. Virginia) AWS Region. You can only use the Cohere Rerank 3.5 model in this Region.
The following table shows model support for reranking:
| Provider | Model | Model ID | Single-region model support |
| --- | --- | --- | --- |
| Amazon | Rerank 1.0 | amazon.rerank-v1:0 | ap-northeast-1 ca-central-1 eu-central-1 us-west-2 |
| Cohere | Rerank 3.5 | cohere.rerank-v3-5:0 | ap-northeast-1 ca-central-1 eu-central-1 us-east-1 us-west-2 |
For more information about reranking with Cohere models and their inference parameters, see [Rerank](https://docs.cohere.com/reference/rerank) on the Cohere documentation website.
# Permissions for reranking in Amazon Bedrock
A user requires the following permissions to use reranking:
+ Access to the reranking models that they plan to use. For more information, see [Access Amazon Bedrock foundation models](model-access.md).
+ Permissions for their role and, if they plan to use reranking in a [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Retrieve.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Retrieve.html) workflow, permissions for the Amazon Bedrock Knowledge Bases service role that has a [trust relationship](kb-permissions.md#kb-permissions-trust) with their role.
**Tip**
To configure the required permissions quickly, you can do the following:
Attach the [AmazonBedrockFullAccess](security-iam-awsmanpol.md#security-iam-awsmanpol-AmazonBedrockFullAccess) AWS managed policy to the user role. For more information about attaching a policy to an IAM role, see [Adding and removing IAM identity permissions](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html).
Use the Amazon Bedrock console to create an Amazon Bedrock Knowledge Bases service role when [creating a knowledge base](knowledge-base-create.md). If you already have an Amazon Bedrock Knowledge Bases service role that the console created for you, you can use the console to update it when [retrieving sources](kb-test-retrieve.md) in the console.
**Important**
When you use reranking in a `Retrieve` workflow with an Amazon Bedrock Knowledge Bases service role, note the following:
If you manually edit the AWS Identity and Access Management (IAM) policy that Amazon Bedrock created for your knowledge base service role, then you might encounter errors when trying to update the permissions in the AWS Management Console. To resolve this issue, in the IAM console, delete the policy version that you created manually. Then, refresh the reranker page in the Amazon Bedrock console and retry.
If you use a custom role, then Amazon Bedrock can't update the knowledge base service role on your behalf. Verify that the permissions are properly configured for the service role.
For a summary of use cases and the permissions needed for them, refer to the following table:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/bedrock/latest/userguide/rerank-prereq.html)
For example permissions policies that you can attach to an IAM role, expand the section that corresponds to your use case:
## Permissions policy for using a reranking model independently
To use [Rerank](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Rerank.html) directly with a list of sources, the user role needs permissions to use both the `bedrock:Rerank` and `bedrock:InvokeModel` actions. Similarly, to prevent usage of a reranking model, you must deny permissions for both actions. To allow the user role to use a reranking model independently, you can attach the following policy to the role:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "RerankSid",
"Effect": "Allow",
"Action": [
"bedrock:Rerank"
],
"Resource": "*"
},
{
"Sid": "InvokeModelSid",
"Effect": "Allow",
"Action": [
"bedrock:InvokeModel"
],
"Resource": [
"arn:aws:bedrock:us-east-1::foundation-model/model-id"
]
}
]
}
```
------
In the preceding policy, for the `bedrock:InvokeModel` action, you scope the permissions to the models that you want to allow the role to use for reranking. To allow access to all models, use a wildcard (*\$1*) in the `Resource` field.
## Permissions policies for using a reranking model in a Retrieve workflow
To use reranking while retrieving data from a knowledge base, you must set up the following permissions:
**For the user role**
The user role needs permissions to use the `bedrock:Retrieve` action. To allow the user role to retrieve data from a knowledge base, you can attach the following policy to the role:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "RetrieveSid",
"Effect": "Allow",
"Action": [
"bedrock:Retrieve"
],
"Resource": [
"arn:aws:bedrock:us-east-1:123456789012:knowledge-base/KnowledgeBaseId"
]
}
]
}
```
------
In the preceding policy, for the `bedrock:Retrieve` action, you scope the permissions to the knowledge bases from which you want to allow the role to retrieve information. To allow access to all knowledge bases, you can use a wildcard (*\$1*) in the `Resource` field.
**For the service role**
The [Amazon Bedrock Knowledge Bases service role](kb-permissions.md) that the user uses needs permissions to use the `bedrock:Rerank` and `bedrock:InvokeModel` actions. You can use the Amazon Bedrock console to configure permissions for your service role automatically when you choose a reranking model when you [configure knowledge base retrieval](kb-test-retrieve.md). Otherwise, to allow the service role to rerank sources during retrieval, you can attach the following policy:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "RerankSid",
"Effect": "Allow",
"Action": [
"bedrock:Rerank"
],
"Resource": "*"
},
{
"Sid": "InvokeModelSid",
"Effect": "Allow",
"Action": [
"bedrock:InvokeModel"
],
"Resource": "arn:aws:bedrock:us-east-1::foundation-model/RerankModelId"
}
]
}
```
------
In the preceding policy, for the `bedrock:InvokeModel` action, you scope the permissions to the models that you want to allow the role to use for reranking. To allow access to all models, you can use a wildcard (\$1) in the `Resource` field.
## Permissions policy for using a reranking model in a RetrieveAndGenerate workflow
To use a reranker model when retrieving data from a knowledge base and subsequently generating responses based on the retrieved results, the user role needs permissions to use the `bedrock:RetrieveAndGenerate`, `bedrock:Rerank`, and `bedrock:InvokeModel` actions. To allow reranking of sources during retrieval, and to allow generation of responses based on the results, you can attach the following policy to the user role:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "RerankRetrieveAndGenerateSid",
"Effect": "Allow",
"Action": [
"bedrock:Rerank",
"bedrock:RetrieveAndGenerate"
],
"Resource": "*"
},
{
"Sid": "InvokeModelSid",
"Effect": "Allow",
"Action": [
"bedrock:InvokeModel"
],
"Resource": [
"arn:aws:bedrock:us-east-1::foundation-model/RerankModelId}",
"arn:aws:bedrock:us-east-1::foundation-model/GenerationModelId}"
]
}
]
}
```
------
In the preceding policy, for the `bedrock:InvokeModel` operation, you scope the permissions to the models that you want to allow the role to use for reranking, and to the models that you want to allow the role to use for generating responses. To allow access to all models, you can use a wildcard (*\$1*) in the `Resource` field.
To further restrict permissions, you can omit actions, or you can specify resources and condition keys by which to filter permissions. For more information about actions, resources, and condition keys, see the following topics in the *Service Authorization Reference*:
+ [Actions defined by Amazon Bedrock](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonbedrock.html#amazonbedrock-actions-as-permissions) – Learn about actions, the resource types that you can scope them to in the `Resource` field, and the condition keys that you can filter permissions on in the `Condition` field.
+ [Resource types defined by Amazon Bedrock](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonbedrock.html#amazonbedrock-resources-for-iam-policies) – Learn about the resource types in Amazon Bedrock.
+ [Condition keys for Amazon Bedrock](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonbedrock.html#amazonbedrock-policy-keys) – Learn about the condition keys in Amazon Bedrock.
# Use a reranker model in Amazon Bedrock
You can use a reranker model directly or while retrieving results during knowledge base query. Choose the tab for your preferred method, and then follow the steps:
------
#### [ Console ]
You can't use a reranker model directly in the AWS Management Console, but you can use a reranker model when querying your knowledge base by doing the following:
1. When you query a knowledge base, open up the **Configurations** pane by choosing the ![\[Three horizontal sliders with adjustable circular controls for settings or parameters.\]](http://docs.aws.amazon.com/bedrock/latest/userguide/images/icons/configurations.png) icon.
1. Expand the **Reranking** section.
1. Choose **Select model** and select a reranker model.
1. If your Amazon Bedrock Knowledge Bases service role is missing [permissions to use the reranker model](rerank-prereq.md), select **Update service role** to modify the role with the proper permissions.
1. (Optional) In the **Additional Reranking options** section, modify any options that you need to.
1. Enter a prompt and select **Run**. The response is the result after applying the reranker model.
For more detailed instructions about carrying out knowledge base query, see [Query a knowledge base and retrieve data](kb-test-retrieve.md) and [Query a knowledge base and generate responses based off the retrieved data](kb-test-retrieve-generate.md).
------
#### [ API ]
For instructions on using a reranker model during knowledge base query, see [Query a knowledge base and retrieve data](kb-test-retrieve.md) and [Query a knowledge base and generate responses based off the retrieved data](kb-test-retrieve-generate.md).
To use a reranker model directly with the Amazon Bedrock API, send a [Rerank](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Rerank.html) request with an [Agents for Amazon Bedrock runtime endpoint](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-rt).
The following fields are required:
****
| Field | Basic description |
| --- | --- |
| queries | An array of one [RerankQuery](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RerankQuery.html) object. Specify TEXT as the type and include the query in the textQuery field. |
| sources | An array of [RerankSource](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RerankSource.html) objects to submit to the reranking model. For each RerankSource, specify INLINE as the type and include a [RerankDocument](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RerankDocument.html) object in the inlineDocumentSource field. See below for details about RerankDocument. |
| rerankingConfiguration | Includes the Amazon Resource Name (ARN) of the reranking model to use, and the number of results to return after reranking, and, optionally, inference configurations for the model. You specify additional model configurations as key-value pairs. For more information, see [Rerank](https://docs.cohere.com/reference/rerank) on the Cohere documentation website. |
The following fields are optional:
****
| Field | Use case |
| --- | --- |
| nextToken | A token returned in a previous response that you can include to provide the next batch of results. |
The format of the `RerankSource` object that you include depends on the format of the document. To see the format for different `RerankSource` types, choose the tab that corresponds to the format of the document:
------
#### [ String ]
If the document is a string, then specify the value of the `type` field of the [RerankDocument](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RerankDocument.html) object as `TEXT` and include the document in the `text` field. For example:
```
{
"inlineDocumentSource": {
"textDocument": {
"text": "string"
},
"type": "TEXT"
},
"type": "INLINE"
}
```
------
#### [ JSON object ]
If the document is a JSON object, then specify the value of the `type` field in the [RerankDocument](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RerankDocument.html) object as `JSON` and include the document in the `jsonDocument` field. For example:
```
{
"inlineDocumentSource": {
"jsonDocument": JSON value,
"type": "JSON"
},
"type": "INLINE"
}
```
------
The response to your `Rerank` request returns a list of [RerankResult](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RerankResult.html) objects in the `results` field. Each object contains the following fields:
+ `document` – Includes information about the document that you submitted.
+ `relevanceScore` – A relevance score for the document, assigned by the reranking model.
+ `index` – Indicates the document's ranking relative to the other documents in the list. The lower the score, the higher the ranking.
If there are too many results to display, then the response returns a value in the `nextToken` field. In this case, to see the next batch of results, include that token in a subsequent request.
------