Guida introduttiva: Ricerca generativa (RAG) con dati di grounding di Azure AI Search

Articolo
01/10/2025

Questa guida introduttiva illustra come inviare query a un modello di completamento della chat per un'esperienza di ricerca conversazionale sul contenuto indicizzato in Ricerca di intelligenza artificiale di Azure. Usare il portale di Azure per configurare le risorse e quindi eseguire il codice Python per chiamare le API.

Prerequisiti

Visual Studio Code con l'estensione Python e il pacchetto Jupyter. Per altre informazioni, vedere Python in Visual Studio Code.
Una sottoscrizione di Azure con autorizzazioni per assegnare i ruoli. Crearne una gratuitamente.
OpenAI di Azure
- Scegliere un'area che supporti il modello di completamento della chat da usare (gpt-4o, gpt-4o-mini o modello equivalente).
- Distribuire il modello di completamento della chat in Azure AI Foundry o usare un altro approccio.
Azure AI Search
- Stessa area di Azure OpenAI.
- È consigliabile usare il livello Basic o superiore.
- Abilitare la classificazione semantica.
- Abilitare il controllo degli accessi in base al ruolo (vedere di seguito).

Per soddisfare il requisito della stessa area, esaminare le aree per il modello di chat che si vuole usare. Dopo aver identificato un'area, verificare che Ricerca intelligenza artificiale di Azure sia disponibile nella stessa area.

Assicurarsi di conoscere il nome del modello distribuito e di disporre degli endpoint per entrambe le risorse di Azure. Queste informazioni verranno fornite nei passaggi seguenti.

Scarica file

Scaricare un notebook Jupyter da GitHub per inviare le richieste in questa guida introduttiva. Per altre informazioni, vedere Download di file da GitHub.

È anche possibile avviare un nuovo file nel sistema locale e creare richieste manualmente seguendo le istruzioni riportate in questo articolo.

Configurare l'accesso

Le richieste all'endpoint di ricerca devono essere autenticate e autorizzate. È possibile usare chiavi API o ruoli per questa attività. Le chiavi sono più facili da iniziare, ma i ruoli sono più sicuri. Questa guida introduttiva presuppone ruoli.

Si stanno configurando due client, quindi sono necessarie autorizzazioni per entrambe le risorse.

Azure AI Search riceve la richiesta di query dal sistema locale. Assegnare a se stessi l'assegnazione di ruolo Lettore dati indice di ricerca se l'indice di esempio degli hotel esiste già. Se non esiste, assegnare a se stessi ruoli Collaboratore servizio di ricerca e Collaboratore ai dati dell'indice di ricerca in modo da poter creare ed eseguire query sull'indice.

Azure OpenAI riceve la query e i risultati della ricerca dal sistema locale. Assegnare a se stessi il ruolo utente OpenAI di Servizi cognitivi in Azure OpenAI.

Accedere al portale di Azure.
Configurare Azure AI Search per l'accesso in base al ruolo:
1. Nel portale di Azure, cercare il servizio Azure AI Search.
2. Nel menu a sinistra, selezionare Impostazioni>Chiavi e quindi selezionare Controllo degli accessi in base al ruolo o Entrambi.
Assegnare ruoli:
1. Nel menu a sinistra selezionare Controllo di accesso (IAM).
2. In Ricerca di intelligenza artificiale di Azure selezionare questi ruoli per creare, caricare ed eseguire query su un indice di ricerca e quindi assegnarli all'identità utente dell'ID Microsoft Entra:
  - Collaboratore ai dati dell'indice di ricerca
  - Collaboratore servizi di ricerca
3. In Azure OpenAI selezionare Controllo di accesso (IAM) per assegnare questo ruolo a se stessi in Azure OpenAI:
  - Utente Servizi cognitivi OpenAI

L'applicazione delle autorizzazioni può richiedere alcuni minuti.

Creare un indice

Un indice di ricerca fornisce dati di base per il modello di chat. È consigliabile usare hotels-sample-index, che può essere creato in pochi minuti ed eseguito in qualsiasi livello del servizio di ricerca. Questo indice viene creato usando dati di esempio predefiniti.

