Skip to content

Commit 960009f

Browse files
aninibreadOxyjunNaapperas
authored
Reranking documentation (#25867)
* reranking documentation * add parameters * changelog and system prompt changes * Apply suggestions from code review * Update src/content/docs/ai-search/usage/rest-api.mdx Co-authored-by: Nuno Pereira <nunoafonso2002@gmail.com> * Update src/content/docs/ai-search/usage/rest-api.mdx Co-authored-by: Nuno Pereira <nunoafonso2002@gmail.com> --------- Co-authored-by: Jun Lee <junlee@cloudflare.com> Co-authored-by: Nuno Pereira <nunoafonso2002@gmail.com>
1 parent 44e9825 commit 960009f

File tree

10 files changed

+205
-13
lines changed

10 files changed

+205
-13
lines changed

‎src/content/changelog/ai-search/2025-10-27-ai-search-reranking-system-prompt.mdx‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
title: Reranking and API-based system prompt configuration in AI Search
3+
description: Improve result accuracy with reranking and dynamically control AI Search responses by setting system prompts in API requests.
4+
products:
5+
- ai-search
6+
date: 2025-10-28
7+
---
8+
9+
[AI Search](/ai-search/) now supports reranking for improved retrieval quality and allows you to set the system prompt directly in your API requests.
10+
11+
## Rerank for more relevant results
12+
13+
You can now enable [reranking](/ai-search/configuration/reranking/) to reorder retrieved documents based on their semantic relevance to the user’s query. Reranking helps improve accuracy, especially for large or noisy datasets where vector similarity alone may not produce the optimal ordering.
14+
15+
You can enable and configure reranking in the dashboard or directly in your API requests:
16+
17+
```javascript
18+
const answer = await env.AI.autorag("my-autorag").aiSearch({
19+
query: "How do I train a llama to deliver coffee?",
20+
model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
21+
reranking: {
22+
enabled: true,
23+
model: "@cf/baai/bge-reranker-base"
24+
}
25+
});
26+
```
27+
28+
## Set system prompts in API
29+
30+
Previously, [system prompts](/ai-search/configuration/system-prompt/) could only be configured in the dashboard. You can now define them directly in your API requests, giving you per-query control over behavior. For example:
31+
32+
```javascript
33+
// Dynamically set query and system prompt in AI Search
34+
async function getAnswer(query, tone) {
35+
const systemPrompt = `You are a ${tone} assistant.`;
36+
37+
const response = await env.AI.autorag("my-autorag").aiSearch({
38+
query: query,
39+
system_prompt: systemPrompt
40+
});
41+
42+
return response;
43+
}
44+
45+
// Example usage
46+
const query = "What is Cloudflare?";
47+
const tone = "friendly";
48+
49+
const answer = await getAnswer(query, tone);
50+
console.log(answer);
51+
```
52+
53+
Learn more about [Reranking](/ai-search/configuration/reranking/) and [System Prompt](/ai-search/configuration/system-prompt/) in AI Search.
54+

‎src/content/docs/ai-search/configuration/index.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ The table below lists all available configuration options:
2222
| [Query rewrite system prompt](/ai-search/configuration/system-prompt/) | yes | Custom system prompt to guide query rewriting behavior |
2323
| [Match threshold](/ai-search/configuration/retrieval-configuration/) | yes | Minimum similarity score required for a vector match |
2424
| [Maximum number of results](/ai-search/configuration/retrieval-configuration/) | yes | Maximum number of vector matches returned (`top_k`) |
25+
| [Reranking](/ai-search/configuration/reranking/) | yes | Rerank to reorder retrieved results by semantic relevance using a reranking model after initial retrieval |
2526
| [Generation model](/ai-search/configuration/models/) | yes | Model used to generate the final response |
2627
| [Generation system prompt](/ai-search/configuration/system-prompt/) | yes | Custom system prompt to guide response generation |
2728
| [Similarity caching](/ai-search/configuration/cache/) | yes | Enable or disable caching of responses for similar (not just exact) prompts |

‎src/content/docs/ai-search/configuration/models/supported-models.mdx‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,11 @@ Production models are the actively supported and recommended models that are sta
5050
| **Workers AI** | `@cf/baai/bge-m3` | 1,024 | 512 | cosine |
5151
| | `@cf/baai/bge-large-en-v1.5` | 1,024 | 512 | cosine |
5252

53+
### Reranking
54+
| Provider | Alias | Input tokens |
55+
|---|---|---|
56+
| **Workers AI** | `@cf/baai/bge-reranker-base` | 512 |
57+
5358
## Transition models
5459

5560
There are currently no models marked for end-of-life.

‎src/content/docs/ai-search/configuration/reranking.mdx‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
---
2+
pcx_content_type: concept
3+
title: Reranking
4+
sidebar:
5+
order: 4
6+
---
7+
8+
import { DashButton } from "~/components";
9+
10+
Reranking can help improve the quality of AI Search results by reordering retrieved documents based on semantic relevance to the user’s query. It applies a secondary model after retrieval to "rerank" the top results before they are outputted.
11+
12+
## How it works
13+
14+
By default, reranking is **disabled** for all AI Search instances. You can enable it during creation or later from the settings page.
15+
16+
When enabled, AI Search will:
17+
18+
1. Retrieve a set of relevant results from your index, constrained by your `max_num_of_results` and `score_threshold` parameters.
19+
2. Pass those results through a [reranking model](/ai-search/configuration/models/supported-models/).
20+
3. Return the reranked results, which the text generation model can use for answer generation.
21+
22+
Reranking helps improve accuracy, especially for large or noisy datasets where vector similarity alone may not produce the optimal ordering.
23+
24+
## Configuration
25+
26+
You can configure reranking in several ways:
27+
28+
### Configure via API
29+
30+
When you make a `/search` or `/ai-search` request using the [Workers Binding](/ai-search/usage/workers-binding/) or [REST API](/ai-search/usage/rest-api/), you can:
31+
32+
- Enable or disable reranking per request
33+
- Specify the reranking model
34+
35+
For example:
36+
37+
```javascript
38+
const answer = await env.AI.autorag("my-autorag").aiSearch({
39+
query: "How do I train a llama to deliver coffee?",
40+
model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
41+
reranking: {
42+
enabled: true,
43+
model: "@cf/baai/bge-reranker-base"
44+
}
45+
});
46+
```
47+
48+
### Configure in dashboard for new AI Search
49+
50+
When creating a new RAG in the dashboard:
51+
52+
1. Go to **AI Search** in the Cloudflare dashboard.
53+
54+
<DashButton url="/?to=/:account/ai/ai-search" />
55+
56+
2. Select **Create** > **Get started**.
57+
3. In the **Retrieval configuration** step, open the **Reranking** dropdown.
58+
4. Toggle **Reranking** on.
59+
5. Select the reranking model.
60+
6. Complete your setup.
61+
62+
### Configure in dashboard for existing AI Search
63+
64+
To update reranking for an existing instance:
65+
66+
1. Go to **AI Search** in the Cloudflare dashboard.
67+
68+
<DashButton url="/?to=/:account/ai/ai-search" />
69+
70+
2. Select an existing AI Search instance.
71+
3. Go to the **Settings** tab.
72+
4. Under **Reranking**, toggle reranking on.
73+
5. Select the reranking model.
74+

‎src/content/docs/ai-search/configuration/system-prompt.mdx‎

Lines changed: 26 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -21,13 +21,7 @@ System prompts are particularly useful for:
2121
- Applying domain-specific tone or terminology
2222
- Encouraging consistent, high-quality output
2323

24-
## How to set your system prompt
25-
26-
The system prompt for your AI Search can be set after it has been created by:
27-
28-
1. Navigating to the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/ai/autorag), and go to AI > AI Search
29-
2. Select your AI Search
30-
3. Go to Settings page and find the System prompt setting for either Query rewrite or Generation
24+
## System prompt configuration
3125

