Guida introduttiva: Eseguire il recupero agentico in Azure AI Search

2025-06-25

Annotazioni

Questa funzionalità è attualmente disponibile in anteprima pubblica. Questa anteprima viene fornita senza un contratto di servizio e non è consigliata per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero presentare funzionalità limitate. Per altre informazioni, vedere le Condizioni supplementari per l'uso delle anteprime di Microsoft Azure.

In questa guida introduttiva, viene utilizzato il recupero agentico per creare un'esperienza di ricerca conversazionale basata su modelli di linguaggio di grandi dimensioni e sui tuoi dati proprietari. Il recupero agentico suddivide le query utente complesse in sottoquery, esegue le sottoquery in parallelo ed estrae i dati di base dai documenti indicizzati in Ricerca di intelligenza artificiale di Azure. L'output è destinato all'integrazione con soluzioni di chat agentiche e personalizzate.

Anche se è possibile fornire dati personalizzati, questo argomento di avvio rapido usa documenti JSON di esempio dell'e-book Earth at Night della NASA. I documenti descrivono argomenti scientifici generali e immagini della Terra di notte come osservato dallo spazio.

Suggerimento

Per iniziare a usare un notebook di Jupyter, vedere invece il repository Azure-Samples/azure-search-dotnet-samples in GitHub.

Prerequisiti

Un account Azure con una sottoscrizione attiva. Creare un account gratuito.
Un servizio ricerca di intelligenza artificiale di Azure sul livello Basic o superiore con semantic ranker abilitato.
Progetto Azure AI Foundry. Quando si crea un progetto Azure AI Foundry, si ottiene una risorsa di Azure AI Foundry (necessaria per le distribuzioni di modelli).
Interfaccia della riga di comando di Azure per l'autenticazione senza chiave con MICROSOFT Entra ID.

Configurare l'accesso in base al ruolo

È possibile usare le chiavi API del servizio di ricerca o Microsoft Entra ID con assegnazioni di ruolo. Le chiavi sono più facili da iniziare, ma i ruoli sono più sicuri.

Per configurare l'accesso basato sui ruoli consigliato:

Accedi al portale di Azure.
Abilitare l'accesso basato sui ruoli nel servizio Ricerca intelligenza artificiale di Azure.
Nel servizio Ricerca intelligenza artificiale di Azure assegnare a se stessi i ruoli seguenti .
- Collaboratore servizi di ricerca
- Collaboratore ai dati dell'indice di ricerca
- Lettore di dati dell'indice di ricerca

Per il recupero agentico, Azure AI Search deve anche accedere alla risorsa Fonderia di Azure OpenAI.

Creare un'identità gestita assegnata dal sistema nel servizio Ricerca intelligenza artificiale di Azure. Ecco come eseguire questa operazione usando l'interfaccia della riga di comando di Azure:
```
az search service update --name YOUR-SEARCH-SERVICE-NAME --resource-group YOUR-RESOURCE-GROUP-NAME --identity-type SystemAssigned
```
Se si dispone già di un'identità gestita, è possibile ignorare questo passaggio.
Nella risorsa Azure AI Foundry, assegnare Utente dei Servizi cognitivi all'identità gestita che hai creato per il servizio di ricerca.

Distribuire modelli

Per usare il recupero agentico, è necessario distribuire uno dei modelli OpenAI di Azure supportati nella risorsa Azure AI Foundry:

Modello di chat per la pianificazione delle query e la generazione di risposte. In questo avvio rapido usiamo gpt-4.1-mini. Facoltativamente, è possibile usare un modello diverso per la pianificazione delle query e un altro per la generazione di risposte, ma questa guida introduttiva usa lo stesso modello per semplicità.
Modello di incorporamento per le query vettoriali. In questo avvio rapido usiamo text-embedding-3-large, ma puoi usare qualsiasi modello di incorporamento che supporta l'attività text-embedding.

Per distribuire i modelli OpenAI di Azure:

Accedere al portale di Azure AI Foundry e selezionare la risorsa Azure AI Foundry.
Nel riquadro sinistro selezionare Catalogo modelli.
Selezionare gpt-4.1-mini e quindi selezionare Usa questo modello.
Specificare un nome di distribuzione. Per semplificare il codice, è consigliabile usare gpt-4.1-mini.
Lasciare le impostazioni predefinite.
Seleziona Distribuisci.
Ripeti i passaggi precedenti, ma questa volta utilizza il modello di embedding text-embedding-3-large.

Ottenere gli endpoint

Nel codice specificare gli endpoint seguenti per stabilire connessioni con il servizio Ricerca intelligenza artificiale di Azure e la risorsa Azure AI Foundry. Questi passaggi presuppongono che l'accesso basato sui ruoli sia stato configurato come descritto in precedenza.

Per ottenere gli endpoint di servizio:

Accedi al portale di Azure.
Nel servizio Ricerca intelligenza artificiale di Azure:
1. Nel riquadro sinistro selezionare Panoramica.
2. Copiare l'URL, che dovrebbe essere simile a https://my-service.search.windows.net.
Nella risorsa Azure AI Foundry:
1. Nel riquadro sinistro, selezionare Gestione risorse>Chiavi ed endpoint.
2. Selezionare la scheda OpenAI e copiare l'URL simile a https://my-resource.openai.azure.com.

Importante

Il recupero agentico ha due modelli di fatturazione basati su token:

Fatturazione da Azure OpenAI per la pianificazione delle query.
Fatturazione per l'esecuzione di query con Azure AI Search (classificazione semantica).

La classificazione semantica è gratuita nell'anteprima pubblica iniziale. Dopo l'anteprima, viene applicata la fatturazione standard dei token. Per altre informazioni, vedere Disponibilità e prezzi del recupero agentico.

Configurazione

Creare una nuova cartella quickstart-agentic-retrieval per contenere l'applicazione e aprire Visual Studio Code in tale cartella con il comando seguente:
```
mkdir quickstart-agentic-retrieval && cd quickstart-agentic-retrieval
```
Creare una nuova applicazione console con il comando seguente:
```
dotnet new console
```
Installare la libreria client di Azure AI Search (Azure.Search.Documents) per .NET con:
```
dotnet add package Azure.Search.Documents --version 11.7.0-beta.4
```
Installare la libreria client OpenAI di Azure (Azure.AI.OpenAI) per .NET con:
```
dotnet add package Azure.AI.OpenAI --version 2.1.0
```
Installare il dotenv pacchetto per caricare le variabili di ambiente da un .env file con:
```
dotnet add package dotenv.net
```
Per l'autenticazione senza chiave consigliata con Microsoft Entra ID, installare il pacchetto Azure.Identity con:
```
dotnet add package Azure.Identity
```
Per l'autenticazione senza chiave consigliata con Microsoft Entra ID, accedere ad Azure con il comando seguente:
```
az login
```

Creare l'indice e l'agente di conoscenza

Creare un nuovo file denominato .env nella quickstart-agentic-retrieval cartella e aggiungere le variabili di ambiente seguenti:
```
AZURE_OPENAI_ENDPOINT=https://<your-ai-foundry-resource-name>.openai.azure.com/
AZURE_OPENAI_GPT_DEPLOYMENT=gpt-4.1-mini
AZURE_SEARCH_ENDPOINT=https://<your-search-service-name>.search.windows.net
AZURE_SEARCH_INDEX_NAME=agentic-retrieval-sample
```
Sostituire <your-search-service-name> e <your-ai-foundry-resource-name> con il nome effettivo del servizio Ricerca intelligenza artificiale di Azure e il nome della risorsa Azure AI Foundry.

In Program.cs copiare e incollare il codice seguente.

