You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[Hybrid search](hybrid-search-overview.md) combines one or more keyword queries with one or more vector queries in a single search request. The queries execute in parallel. The results are merged and reordered by new search scores, using [Reciprocal Rank Fusion (RRF)](hybrid-search-ranking.md) to return a single ranked result set.
17
+
[Hybrid search](hybrid-search-overview.md) combines one or more text (keyword) queries with one or more vector queries in a single search request. The queries execute in parallel. The results are merged and reordered by new search scores, using [Reciprocal Rank Fusion (RRF)](hybrid-search-ranking.md) to return a unified result set.
18
18
19
-
In most cases, [per benchmark tests](https://techcommunity.microsoft.com/t5/ai-azure-ai-services-blog/azure-ai-search-outperforming-vector-search-with-hybrid/ba-p/3929167), hybrid queries with semantic ranking return the most relevant results.
19
+
In many cases, [per benchmark tests](https://techcommunity.microsoft.com/t5/ai-azure-ai-services-blog/azure-ai-search-outperforming-vector-search-with-hybrid/ba-p/3929167), hybrid queries with semantic ranking return the most relevant results.
20
20
21
-
To define a hybrid query, use REST API [**2023-11-01**](/rest/api/searchservice/documents/search-post), [**2023-10-01-preview**](/rest/api/searchservice/documents/search-post?view=rest-searchservice-2023-10-01-preview&preserve-view=true), [**2024-03-01-preview**](/rest/api/searchservice/documents/search-post?view=rest-searchservice-2024-03-01-preview&preserve-view=true), Search Explorer in the Azure portal, or newer versions of the Azure SDKs.
21
+
To improve relevance:
22
+
23
+
+ New parameters [maxTextRecallSize and countAndFacetMode(preview)](#set-maxtextrecallsize-and-countandfacetmode-preview) give you more control over text inputs into a hybrid query.
24
+
25
+
+ New [vector weighting](vector-search-how-to-query.md#vector-weighting-preview) lets you set the relative weight of the vector query. This feature is particularly useful in complex queries where two or more distinct result sets need to be combined, as is the case for hybrid search.
22
26
23
27
## Prerequisites
24
28
@@ -28,6 +32,15 @@ To define a hybrid query, use REST API [**2023-11-01**](/rest/api/searchservice/
28
32
29
33
+ (Optional) If you want text-to-vector conversion of a query string (currently in preview), [create and assign a vectorizer](vector-search-how-to-configure-vectorizer.md) to vector fields in the search index.
30
34
35
+
## Choose an API or tool
36
+
37
+
+[**2023-11-01**](/rest/api/searchservice/documents/search-post) stable version
38
+
+[**2023-10-01-preview**](/rest/api/searchservice/documents/search-post?view=rest-searchservice-2023-10-01-preview&preserve-view=true), adds integrated vectorization to the vector side of a hybrid query
39
+
+[**2024-03-01-preview**](/rest/api/searchservice/documents/search-post?view=rest-searchservice-2024-03-01-preview&preserve-view=true), adds narrow data types and scalar quantization to the vector side of a hybrid query
40
+
+[**2024-05-01-preview**](/rest/api/searchservice/documents/search-post?view=rest-searchservice-2024-05-01-preview&preserve-view=true) adds `maxTextRecallSize` and `countAndFacetMode` specifially for hybrid search
41
+
+ Search Explorer in the Azure portal (targets 2024-05-01-preview behaviors)
42
+
+ Newer stable or beta packages of the Azure SDKs (see change logs for SDK feature support)
43
+
31
44
## Run a hybrid query in Search Explorer
32
45
33
46
1. In [Search Explorer](search-explorer.md), make sure the API version is **2023-10-01-preview** or later.
@@ -73,22 +86,37 @@ POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/d
73
86
Content-Type: application/json
74
87
api-key: {{admin-api-key}}
75
88
{
76
-
"vectorQueries": [{
77
-
"vector": [
78
-
-0.009154141,
79
-
0.018708462,
80
-
. . .
81
-
-0.02178128,
82
-
-0.00086512347
83
-
],
84
-
"fields": "DescriptionVector",
85
-
"kind": "vector",
86
-
"exhaustive": true,
87
-
"k": 10
88
-
}],
89
+
"vectorQueries": [
90
+
{
91
+
"vector": [
92
+
-0.009154141,
93
+
0.018708462,
94
+
. . .
95
+
-0.02178128,
96
+
-0.00086512347
97
+
],
98
+
"fields": "DescriptionVector",
99
+
"kind": "vector",
100
+
"exhaustive": true,
101
+
"k": 10
102
+
},
103
+
{
104
+
"vector": [
105
+
-0.009154141,
106
+
0.018708462,
107
+
. . .
108
+
-0.02178128,
109
+
-0.00086512347
110
+
],
111
+
"fields": "DescriptionVector",
112
+
"kind": "vector",
113
+
"exhaustive": true,
114
+
"k": 10
115
+
}
116
+
],
89
117
"search": "historic hotel walk to restaurants and shopping",
90
118
"select": "HotelName, Description, Address/City",
91
-
"top": "10"
119
+
"top": 10
92
120
}
93
121
```
94
122
@@ -222,7 +250,75 @@ api-key: {{admin-api-key}}
222
250
223
251
+ Prefiltering is applied before query execution. If prefilter reduces the search area to 100 documents, the vector query executes over the "DescriptionVector" field for those 100 documents, returning the k=50 best matches. Those 50 matching documents then pass to RRF for merged results, and then to semantic ranker.
224
252
225
-
+ Postfilter is applied after query execution. If k=50 returns 50 matches on the vector query side, then the post-filter is applied to the 50 matches, reducing results that meet filter criteria, leaving you with fewer than 50 documents to pass to semantic ranker
253
+
+ Postfilter is applied after query execution. If k=50 returns 50 matches on the vector query side, then the post-filter is applied to the 50 matches, reducing results that meet filter criteria, leaving you with fewer than 50 documents to pass to semantic ranker.
254
+
255
+
## Set maxTextRecallSize and countAndFacetMode (preview)
256
+
257
+
This section explains how to adjust the inputs to a hybrid query by controlling the amount BM25-ranked results that flow to the hybrid ranking model. Controlling over the BM25-ranked input gives you more options for relevance tuning in hybrid scenarios.
258
+
259
+
> [!TIP]
260
+
> Another option to consider is a supplemental or replacement technique, is [vector weighting](vector-search-how-to-query.md#vector-weighting-preview), which increases the importance of vector queries in the request.
261
+
262
+
1. Use [Search - POST](/rest/api/searchservice/documents/search-post?view=rest-searchservice-2024-05-01-preview&preserve-view=true) or [Search - GET](/rest/api/searchservice/documents/search-get?view=rest-searchservice-2024-05-01-preview&preserve-view=true) in 2024-05-01-preview to specify these parameters.
263
+
264
+
1. Add a `hybridSearch` query parameter object to set the maximum number of documents recalled through the BM25-ranked results of a hybrid query. It has two properties:
265
+
266
+
+`maxTextRecallSize` specifies the number of BM25-ranked results to provide to the Reciprocal Rank Fusion (RRF) ranker used in hybrid queries. The default is 1,000. The maximum is 10,000.
267
+
268
+
+`countAndFacetMode` reports the counts for the BM25-ranked results (and for facets if you're using them). The default is all documents that match the query. Optionally, you can scope "count" to the `maxTextRecallSize`.
269
+
270
+
1. Reduce `maxTextRecallSize` if vector similarity search is generally outperforming the text-side of the the hybrid query.
271
+
272
+
1. Raise `maxTextRecallSize` if you have a large index, and the default isn't capturing a sufficient number of results. With a larger BM25-ranked result set, you can also set `top`, `skip`, and `next` to retrieve portions of those results.
273
+
274
+
The following REST examples show two use-cases for setting `maxTextRecallSize`.
275
+
276
+
The first example reduces `maxTextRecallSize` to 100, limiting the text side of the hybrid query to just 100 document. It also sets `countAndFacetMode` to include only those results from `maxTextRecallSize`.
277
+
278
+
```http
279
+
POST https://[service-name].search.windows.net/indexes/[index-name]/docs/search?api-version=2024-05-01-Preview
280
+
281
+
{
282
+
"vectorQueries": [
283
+
{
284
+
"kind": "vector",
285
+
"vector": [1.0, 2.0, 3.0],
286
+
"fields": "my_vector_field",
287
+
"k": 10
288
+
}
289
+
],
290
+
"search": "hello world",
291
+
"hybridSearch": {
292
+
"maxTextRecallSize": 100,
293
+
"countAndFacetMode": "countRetrievableResults"
294
+
}
295
+
}
296
+
```
297
+
298
+
The second example raises `maxTextRecallSize` to 5,000. It also uses top, skip, and next to pull results from large result sets. In this case, the request pulls in BM25-ranked results starting at position 1,500 through 2,000 as the text query contribution to the RRF composite result set.
299
+
300
+
```http
301
+
POST https://[service-name].search.windows.net/indexes/[index-name]/docs/search?api-version=2024-05-01-Preview
Copy file name to clipboardExpand all lines: articles/search/hybrid-search-ranking.md
+21-3Lines changed: 21 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,7 +9,7 @@ ms.service: cognitive-search
9
9
ms.custom:
10
10
- ignite-2023
11
11
ms.topic: conceptual
12
-
ms.date: 11/01/2023
12
+
ms.date: 06/12/2024
13
13
---
14
14
15
15
# Relevance scoring in hybrid search using Reciprocal Rank Fusion (RRF)
@@ -57,13 +57,31 @@ The following chart identifies the scoring property returned on each match, algo
57
57
58
58
Semantic ranking doesn't participate in RRF. Its score (`@search.rerankerScore`) is always reported separately in the query response. Semantic ranking can rerank full text and hybrid search results, assuming those results include fields having semantically rich content.
59
59
60
+
## Weighted scores
61
+
62
+
Starting in 2024-05-01-preview, you can [weight vector queries](vector-search-how-to-query.md#vector-weighting-preview) to increase or decrease their importance in a hybrid query.
63
+
64
+
Recall that when computing RRF for a certain document, the search engine looks at the rank of that document for each result set where it shows up. Assume a document shows up in three separate search results, where the results are from two vector queries and one text BM25-ranked query. The position of the document varies in each result.
65
+
66
+
| Match found | Position in results |@search.score | weight multiplier |@search.score (weighted) |
67
+
|--|--|--|--|--|--|
68
+
| vector results one | position 1 | 0.8383955 | 0.5 | 0.41919775 |
69
+
| vector results two | position 5 | 0.81514114 | 2.0 | 1.63028228 |
70
+
| BM25 results | position 10 | 0.8577363 | NA | 0.8577363 |
71
+
72
+
The document's position in each result set corresponds to an initial score, which are added up to create the final RRF score for that document.
73
+
74
+
If you add vector weighting, the initial scores are subect to a weighting multiplier that increases or decreases the score. The default is 1.0, which means no weighting and the initial score is used as-is in RRF scoring. However, if you add a weight of 0.5, the score is reduced and that result becomes less important in the combined ranking. Conversely, if you add a weight of 2.0, the score becomes a larger factor in the overall RRF score.
75
+
76
+
In this example, the @search.score (weighted) values are passed to the RRF ranking model.
77
+
60
78
## Number of ranked results in a hybrid query response
61
79
62
80
By default, if you aren't using pagination, the search engine returns the top 50 highest ranking matches for full text search, and the most similar `k` matches for vector search. In a hybrid query, `top` determines the number of results in the response. Based on defaults, the top 50 highest ranked matches of the unified result set are returned.
63
81
64
-
Often, the search engine finds more results than `top` and `k`. To return more results, use the paging parameters `top`, `skip`, and `next`. Paging is how you determine the number of results on each logical page and navigate through the full payload.
82
+
Often, the search engine finds more results than `top` and `k`. To return more results, use the paging parameters `top`, `skip`, and `next`. Paging is how you determine the number of results on each logical page and navigate through the full payload. You can set `maxTextRecallSize` to larger values (the default is 1,000) to return more results from the text side of hybrid query.
65
83
66
-
Full text search is subject to a maximum limit of 1,000 matches (see [API response limits](search-limits-quotas-capacity.md#api-response-limits)). Once 1,000 matches are found, the search engine no longer looks for more.
84
+
By default, full text search is subject to a maximum limit of 1,000 matches (see [API response limits](search-limits-quotas-capacity.md#api-response-limits)). Once 1,000 matches are found, the search engine no longer looks for more.
67
85
68
86
For more information, see [How to work with search results](search-pagination-page-layout.md).
Copy file name to clipboardExpand all lines: articles/search/search-pagination-page-layout.md
+3-1Lines changed: 3 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,7 +10,7 @@ ms.service: cognitive-search
10
10
ms.custom:
11
11
- ignite-2023
12
12
ms.topic: how-to
13
-
ms.date: 08/31/2023
13
+
ms.date: 06/12/2024
14
14
---
15
15
16
16
# How to shape results in Azure AI Search
@@ -68,6 +68,8 @@ Count won't be affected by routine maintenance or other workloads on the search
68
68
69
69
By default, the search engine returns up to the first 50 matches. The top 50 are determined by search score, assuming the query is full text search or semantic. Otherwise, the top 50 are an arbitrary order for exact match queries (where uniform "@searchScore=1.0" indicates arbitrary ranking).
70
70
71
+
The upper limit is 1,000 documents returned per page of search results, so you can set top to return up to 1000 document in the first result. In newer preview APIs, if you're using a hybrid query, you can [specify maxTextRecallSize](hybrid-search-how-to-query.md#set-maxtextrecallsize-and-countandfacetmode-preview) to return up to 10,000 documents.
72
+
71
73
To control the paging of all documents returned in a result set, add `$top` and `$skip` parameters to the GET query request, or `top` and `skip` to the POST query request. The following list explains the logic.
72
74
73
75
+ Return the first set of 15 matching documents plus a count of total matches: `GET /indexes/<INDEX-NAME>/docs?search=<QUERY STRING>&$top=15&$skip=0&$count=true`
This article uses REST for illustration. For code samples in other languages, see the [azure-search-vector-samples](https://github.com/Azure/azure-search-vector-samples) GitHub repository for end-to-end solutions that include vector queries.
@@ -598,51 +597,45 @@ POST https://[service-name].search.windows.net/indexes/[index-name]/docs/search?
598
597
599
598
Filtering occurs before [fusing results](hybrid-search-ranking.md) from different recall sets.
600
599
600
+
<!-- Keep H2 as-is. Direct link from a blog post. Bulk of maxtextsizerecall has moved to hybrid query doc-->
601
601
## MaxTextSizeRecall for hybrid search (preview)
602
602
603
-
Add a `hybridSearch` query parameter object to specify the maximum number of documents recalled using text queries in hybrid (text and vector) search. The default is 1,000 documents. With this parameter, you can increase or decrease the number of results returned in hybrid queries.
603
+
Vector queries are often used in hybrid constructs that include nonvector fields. If you discover that BM25-ranked results are over or under represented in a hybrid query results, you can [set `maxTextRecallSize`](hybrid-search-how-to-query.md#set-maxtextrecallsize-and-countandfacetmode-preview) to increase or decrease the BM25-ranked results provided for hybrid ranking.
604
604
605
-
```http
606
-
POST https://[service-name].search.windows.net/indexes/[index-name]/docs/search?api-version=2024-05-01-Preview
607
-
Content-Type: application/json
608
-
api-key: [admin key]
605
+
You can only set this property in hybrid requests that include both "search" and "vectorQueries" components.
609
606
610
-
{
611
-
"vectorQueries": [
612
-
{
613
-
"kind": "vector",
614
-
"vector": [1.0, 2.0, 3.0],
615
-
"fields": "my_vector_field",
616
-
"k": 10
617
-
}
618
-
],
619
-
"search": "hello world",
620
-
"hybridSearch": {
621
-
"maxTextRecallSize": 100,
622
-
"countAndFacetMode": "countAllResults"
623
-
}
624
-
}
625
-
```
607
+
For more information, see [Set maxTextRecallSize - Create a hybrid query](hybrid-search-how-to-query.md#set-maxtextrecallsize-and-countandfacetmode-preview).
626
608
627
609
## Vector weighting (preview)
628
610
629
-
Add a `weight` query parameter to specify the relative weight of each vector included in search operations. This feature is particularly useful in complex queries where two or more distinct result sets need to be combined, such as in hybrid search or multivector requests.
611
+
Add a `weight` query parameter to specify the relative weight of each vector included in search operations. This value is used when combining the results of multiple ranking lists produced by two or more vector queries in the same request, or from the vector portion of a hybrid query.
612
+
613
+
The default is 1.0 and the value must be a positive number larger than zero.
614
+
615
+
Weights are used when calculating the [reciprocal rank fusion](hybrid-search-ranking.md#weighted-scores) scores of each document. The calculation is multiplier of the `weight` value against the rank score of the document within its respective result set.
630
616
631
-
Weights are used when calculating the [reciprocal rank fusion](hybrid-search-ranking.md) scores of each document. The calculation is multiplier of the `weight` value against the rank score of the document within its respective result set.
617
+
The following example is a hybrid query with two vector query strings and one text string. Weights are assigned to the vector queries. The first query is 0.5 or half the weight, reducing its importance in the request. The second vectory query is twice as important.
618
+
619
+
Text queries have no weight parameters, but you can increase or decrease their importance by setting [maxTextRecallSize](hybrid-search-how-to-query.md#set-maxtextrecallsize-and-countandfacetmode-preview).
632
620
633
621
```http
634
622
POST https://[service-name].search.windows.net/indexes/[index-name]/docs/search?api-version=2024-05-01-Preview
0 commit comments