Nel portale di Azure, trovare il proprio servizio di ricerca.
Nella pagina iniziale Panoramica, selezionare Importa dati per avviare la procedura guidata.
Nella pagina Connettersi ai dati, selezionare Esempi nell'elenco a discesa.
Scegliere l'esempio hotels-sample.
Selezionare Avanti nelle pagine rimanenti, accettando i valori predefiniti.
Dopo aver creato l'indice, selezionare Gestione ricerca>Indici nel menu a sinistra per aprire l'indice.
Selezionare Modifica JSON.
Scorrere fino alla fine dell'indice, dove è possibile trovare segnaposto per i costrutti che possono essere aggiunti a un indice.
```
"analyzers": [],
"tokenizers": [],
"tokenFilters": [],
"charFilters": [],
"normalizers": [],
```

In una nuova riga dopo "normalizer", incollare la configurazione semantica seguente. In questo esempio viene specificato "defaultConfiguration", che è importante per l'esecuzione di questa guida introduttiva.

"semantic":{
   "defaultConfiguration":"semantic-config",
   "configurations":[
      {
         "name":"semantic-config",
         "prioritizedFields":{
            "titleField":{
               "fieldName":"HotelName"
            },
            "prioritizedContentFields":[
               {
                  "fieldName":"Description"
               }
            ],
            "prioritizedKeywordsFields":[
               {
                  "fieldName":"Category"
               },
               {
                  "fieldName":"Tags"
               }
            ]
         }
      }
   ]
},

Selezionare Salva per salvare le modifiche.

Eseguire la query seguente in Esplora ricerche per testare l'indice: complimentary breakfast.

L'output dovrebbe essere simile all'esempio seguente. I risultati restituiti direttamente dal motore di ricerca sono costituiti da campi e dai relativi valori verbatim, insieme ai metadati come un punteggio di ricerca e un punteggio di classificazione semantica e una didascalia se si usa il classificatore semantico. È stata usata un'istruzione select per restituire solo i campi HotelName, Description e Tags.

{
"@odata.count": 18,
"@search.answers": [],
"value": [
   {
      "@search.score": 2.2896252,
      "@search.rerankerScore": 2.506816864013672,
      "@search.captions": [
      {
         "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..",
         "highlights": ""
      }
      ],
      "HotelName": "Head Wind Resort",
      "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.",
      "Tags": [
      "coffee in lobby",
      "free wifi",
      "view"
      ]
   },
   {
      "@search.score": 2.2158256,
      "@search.rerankerScore": 2.288334846496582,
      "@search.captions": [
      {
         "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..",
         "highlights": ""
      }
      ],
      "HotelName": "Swan Bird Lake Inn",
      "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.",
      "Tags": [
      "continental breakfast",
      "free wifi",
      "24-hour front desk service"
      ]
   },
   {
      "@search.score": 0.92481667,
      "@search.rerankerScore": 2.221315860748291,
      "@search.captions": [
      {
         "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..",
         "highlights": ""
      }
      ],
      "HotelName": "White Mountain Lodge & Suites",
      "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.",
      "Tags": [
      "continental breakfast",
      "pool",
      "restaurant"
      ]
   },
   . . .
]}

Ottenere gli endpoint del servizio

Nelle sezioni rimanenti si configurano le chiamate dell'API ad Azure OpenAI e Azure AI Search. Ottenere gli endpoint del servizio in modo che sia possibile specificarli come variabili nel codice.

Accedere al portale di Azure.
Trovare il servizio di ricerca.
Nella pagina iniziale Panoramica, copiare l'URL. Un endpoint di esempio potrebbe essere simile a https://example.search.windows.net.
Trovare il servizio Azure OpenAI.
Nella pagina iniziale Panoramica, selezionare il collegamento per visualizzare gli endpoint. Copia l'URL. Un endpoint di esempio potrebbe essere simile a https://example.openai.azure.com/.

Creare un ambiente virtuale

In questo passaggio tornare al sistema locale e a Visual Studio Code. È consigliabile creare un ambiente virtuale in modo da poter installare le dipendenze in isolamento.

In Visual Studio Code aprire la cartella contenente Quickstart-RAG.ipynb.
Premere CTRL+MAIUSC-P per aprire il riquadro comandi, cercare "Python: Crea ambiente" e quindi selezionare Venv per creare un ambiente virtuale nell'area di lavoro corrente.
Selezionare Avvio rapido-RAG\requirements.txt per le dipendenze.

