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
@@ -21,101 +21,38 @@ This quickstart is based on the [Quickstart-Agentic-Retrieval](https://github.co
21
21
22
22
+ An [Azure AI Search service](../../search-create-service-portal.md) on the Basic tier or higher with [semantic ranker enabled](../../semantic-how-to-enable-disable.md).
23
23
24
-
+ An [Azure OpenAI resource](/azure/ai-services/openai/how-to/create-resource).
24
+
+ An [Azure AI Foundry project](/azure/ai-foundry/how-to/create-projects). You get an Azure AI Foundry resource (that's needed for model deployments) when you create an Azure AI Foundry project.
25
25
26
26
+[Visual Studio Code](https://code.visualstudio.com/download) with the [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python) and [Jupyter package](https://pypi.org/project/jupyter/).
27
27
28
-
## Deploy models
28
+
+ The [Azure CLI](/cli/azure/install-azure-cli) for keyless authentication with Microsoft Entra ID.
29
29
30
-
To run agenticretrieval, you must deploy the following models to your Azure OpenAI resource:
30
+
[!INCLUDE [Setup](./agentic-retrieval-setup.md)]
31
31
32
-
+ An LLM for query planning.
33
-
34
-
+ An LLM for answer generation.
35
-
36
-
+ (Optional) An embedding model for vector queries.
37
-
38
-
Agentic retrieval [supports several models](../../search-agentic-retrieval-how-to-create.md#supported-models), but this quickstart assumes `gpt-4o-mini` for both LLMs and `text-embedding-3-large` for the embedding model.
39
-
40
-
To deploy the Azure OpenAI models:
41
-
42
-
1. Sign in to the [Azure AI Foundry portal](https://ai.azure.com/?cid=learnDocs) and select your Azure OpenAI resource.
43
-
44
-
1. From the left pane, select **Model catalog**.
45
-
46
-
1. Select **gpt-4o-mini**, and then select **Use this model**.
47
-
48
-
1. Specify a deployment name. To simplify your code, we recommend **gpt-4o-mini**.
49
-
50
-
1. Accept the defaults.
51
-
52
-
1. Select **Deploy**.
53
-
54
-
1. Repeat the previous steps for **text-embedding-3-large**.
55
-
56
-
## Configure role-based access
57
-
58
-
Azure AI Search needs access to your Azure OpenAI models. For this task, you can use API keys or Microsoft Entra ID with role assignments. Keys are easier to start with, but roles are more secure. This quickstart assumes roles.
59
-
60
-
To configure the recommended role-based access:
61
-
62
-
1. Sign in to the [Azure portal](https://portal.azure.com/).
63
-
64
-
1.[Enable role-based access](../../search-security-enable-roles.md) on your Azure AI Search service.
65
-
66
-
1.[Create a system-assigned managed identity](../../search-howto-managed-identities-data-sources.md#create-a-system-managed-identity) on your Azure AI Search service.
67
-
68
-
1. On your Azure AI Search service, [assign the following roles](../../search-security-rbac.md#how-to-assign-roles-in-the-azure-portal) to yourself.
69
-
70
-
+**Search Service Contributor**
71
-
72
-
+**Search Index Data Contributor**
73
-
74
-
+**Search Index Data Reader**
75
-
76
-
1. On your Azure OpenAI resource, assign **Cognitive Services User** to the managed identity of your search service.
77
-
78
-
## Get endpoints
79
-
80
-
In your code, you specify the following endpoints to establish connections with Azure AI Search and Azure OpenAI. These steps assume that you configured role-based access in the previous section.
81
-
82
-
To obtain your service endpoints:
83
-
84
-
1. Sign in to the [Azure portal](https://portal.azure.com/).
85
-
86
-
1. On your Azure AI Search service:
87
-
88
-
1. From the left pane, select **Overview**.
89
-
90
-
1. Copy the URL, which should be similar to `https://my-service.search.windows.net`.
91
-
92
-
1. On your Azure OpenAI resource:
32
+
## Connect from your local system
93
33
94
-
1. From the left pane, select **Resource Management** > **Keys and Endpoint**.
34
+
You configured role-based access to interact with Azure AI Search and Azure OpenAI.
95
35
96
-
1. Copy the URL, which should be similar to `https://my-resource.openai.azure.com`.
36
+
To connect from your local system:
97
37
98
-
## Connect from your local system
38
+
1. Open a new terminal in Visual Studio Code and change to the directory where you want to save your files.
39
+
1. Run the following Azure CLI command and sign in with your Azure account. If you have multiple subscriptions, select the one that contains your Azure AI Search service and Azure AI Foundry project.
99
40
100
-
You configured role-based access to interact with Azure AI Search and Azure OpenAI. From the command line, use the Azure CLI to sign in to the same subscription and tenant for both services. For more information, see [Quickstart: Connect without keys](../../search-get-started-rbac.md).
101
-
102
-
```azurecli
103
-
az account show
41
+
```azurecli
42
+
az login
43
+
```
104
44
105
-
az account set --subscription <PUT YOUR SUBSCRIPTION ID HERE>
106
-
107
-
az login --tenant <PUT YOUR TENANT ID HERE>
108
-
```
45
+
For more information, see [Quickstart: Connect without keys](../../search-get-started-rbac.md).
109
46
110
47
## Install packages and load connections
111
48
112
49
Before you run any code, install Python packages and define credentials, endpoints, and deployment details for connections to Azure AI Search and Azure OpenAI. These values are used in subsequent operations.
113
50
114
51
To install the packages and load the connections:
115
52
116
-
1. In Visual Studio Code, create a `.ipynb` file.
53
+
1. In Visual Studio Code, create a `.ipynb` file. For example, you can name the file `quickstart-agentic-retrieval.ipynb`.
117
54
118
-
1.Install the following packages.
55
+
1. In the first code cell, paste the following code to install the required packages.
1. Replace`endpoint`and`azure_openai_endpoint`with the values you obtained in [Get endpoints](#get-endpoints).
89
+
1. Set `endpoint` to your Azure AI Search endpoint, which looks like `https://<your-search-service-name>.search.windows.net.` Set `azure_openai_endpoint` to your Azure AI Foundry endpoint, which looks like `https://<your-foundry-resource-name>.openai.azure.com.` You obtained both values in the [Get endpoints](#get-endpoints) section.
151
90
152
91
1. To verify the variables, run the code cell.
153
92
154
93
## Create a search index
155
94
156
95
In Azure AI Search, an index is a structured collection of data. The following code defines an index named `earth_at_night`, which you specified using the `index_name` variable in the previous section.
157
96
97
+
Add and run a new code cell in the `quickstart-agentic-retrieval.ipynb` notebook with the following code:
from azure.search.documents.indexes import SearchIndexClient
@@ -215,6 +156,8 @@ The index schema contains fields for document identification and page content, e
215
156
216
157
Currently, the `earth_at_night` index is empty. Run the following code to populate the index with JSON documents from NASA's Earth at Night e-book. As required by Azure AI Search, each document conforms to the fields and data types defined in the index schema.
217
158
159
+
Add and run a new code cell in the `quickstart-agentic-retrieval.ipynb` notebook with the following code:
160
+
218
161
```Python
219
162
from azure.search.documents import SearchIndexingBufferedSender
220
163
import requests
@@ -230,10 +173,12 @@ print(f"Documents uploaded to index '{index_name}'")
230
173
231
174
## Create a knowledge agent
232
175
233
-
To connect Azure AI Search to your `gpt-4o-mini` deployment and target the `earth_at_night` index at query time, you need a knowledge agent. The following code defines a knowledge agent named `earth-search-agent`, which you specified using the `agent_name` variable in a previous section.
176
+
To connect Azure AI Search to your `gpt-4.1-mini` deployment and target the `earth_at_night` index at query time, you need a knowledge agent. The following code defines a knowledge agent named `earth-search-agent`, which you specified using the `agent_name` variable in a previous section.
234
177
235
178
To ensure relevant and semantically meaningful responses, `default_reranker_threshold` is set to exclude responses with a reranker score of `2.5` or lower.
236
179
180
+
Add and run a new code cell in the `quickstart-agentic-retrieval.ipynb` notebook with the following code:
181
+
237
182
```Python
238
183
from azure.search.documents.indexes.models import KnowledgeAgent, KnowledgeAgentAzureOpenAIModel, KnowledgeAgentTargetIndex, KnowledgeAgentRequestLimits, AzureOpenAIVectorizerParameters
239
184
@@ -266,6 +211,8 @@ The next step is to define the knowledge agent instructions and conversation con
266
211
267
212
For now, create the following assistant message, which instructs `earth-search-agent` to answer questions about the Earth at night, cite sources using their `ref_id`, and respond with "I don't know" when answers are unavailable.
268
213
214
+
Add and run a new code cell in the `quickstart-agentic-retrieval.ipynb` notebook with the following code:
215
+
269
216
```Python
270
217
instructions ="""
271
218
An Q&A agent that can answer questions about the Earth at night.
@@ -287,6 +234,8 @@ You're ready to initiate the agentic retrieval pipeline. The input for this pipe
287
234
288
235
The following code sends a two-part user query to `earth-search-agent`, which deconstructs the query into subqueries, runs the subqueries against both text fields and vector embeddings in the `earth_at_night` index, and ranks and merges the results. The response is then appended to the `messages` array.
289
236
237
+
Add and run a new code cell in the `quickstart-agentic-retrieval.ipynb` notebook with the following code:
238
+
290
239
```Python
291
240
from azure.search.documents.agent import KnowledgeAgentRetrievalClient
292
241
from azure.search.documents.agent.models import KnowledgeAgentRetrievalRequest, KnowledgeAgentMessage, KnowledgeAgentMessageTextContent, KnowledgeAgentIndexParams
@@ -315,7 +264,9 @@ messages.append({
315
264
316
265
### Review the response, activity, and results
317
266
318
-
To output the response, activity, and results of the retrieval pipeline, run the following code.
267
+
Now you want to display the response, activity, and results of the retrieval pipeline.
268
+
269
+
Add and run a new code cell in the `quickstart-agentic-retrieval.ipynb` notebook with the following code:
319
270
320
271
```Python
321
272
import textwrap
@@ -335,7 +286,7 @@ The output should be similar to the following example, where:
335
286
336
287
+`Response` provides a text string of the most relevant documents (or chunks) in the search index based on the user query. As shown later in this quickstart, you can pass this string to an LLM for answer generation.
337
288
338
-
+`Activity` tracks the steps that were taken during the retrieval process, including the subqueries generated by your `gpt-4o-mini` deployment and the tokens used for query planning and execution.
289
+
+`Activity` tracks the steps that were taken during the retrieval process, including the subqueries generated by your `gpt-4.1-mini` deployment and the tokens used for query planning and execution.
339
290
340
291
+`Results` lists the documents that contributed to the response, each one identified by their `doc_key`.
341
292
@@ -391,7 +342,9 @@ Results
391
342
392
343
## Create the Azure OpenAI client
393
344
394
-
To extend the retrieval pipeline from answer *extraction* to answer *generation*, set up the Azure OpenAI client to interact with your `gpt-4o-mini` deployment, which you specified using the `answer_model` variable in a previous section.
345
+
To extend the retrieval pipeline from answer *extraction* to answer *generation*, set up the Azure OpenAI client to interact with your `gpt-4.1-mini` deployment, which you specified using the `answer_model` variable in a previous section.
346
+
347
+
Add and run a new code cell in the `quickstart-agentic-retrieval.ipynb` notebook with the following code:
395
348
396
349
```Python
397
350
from openai import AzureOpenAI
@@ -407,7 +360,9 @@ client = AzureOpenAI(
407
360
408
361
### Use the Responses API to generate an answer
409
362
410
-
You can now use the Responses API to generate a detailed answer based on the indexed documents. The following code sends the `messages` array, which contains the conversation history, to your `gpt-4o-mini` deployment.
363
+
You can now use the Responses API to generate a detailed answer based on the indexed documents. The following code sends the `messages` array, which contains the conversation history, to your `gpt-4.1-mini` deployment.
364
+
365
+
Add and run a new code cell in the `quickstart-agentic-retrieval.ipynb` notebook with the following code:
The output should be similar to the following example, which uses the reasoning capabilities of `gpt-4o-mini` to provide contextually relevant answers.
377
+
The output should be similar to the following example, which uses the reasoning capabilities of `gpt-4.1-mini` to provide contextually relevant answers.
423
378
424
379
```
425
380
Suburban belts often exhibit larger December brightening than urban cores primarily because of the type of development and light distribution in those areas. Suburbs tend to have more uniform and expansive lighting, making them more visible in nighttime satellite images. In contrast, urban cores, although having higher absolute light levels, often contain dense building clusters that can cause light to be obscured or concentrated in smaller areas, leading to less visible brightening when viewed from space. Regarding the visibility of the Phoenix nighttime street grid from space, it is attributed to the city's grid layout and the intensity of its street lighting. The grid pattern of the streets and the significant development around them create a stark contrast against less developed areas. Conversely, large stretches of interstate in the Midwest may remain dimmer due to fewer densely populated structures and less intensive street lighting, resulting in less illumination overall. For more detailed insights, you can refer to the sources: [0] and [1].
@@ -429,6 +384,8 @@ Suburban belts often exhibit larger December brightening than urban cores primar
429
384
430
385
Alternatively, you can use the Chat Completions API for answer generation.
431
386
387
+
Add and run a new code cell in the `quickstart-agentic-retrieval.ipynb` notebook with the following code:
388
+
432
389
```Python
433
390
response = client.chat.completions.create(
434
391
model=answer_model,
@@ -449,6 +406,8 @@ Suburban belts tend to display larger December brightening than urban cores, des
449
406
450
407
Continue the conversation by sending another user query to `earth-search-agent`. The following code reruns the retrieval pipeline, fetching relevant content from the `earth_at_night` index and appending the response to the `messages` array. However, unlike before, you can now use the Azure OpenAI client to generate an answer based on the retrieved content.
451
408
409
+
Add and run a new code cell in the `quickstart-agentic-retrieval.ipynb` notebook with the following code:
410
+
452
411
```Python
453
412
messages.append({
454
413
"role": "user",
@@ -469,7 +428,9 @@ messages.append({
469
428
470
429
### Review the new response, activity, and results
471
430
472
-
To output the latest response, activity, and results of the retrieval pipeline, run the following code.
431
+
Now you want to display the response, activity, and results of the retrieval pipeline.
432
+
433
+
Add and run a new code cell in the `quickstart-agentic-retrieval.ipynb` notebook with the following code:
473
434
474
435
```Python
475
436
import textwrap
@@ -489,6 +450,8 @@ print(json.dumps([r.as_dict() for r in retrieval_result.references], indent=2))
489
450
490
451
Now that you've sent multiple user queries, use the Responses API to generate an answer based on the indexed documents and conversation history, which is captured in the `messages` array.
491
452
453
+
Add and run a new code cell in the `quickstart-agentic-retrieval.ipynb` notebook with the following code:
454
+
492
455
```Python
493
456
response = client.responses.create(
494
457
model=answer_model,
@@ -513,6 +476,8 @@ In the Azure portal, you can find and manage resources by selecting **All resour
513
476
514
477
### Delete the knowledge agent
515
478
479
+
Add and run a new code cell in the `quickstart-agentic-retrieval.ipynb` notebook with the following code:
![learn-build-service-prod[bot]](https://avatars.githubusercontent.com/in/237442?v=4&size=40){kind=avatar}
0 commit comments