Skip to content

Commit b0f113a

Browse files
alexwolfmsftalexwolfmsft
committed
new RAG quickstart
1 parent ccc72f1 commit b0f113a

File tree

3 files changed

+341
-0
lines changed

3 files changed

+341
-0
lines changed

‎articles/search/includes/quickstarts/search-get-started-rag-dotnet.md

Lines changed: 333 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,333 @@
1+
---
2+
manager: nitinme
3+
author: haileytap
4+
ms.author: haileytapia
5+
ms.service: azure-ai-search
6+
ms.topic: include
7+
ms.date: 06/05/2025
8+
---
9+
## Prerequisites
10+
11+
- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
12+
13+
- An [Azure OpenAI resource](/azure/ai-services/openai/how-to/create-resource).
14+
- [Choose a region](/azure/ai-services/openai/concepts/models?tabs=global-standard%2Cstandard-chat-completions#global-standard-model-availability) that supports the chat completion model you want to use (gpt-4o, gpt-4o-mini, or an equivalent model).
15+
- [Deploy the chat completion model](/azure/ai-foundry/how-to/deploy-models-openai) in Azure AI Foundry or [use another approach](/azure/ai-services/openai/how-to/working-with-models).
16+
- An [Azure AI Search resource](../../search-create-service-portal.md).
17+
- We recommend using the Basic tier or higher.
18+
- [Enable semantic ranking](../../semantic-how-to-enable-disable.md).
19+
- [Visual Studio Code](https://code.visualstudio.com/download) with the [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python) and the [Jupyter package](https://pypi.org/project/jupyter/). For more information, see [Python in Visual Studio Code](https://code.visualstudio.com/docs/languages/python).
20+
21+
## Configure access
22+
23+
Requests to the search endpoint must be authenticated and authorized. You can use API keys or roles for this task. Keys are easier to start with, but roles are more secure. This quickstart assumes roles.
24+
25+
You're setting up two clients, so you need permissions on both resources.
26+
27+
Azure AI Search is receiving the query request from your local system. Assign yourself the **Search Index Data Reader** role assignment if the hotels sample index already exists. If it doesn't exist, assign yourself **Search Service Contributor** and **Search Index Data Contributor** roles so that you can create and query the index.
28+
29+
Azure OpenAI is receiving the query and the search results from your local system. Assign yourself the **Cognitive Services OpenAI User** role on Azure OpenAI.
30+
31+
1. Sign in to the [Azure portal](https://portal.azure.com).
32+
33+
1. Configure Azure AI Search for role-based access:
34+
35+
1. In the Azure portal, find your Azure AI Search service.
36+
37+
1. On the left menu, select **Settings** > **Keys**, and then select either **Role-based access control** or **Both**.
38+
39+
1. Assign roles:
40+
41+
1. On the left menu, select **Access control (IAM)**.
42+
43+
1. On Azure AI Search, select these roles to create, load, and query a search index, and then assign them to your Microsoft Entra ID user identity:
44+
45+
- **Search Index Data Contributor**
46+
- **Search Service Contributor**
47+
48+
1. On Azure OpenAI, select **Access control (IAM)** to assign this role to yourself on Azure OpenAI:
49+
50+
- **Cognitive Services OpenAI User**
51+
52+
It can take several minutes for permissions to take effect.
53+
54+
## Create an index
55+
56+
A search index provides grounding data for the chat model. We recommend the hotels-sample-index, which can be created in minutes and runs on any search service tier. This index is created using built-in sample data.
57+
58+
1. In the Azure portal, [find your search service](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.Search%2FsearchServices).
59+
60+
1. On the **Overview** home page, select [**Import data**](../../search-get-started-portal.md) to start the wizard.
61+
62+
1. On the **Connect to your data** page, select **Samples** from the dropdown list.
63+
64+
1. Choose the **hotels-sample**.
65+
66+
1. Select **Next** through the remaining pages, accepting the default values.
67+
68+
1. Once the index is created, select **Search management** > **Indexes** from the left menu to open the index.
69+
70+
1. Select **Edit JSON**.
71+
72+
1. Scroll to the end of the index, where you can find placeholders for constructs that can be added to an index.
73+
74+
```json
75+
"analyzers": [],
76+
"tokenizers": [],
77+
"tokenFilters": [],
78+
"charFilters": [],
79+
"normalizers": [],
80+
```
81+
82+
1. On a new line after "normalizers", paste in the following semantic configuration. This example specifies a `"defaultConfiguration"`, which is important to the running of this quickstart.
83+
84+
```json
85+
"semantic":{
86+
"defaultConfiguration":"semantic-config",
87+
"configurations":[
88+
{
89+
"name":"semantic-config",
90+
"prioritizedFields":{
91+
"titleField":{
92+
"fieldName":"HotelName"
93+
},
94+
"prioritizedContentFields":[
95+
{
96+
"fieldName":"Description"
97+
}
98+
],
99+
"prioritizedKeywordsFields":[
100+
{
101+
"fieldName":"Category"
102+
},
103+
{
104+
"fieldName":"Tags"
105+
}
106+
]
107+
}
108+
}
109+
]
110+
},
111+
```
112+
113+
1. **Save** your changes.
114+
115+
1. Run the following query in [Search Explorer](../../search-explorer.md) to test your index: `complimentary breakfast`.
116+
117+
Output should look similar to the following example. Results that are returned directly from the search engine consist of fields and their verbatim values, along with metadata like a search score and a semantic ranking score and caption if you use semantic ranker. We used a [select statement](../../search-query-odata-select.md) to return just the HotelName, Description, and Tags fields.
118+
119+
```
120+
{
121+
"@odata.count": 18,
122+
"@search.answers": [],
123+
"value": [
124+
{
125+
"@search.score": 2.2896252,
126+
"@search.rerankerScore": 2.506816864013672,
127+
"@search.captions": [
128+
{
129+
"text": "Head Wind Resort. Suite. coffee in lobby\r\nfree wifi\r\nview. The best of old town hospitality combined with views of the river and cool breezes off the prairie. Our penthouse suites offer views for miles and the rooftop plaza is open to all guests from sunset to 10 p.m. Enjoy a **complimentary continental breakfast** in the lobby, and free Wi-Fi throughout the hotel..",
130+
"highlights": ""
131+
}
132+
],
133+
"HotelName": "Head Wind Resort",
134+
"Description": "The best of old town hospitality combined with views of the river and cool breezes off the prairie. Our penthouse suites offer views for miles and the rooftop plaza is open to all guests from sunset to 10 p.m. Enjoy a complimentary continental breakfast in the lobby, and free Wi-Fi throughout the hotel.",
135+
"Tags": [
136+
"coffee in lobby",
137+
"free wifi",
138+
"view"
139+
]
140+
},
141+
{
142+
"@search.score": 2.2158256,
143+
"@search.rerankerScore": 2.288334846496582,
144+
"@search.captions": [
145+
{
146+
"text": "Swan Bird Lake Inn. Budget. continental breakfast\r\nfree wifi\r\n24-hour front desk service. We serve a continental-style breakfast each morning, featuring a variety of food and drinks. Our locally made, oh-so-soft, caramel cinnamon rolls are a favorite with our guests. Other breakfast items include coffee, orange juice, milk, cereal, instant oatmeal, bagels, and muffins..",
147+
"highlights": ""
148+
}
149+
],
150+
"HotelName": "Swan Bird Lake Inn",
151+
"Description": "We serve a continental-style breakfast each morning, featuring a variety of food and drinks. Our locally made, oh-so-soft, caramel cinnamon rolls are a favorite with our guests. Other breakfast items include coffee, orange juice, milk, cereal, instant oatmeal, bagels, and muffins.",
152+
"Tags": [
153+
"continental breakfast",
154+
"free wifi",
155+
"24-hour front desk service"
156+
]
157+
},
158+
{
159+
"@search.score": 0.92481667,
160+
"@search.rerankerScore": 2.221315860748291,
161+
"@search.captions": [
162+
{
163+
"text": "White Mountain Lodge & Suites. Resort and Spa. continental breakfast\r\npool\r\nrestaurant. 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..",
164+
"highlights": ""
165+
}
166+
],
167+
"HotelName": "White Mountain Lodge & Suites",
168+
"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.",
169+
"Tags": [
170+
"continental breakfast",
171+
"pool",
172+
"restaurant"
173+
]
174+
},
175+
. . .
176+
]}
177+
```
178+
179+
## Get service endpoints
180+
181+
In the remaining sections, you set up API calls to Azure OpenAI and Azure AI Search. Get the service endpoints so that you can provide them as variables in your code.
182+
183+
1. Sign in to the [Azure portal](https://portal.azure.com).
184+
185+
1. [Find your search service](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.Search%2FsearchServices).
186+
187+
1. On the **Overview** home page, copy the URL. An example endpoint might look like `https://example.search.windows.net`.
188+
189+
1. [Find your Azure OpenAI service](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.CognitiveServices%2Faccounts).
190+
191+
1. On the **Overview** home page, select the link to view the endpoints. Copy the URL. An example endpoint might look like `https://example.openai.azure.com/`.
192+
193+
## Sign in to Azure
194+
195+
You're using Microsoft Entra ID and role assignments for the connection. Make sure you're logged in to the same tenant and subscription as Azure AI Search and Azure OpenAI. You can use the Azure CLI on the command line to show current properties, change properties, and to sign in. For more information, see [Connect without keys](../../search-get-started-rbac.md).
196+
197+
Run each of the following commands in sequence.
198+
199+
```azure-cli
200+
az account show
201+
202+
az account set --subscription <PUT YOUR SUBSCRIPTION ID HERE>
203+
204+
az login --tenant <PUT YOUR TENANT ID HERE>
205+
```
206+
207+
You should now be logged in to Azure from your local device.
208+
209+
## Create the .NET app
210+
211+
Complete the following steps to create a .NET console app to connect to an AI model.
212+
213+
1. In an empty directory on your computer, use the `dotnet new` command to create a new console app:
214+
215+
```dotnetcli
216+
dotnet new console -o AISearchRag
217+
```
218+
219+
1. Change directory into the app folder:
220+
221+
```dotnetcli
222+
cd AISearchRag
223+
```
224+
225+
1. Install the required packages:
226+
227+
```bash
228+
dotnet add package Azure.AI.OpenAI
229+
dotnet add package Azure.Identity
230+
dotnet add package Azure.Search.Documents
231+
```
232+
233+
1. Open the app in Visual Studio Code (or your editor of choice).
234+
235+
```bash
236+
code .
237+
```
238+
239+
## Set up the query and chat thread
240+
241+
Add the following code to connect to and query the Azure AI Search and Azure OpenAI services.
242+
243+
:::code language="csharp" source="~/azure-search-dotnet-samples/quickstart-rag/minimal-query/Program.cs" :::
244+
245+
The output from Azure OpenAI consists of recommendations for several hotels, such as the following example:
246+
247+
```output
248+
Sure! Here are a few hotels that offer complimentary breakfast:
249+
250+
- **Head Wind Resort**
251+
- Complimentary continental breakfast in the lobby
252+
- Free Wi-Fi throughout the hotel
253+
254+
- **Double Sanctuary Resort**
255+
- Continental breakfast included
256+
257+
- **White Mountain Lodge & Suites**
258+
- Continental breakfast available
259+
260+
- **Swan Bird Lake Inn**
261+
- Continental-style breakfast each morning with a variety of food and drinks
262+
such as caramel cinnamon rolls, coffee, orange juice, milk, cereal,
263+
instant oatmeal, bagels, and muffins
264+
```
265+
266+
If you get a **Forbidden** error message, check Azure AI Search configuration to make sure role-based access is enabled.
267+
268+
If you get an **Authorization failed** error message, wait a few minutes and try again. It can take several minutes for role assignments to become operational.
269+
270+
If you get a **Resource not found** error message, check the resource URIs and make sure the API version on the chat model is valid.
271+
272+
Otherwise, to experiment further, change the query and rerun the last step to better understand how the model works with the grounding data.
273+
274+
You can also modify the prompt to change the tone or structure of the output.
275+
276+
## Send a complex RAG query
277+
278+
Azure AI Search supports [complex types](../../search-howto-complex-data-types.md) for nested JSON structures. In the hotels-sample-index, `Address` is an example of a complex type, consisting of `Address.StreetAddress`, `Address.City`, `Address.StateProvince`, `Address.PostalCode`, and `Address.Country`. The index also has complex collection of `Rooms` for each hotel.
279+
280+
If your index has complex types, your query can provide those fields if you first convert the search results output to JSON, and then pass the JSON to the chat model.
281+
282+
The following example updates the user prompt and adds complex types to the request:
283+
284+
:::code language="csharp" source="~/azure-search-dotnet-samples/quickstart-rag/complex-query/Program.cs" :::
285+
286+
The output from Azure OpenAI consists of recommendations for several hotels, such as the following example:
287+
288+
```output
289+
1. **Double Sanctuary Resort**
290+
- **Description**: 5-star luxury hotel with the biggest rooms in the city. Recognized as the #1 hotel in the area by Traveler magazine. Features include free WiFi, flexible check-in/out, a fitness center, and in-room espresso.
291+
- **Address**: 2211 Elliott Ave, Seattle, WA, 98121, USA
292+
- **Tags**: view, pool, restaurant, bar, continental breakfast
293+
- **Room Rate for 4 People**:
294+
- Suite, 2 Queen Beds: $254.99 per night
295+
296+
2. **Starlight Suites**
297+
- **Description**: Spacious all-suite hotel with complimentary airport shuttle and WiFi. Facilities include an indoor/outdoor pool, fitness center, and Florida Green certification. Complimentary coffee and HDTV are also available.
298+
- **Address**: 19575 Biscayne Blvd, Aventura, FL, 33180, USA
299+
- **Tags**: pool, coffee in lobby, free wifi
300+
- **Room Rate for 4 People**:
301+
- Suite, 2 Queen Beds (Cityside): $231.99 per night
302+
- Deluxe Room, 2 Queen Beds (Waterfront View): $148.99 per night
303+
304+
3. **Good Business Hotel**
305+
- **Description**: Located one mile from the airport with free WiFi, an outdoor pool, and a complimentary airport shuttle. Close proximity to Lake Lanier and downtown. The business center includes printers, a copy machine, fax, and a work area.
306+
- **Address**: 4400 Ashford Dunwoody Rd NE, Atlanta, GA, 30346, USA
307+
- **Tags**: pool, continental breakfast, free parking
308+
- **Room Rate for 4 People**:
309+
- Budget Room, 2 Queen Beds (Amenities): $60.99 per night
310+
- Deluxe Room, 2 Queen Beds (Amenities): $139.99 per night
311+
```
312+
313+
## Troubleshooting errors
314+
315+
If you see output messages while debugging related to `ManagedIdentityCredential` and token acquisition failures, it could be that you have multiple tenants, and your Azure sign-in is using a tenant that doesn't have your search service. To get your tenant ID, search the Azure portal for "tenant properties" or run `az login tenant list`.
316+
317+
Once you have your tenant ID, run `az login --tenant <YOUR-TENANT-ID>` at a command prompt, and then rerun the script.
318+
319+
You can also log errors in your code by creating an instance of `ILogger`:
320+
321+
```csharp
322+
using var loggerFactory = LoggerFactory.Create(builder =>
323+
{
324+
builder.AddConsole();
325+
});
326+
ILogger logger = loggerFactory.CreateLogger<Program>();
327+
```
328+
329+
## Clean up
330+
331+
When you're working in your own subscription, it's a good idea at the end of a project to identify whether you still need the resources you created. Resources left running can cost you money. You can delete resources individually or delete the resource group to delete the entire set of resources.
332+
333+
You can find and manage resources in the Azure portal by using the **All resources** or **Resource groups** link in the leftmost pane.

‎articles/search/search-get-started-rag.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,12 @@ In this quickstart, you send queries to a chat completion model for a conversati
3535

3636
::: zone-end
3737

38+
::: zone pivot="csharp"
39+
40+
[!INCLUDE [.NET quickstart](includes/quickstarts/search-get-started-rag-dotnet.md)]
41+
42+
::: zone-end
43+
3844
## Related content
3945

4046
- [Tutorial: Build a RAG solution in Azure AI Search](tutorial-rag-build-solution.md)

‎zone-pivots/zone-pivot-groups.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -285,6 +285,8 @@ groups:
285285
title: Python
286286
- id: typescript
287287
title: TypeScript
288+
- id: csharp
289+
title: C#
288290
# Owner: diberry
289291
- id: programming-languages-rest-ps-py-js
290292
title: Programming languages

0 commit comments

Comments
 (0)