La creazione dell'ambiente richiede alcuni minuti. Quando l'ambiente è pronto, continuare con il passaggio successivo.

Si usano l'ID e le assegnazioni di ruolo di Microsoft Entra per la connessione. Assicurarsi di aver eseguito l'accesso allo stesso tenant e alla stessa sottoscrizione di Ricerca di intelligenza artificiale di Azure e Di Azure OpenAI. È possibile usare l'interfaccia della riga di comando di Azure nella riga di comando per visualizzare le proprietà correnti, modificare le proprietà e accedere. Per altre informazioni, vedere Connettersi senza chiavi.

Eseguire ognuno dei comandi seguenti in sequenza.

az account show

az account set --subscription <PUT YOUR SUBSCRIPTION ID HERE>

az login --tenant <PUT YOUR TENANT ID HERE>

A questo ora si dovrebbe accedere ad Azure dal dispositivo locale.

Configurare la query e il thread della chat

Questa sezione usa Visual Studio Code e Python per chiamare le API di completamento chat in Azure OpenAI.

Avviare Visual Studio Code e aprire il file .ipynb o creare un nuovo file Python.

Installare i pacchetti Python seguenti.

! pip install azure-search-documents==11.6.0b5 --quiet
! pip install azure-identity==1.16.1 --quiet
! pip install openai --quiet
! pip install aiohttp --quiet
! pip install ipykernel --quiet

Impostare le variabili seguenti, sostituendo i segnaposto con gli endpoint raccolti nel passaggio precedente.

 AZURE_SEARCH_SERVICE: str = "PUT YOUR SEARCH SERVICE ENDPOINT HERE"
 AZURE_OPENAI_ACCOUNT: str = "PUT YOUR AZURE OPENAI ENDPOINT HERE"
 AZURE_DEPLOYMENT_MODEL: str = "gpt-4o"

Configurare i client, la richiesta, la query e la risposta.

Per il cloud Azure per enti pubblici, modificare l'endpoint API nel provider di token in "https://cognitiveservices.azure.us/.default".

# Set up the query for generating responses
 from azure.identity import DefaultAzureCredential
 from azure.identity import get_bearer_token_provider
 from azure.search.documents import SearchClient
 from openai import AzureOpenAI

 credential = DefaultAzureCredential()
 token_provider = get_bearer_token_provider(credential, "https://cognitiveservices.azure.com/.default")
 openai_client = AzureOpenAI(
     api_version="2024-06-01",
     azure_endpoint=AZURE_OPENAI_ACCOUNT,
     azure_ad_token_provider=token_provider
 )

 search_client = SearchClient(
     endpoint=AZURE_SEARCH_SERVICE,
     index_name="hotels-sample-index",
     credential=credential
 )

 # This prompt provides instructions to the model
 GROUNDED_PROMPT="""
 You are a friendly assistant that recommends hotels based on activities and amenities.
 Answer the query using only the sources provided below in a friendly and concise bulleted manner.
 Answer ONLY with the facts listed in the list of sources below.
 If there isn't enough information below, say you don't know.
 Do not generate answers that don't use the sources below.
 Query: {query}
 Sources:\n{sources}
 """

 # Query is the question being asked. It's sent to the search engine and the chat model
 query="Can you recommend a few hotels with complimentary breakfast?"

 # Search results are created by the search client
 # Search results are composed of the top 5 results and the fields selected from the search index
 # Search results include the top 5 matches to your query
 search_results = search_client.search(
     search_text=query,
     top=5,
     select="Description,HotelName,Tags"
 )
 sources_formatted = "\n".join([f'{document["HotelName"]}:{document["Description"]}:{document["Tags"]}' for document in search_results])

 # Send the search results and the query to the LLM to generate a response based on the prompt.
 response = openai_client.chat.completions.create(
     messages=[
         {
             "role": "user",
             "content": GROUNDED_PROMPT.format(query=query, sources=sources_formatted)
         }
     ],
     model=AZURE_DEPLOYMENT_MODEL
 )

 # Here is the response from the chat model.
 print(response.choices[0].message.content)