3226
### Default system prompt
3327

@@ -39,6 +33,31 @@ You can view the effective system prompt used for any AI Search's model call thr
3933
The default system prompt can change and evolve over time to improve performance and quality.
4034
:::
4135

36+
### Configure via API
37+
38+
When you make a `/ai-search` request using the [Workers Binding](/ai-search/usage/workers-binding/) or [REST API](/ai-search/usage/rest-api/), you can set the system prompt programmatically.
39+
40+
For example:
41+
42+
```javascript
43+
const answer = await env.AI.autorag("my-autorag").aiSearch({
44+
query: "How do I train a llama to deliver coffee?",
45+
model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
46+
system_prompt: "You are a helpful assistant."
47+
});
48+
```
49+
50+
import { DashButton } from "~/components";
51+
52+
### Configure via Dashboard
53+
The system prompt for your AI Search can be set after it has been created:
54+
55+
1. Go to **AI Search** in the Cloudflare dashboard.
56+
<DashButton url="/?to=/:account/ai/ai-search" />
57+
2. Select an existing AI Search instance.
58+
3. Go to the **Settings** tab.
59+
4. Go to **Query rewrite** or **Generation**, and edit the **System prompt**.
60+
4261
## Query rewriting system prompt
4362

4463
If query rewriting is enabled, you can provide a custom system prompt to control how the model rewrites user queries. In this step, the model receives:

