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
In this quickstart, build a console application by using the [**Azure.Search.Documents**](/dotnet/api/overview/azure/search.documents-readme) client library to add semantic ranking to an existing search index.
14
14
15
-
Build a console application by using the [**Azure.Search.Documents**](/dotnet/api/overview/azure/search.documents-readme) client library to add semantic ranking to an existing search index.
15
+
> [!TIP]
16
+
> You can [download the source code](https://github.com/Azure-Samples/azure-search-dotnet-samples/tree/main/quickstart-semantic-search/SemanticSearchQuickstart) to start with a finished project or follow these steps to create your own.
16
17
17
-
Alternatively, you can [download the source code](https://github.com/Azure-Samples/azure-search-dotnet-samples/tree/main/quickstart-semantic-search/SemanticSearchQuickstart) to start with a finished project.
18
+
## Set up the client
18
19
19
-
#### Set up your environment
20
+
In this quickstart, you use an IDE and the [Azure.Search.Documents](TBD) library to configure and use a semantic ranker.
21
+
22
+
We recommend [Visual Studio](TBD) for this quickstart.
23
+
24
+
### Install libraries
20
25
21
26
1. Start Visual Studio and create a new project for a console app.
22
27
@@ -28,7 +33,7 @@ Alternatively, you can [download the source code](https://github.com/Azure-Sampl
28
33
29
34
1. Select **Install** to add the assembly to your project and solution.
30
35
31
-
####Create a search client
36
+
### Create a search client
32
37
33
38
1. In *Program.cs*, add the following `using` directives.
34
39
@@ -40,7 +45,7 @@ Alternatively, you can [download the source code](https://github.com/Azure-Sampl
40
45
usingAzure.Search.Documents.Models;
41
46
```
42
47
43
-
1. Create two clients: [SearchIndexClient](/dotnet/api/azure.search.documents.indexes.searchindexclient)creates the index, and [SearchClient](/dotnet/api/azure.search.documents.searchclient)loads and queries an existing index.
48
+
1. Create two clients: [SearchIndexClient](/dotnet/api/azure.search.documents.indexes.searchindexclient)to update the index, and [SearchClient](/dotnet/api/azure.search.documents.searchclient)to query an index.
44
49
45
50
Both clients need the service endpoint and an admin API key for authentication with create/delete rights. However, the code builds out the URI for you, so specify only the search service name for the `serviceName` property. Don't include `https://` or `.search.windows.net`.
46
51
@@ -63,60 +68,13 @@ Alternatively, you can [download the source code](https://github.com/Azure-Sampl
63
68
}
64
69
```
65
70
66
-
#### Create an index
67
-
68
-
Createorupdateanindexschematoincludea `SemanticConfiguration`. Ifyou're updating an existing index, this modification doesn'trequireareindexingbecausethestructureofyourdocumentsisunchanged.
Azure AI Search searches over content stored in the service. The code for uploading documents is identical to the [C# quickstart for full text search](/azure/search/search-get-started-text) so we don't need to duplicate it here. You should have four hotels with names, addresses, and descriptions. Your solution should have types for Hotels and Addresses.
75
+
## Search with semantic reranking
118
76
119
-
#### Search an index
77
+
TBD
120
78
121
79
Here's a query that invokes semantic ranker, with search options for specifying parameters:
122
80
@@ -149,7 +107,7 @@ In contrast, when semantic ranking is applied to the same query ("restaurant on
149
107
150
108
:::image type="content" source="../../media/quickstart-semantic/semantic-ranking.png" alt-text="Screenshot showing matches ranked based on semantic ranking.":::
151
109
152
-
####Run the program
110
+
### Run the program
153
111
154
112
Press F5 to rebuild the app and run the program in its entirety.
> You can [download and run a finished notebook](https://github.com/Azure-Samples/azure-search-python-samples/tree/main/Quickstart-Semantic-Search) to start with a finished project or follow these steps to create your own.
14
15
15
-
Use a Jupyter notebook and the [**azure-search-documents**](/python/api/overview/azure/search-documents-readme) library in the Azure SDK for Python to learn about semantic ranking.
16
+
## Set up the client
16
17
17
-
Alternatively, you can [download and run a finished notebook](https://github.com/Azure-Samples/azure-search-python-samples/tree/main/Quickstart-Semantic-Search).
18
-
19
-
#### Set up your environment
18
+
In this quickstart, use a Jupyter notebook and the [**azure-search-documents**](/python/api/overview/azure/search-documents-readme) library in the Azure SDK for Python to learn about semantic ranking.
20
19
21
20
Use [Visual Studio Code with the Python extension](https://code.visualstudio.com/docs/languages/python), or equivalent IDE, with Python 3.10 or later.
22
21
@@ -36,7 +35,7 @@ We recommend a virtual environment for this quickstart:
36
35
37
36
It can take a minute to set up. If you run into problems, see [Python environments in VS Code](https://code.visualstudio.com/docs/python/environments).
38
37
39
-
####Install packages and set variables
38
+
### Install packages and set variables
40
39
41
40
1. Install packages, including [azure-search-documents](/python/api/azure-search-documents).
42
41
@@ -54,7 +53,7 @@ It can take a minute to set up. If you run into problems, see [Python environmen
54
53
index_name: str="hotels-quickstart"
55
54
```
56
55
57
-
#### Create an index
56
+
### Create or update an index
58
57
59
58
Create or update an index schema to include a `SemanticConfiguration`. If you're updating an existing index, this modification doesn't require a reindexing because the structure of your documents is unchanged.
60
59
@@ -118,7 +117,7 @@ result = index_client.create_or_update_index(index)
118
117
print(f'{result.name} created')
119
118
```
120
119
121
-
####Create a documents payload
120
+
### Create a documents payload
122
121
123
122
You can push JSON documents to a search index. Documents must match the index schema.
For comparison purposes, run a text query with BM25 relevance scoring. Full text search is invoked when you provide a query string. The response consists of ranked results, where higher scores are awarded to documents having more instances of matching terms, or more important terms.
240
239
@@ -253,7 +252,7 @@ for result in results:
253
252
print(f"Description: {result['Description']}")
254
253
```
255
254
256
-
####Run a semantic query
255
+
### Run a semantic query
257
256
258
257
Now add semantic ranking. New parameters include `query_type` and `semantic_configuration_name`.
Copy file name to clipboardExpand all lines: articles/search/includes/quickstarts/semantic-ranker-intro.md
+94-8Lines changed: 94 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,22 +9,108 @@ ms.date: 06/25/2025
9
9
10
10
In this quickstart, you learn about the index and query modifications that invoke semantic ranker.
11
11
12
-
In Azure AI Search, [semantic ranking](semantic-search-overview.md) is query-side functionality that uses machine reading comprehension from Microsoft to rescore search results, promoting the most semantically relevant matches to the top of the list. Depending on the content and the query, semantic ranking can [significantly improve search relevance](https://techcommunity.microsoft.com/t5/azure-ai-services-blog/azure-cognitive-search-outperforming-vector-search-with-hybrid/ba-p/3929167) with minimal developer effort. Semantic ranking is also required for [agentic retrieval (preview)](search-agentic-retrieval-concept.md).
12
+
In Azure AI Search, [semantic ranking](../../semantic-search-overview.md) is query-side functionality that uses machine reading comprehension from Microsoft to rescore search results, promoting the most semantically relevant matches to the top of the list. Depending on the content and the query, semantic ranking can [significantly improve search relevance](https://techcommunity.microsoft.com/t5/azure-ai-services-blog/azure-cognitive-search-outperforming-vector-search-with-hybrid/ba-p/3929167) with minimal developer effort. Semantic ranking is also required for [agentic retrieval (preview)](../../search-agentic-retrieval-concept.md).
13
13
14
-
You can add a semantic configuration to an existing index with no rebuild requirement. Semantic ranking is effective on content that's informational or descriptive.
14
+
You can add a semantic configuration to an existing index with no rebuild requirement. Semantic ranking is most effective on content that's informational or descriptive.
15
+
16
+
In this quickstart:
17
+
18
+
> [!div class="checklist"]
19
+
> - Add a *semantic configuration* to a search index
20
+
> - Add semantic parameters to a query
15
21
16
22
## Prerequisites
17
23
18
24
+ An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
19
25
20
-
+ An [Azure AI Search service](search-create-service-portal.md), at Basic tier or higher, with [semantic ranker enabled](semantic-how-to-enable-disable.md).
26
+
+ An [Azure AI Search service](../../search-create-service-portal.md), at Basic tier or higher, with [semantic ranker enabled](semantic-how-to-enable-disable.md).
27
+
28
+
+ A [new or existing index](../../search-how-to-create-search-index.md) with descriptive or verbose text fields, attributed as retrievable in your index.
29
+
30
+
## Configure role-based access
31
+
32
+
TBD
33
+
34
+
## Start with an index
35
+
36
+
This quickstart assumes an existing index, modified to include a semantic configuration. We recommend the [hotels-sample-index](../../search-get-started-portal.md) that you can create in minutes using an Azure portal wizard.
37
+
38
+
If you don't have access to the Azure portal, you can create a hotels-quickstart-index by following the instructions in [Quickstart: Full text search](../../search-get-started-text.md).
39
+
40
+
Both indexes have a "Description" field that's suitable for demonstrating the semantic ranker.
41
+
42
+
1. Sign in to the Azure portal and find your search service.
43
+
44
+
1. Under **Search management** > **Indexes**, open the hotels index. Make sure the index doesn't have a semantic configuration.
21
45
22
-
+ A [new or existing index](search-how-to-create-search-index.md) with descriptive or verbose text fields, attributed as retrievable in your index.
46
+
:::image type="content" source="../../media/search-get-started-semantic/no-semantic-configuration.png" alt-text="Screenshot of an empty semantic configuration page in the Azure portal.":::
23
47
24
-
## How to add a semantic ranker
48
+
1. In **Search explorer**, enter this search string "good trails for running or biking and outdoor activities" so that you can view the response *before*semantic ranking is applied. Your response should be similar to the following example, as scored by the default L1 ranker for full text search. For readability, the example below selects just the "HotelName" and "Description" fields.
25
49
26
-
To use semantic ranker, add a *semantic configuration* to a search index, and add parameters to a query. If you have an existing index, you can make these changes without having to reindex your content because there's no impact on the structure of your searchable content.
50
+
```json
51
+
"@odata.count": 11,
52
+
"value": [
53
+
{
54
+
"@search.score": 3.5593667,
55
+
"HotelName": "Winter Panorama Resort",
56
+
"Description": "Plenty of great skiing, outdoor ice skating, sleigh rides, tubing and snow biking. Yoga, group exercise classes and outdoor hockey are available year-round, plus numerous options for shopping as well as great spa services. Newly-renovated with large rooms, free 24-hr airport shuttle & a new restaurant. Rooms/suites offer mini-fridges & 49-inch HDTVs."
57
+
},
58
+
{
59
+
"@search.score": 3.0720026,
60
+
"HotelName": "Good Business Hotel",
61
+
"Description": "1 Mile from the airport. Free WiFi, Outdoor Pool, Complimentary Airport Shuttle, 6 miles from Lake Lanier & 10 miles from downtown. Our business center includes printers, a copy machine, fax, and a work area."
62
+
},
63
+
{
64
+
"@search.score": 2.2779887,
65
+
"HotelName": "Trails End Motel",
66
+
"Description": "Only 8 miles from Downtown. On-site bar/restaurant, Free hot breakfast buffet, Free wireless internet, All non-smoking hotel. Only 15 miles from airport."
67
+
},
68
+
{
69
+
"@search.score": 1.7617674,
70
+
"HotelName": "Royal Cottage Resort",
71
+
"Description": "Your home away from home. Brand new fully equipped premium rooms, fast WiFi, full kitchen, washer & dryer, fitness center. Inner courtyard includes water features and outdoor seating. All units include fireplaces and small outdoor balconies. Pets accepted."
72
+
},
73
+
{
74
+
"@search.score": 1.5327098,
75
+
"HotelName": "City Center Summer Wind Resort",
76
+
"Description": "Eco-friendly from our gardens to table, with a rooftop serenity pool and outdoor seating to take in the sunset. Just steps away from the Convention Center. Located in the heart of downtown with modern rooms with stunning city views, 24-7 dining options, free WiFi and easy valet parking."
77
+
},
78
+
{
79
+
"@search.score": 1.5104222,
80
+
"HotelName": "Foot Happy Suites",
81
+
"Description": "Downtown in the heart of the business district. Close to everything. Leave your car behind and walk to the park, shopping, and restaurants. Or grab one of our bikes and take your explorations a little further."
82
+
},
83
+
{
84
+
"@search.score": 1.4453387,
85
+
"HotelName": "Economy Universe Motel",
86
+
"Description": "Local, family-run hotel in bustling downtown Redmond. We are a pet-friendly establishment, near expansive Marymoor park, haven to pet owners, joggers, and sports enthusiasts. Close to the highway and just a short drive away from major cities."
87
+
},
88
+
{
89
+
"@search.score": 1.3732712,
90
+
"HotelName": "Starlight Suites",
91
+
"Description": "Complimentary Airport Shuttle & WiFi. Book Now and save - Spacious All Suite Hotel, Indoor Outdoor Pool, Fitness Center, Florida Green certified, Complimentary Coffee, HDTV"
92
+
},
93
+
{
94
+
"@search.score": 1.2054883,
95
+
"HotelName": "Happy Lake Resort & Restaurant",
96
+
"Description": "The largest year-round resort in the area offering more of everything for your vacation – at the best value! What can you enjoy while at the resort, aside from the mile-long sandy beaches of the lake? Check out our activities sure to excite both young and young-at-heart guests. We have it all, including being named “Property of the Year” and a “Top Ten Resort” by top publications."
97
+
},
98
+
{
99
+
"@search.score": 1.161385,
100
+
"HotelName": "White Mountain Lodge & Suites",
101
+
"Description": "Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings."
102
+
},
103
+
{
104
+
"@search.score": 0.8955848,
105
+
"HotelName": "Windy Ocean Motel",
106
+
"Description": "Oceanfront hotel overlooking the beach features rooms with a private balcony and 2 indoor and outdoor pools. Inspired by the natural beauty of the island, each room includes an original painting of local scenes by the owner. Rooms include a mini fridge, Keurig coffee maker, and flatscreen TV. Various shops and art entertainment are on the boardwalk, just steps away."
107
+
}
108
+
]
109
+
}
110
+
```
27
111
28
-
+ A semantic configuration sets a priority order for fields that contribute a title, keywords, and content used in semantic reranking. Field prioritization allows for faster processing.
112
+
Later, you can try this query again after semantic ranking is configured to see how the response changes.
29
113
30
-
+ Queries that invoke semantic ranker include parameters for query type and whether captions and answers are returned. You can add these parameters to your existing query logic. There's no conflict with other parameters.
114
+
> [!TIP]
115
+
> You can add a semantic configuration in the Azure portal. However, if you want to learn how to add a semantic configuration programmatically, continue with the instructions in this quickstart.
0 commit comments