using dotenv.net;
using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using System.Net.Http;
using System.Text.Json;
using Azure.Search.Documents;
using Azure.Search.Documents.Models;
using Azure.Search.Documents.Agents;
using Azure.Search.Documents.Agents.Models;
using Azure.AI.OpenAI;
using OpenAI.Chat;

namespace AzureSearch.Quickstart
{
    class Program
    {
        static async Task Main(string[] args)
        {
            // Load environment variables from .env file
            // Ensure you have a .env file in the same directory with the required variables.
            DotEnv.Load();

            string endpoint = Environment.GetEnvironmentVariable("AZURE_SEARCH_ENDPOINT") 
                ?? throw new InvalidOperationException("AZURE_SEARCH_ENDPOINT is not set.");
            string azureOpenAIEndpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") 
                ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");

            string azureOpenAIGptDeployment = "gpt-4.1-mini";
            string azureOpenAIGptModel = "gpt-4.1-mini";
            string azureOpenAIEmbeddingDeployment = "text-embedding-3-large";
            string azureOpenAIEmbeddingModel = "text-embedding-3-large";

            string indexName = "earth_at_night";
            string agentName = "earth-search-agent";

            var credential = new DefaultAzureCredential();            

            // Define the fields for the index
            var fields = new List<SearchField>
            {
                new SimpleField("id", SearchFieldDataType.String) 
                { 
                    IsKey = true, 
                    IsFilterable = true, 
                    IsSortable = true, 
                    IsFacetable = true 
                },
                new SearchField("page_chunk", SearchFieldDataType.String) 
                { 
                    IsFilterable = false, 
                    IsSortable = false, 
                    IsFacetable = false 
                },
                new SearchField("page_embedding_text_3_large", SearchFieldDataType.Collection(SearchFieldDataType.Single)) 
                { 
                    VectorSearchDimensions = 3072, 
                    VectorSearchProfileName = "hnsw_text_3_large" 
                },
                new SimpleField("page_number", SearchFieldDataType.Int32) 
                { 
                    IsFilterable = true, 
                    IsSortable = true, 
                    IsFacetable = true 
                }
            };// Define the vectorizer
            var vectorizer = new AzureOpenAIVectorizer(vectorizerName: "azure_openai_text_3_large")
            {
                Parameters = new AzureOpenAIVectorizerParameters
                {
                    ResourceUri = new Uri(azureOpenAIEndpoint),
                    DeploymentName = azureOpenAIEmbeddingDeployment,
                    ModelName = azureOpenAIEmbeddingModel
                }
            };

            // Define the vector search profile and algorithm
            var vectorSearch = new VectorSearch()
            {
                Profiles =
                {
                    new VectorSearchProfile(
                        name: "hnsw_text_3_large",
                        algorithmConfigurationName: "alg"
                    )
                    {
                        VectorizerName = "azure_openai_text_3_large"
                    }
                },
                Algorithms =
                {
                    new HnswAlgorithmConfiguration(name: "alg")
                },
                Vectorizers =
                {
                    vectorizer
                }
            };

            // Define semantic configuration
            var semanticConfig = new SemanticConfiguration(
                name: "semantic_config",
                prioritizedFields: new SemanticPrioritizedFields
                {
                    ContentFields = { new SemanticField("page_chunk") }
                }
            );

            var semanticSearch = new SemanticSearch()
            {
                DefaultConfigurationName = "semantic_config",
                Configurations =
                {
                    semanticConfig
                }
            };

            // Create the index
            var index = new SearchIndex(indexName)
            {
                Fields = fields,
                VectorSearch = vectorSearch,
                SemanticSearch = semanticSearch
            };

            // Create the index client. Delete the index if it exists and then recreate it.
            var indexClient = new SearchIndexClient(new Uri(endpoint), credential);
            try
            {
                await indexClient.DeleteIndexAsync(indexName);
                Console.WriteLine($"Index '{indexName}' deleted successfully (if it existed).");
            }
            catch (Exception ex)
            {
                Console.WriteLine($"Index '{indexName}' could not be deleted or did not exist: {ex.Message}");
            }            
            await indexClient.CreateOrUpdateIndexAsync(index);
            Console.WriteLine($"Index '{indexName}' created or updated successfully");

            // Download the documents from the GitHub URL
            string url = "https://raw.githubusercontent.com/Azure-Samples/azure-search-sample-data/refs/heads/main/nasa-e-book/earth-at-night-json/documents.json";
            var httpClient = new HttpClient();
            var response = await httpClient.GetAsync(url);
            response.EnsureSuccessStatusCode();
            var json = await response.Content.ReadAsStringAsync();

            var documents = JsonSerializer.Deserialize<List<Dictionary<string, object>>>(json);
            var searchClient = new SearchClient(new Uri(endpoint), indexName, credential);
            var searchIndexingBufferedSender = new SearchIndexingBufferedSender<Dictionary<string, object>>(
                searchClient,
                new SearchIndexingBufferedSenderOptions<Dictionary<string, object>>
                {
                    KeyFieldAccessor = doc => doc["id"].ToString(),
                }
            );            
            await searchIndexingBufferedSender.UploadDocumentsAsync(documents);
            await searchIndexingBufferedSender.FlushAsync();
            Console.WriteLine($"Documents uploaded to index '{indexName}'");

            var openAiParameters = new AzureOpenAIVectorizerParameters
            {
                ResourceUri = new Uri(azureOpenAIEndpoint),
                DeploymentName = azureOpenAIGptDeployment,
                ModelName = azureOpenAIGptModel
            };

            var agentModel = new KnowledgeAgentAzureOpenAIModel(azureOpenAIParameters: openAiParameters);

            var targetIndex = new KnowledgeAgentTargetIndex(indexName)
            {
                DefaultRerankerThreshold = 2.5f
            };            
            // Create the knowledge agent
            var agent = new KnowledgeAgent(
                name: agentName,
                models: new[] { agentModel },
                targetIndexes: new[] { targetIndex });
            await indexClient.CreateOrUpdateKnowledgeAgentAsync(agent);
            Console.WriteLine($"Search agent '{agentName}' created or updated successfully");

            string instructions = @"
            A Q&A agent that can answer questions about the Earth at night.
            Sources have a JSON format with a ref_id that must be cited in the answer.
            If you do not have the answer, respond with ""I don't know"".
            ";

            var messages = new List<Dictionary<string, object>>
            {
                new Dictionary<string, object>
                {
                    { "role", "system" },
                    { "content", instructions }
                }
            };            
            var agentClient = new KnowledgeAgentRetrievalClient(
                endpoint: new Uri(endpoint),
                agentName: agentName,
                tokenCredential: new DefaultAzureCredential()
            );

            messages.Add(new Dictionary<string, object>
            {
                { "role", "user" },
                { "content", @"
                Why do suburban belts display larger December brightening than urban cores even though absolute light levels are higher downtown?
                Why is the Phoenix nighttime street grid is so sharply visible from space, whereas large stretches of the interstate between midwestern cities remain comparatively dim?
                " }
            });            
            var retrievalResult = await agentClient.RetrieveAsync(
                retrievalRequest: new KnowledgeAgentRetrievalRequest(
                    messages: messages
                        .Where(message => message["role"].ToString() != "system")
                        .Select(message => new KnowledgeAgentMessage(
                            role: message["role"].ToString(),
                            content: new[] { new KnowledgeAgentMessageTextContent(message["content"].ToString()) }))
                        .ToList()
                )
                {
                    TargetIndexParams = { new KnowledgeAgentIndexParams { IndexName = indexName, RerankerThreshold = 2.5f } }
                }
            );            
            messages.Add(new Dictionary<string, object>
            {
                { "role", "assistant" },
                { "content", (retrievalResult.Value.Response[0].Content[0] as KnowledgeAgentMessageTextContent).Text }
            });

            Console.WriteLine((retrievalResult.Value.Response[0].Content[0] as KnowledgeAgentMessageTextContent).Text);

            Console.WriteLine("Activities:");
            foreach (var activity in retrievalResult.Value.Activity)
            {
                Console.WriteLine($"Activity Type: {activity.GetType().Name}");
                string activityJson = JsonSerializer.Serialize(
                    activity,
                    activity.GetType(),
                    new JsonSerializerOptions { WriteIndented = true }
                );
                Console.WriteLine(activityJson);
            }

            Console.WriteLine("Results");
            foreach (var reference in retrievalResult.Value.References)
            {
                Console.WriteLine($"Reference Type: {reference.GetType().Name}");
                string referenceJson = JsonSerializer.Serialize(
                    reference,
                    reference.GetType(),
                    new JsonSerializerOptions { WriteIndented = true }
                );
                Console.WriteLine(referenceJson);            }

            AzureOpenAIClient azureClient = new(
                new Uri(azureOpenAIEndpoint),
                new DefaultAzureCredential());
            ChatClient chatClient = azureClient.GetChatClient(azureOpenAIGptDeployment);

            List<ChatMessage> chatMessages = messages
                .Select<Dictionary<string, object>, ChatMessage>(m => m["role"].ToString() switch
                {
                    "user" => new UserChatMessage(m["content"].ToString()),
                    "assistant" => new AssistantChatMessage(m["content"].ToString()),
                    "system" => new SystemChatMessage(m["content"].ToString()),
                    _ => null
                })                
                .Where(m => m != null)
                .ToList();

            var result = await chatClient.CompleteChatAsync(chatMessages);
            Console.WriteLine($"[ASSISTANT]: {result.Value.Content[0].Text.Replace(".", "\n")}");

            messages.Add(new Dictionary<string, object>
            {
                { "role", "user" },
                { "content", "How do I find lava at night?" }            
            });

            var retrievalResult2 = await agentClient.RetrieveAsync(
                retrievalRequest: new KnowledgeAgentRetrievalRequest(
                    messages: messages
                        .Where(message => message["role"].ToString() != "system")
                        .Select(message => new KnowledgeAgentMessage(
                            role: message["role"].ToString(),
                            content: new[] { new KnowledgeAgentMessageTextContent(message["content"].ToString()) }))
                        .ToList()
                )
                {
                    TargetIndexParams = { new KnowledgeAgentIndexParams { IndexName = indexName, RerankerThreshold = 2.5f } }
                }
            );

            messages.Add(new Dictionary<string, object>
            {
                { "role", "assistant" },
                { "content", (retrievalResult2.Value.Response[0].Content[0] as KnowledgeAgentMessageTextContent).Text }
            });

            Console.WriteLine((retrievalResult2.Value.Response[0].Content[0] as KnowledgeAgentMessageTextContent).Text);

            Console.WriteLine("Activities:");
            foreach (var activity in retrievalResult2.Value.Activity)
            {
                Console.WriteLine($"Activity Type: {activity.GetType().Name}");
                string activityJson2 = JsonSerializer.Serialize(
                    activity,
                    activity.GetType(),
                    new JsonSerializerOptions { WriteIndented = true }
                );
                Console.WriteLine(activityJson2);
            }

            Console.WriteLine("Results");
            foreach (var reference in retrievalResult2.Value.References)
            {
                Console.WriteLine($"Reference Type: {reference.GetType().Name}");
                string referenceJson2 = JsonSerializer.Serialize(
                    reference,
                    reference.GetType(),
                    new JsonSerializerOptions { WriteIndented = true }
                );
                Console.WriteLine(referenceJson2);
            }

            List<ChatMessage> chatMessages2 = messages
                .Select<Dictionary<string, object>, ChatMessage>(m => m["role"].ToString() switch
                {
                    "user" => new UserChatMessage(m["content"].ToString()),
                    "assistant" => new AssistantChatMessage(m["content"].ToString()),
                    "system" => new SystemChatMessage(m["content"].ToString()),
                    _ => null
                })                
                .Where(m => m != null)
                .ToList();

            var result2 = await chatClient.CompleteChatAsync(chatMessages2);
            Console.WriteLine($"[ASSISTANT]: {result2.Value.Content[0].Text.Replace(".", "\n")}");

            await indexClient.DeleteKnowledgeAgentAsync(agentName);
            System.Console.WriteLine($"Search agent '{agentName}' deleted successfully");

            await indexClient.DeleteIndexAsync(indexName);            
            System.Console.WriteLine($"Index '{indexName}' deleted successfully");
        }
    }
}

Compilare ed eseguire l'applicazione con il comando seguente:
```
dotnet run
```

Risultato

L'output dell'applicazione dovrebbe essere simile al seguente:

Index 'earth_at_night' deleted successfully (if it existed).
Index 'earth_at_night' created or updated successfully
Documents uploaded to index 'earth_at_night'
Search agent 'earth-search-agent' created or updated successfully
[]
Activities:
Activity Type: KnowledgeAgentModelQueryPlanningActivityRecord
{
  "InputTokens": 1265,
  "OutputTokens": 536,
  "ElapsedMs": null,
  "Id": 0
}
Activity Type: KnowledgeAgentSearchActivityRecord
{
  "TargetIndex": "earth_at_night",
  "Query": {
    "Search": "Reasons for larger December brightening in suburban belts compared to urban cores despite higher absolute light levels downtown",
    "Filter": null
  },
  "QueryTime": "2025-06-19T14:02:27.504+00:00",
  "Count": 0,
  "ElapsedMs": 768,
  "Id": 1
}
Activity Type: KnowledgeAgentSearchActivityRecord
{
  "TargetIndex": "earth_at_night",
  "Query": {
    "Search": "Why is the Phoenix nighttime street grid sharply visible from space while large stretches of interstate between Midwestern cities are comparatively dim?",
    "Filter": null
  },
  "QueryTime": "2025-06-19T14:02:27.817+00:00",
  "Count": 0,
  "ElapsedMs": 292,
  "Id": 2
}
Activity Type: KnowledgeAgentSemanticRankerActivityRecord
{
  "InputTokens": 52609,
  "ElapsedMs": null,
  "Id": 3
}
Results
[ASSISTANT]: The suburban belts display larger December brightening than urban cores because suburban areas often have more residential lighting that increases during December holidays, such as decorative lights, leading to a noticeable rise in brightness
 In contrast, urban cores already have very high absolute light levels, so the relative increase from additional lighting is less significant


Regarding Phoenix's nighttime street grid visibility from space, it is sharply visible because the city has a distinctive, well-lit, and uniformly spaced street grid pattern that emits consistent light
 In contrast, large stretches of interstate highways between Midwestern cities remain comparatively dim because highways have less continuous lighting, with fewer lights spread over longer distances, making them less prominent from space [ref_id: night_earth_study_2021]

[{"ref_id":0,"content":"<!-- PageHeader=\"Volcanoes\" -->\n\n## Volcanoes\n\n### The Infrared Glows of Kilauea's Lava Flows—Hawaii\n\nIn early May 2018, an eruption on Hawaii's Kilauea volcano began to unfold. The eruption took a dangerous turn on May 3, 2018, when new fissures opened in the residential neighborhood of Leilani Estates. During the summer-long eruptive event, other fissures emerged along the East Rift Zone. Lava from vents along the rift zone flowed downslope, reaching the ocean in several areas, and filling in Kapoho Bay.\n\nA time series of Landsat 8 imagery shows the progression of the lava flows from May 16 to August 13. The night view combines thermal, shortwave infrared, and near-infrared wavelengths to tease out the very hot lava (bright white), cooling lava (red), and lava flows obstructed by clouds (purple).\n\n#### Figure: Location of Kilauea Volcano, Hawaii\n\nA globe is shown centered on North America, with a marker placed in the Pacific Ocean indicating the location of Hawaii, to the southwest of the mainland United States.\n\n<!-- PageFooter=\"Earth at Night\" -->\n<!-- PageNumber=\"44\" -->"},{"ref_id":1,"content":"<!-- PageHeader=\"Volcanoes\" -->\n\n### Nighttime Glow at Mount Etna - Italy\n\nAt about 2:30 a.m. local time on March 16, 2017, the VIIRS DNB on the Suomi NPP satellite captured this nighttime image of lava flowing on Mount Etna in Sicily, Italy. Etna is one of the world's most active volcanoes.\n\n#### Figure: Location of Mount Etna\nA world globe is depicted, with a marker indicating the location of Mount Etna in Sicily, Italy, in southern Europe near the center of the Mediterranean Sea.\n\n<!-- PageFooter=\"Earth at Night\" -->\n<!-- PageNumber=\"48\" -->"},{"ref_id":2,"content":"For the first time in perhaps a decade, Mount Etna experienced a \"flank eruption\"—erupting from its side instead of its summit—on December 24, 2018. The activity was accompanied by 130 earthquakes occurring over three hours that morning. Mount Etna, Europe’s most active volcano, has seen periodic activity on this part of the mountain since 2013. The Operational Land Imager (OLI) on the Landsat 8 satellite acquired the main image of Mount Etna on December 28, 2018.\n\nThe inset image highlights the active vent and thermal infrared signature from lava flows, which can be seen near the newly formed fissure on the southeastern side of the volcano. The inset was created with data from OLI and the Thermal Infrared Sensor (TIRS) on Landsat 8. Ash spewing from the fissure cloaked adjacent villages and delayed aircraft from landing at the nearby Catania airport. Earthquakes occurred in the subsequent days after the initial eruption and displaced hundreds of people from their homes.\n\nFor nighttime images of Mount Etna’s March 2017 eruption, see pages 48–51.\n\n---\n\n### Hazards of Volcanic Ash Plumes and Satellite Observation\n\nWith the help of moonlight, satellite instruments can track volcanic ash plumes, which present significant hazards to airplanes in flight. The volcanic ash—composed of tiny pieces of glass and rock—is abrasive to engine turbine blades, and can melt on the blades and other engine parts, causing damage and even engine stalls. This poses a danger to both the plane’s integrity and passenger safety. Volcanic ash also reduces visibility for pilots and can cause etching of windshields, further reducing pilots’ ability to see. Nightlight images can be combined with thermal images to provide a more complete view of volcanic activity on Earth’s surface.\n\nThe VIIRS Day/Night Band (DNB) on polar-orbiting satellites uses faint light sources such as moonlight, airglow (the atmosphere’s self-illumination through chemical reactions), zodiacal light (sunlight scattered by interplanetary dust), and starlight from the Milky Way. Using these dim light sources, the DNB can detect changes in clouds, snow cover, and sea ice:\n\n#### Table: Light Sources Used by VIIRS DNB\n\n| Light Source         | Description                                                        
          |\n|----------------------|------------------------------------------------------------------------------|\n| Moonlight            | Reflected sunlight from the Moon, illuminating Earth's surface at night      |\n| Airglow              | Atmospheric self-illumination from chemical reactions                        |\n| Zodiacal Light       | Sunlight scattered by interplanetary dust                                    |\n| Starlight/Milky Way  | Faint illumination provided by stars in the Milky Way                        |\n\nGeostationary Operational Environmental Satellites (GOES), managed by NOAA, orbit over Earth’s equator and offer uninterrupted observations of North America. High-latitude areas such as Alaska benefit from polar-orbiting satellites like Suomi NPP, which provide overlapping coverage at the poles, enabling more data collection in these regions. During polar darkness (winter months), VIIRS DNB data allow scientists to:\n\n- Observe sea ice formation\n- Monitor snow cover extent at the highest latitudes\n- Detect open water for ship navigation\n\n#### Table: Satellite Coverage Overview\n\n| Satellite Type          | Orbit           | Coverage Area         | Special Utility                              |\n|------------------------|-----------------|----------------------|----------------------------------------------|\n| GOES              
     | Geostationary   | Equatorial/North America | Continuous regional monitoring              |\n| Polar-Orbiting (e.g., Suomi NPP) | Polar-orbiting    | Poles/high latitudes      | Overlapping passes; useful during polar night|\n\n---\n\n### Weather Forecasting and Nightlight Data\n\nThe use of nightlight data by weather forecasters is growing as the VIIRS instrument enables observation of clouds at night illuminated by sources such as moonlight and lightning. Scientists use these data to study the nighttime behavior of weather systems, including severe storms, which can develop and strike populous areas at night as well as during the day. Combined with thermal data, visible nightlight data allow the detection of clouds at various heights in the atmosphere, such as dense marine fog. This capability enables weather forecasters to issue marine advisories with higher confidence, leading to greater utility. (See \"Marine Layer Clouds—California\" on page 56.)\n\nIn this section of the book, you will see how nightlight data are used to observe nature’s spectacular light shows across a wide range of sources.\n\n---\n\n#### Notable Data from Mount Etna Flank Eruption (December 2018)\n\n| Event/Observation                  | Details                                        
                            |\n|-------------------------------------|----------------------------------------------------------------------------|\n| Date of Flank Eruption              | December 24, 2018                                                          |\n| Number of Earthquakes               | 130 earthquakes within 3 hours                                              |\n| Image Acquisition                   | December 28, 2018 by Landsat 8 OLI                                   
      |\n| Location of Eruption                | Southeastern side of Mount Etna                   
                         |\n| Thermal Imaging Data                | From OLI and TIRS (Landsat 8), highlighting active vent and lava flows     |\n| Impact on Villages/Air Transport    | Ash covered villages; delayed aircraft at Catania airport                  |\n| Displacement                   
     | Hundreds of residents displaced                                            |\n| Ongoing Seismic Activity            | Earthquakes continued after initial eruption                             
  |\n\n---\n\n<!-- PageFooter=\"Earth at Night\" -->\n<!-- PageNumber=\"30\" -->"},{"ref_id":3,"content":"# Volcanoes\n\n---\n\n### Mount Etna Erupts - Italy\n\nThe highly active Mount Etna in Italy sent red lava rolling down its flank on March 19, 2017. An astronaut onboard the ISS took the photograph below of the volcano and its environs that night. City lights surround the mostly dark volcanic area.\n\n---\n\n#### Figure 1: Location of Mount Etna, Italy\n\nA world map highlighting the location of Mount Etna in southern Italy. The marker indicates its geographic placement on the east coast of Sicily, Italy, in the Mediterranean region, south of mainland Europe and north of northern Africa.\n\n---\n\n#### Figure 2: Nighttime View of Mount Etna's Eruption and Surrounding Cities\n\nThis is a nighttime satellite image taken on March 19, 2017, showing the eruption of Mount Etna (southeastern cone) with visible bright red and orange coloring indicating flowing lava from a lateral vent. The surrounding areas are illuminated by city lights, with the following geographic references labeled:\n\n| Location        | Position in Image         | Visible Characteristics             
       |\n|-----------------|--------------------------|--------------------------------------------|\n| Mt. Etna (southeastern cone) | Top center-left | Bright red/orange lava flow                |\n| Lateral vent    | Left of the volcano       | Faint red/orange flow extending outwards   |\n| Resort          | Below the volcano, to the left   | Small cluster of lights                    |\n| Giarre          | Top right                 | Bright cluster of city lights              |\n| Acireale        | Center right              | Large, bright area of city lights          |\n| Biancavilla     | Bottom left               | Smaller cluster of city lights             |\n\nAn arrow pointing north is shown on the image for orientation.\n\n---\n\n<!-- Earth at Night Page Footer -->\n<!-- Page Number: 50 -->"},{"ref_id":4,"content":"# Volcanoes\n\n## Figure: Satellite Image of Sicily and Mount Etna Lava, March 16, 2017\n\nThe annotated satellite image below shows the island of Sicily and the surrounding region at night, highlighting city lights and volcanic activity.\n\n**Description:**\n\n- **Date of image:** March 16, 2017\n- **Geographical locations labeled:**\n    - Major cities: Palermo (northwest Sicily), Marsala (western Sicily), Catania (eastern Sicily)\n    - Significant feature: Mount Etna, labeled with an adjacent \"hot lava\" region showing the glow from active lava flows\n    - Surrounding water body: Mediterranean Sea\n    - Island: Malta to the south of Sicily\n- **Other details:** \n    - The image is shown at night, with bright spots indicating city lights.\n    - The position of \"hot lava\" near Mount Etna is distinctly visible as a bright spot different from other city lights, indicating volcanic activity.\n    - A scale bar is included showing a reference length of 50 km.\n    - North direction is indicated with an arrow.\n    - Cloud cover is visible in the southwest part of the image, partially obscuring the view near Marsala and Malta.\n\n**Summary of Features Visualized:**\n\n| Feature          | Description                 
                          |\n|------------------|------------------------------------------------------|\n| Cities           | Bright clusters indicating locations: Palermo, Marsala, Catania |\n| Mount Etna       | Marked on the map, located on the eastern side of Sicily, with visible hot lava activity |\n| Malta            | Clearly visible to the south of Sicily               |\n| Water bodies     | Mediterranean Sea labeled                            |\n| Scale & Direction| 50 km scale bar and North indicator                  |\n| Date             | March 16, 2017                     
                  |\n| Cloud Cover      | Visible in the lower left (southern) part of the image |\n\nThis figure demonstrates the visibility of volcanic activity at Mount Etna from space at night, distinguishing the light from hot lava against the background city lights of Sicily and Malta."},{"ref_id":5,"content":"## Nature's Light Shows\n\nAt night, with the light of the Sun removed, nature's brilliant glow from Earth's surface becomes visible to the naked eye from space. Some of Earth's most spectacular light shows are natural, like the aurora borealis, or Northern Lights, in the Northern Hemisphere (aurora australis, or Southern Lights, in the Southern Hemisphere). The auroras are natural electrical phenomena caused by charged particles that race from the Sun toward Earth, inducing chemical reactions in the upper atmosphere and creating the appearance of streamers of reddish or greenish light in the sky, usually near the northern or southern magnetic pole. Other natural lights can indicate danger, like a raging forest fire encroaching on a city, town, or community, or lava spewing from an erupting volcano.\n\nWhatever the source, the ability of humans to monitor nature's light shows at night has practical applications for society. For example, tracking fires during nighttime hours allows for continuous monitoring and enhances our ability to protect humans and other animals, plants, and infrastructure. Combined with other data sources, our ability to observe the light of fires at night allows emergency managers to more efficiently and accurately issue warnings and evacuation orders and allows firefighting efforts to continue through the night. With enough moonlight (e.g., full-Moon phase), it's even possible to track the movement of smoke plumes at night, which can impact air quality, regardless of time of day.\n\nAnother natural source of light at night is emitted from glowing lava flows at the site of active volcanoes. Again, with enough moonlight, these dramatic scenes can be tracked and monitored for both scientific research and public safety.\n\n\n### Figure: The Northern Lights Viewed from Space\n\n**September 17, 2011**\n\nThis photo, taken from the International Space Station on September 17, 2011, shows a spectacular display of the aurora borealis (Northern Lights) as green and reddish light in the night sky above Earth. In the foreground, part of a Soyuz spacecraft is visible, silhouetted against the bright auroral light. The green glow is generated by energetic charged particles from the Sun interacting with Earth's upper atmosphere, exciting oxygen and nitrogen atoms, and producing characteristic colors. The image demonstrates the vividness and grandeur of natural night-time light phenomena as seen from orbit."}]
Activities:
Activity Type: KnowledgeAgentModelQueryPlanningActivityRecord
{
  "InputTokens": 1289,
  "OutputTokens": 116,
  "ElapsedMs": null,
  "Id": 0
}
Activity Type: KnowledgeAgentSearchActivityRecord
{
  "TargetIndex": "earth_at_night",
  "Query": {
    "Search": "How to locate lava flows at night?",
    "Filter": null
  },
  "QueryTime": "2025-06-19T14:02:44.67+00:00",
  "Count": 6,
  "ElapsedMs": 235,
  "Id": 1
}
Activity Type: KnowledgeAgentSemanticRankerActivityRecord
{
  "InputTokens": 24807,
  "ElapsedMs": null,
  "Id": 2
}
Results
Reference Type: KnowledgeAgentAzureSearchDocReference
{
  "DocKey": "earth_at_night_508_page_60_verbalized",
  "SourceData": {},
  "Id": "0",
  "ActivitySource": 1
}
Reference Type: KnowledgeAgentAzureSearchDocReference
{
  "DocKey": "earth_at_night_508_page_64_verbalized",
  "SourceData": {},
  "Id": "1",
  "ActivitySource": 1
}
Reference Type: KnowledgeAgentAzureSearchDocReference
{
  "DocKey": "earth_at_night_508_page_46_verbalized",
  "SourceData": {},
  "Id": "2",
  "ActivitySource": 1
}
Reference Type: KnowledgeAgentAzureSearchDocReference
{
  "DocKey": "earth_at_night_508_page_66_verbalized",
  "SourceData": {},
  "Id": "3",
  "ActivitySource": 1
}
Reference Type: KnowledgeAgentAzureSearchDocReference
{
  "DocKey": "earth_at_night_508_page_65_verbalized",
  "SourceData": {},
  "Id": "4",
  "ActivitySource": 1
}
Reference Type: KnowledgeAgentAzureSearchDocReference
{
  "DocKey": "earth_at_night_508_page_44_verbalized",
  "SourceData": {},
  "Id": "5",
  "ActivitySource": 1
}
[ASSISTANT]: You can find lava at night primarily by using satellite imagery that captures the thermal and visible light emissions from active volcanoes
 Very hot lava emits strong infrared radiation and glows visibly, which can be detected from space, especially when combined with moonlight or other faint light sources
 For example, satellites like Landsat 8 and VIIRS on Suomi NPP have captured nighttime images of lava flows on volcanoes such as Kilauea in Hawaii and Mount Etna in Italy
 These images show bright white-hot areas indicating very hot lava and reddish areas for cooling lava flows (ref_id 0, 1, 3, 4)


Lava glows visibly due to its intense heat, which makes it stand out even at night against the darkness and city lights
 Nighttime satellite images combine thermal infrared wavelengths and near-infrared to distinguish active lava from surrounding cooler ground
 Monitoring these nighttime glows allows scientists to study volcanic activity and also helps with hazard assessment


So, at night, the best way to find lava is through thermal and infrared satellite imagery that detects the glow and heat signatures of lava flows from active volcanoes


References: 0, 1, 3, 4
Search agent 'earth-search-agent' deleted successfully
Index 'earth_at_night' deleted successfully

Spiegazione del codice

Ora che si dispone del codice, è possibile suddividere i componenti chiave:

Creare un indice di ricerca
Caricare documenti nell'indice
Creare un agente della conoscenza
Configurare i messaggi
Eseguire la pipeline di recupero
Esaminare la risposta, l'attività e i risultati
Creare il client OpenAI di Azure
Usare l'API di Completamento chat per generare una risposta
Continuare la conversazione

Creare un indice di ricerca

In Ricerca di intelligenza artificiale di Azure un indice è una raccolta strutturata di dati. Il codice seguente definisce un indice denominato earth_at_night per contenere testo normale e contenuto vettoriale. È possibile usare un indice esistente, ma deve soddisfare i criteri per i carichi di lavoro di recupero agentici.

// Define the fields for the index
var fields = new List<SearchField>
{
    new SimpleField("id", SearchFieldDataType.String) { IsKey = true, IsFilterable = true, IsSortable = true, IsFacetable = true },
    new SearchField("page_chunk", SearchFieldDataType.String) { IsFilterable = false, IsSortable = false, IsFacetable = false },
    new SearchField("page_embedding_text_3_large", SearchFieldDataType.Collection(SearchFieldDataType.Single)) { VectorSearchDimensions = 3072, VectorSearchProfileName = "hnsw_text_3_large" },
    new SimpleField("page_number", SearchFieldDataType.Int32) { IsFilterable = true, IsSortable = true, IsFacetable = true }
};            
// Define the vectorizer
var vectorizer = new AzureOpenAIVectorizer(vectorizerName: "azure_openai_text_3_large")
{
    Parameters = new AzureOpenAIVectorizerParameters
    {
        ResourceUri = new Uri(azureOpenAIEndpoint),
        DeploymentName = azureOpenAIEmbeddingDeployment,
        ModelName = azureOpenAIEmbeddingModel
    }
};

// Define the vector search profile and algorithm
var vectorSearch = new VectorSearch()
{
    Profiles =
    {
        new VectorSearchProfile(
            name: "hnsw_text_3_large",
            algorithmConfigurationName: "alg"
        )
        {
            VectorizerName = "azure_openai_text_3_large"
        }
    },
    Algorithms =
    {
        new HnswAlgorithmConfiguration(name: "alg")
    },
    Vectorizers =
    {
        vectorizer
    }
};

// Define semantic configuration
var semanticConfig = new SemanticConfiguration(
    name: "semantic_config",
    prioritizedFields: new SemanticPrioritizedFields
    {
        ContentFields = { new SemanticField("page_chunk") }
    }
);

var semanticSearch = new SemanticSearch()
{
    DefaultConfigurationName = "semantic_config",
    Configurations =
    {
        semanticConfig
    }
};

// Create the index
var index = new SearchIndex(indexName)
{
    Fields = fields,
    VectorSearch = vectorSearch,
    SemanticSearch = semanticSearch
};

// Create the index client and delete the index if it exists, then create it
var indexClient = new SearchIndexClient(new Uri(endpoint), credential);
try
{
    await indexClient.DeleteIndexAsync(indexName);
    Console.WriteLine($"Index '{indexName}' deleted successfully (if it existed).");
}
catch (Exception ex)
{
    Console.WriteLine($"Index '{indexName}' could not be deleted or did not exist: {ex.Message}");
}
await indexClient.CreateOrUpdateIndexAsync(index);

Console.WriteLine($"Index '{indexName}' created or updated successfully");

Lo schema dell'indice contiene campi per l'identificazione dei documenti e il contenuto della pagina, gli incorporamenti e i numeri. Include anche configurazioni per le query di classificazione semantica e vettoriali, che usano il text-embedding-3-large modello distribuito in precedenza.

Caricare documenti nell'indice

Attualmente, l'indice earth_at_night è vuoto. Eseguire il codice seguente per popolare l'indice con i documenti JSON dell'e-book Earth at Night della NASA. Come richiesto da Ricerca di intelligenza artificiale di Azure, ogni documento è conforme ai campi e ai tipi di dati definiti nello schema dell'indice.

// Download the documents from the GitHub URL
string url = "https://raw.githubusercontent.com/Azure-Samples/azure-search-sample-data/refs/heads/main/nasa-e-book/earth-at-night-json/documents.json";
var httpClient = new HttpClient();
var response = await httpClient.GetAsync(url);
response.EnsureSuccessStatusCode();
var json = await response.Content.ReadAsStringAsync();

var documents = JsonSerializer.Deserialize<List<Dictionary<string, object>>>(json);
var searchClient = new SearchClient(new Uri(endpoint), indexName, credential);
var searchIndexingBufferedSender = new SearchIndexingBufferedSender<Dictionary<string, object>>(
    searchClient,
    new SearchIndexingBufferedSenderOptions<Dictionary<string, object>>
    {
        KeyFieldAccessor = doc => doc["id"].ToString(),
    }
);

await searchIndexingBufferedSender.UploadDocumentsAsync(documents);
await searchIndexingBufferedSender.FlushAsync();

Console.WriteLine($"Documents uploaded to index '{indexName}'");

Creare un agente di conoscenza

Per connettere Azure AI Search alla distribuzione gpt-4.1-mini e impostare come destinazione l'indice earth_at_night in fase di query, è necessario un agente di conoscenza. Il codice seguente definisce un agente di conoscenza denominato earth-search-agent che usa il KnowledgeAgentAzureOpenAIModel per elaborare le query e recuperare i documenti pertinenti dall'indice earth_at_night.

Per garantire risposte rilevanti e semanticamente significative, DefaultRerankerThreshold è impostata per escludere le risposte con un punteggio di reranker pari 2.5 o inferiore.

var openAiParameters = new AzureOpenAIVectorizerParameters
{
    ResourceUri = new Uri(azureOpenAIEndpoint),
    DeploymentName = azureOpenAIGptDeployment,
    ModelName = azureOpenAIGptModel
};

var agentModel = new KnowledgeAgentAzureOpenAIModel(azureOpenAIParameters: openAiParameters);

var targetIndex = new KnowledgeAgentTargetIndex(indexName)
{
    DefaultRerankerThreshold = 2.5f
};

// Create the knowledge agent
var agent = new KnowledgeAgent(
    name: agentName,
    models: new[] { agentModel },
    targetIndexes: new[] { targetIndex });
await indexClient.CreateOrUpdateKnowledgeAgentAsync(agent);
Console.WriteLine($"Search agent '{agentName}' created or updated successfully");

Configurare i messaggi

I messaggi sono l'input per la route di recupero e contengono la cronologia delle conversazioni. Ogni messaggio include un ruolo che indica l'origine, ad esempio assistente o utente, e il contenuto in linguaggio naturale. L'LLM usato determina quali ruoli sono validi.

Un messaggio utente rappresenta la query da elaborare, mentre un messaggio di assistente guida l'agente della knowledge base su come rispondere. Durante il processo di recupero, questi messaggi vengono inviati a un LLM per estrarre le risposte pertinenti dai documenti indicizzati.

Questo messaggio di assistente indica earth-search-agent di rispondere a domande sulla Terra di notte, citare le fonti usando il loro ref_id e rispondere con "non lo so" quando le risposte non sono disponibili.

string instructions = @"
A Q&A agent that can answer questions about the Earth at night.
Sources have a JSON format with a ref_id that must be cited in the answer.
If you do not have the answer, respond with ""I don't know"".
";

var messages = new List<Dictionary<string, object>>
{
    new Dictionary<string, object>
    {
        { "role", "system" },
        { "content", instructions }
    }
};

Eseguire la pipeline di recupero

Questo passaggio esegue la pipeline di recupero per estrarre informazioni rilevanti dall'indice di ricerca. In base ai messaggi e ai parametri della richiesta di recupero, l'LLM:

Analizza l'intera cronologia delle conversazioni per determinare le informazioni sottostanti necessarie.
Suddivide la query utente composta in sottoquery mirate.
Esegue ogni sottoquery contemporaneamente su campi di testo e incorporamenti vettoriali nell'indice.
Usa il classificatore semantico per riordinare i risultati di tutte le sottoquery.
Unisce i risultati in una singola stringa.

Il codice seguente invia una query utente in due parti a earth-search-agent, che decostruisce la query in sottoquery, esegue le sottoquery su entrambi i campi di testo e gli incorporamenti vettoriali nell'indice earth_at_night e classifica e unisce i risultati. La risposta viene quindi aggiunta all'elenco messages .

var agentClient = new KnowledgeAgentRetrievalClient(
    endpoint: new Uri(endpoint),
    agentName: agentName,
    tokenCredential: new DefaultAzureCredential()
);            

messages.Add(new Dictionary<string, object>
{
    { "role", "user" },
    { "content", @"
Why do suburban belts display larger December brightening than urban cores even though absolute light levels are higher downtown?
Why is the Phoenix nighttime street grid is so sharply visible from space, whereas large stretches of the interstate between midwestern cities remain comparatively dim?
" }
});

var retrievalResult = await agentClient.RetrieveAsync(
    retrievalRequest: new KnowledgeAgentRetrievalRequest(
            messages: messages
                .Where(message => message["role"].ToString() != "system")
                .Select(
                message => new KnowledgeAgentMessage(
                    role: message["role"].ToString(),
                    content: new[] { new KnowledgeAgentMessageTextContent(message["content"].ToString()) }))
                .ToList()
            )
        {
            TargetIndexParams = { new KnowledgeAgentIndexParams { IndexName = indexName, RerankerThreshold = 2.5f } }
        }
    );

messages.Add(new Dictionary<string, object>
{
    { "role", "assistant" },
    { "content", (retrievalResult.Value.Response[0].Content[0] as KnowledgeAgentMessageTextContent).Text }
});

Esaminare la risposta, l'attività e i risultati

Ora si vuole visualizzare la risposta, l'attività e i risultati della pipeline di recupero.

Ogni risposta di recupero da Azure AI Search di Azure include:

Stringa unificata che rappresenta i dati di base dai risultati della ricerca.
Il piano di query.
Dati di riferimento che mostrano quali blocchi dei documenti di origine hanno contribuito alla stringa unificata.

Console.WriteLine((retrievalResult.Value.Response[0].Content[0] as KnowledgeAgentMessageTextContent).Text);
Console.WriteLine("Activities:");
foreach (var activity in retrievalResult.Value.Activity)
{
    Console.WriteLine($"Activity Type: {activity.GetType().Name}");
    string activityJson = JsonSerializer.Serialize(
        activity,
        activity.GetType(),
        new JsonSerializerOptions { WriteIndented = true }
    );
    Console.WriteLine(activityJson);
}

Console.WriteLine("Results");
foreach (var reference in retrievalResult.Value.References)
{
    Console.WriteLine($"Reference Type: {reference.GetType().Name}");
    string referenceJson = JsonSerializer.Serialize(
        reference,
        reference.GetType(),
        new JsonSerializerOptions { WriteIndented = true }
    );
    Console.WriteLine(referenceJson);
}

L'output deve includere:

Response fornisce una stringa di testo dei documenti più rilevanti (o blocchi) nell'indice di ricerca in base alla query dell'utente. Come illustrato più avanti in questa guida introduttiva, è possibile passare questa stringa a un LLM per la generazione di risposte.
Activity tiene traccia dei passaggi eseguiti durante il processo di recupero, incluse le sottoquery generate dalla gpt-4.1-mini distribuzione e i token usati per la pianificazione e l'esecuzione delle query.
Results elenca i documenti che hanno contribuito alla risposta, ognuno identificato dal relativo DocKey.

Creare il client OpenAI di Azure

Per estendere la pipeline di recupero dall'estrazione di risposte alla generazione di risposte, configurare il client Azure OpenAI per interagire con la distribuzione gpt-4.1-mini, che è stata specificata usando la variabile answer_model in una sezione precedente.

AzureOpenAIClient azureClient = new(
    new Uri(azureOpenAIEndpoint),
    new DefaultAzureCredential());

Usa l'API di completamento della chat per generare una risposta

Un'opzione per la generazione di risposte è l'API Completamento chat, che passa la cronologia delle conversazioni a LLM per l'elaborazione.

ChatClient chatClient = azureClient.GetChatClient(azureOpenAIGptDeployment);            
List<ChatMessage> chatMessages = messages
    .Select<Dictionary<string, object>, ChatMessage>(m => m["role"].ToString() switch
    {
        "user" => new UserChatMessage(m["content"].ToString()),
        "assistant" => new AssistantChatMessage(m["content"].ToString()),
        "system" => new SystemChatMessage(m["content"].ToString()),
        _ => null
    })
    .Where(m => m != null)
    .ToList();


var result = await chatClient.CompleteChatAsync(chatMessages);

Console.WriteLine($"[ASSISTANT]: {result.Value.Content[0].Text.Replace(".", "\n")}");

Continuare la conversazione

Per continuare la conversazione, invia un'altra query utente a earth-search-agent. Il codice seguente esegue nuovamente la pipeline di recupero, recuperando il contenuto pertinente dall'indice earth_at_night e accodando la risposta all'elenco messages . Tuttavia, a differenza di prima, è ora possibile usare il client OpenAI di Azure per generare una risposta in base al contenuto recuperato.

messages.Add(new Dictionary<string, object>
{
    { "role", "user" },
    { "content", "How do I find lava at night?" }
});

var retrievalResult2 = await agentClient.RetrieveAsync(
    retrievalRequest: new KnowledgeAgentRetrievalRequest(
            messages: messages
                .Where(message => message["role"].ToString() != "system")
                .Select(
                message => new KnowledgeAgentMessage(
                    role: message["role"].ToString(),
                    content: new[] { new KnowledgeAgentMessageTextContent(message["content"].ToString()) }))
                .ToList()
            )
        {
            TargetIndexParams = { new KnowledgeAgentIndexParams { IndexName = indexName, RerankerThreshold = 2.5f } }
        }
    );

messages.Add(new Dictionary<string, object>
{
    { "role", "assistant" },
    { "content", (retrievalResult2.Value.Response[0].Content[0] as KnowledgeAgentMessageTextContent).Text }
});

Pulire le risorse

Quando si lavora nel proprio abbonamento, è consigliabile completare un progetto determinando se sono ancora necessarie le risorse create. Le risorse lasciate in esecuzione possono avere un costo. È possibile eliminare le risorse singolarmente oppure eliminare il gruppo di risorse per eliminare l'intero set di risorse.

Nel portale di Azure è possibile trovare e gestire le risorse selezionando Tutte le risorse o Gruppi di risorse nel riquadro sinistro. È anche possibile eseguire il codice seguente per eliminare gli oggetti creati in questa guida introduttiva.

Eliminare l'agente di conoscenza

L'agente di conoscenza creato in questa guida introduttiva è stato eliminato usando il frammento di codice seguente da Program.cs:

await indexClient.DeleteKnowledgeAgentAsync(agentName);
Console.WriteLine($"Search agent '{agentName}' deleted successfully");

Eliminare l'indice di ricerca

L'indice di ricerca creato in questa guida introduttiva è stato eliminato usando il frammento di codice seguente da Program.cs:

await indexClient.DeleteIndexAsync(indexName);
Console.WriteLine($"Index '{indexName}' deleted successfully");

Annotazioni

Questa guida introduttiva si basa sul Jupyter Notebook Quickstart-Agentic-Retrieval in GitHub.

Prerequisiti

Un account Azure con una sottoscrizione attiva. Creare un account gratuito.
Un servizio ricerca di intelligenza artificiale di Azure sul livello Basic o superiore con semantic ranker abilitato.
Progetto Azure AI Foundry. Quando si crea un progetto Azure AI Foundry, si ottiene una risorsa di Azure AI Foundry (necessaria per le distribuzioni di modelli).
Visual Studio Code con l'estensione Python e il pacchetto Jupyter.
Interfaccia della riga di comando di Azure per l'autenticazione senza chiave con MICROSOFT Entra ID.

Configurare l'accesso in base al ruolo

È possibile usare le chiavi API del servizio di ricerca o Microsoft Entra ID con assegnazioni di ruolo. Le chiavi sono più facili da iniziare, ma i ruoli sono più sicuri.

Per configurare l'accesso basato sui ruoli consigliato:

Accedi al portale di Azure.
Abilitare l'accesso basato sui ruoli nel servizio Ricerca intelligenza artificiale di Azure.
Nel servizio Ricerca intelligenza artificiale di Azure assegnare a se stessi i ruoli seguenti .
- Collaboratore servizi di ricerca
- Collaboratore ai dati dell'indice di ricerca
- Lettore di dati dell'indice di ricerca

Per il recupero agentico, Azure AI Search deve anche accedere alla risorsa Fonderia di Azure OpenAI.

Creare un'identità gestita assegnata dal sistema nel servizio Ricerca intelligenza artificiale di Azure. Ecco come eseguire questa operazione usando l'interfaccia della riga di comando di Azure:
```
az search service update --name YOUR-SEARCH-SERVICE-NAME --resource-group YOUR-RESOURCE-GROUP-NAME --identity-type SystemAssigned
```
Se si dispone già di un'identità gestita, è possibile ignorare questo passaggio.
Nella risorsa Azure AI Foundry, assegnare Utente dei Servizi cognitivi all'identità gestita che hai creato per il servizio di ricerca.

Distribuire modelli

Per usare il recupero agentico, è necessario distribuire uno dei modelli OpenAI di Azure supportati nella risorsa Azure AI Foundry:

Modello di chat per la pianificazione delle query e la generazione di risposte. In questo avvio rapido usiamo gpt-4.1-mini. Facoltativamente, è possibile usare un modello diverso per la pianificazione delle query e un altro per la generazione di risposte, ma questa guida introduttiva usa lo stesso modello per semplicità.
Modello di incorporamento per le query vettoriali. In questo avvio rapido usiamo text-embedding-3-large, ma puoi usare qualsiasi modello di incorporamento che supporta l'attività text-embedding.

Per distribuire i modelli OpenAI di Azure:

Accedere al portale di Azure AI Foundry e selezionare la risorsa Azure AI Foundry.
Nel riquadro sinistro selezionare Catalogo modelli.
Selezionare gpt-4.1-mini e quindi selezionare Usa questo modello.
Specificare un nome di distribuzione. Per semplificare il codice, è consigliabile usare gpt-4.1-mini.
Lasciare le impostazioni predefinite.
Seleziona Distribuisci.
Ripeti i passaggi precedenti, ma questa volta utilizza il modello di embedding text-embedding-3-large.

Ottenere gli endpoint

Per ottenere gli endpoint di servizio:

Accedi al portale di Azure.
Nel servizio Ricerca intelligenza artificiale di Azure:
1. Nel riquadro sinistro selezionare Panoramica.
2. Copiare l'URL, che dovrebbe essere simile a https://my-service.search.windows.net.
Nella risorsa Azure AI Foundry:
1. Nel riquadro sinistro, selezionare Gestione risorse>Chiavi ed endpoint.
2. Selezionare la scheda OpenAI e copiare l'URL simile a https://my-resource.openai.azure.com.

Importante

Il recupero agentico ha due modelli di fatturazione basati su token:

Fatturazione da Azure OpenAI per la pianificazione delle query.
Fatturazione per l'esecuzione di query con Azure AI Search (classificazione semantica).

Connettersi dal sistema locale

L'accesso basato sui ruoli è stato configurato per interagire con Ricerca di intelligenza artificiale di Azure e Azure OpenAI.

Per connettersi dal sistema locale:

Aprire un nuovo terminale in Visual Studio Code e passare alla directory in cui salvare i file.
Esegui il seguente comando CLI di Azure ed effettua l'accesso con il tuo account Azure. Se si hanno più sottoscrizioni, selezionare quella che contiene il servizio Ricerca intelligenza artificiale di Azure e il progetto Azure AI Foundry.
```
az login
```

Per altre informazioni, vedere Avvio rapido: Connettersi senza chiavi.

Installare pacchetti e caricare connessioni

Prima di eseguire qualsiasi codice, installare pacchetti Python e definire credenziali, endpoint e dettagli di distribuzione per le connessioni a Ricerca di intelligenza artificiale di Azure e Azure OpenAI. Questi valori vengono usati nelle operazioni successive.

Per installare i pacchetti e caricare le connessioni:

In Visual Studio Code creare un .ipynb file. Ad esempio, è possibile denominare il file quickstart-agentic-retrieval.ipynb.

Nella prima cella di codice incollare il codice seguente per installare i pacchetti necessari.

! pip install azure-search-documents==11.6.0b12 --quiet
! pip install azure-identity --quiet
! pip install openai --quiet
! pip install aiohttp --quiet
! pip install ipykernel --quiet
! pip install requests --quiet

È possibile eseguire questa cella selezionando il pulsante Esegui cella o premendo Shift+Enter.

Aggiungere un'altra cella di codice e incollare le seguenti istruzioni di importazione e variabili.

from azure.identity import DefaultAzureCredential, get_bearer_token_provider
import os

endpoint = "PUT YOUR SEARCH SERVICE ENDPOINT HERE"
credential = DefaultAzureCredential()
token_provider = get_bearer_token_provider(credential, "https://search.azure.com/.default")
azure_openai_endpoint = "PUT YOUR AZURE AI FOUNDRY ENDPOINT HERE"
azure_openai_gpt_deployment = "gpt-4.1-mini"
azure_openai_gpt_model = "gpt-4.1-mini"
azure_openai_api_version = "2025-03-01-preview"
azure_openai_embedding_deployment = "text-embedding-3-large"
azure_openai_embedding_model = "text-embedding-3-large"
index_name = "earth_at_night"
agent_name = "earth-search-agent"
answer_model = "gpt-4.1-mini"
api_version = "2025-05-01-Preview"

Imposta endpoint sul tuo endpoint di Ricerca AI di Azure, che appare simile a https://<your-search-service-name>.search.windows.net.. Imposta azure_openai_endpoint sul tuo endpoint di Azure AI Foundry, che appare simile a https://<your-foundry-resource-name>.openai.azure.com.. Hai ottenuto entrambi i valori nella sezione Ottenere gli endpoint.
Per verificare le variabili, eseguire la cella di codice.

Creare un indice di ricerca

In Ricerca di intelligenza artificiale di Azure un indice è una raccolta strutturata di dati. Il codice seguente definisce un indice denominato earth_at_night, specificato usando la index_name variabile nella sezione precedente.