‎src/content/docs/ai-search/usage/rest-api.mdx‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,11 @@ curl https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai-search/rags/{
5252
"rewrite_query": false,
5353
"max_num_results": 10,
5454
"ranking_options": {
55-
"score_threshold": 0.3
55+
"score_threshold": 0.3,
56+
},
57+
"reranking": {
58+
"enabled": true,
59+
"model": "@cf/baai/bge-reranker-base"
5660
},
5761
"stream": true,
5862
}'
@@ -89,9 +93,12 @@ curl https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai-search/rags/{
8993
"rewrite_query": true,
9094
"max_num_results": 10,
9195
"ranking_options": {
92-
"score_threshold": 0.3
96+
"score_threshold": 0.3,
9397
},
94-
}'
98+
"reranking": {
99+
"enabled": true,
100+
"model": "@cf/baai/bge-reranker-base"
101+
}'
95102

96103
```
97104

‎src/content/docs/ai-search/usage/workers-binding.mdx‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,8 +46,12 @@ const answer = await env.AI.autorag("my-autorag").aiSearch({
4646
rewrite_query: true,
4747
max_num_results: 2,
4848
ranking_options: {
49-
score_threshold: 0.3,
49+
score_threshold: 0.3
5050
},
51+
reranking: {
52+
enabled: true,
53+
model: "@cf/baai/bge-reranker-base"
54+
},
5155
stream: true,
5256
});
5357
```
@@ -115,8 +119,12 @@ const answer = await env.AI.autorag("my-autorag").search({
115119
rewrite_query: true,
116120
max_num_results: 2,
117121
ranking_options: {
118-
score_threshold: 0.3,
122+
score_threshold: 0.3
119123
},
124+
reranking: {
125+
enabled: true,
126+
model: "@cf/baai/bge-reranker-base"
127+
}
120128
});
121129
```
122130

‎src/content/docs/r2/api/tokens.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ To create an API token:
2020
1. In the Cloudflare dashboard, go to the **R2 object storage** page.
2121

2222
<DashButton url="/?to=/:account/r2/overview" />
23-
2. Select **Manage API tokens**.
23+
2. Select **Manage in API tokens**.
2424
3. Choose to create either:
2525
- **Create Account API token** - These tokens are tied to the Cloudflare account itself and can be used by any authorized system or user. Only users with the Super Administrator role can view or create them. These tokens remain valid until manually revoked.
2626
- **Create User API token** - These tokens are tied to your individual Cloudflare user. They inherit your personal permissions and become inactive if your user is removed from the account.

‎src/content/partials/ai-search/ai-search-api-params.mdx‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,10 @@ The input query.
1212

1313
The text-generation model that is used to generate the response for the query. For a list of valid options, check the AI Search Generation model Settings. Defaults to the generation model selected in the AI Search Settings.
1414

15+
`system_prompt` <Type text="string" /> <MetaInfo text="optional" />
16+
17+
The system prompt for generating the answer.
18+
1519
`rewrite_query` <Type text="boolean" /> <MetaInfo text="optional" />
1620

1721
Rewrites the original query into a search optimized query to improve retrieval accuracy. Defaults to `false`.
@@ -27,6 +31,16 @@ Configurations for customizing result ranking. Defaults to `{}`.
2731
- `score_threshold` <Type text="number" /> <MetaInfo text="optional" />
2832
- The minimum match score required for a result to be considered a match. Defaults to `0`. Must be between `0` and `1`.
2933

34+
`reranking` <Type text="object" /> <MetaInfo text="optional" />
35+
36+
Configurations for customizing reranking. Defaults to `{}`.
37+
38+
- `enabled` <Type text="boolean" /> <MetaInfo text="optional" />
39+
- Enables or disables reranking, which reorders retrieved results based on semantic relevance using a reranking model. Defaults to `false`.
40+
41+
- `model` <Type text="string" /> <MetaInfo text="optional" />
42+
- The reranking model to use when reranking is enabled.
43+
3044
`stream` <Type text="boolean" /> <MetaInfo text="optional" />
3145

3246
Returns a stream of results as they are available. Defaults to `false`.

‎src/content/partials/ai-search/search-api-params.mdx‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,16 @@ Configurations for customizing result ranking. Defaults to `{}`.
2323
- `score_threshold` <Type text="number" /> <MetaInfo text="optional" />
2424
- The minimum match score required for a result to be considered a match. Defaults to `0`. Must be between `0` and `1`.
2525

26+
`reranking` <Type text="object" /> <MetaInfo text="optional" />
27+
28+
Configurations for customizing reranking. Defaults to `{}`.
29+
30+
- `enabled` <Type text="boolean" /> <MetaInfo text="optional" />
31+
- Enables or disables reranking, which reorders retrieved results based on semantic relevance using a reranking model. Defaults to `false`.
32+
33+
- `model` <Type text="string" /> <MetaInfo text="optional" />
34+
- The reranking model to use when reranking is enabled.
35+
2636
`filters` <Type text="object" /> <MetaInfo text="optional" />
2737

2838
Narrow down search results based on metadata, like folder and date, so only relevant content is retrieved. For more details, refer to [Metadata filtering](/ai-search/configuration/metadata).

0 commit comments

Comments
 (0)