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

Articolo
10/31/2024

Questa guida introduttiva illustra come inviare query di base e complesse a un modello LLM (Large Language Model) 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

Una sottoscrizione di Azure. Crearne una gratuitamente.
Azure AI Search, livello base o superiore in modo da abilitare il classificatore semantico. L'area deve essere la stessa usata per Azure OpenAI.
Risorsa OpenAI di Azure con una distribuzione di gpt-4o, gpt-4o-minio LLM equivalente, nella stessa area di Ricerca di intelligenza artificiale di Azure.
Visual Studio Code con l'estensione Python e il pacchetto Jupyter. Per altre informazioni, vedere Python in Visual Studio Code.

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 il ruolo di Lettore di dati dell’indice di ricerca per tale attività. Se si sta creando e caricando anche l'indice di esempio dell'hotel, aggiungere anche i ruoli Collaboratore del servizio di ricerca e Collaboratore dei dati dell’indice di ricerca.

Azure OpenAI sta ricevendo la (query) "Puoi consigliare degli hotel" dal sistema locale, oltre a ricevere i risultati della ricerca (origine) dal servizio di ricerca. Assegnare a se stessi e al servizio di ricerca il ruolo Utente OpenAI di Servizi cognitivi.

Accedere al portale di Azure.
Configurare Azure AI Search per l'uso di un'identità gestita assegnata dal sistema in modo che sia possibile assegnarvi ruoli:
1. Nel portale di Azure, trovare il proprio servizio di ricerca.
2. Nel menu a sinistra, selezionare Impostazioni>Identity.
3. All'interno della scheda Assegnata dal sistema, impostare lo stato su Attivato.
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 Azure AI Search, assicurarsi di avere le autorizzazioni per creare, caricare ed eseguire query su un indice di ricerca:
  - Lettore di dati dell'indice di ricerca
  - Collaboratore ai dati dell'indice di ricerca
  - Collaboratore servizi di ricerca
3. In Azure OpenAI, selezionare Controllo di accesso (IAM) per assegnare a se stessi e le autorizzazioni di identità del servizio di ricerca in Azure OpenAI. Il codice per questa guida introduttiva viene eseguito in locale. Le richieste ad Azure OpenAI provengono dal sistema. Inoltre, i risultati della ricerca dal motore di ricerca vengono passati ad Azure OpenAI. Per questi motivi, sia l'utente che il servizio di ricerca necessitano di autorizzazioni per Azure OpenAI.
  - Utente Servizi cognitivi OpenAI

L'applicazione delle autorizzazioni può richiedere alcuni minuti.

Creare un indice

È 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.

Cercare "semantic" per trovare la sezione nell'indice relativa a una configurazione semantica. Sostituire la riga vuota "semantic": {} con 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/.

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 intall aiohttp --quiet
! pip intall 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.

# 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 LLM.
 query="Can you recommend a few hotels with complimentary breakfast?"

 # Set up the search results and the chat thread.
 # Retrieve the selected fields from the search index related to the question.
 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])

 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 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.

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 json all'LLM. 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.

Per trovare e gestire le risorse nel portale, usare il link Tutte le risorse o Gruppi di risorse nel riquadro a sinistra.

Vedi anche

Esercitazione: Come creare una soluzione RAG in Azure AI Search

Condividi tramite