L'output proviene da Azure OpenAI ed è costituito da consigli per diversi hotel. Di seguito è riportato un esempio dell'aspetto dell'output:

Sure! Here are a few hotels that offer complimentary breakfast:

- **Head Wind Resort**
- Complimentary continental breakfast in the lobby
- Free Wi-Fi throughout the hotel

- **Double Sanctuary Resort**
- Continental breakfast included

- **White Mountain Lodge & Suites**
- Continental breakfast available

- **Swan Bird Lake Inn**
- Continental-style breakfast each morning with a variety of food and drinks 
 such as caramel cinnamon rolls, coffee, orange juice, milk, cereal, 
 instant oatmeal, bagels, and muffins

Se viene visualizzato un messaggio di errore di tipo Non consentito, controllare la configurazione di Azure AI Search per assicurarsi che l'accesso basato sui ruoli sia abilitato.

Se viene visualizzato un messaggio di errore di tipo Autorizzazione non riuscita, attendere alcuni minuti e riprovare. Potrebbero essere necessari alcuni minuti perché le assegnazioni di ruolo diventino operative.

Se viene visualizzato un messaggio di errore Relativo alla risorsa, controllare gli URI della risorsa e assicurarsi che la versione dell'API nel modello di chat sia valida.

In caso contrario, per continuare a sperimentare, modificare la query ed eseguire di nuovo l'ultimo passaggio per comprendere meglio il funzionamento del modello con i dati di base.

È anche possibile modificare il prompt per modificare il tono o la struttura dell'output.

È anche possibile testare la query senza classificazione semantica impostando use_semantic_reranker=False nel passaggio parametri di query. La classificazione semantica può migliorare sensibilmente la pertinenza dei risultati delle query e la capacità dell'LLM di restituire informazioni utili. Sperimentare può aiutare a decidere se questo faccia una differenza sostanziale per il contenuto.

Inviare una query RAG complessa

Ricerca di intelligenza artificiale di Azure supporta tipi complessi per strutture JSON annidate. Nell'indice hotels-sample-index è Address un esempio di tipo complesso, costituito da Address.StreetAddress, Address.CityAddress.StateProvince, Address.PostalCode, e Address.Country. L'indice ha anche una raccolta complessa di Rooms per ogni hotel.

Se l'indice ha tipi complessi, la query può fornire tali campi se si converte prima l'output dei risultati della ricerca in JSON e quindi si passa il codice JSON al modello di chat. Nell'esempio seguente vengono aggiunti tipi complessi alla richiesta. Le istruzioni di formattazione includono una specifica JSON.

import json

# Query is the question being asked. It's sent to the search engine and the LLM.
query="Can you recommend a few hotels that offer complimentary breakfast? 
Tell me their description, address, tags, and the rate for one room that sleeps 4 people."

# Set up the search results and the chat thread.
# Retrieve the selected fields from the search index related to the question.
selected_fields = ["HotelName","Description","Address","Rooms","Tags"]
search_results = search_client.search(
    search_text=query,
    top=5,
    select=selected_fields,
    query_type="semantic"
)
sources_filtered = [{field: result[field] for field in selected_fields} for result in search_results]
sources_formatted = "\n".join([json.dumps(source) for source in sources_filtered])

response = openai_client.chat.completions.create(
    messages=[
        {
            "role": "user",
            "content": GROUNDED_PROMPT.format(query=query, sources=sources_formatted)
        }
    ],
    model=AZURE_DEPLOYMENT_MODEL
)

print(response.choices[0].message.content)

L'output proviene da Azure OpenAI e aggiunge contenuto da tipi complessi.

Here are a few hotels that offer complimentary breakfast and have rooms that sleep 4 people:

1. **Head Wind Resort**
   - **Description:** The best of old town hospitality combined with views of the river and 
   cool breezes off the prairie. Enjoy a complimentary continental breakfast in the lobby, 
   and free Wi-Fi throughout the hotel.
   - **Address:** 7633 E 63rd Pl, Tulsa, OK 74133, USA
   - **Tags:** Coffee in lobby, free Wi-Fi, view
   - **Room for 4:** Suite, 2 Queen Beds (Amenities) - $254.99

2. **Double Sanctuary Resort**
   - **Description:** 5-star Luxury Hotel - Biggest Rooms in the city. #1 Hotel in the area 
   listed by Traveler magazine. Free WiFi, Flexible check in/out, Fitness Center & espresso 
   in room. Offers continental breakfast.
   - **Address:** 2211 Elliott Ave, Seattle, WA 98121, USA
   - **Tags:** View, pool, restaurant, bar, continental breakfast
   - **Room for 4:** Suite, 2 Queen Beds (Amenities) - $254.99

3. **Swan Bird Lake Inn**
   - **Description:** Continental-style breakfast featuring a variety of food and drinks. 
   Locally made caramel cinnamon rolls are a favorite.
   - **Address:** 1 Memorial Dr, Cambridge, MA 02142, USA
   - **Tags:** Continental breakfast, free Wi-Fi, 24-hour front desk service
   - **Room for 4:** Budget Room, 2 Queen Beds (City View) - $85.99

4. **Gastronomic Landscape Hotel**
   - **Description:** Known for its culinary excellence under the management of William Dough, 
   offers continental breakfast.
   - **Address:** 3393 Peachtree Rd, Atlanta, GA 30326, USA
   - **Tags:** Restaurant, bar, continental breakfast
   - **Room for 4:** Budget Room, 2 Queen Beds (Amenities) - $66.99
...
   - **Tags:** Pool, continental breakfast, free parking
   - **Room for 4:** Budget Room, 2 Queen Beds (Amenities) - $60.99

Enjoy your stay! Let me know if you need any more information.

Risoluzione degli errori

Per eseguire il debug degli errori di autenticazione, inserire il codice seguente prima del passaggio che chiama il motore di ricerca e il modello linguistico di grandi dimensioni (LLM).

import sys
import logging # Set the logging level for all azure-storage-* libraries
logger = logging.getLogger('azure.identity') 
logger.setLevel(logging.DEBUG)

handler = logging.StreamHandler(stream=sys.stdout)
formatter = logging.Formatter('[%(levelname)s %(name)s] %(message)s')
handler.setFormatter(formatter)
logger.addHandler(handler)

Eseguire di nuovo lo script di query. Si dovrebbero ottenere ora istruzioni INFO e DEBUG nell'output che forniscono maggiori dettagli sul problema.

Se vengono visualizzati messaggi di output correlati a ManagedIdentityCredential ed errori di acquisizione dei token, è possibile che siano presenti più tenant e che l'accesso di Azure usi un tenant che non ha il servizio di ricerca specifico. Per ottenere l'ID tenant, cercare "proprietà tenant" nel portale di Azure o eseguire az login tenant list.

Quando si ha un ID tenant, eseguire az login --tenant <YOUR-TENANT-ID> al prompt dei comandi e quindi eseguire di nuovo lo script.

Eseguire la pulizia

Quando si lavora nella propria sottoscrizione, al termine di un progetto è buona norma determinare se le risorse create sono ancora necessarie. Le risorse che rimangono in esecuzione hanno un costo. È possibile eliminare risorse singole oppure gruppi di risorse per eliminare l'intero set di risorse.

È possibile trovare e gestire le risorse nella portale di Azure usando il collegamento Tutte le risorse o Gruppi di risorse nel riquadro più a sinistra.

Vedi anche

Esercitazione: Come creare una soluzione RAG in Azure AI Search

Condividi tramite

Guida introduttiva: Ricerca generativa (RAG) con dati di grounding di Azure AI Search

Prerequisiti

Scarica file

Configurare l'accesso

Creare un indice

Ottenere gli endpoint del servizio

Creare un ambiente virtuale

Configurare la query e il thread della chat

Inviare una query RAG complessa

Risoluzione degli errori

Eseguire la pulizia

Vedi anche

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

Guida introduttiva: Ricerca generativa (RAG) con dati di grounding di Azure AI Search

Prerequisiti

Scarica file

Configurare l'accesso

Creare un indice

Ottenere gli endpoint del servizio

Creare un ambiente virtuale

Accedere ad Azure

Configurare la query e il thread della chat

Inviare una query RAG complessa

Risoluzione degli errori

Eseguire la pulizia

Vedi anche

Commenti e suggerimenti

Risorse aggiuntive