Quickstart: Generatieve zoekopdrachten (RAG) met grondgegevens uit Azure AI Search

Artikel
01/10/2025

In deze quickstart ziet u hoe u query's naar een voltooiingsmodel voor chatberichten verzendt voor een gesprekszoekervaring via uw geïndexeerde inhoud in Azure AI Search. U gebruikt Azure Portal om de resources in te stellen en vervolgens Python-code uit te voeren om de API's aan te roepen.

Vereisten

Visual Studio Code met de Python-extensie en het Jupyter-pakket. Zie Python in Visual Studio Code voor meer informatie.
Een Azure-abonnement met machtigingen voor het toewijzen van rollen. Maak gratis een account.
Azure OpenAI
- Kies een regio die ondersteuning biedt voor het voltooiingsmodel voor chatten dat u wilt gebruiken (gpt-4o, gpt-4o-mini of gelijkwaardig model).
- Implementeer het voltooiingsmodel voor chats in Azure AI Foundry of gebruik een andere benadering.
Azure AI Search
- Dezelfde regio als Azure OpenAI.
- De Basic-laag of hoger wordt aanbevolen.
- Schakel semantische rangschikking in.
- Schakel op rollen gebaseerd toegangsbeheer in (zie hieronder).

Als u wilt voldoen aan dezelfde regiovereiste, bekijkt u eerst de regio's voor het chatmodel dat u wilt gebruiken. Zodra u een regio hebt geïdentificeerd, controleert u of Azure AI Search beschikbaar is in dezelfde regio.

Zorg ervoor dat u de naam van het geïmplementeerde model kent en de eindpunten voor beide Azure-resources bij de hand hebt. U geeft deze informatie op in de volgende stappen.

Bestand downloaden

Download een Jupyter-notebook van GitHub om de aanvragen in deze quickstart te verzenden. Zie Bestanden downloaden van GitHub voor meer informatie.

U kunt ook een nieuw bestand op uw lokale systeem starten en handmatig aanvragen maken met behulp van de instructies in dit artikel.

Toegang configureren

Aanvragen voor het zoekeindpunt moeten worden geverifieerd en geautoriseerd. U kunt API-sleutels of -rollen voor deze taak gebruiken. Sleutels zijn gemakkelijker te beginnen, maar rollen zijn veiliger. In deze quickstart wordt ervan uitgegaan dat rollen zijn.

U stelt twee clients in, dus u hebt machtigingen nodig voor beide resources.

Azure AI Search ontvangt de queryaanvraag van uw lokale systeem. Wijs uzelf de roltoewijzing gegevenslezer van de zoekindex toe als de voorbeeldindex van hotels al bestaat. Als deze niet bestaat, wijst u uzelf de rollen Inzender voor zoekservice en Inzender voor zoekindexgegevens toe, zodat u de index kunt maken en er query's op kunt uitvoeren.

Azure OpenAI ontvangt de query en de zoekresultaten van uw lokale systeem. Wijs uzelf de Gebruikersrol Cognitive Services OpenAI toe in Azure OpenAI.

Meld u aan bij het Azure-portaal.
Configureer Azure AI Search voor op rollen gebaseerde toegang:
1. Zoek in Azure Portal uw Azure AI-Search-service.
2. Selecteer in het linkermenu Instellingensleutels> en selecteer vervolgens op rollen gebaseerd toegangsbeheer of Beide.
Rollen toewijzen:
1. Selecteer toegangsbeheer (IAM) in het linkermenu.
2. Selecteer in Azure AI Search deze rollen om een zoekindex te maken, laden en er query's op uit te voeren en wijs deze vervolgens toe aan uw Microsoft Entra ID-gebruikersidentiteit:
  - Inzender voor zoekindexgegevens
  - Inzender voor zoekservice
3. Selecteer in Azure OpenAI toegangsbeheer (IAM) om deze rol aan uzelf toe te wijzen in Azure OpenAI:
  - Cognitive Services OpenAI-gebruiker

Het kan enkele minuten duren voordat machtigingen van kracht worden.

Een index maken

Een zoekindex biedt grondgegevens voor het chatmodel. We raden de hotels-sample-index aan, die in enkele minuten kan worden gemaakt en uitgevoerd op elke zoekservicelaag. Deze index wordt gemaakt met behulp van ingebouwde voorbeeldgegevens.

Zoek uw zoekservice in Azure Portal.
Selecteer op de startpagina Overzicht de optie Gegevens importeren om de wizard te starten.
Selecteer op de pagina Verbinding maken met uw gegevens voorbeelden in de vervolgkeuzelijst.
Kies het hotelvoorbeeld.
Selecteer Volgende via de resterende pagina's en accepteer de standaardwaarden.
Nadat de index is gemaakt, selecteert u Zoekbeheerindexen> in het linkermenu om de index te openen.
Selecteer JSON bewerken.
Schuif naar het einde van de index, waar u tijdelijke aanduidingen kunt vinden voor constructies die aan een index kunnen worden toegevoegd.
```
"analyzers": [],
"tokenizers": [],
"tokenFilters": [],
"charFilters": [],
"normalizers": [],
```

Plak op een nieuwe regel na normalizers de volgende semantische configuratie. In dit voorbeeld wordt een "defaultConfiguration", wat belangrijk is voor het uitvoeren van deze quickstart.

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

Sla uw wijzigingen op.

Voer de volgende query uit in Search Explorer om uw index te testen: complimentary breakfast

Uitvoer moet er ongeveer uitzien als in het volgende voorbeeld. Resultaten die rechtstreeks vanuit de zoekmachine worden geretourneerd, bestaan uit velden en hun exacte waarden, samen met metagegevens zoals een zoekscore en een semantische classificatiescore en bijschrift als u semantische rangschikking gebruikt. We hebben een select-instructie gebruikt om alleen de velden HotelName, Description en Tags te retourneren.

{
"@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"
      ]
   },
   . . .
]}

Service-eindpunten ophalen

In de resterende secties stelt u API-aanroepen in op Azure OpenAI en Azure AI Search. Haal de service-eindpunten op, zodat u ze kunt opgeven als variabelen in uw code.

Meld u aan bij het Azure-portaal.
Zoek uw zoekservice.
Kopieer de URL op de startpagina Overzicht . Een eindpunt ziet er bijvoorbeeld uit als https://example.search.windows.net.
Zoek uw Azure OpenAI-service.
Selecteer op de startpagina Overzicht de koppeling om de eindpunten weer te geven. Kopieer de URL. Een eindpunt ziet er bijvoorbeeld uit als https://example.openai.azure.com/.

Een virtuele omgeving maken

In deze stap gaat u terug naar uw lokale systeem en Visual Studio Code. U wordt aangeraden een virtuele omgeving te maken, zodat u de afhankelijkheden geïsoleerd kunt installeren.

Open in Visual Studio Code de map met Quickstart-RAG.ipynb.
Druk op Ctrl-shift-P om het opdrachtenpalet te openen, zoek naar Python: Omgeving maken en selecteer Venv vervolgens om een virtuele omgeving te maken in de huidige werkruimte.
Selecteer Quickstart-RAG\requirements.txt voor de afhankelijkheden.

Het duurt enkele minuten om de omgeving te maken. Wanneer de omgeving gereed is, gaat u verder met de volgende stap.

U gebruikt Microsoft Entra-id en roltoewijzingen voor de verbinding. Zorg ervoor dat u bent aangemeld bij dezelfde tenant en hetzelfde abonnement als Azure AI Search en Azure OpenAI. U kunt de Azure CLI op de opdrachtregel gebruiken om de huidige eigenschappen weer te geven, eigenschappen te wijzigen en u aan te melden. Zie Verbinding maken zonder sleutels voor meer informatie.

Voer elk van de volgende opdrachten op volgorde uit.

az account show

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

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

U moet nu vanaf uw lokale apparaat zijn aangemeld bij Azure.

De query- en chatthread instellen

In deze sectie worden Visual Studio Code en Python gebruikt om de API's voor chatvoltooiing aan te roepen in Azure OpenAI.

Start Visual Studio Code en open het .ipynb-bestand of maak een nieuw Python-bestand.

Installeer de volgende Python-pakketten.

! 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

Stel de volgende variabelen in, waarbij u tijdelijke aanduidingen vervangt door de eindpunten die u in de vorige stap hebt verzameld.

 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"

Stel clients, de prompt, query en het antwoord in.

Wijzig voor de Azure Government-cloud het API-eindpunt van de tokenprovider 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)

De uitvoer is afkomstig van Azure OpenAI en bestaat uit aanbevelingen voor verschillende hotels. Hier volgt een voorbeeld van hoe de uitvoer eruit kan zien:

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

Als u een foutbericht Verboden krijgt, controleert u de Configuratie van Azure AI Search om ervoor te zorgen dat op rollen gebaseerde toegang is ingeschakeld.

Als er een foutbericht met autorisatie is mislukt , wacht u enkele minuten en probeert u het opnieuw. Het kan enkele minuten duren voordat roltoewijzingen operationeel worden.

Als er een foutbericht wordt weergegeven dat een resource niet is gevonden , controleert u de resource-URI's en controleert u of de API-versie van het chatmodel geldig is.

Als u verder wilt experimenteren, wijzigt u de query en voert u de laatste stap opnieuw uit om beter te begrijpen hoe het model werkt met de grondgegevens.

U kunt ook de prompt wijzigen om de toon of structuur van de uitvoer te wijzigen.

U kunt de query ook proberen zonder semantische classificatie door in te stellen use_semantic_reranker=False in de stap queryparameters. Semantische classificatie kan de relevantie van queryresultaten en de mogelijkheid van de LLM om nuttige informatie te retourneren, aanzienlijk verbeteren. Met experimenten kunt u bepalen of dit een verschil maakt voor uw inhoud.

Een complexe RAG-query verzenden

Azure AI Search ondersteunt complexe typen voor geneste JSON-structuren. In de hotels-sample-index Address is een voorbeeld van een complex type, bestaande uit Address.StreetAddress, Address.City, Address.StateProvince, en Address.PostalCode.Address.Country De index heeft ook een complexe verzameling van Rooms elk hotel.

Als uw index complexe typen heeft, kan uw query deze velden leveren als u eerst de uitvoer van zoekresultaten converteert naar JSON en vervolgens de JSON doorgeeft aan het chatmodel. In het volgende voorbeeld worden complexe typen aan de aanvraag toegevoegd. De opmaakinstructies bevatten een JSON-specificatie.

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)

De uitvoer is afkomstig van Azure OpenAI en voegt inhoud van complexe typen toe.

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.

Fouten oplossen

Als u verificatiefouten wilt opsporen, voegt u de volgende code in vóór de stap die de zoekmachine en de LLM aanroept.

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)

Voer het queryscript opnieuw uit. U krijgt nu INFO- en DEBUG-instructies in de uitvoer die meer informatie geven over het probleem.

Als er uitvoerberichten worden weergegeven met betrekking tot managedIdentityCredential- en tokenverwervingsfouten, kan het zijn dat u meerdere tenants hebt en dat uw Azure-aanmelding gebruikmaakt van een tenant die niet over uw zoekservice beschikt. Als u uw tenant-id wilt ophalen, zoekt u in Azure Portal naar 'tenanteigenschappen' of voert u deze uit az login tenant list.

Zodra u uw tenant-id hebt, voert u deze uit az login --tenant <YOUR-TENANT-ID> bij een opdrachtprompt en voert u het script opnieuw uit.

Opschonen

Wanneer u in uw eigen abonnement werkt, is het een goed idee om aan het einde van een project te bepalen of u de gemaakte resources nog nodig hebt. Resources die actief blijven, kunnen u geld kosten. U kunt resources afzonderlijk verwijderen, maar u kunt ook de resourcegroep verwijderen als u de volledige resourceset wilt verwijderen.

U kunt resources vinden en beheren in Azure Portal met behulp van de koppeling Alle resources of resourcegroepen in het meest linkse deelvenster.

Zie ook

Zelfstudie: Een RAG-oplossing bouwen in Azure AI Search

Delen via

Quickstart: Generatieve zoekopdrachten (RAG) met grondgegevens uit Azure AI Search

Vereisten

Bestand downloaden

Toegang configureren

Een index maken

Service-eindpunten ophalen

Een virtuele omgeving maken

De query- en chatthread instellen

Een complexe RAG-query verzenden

Fouten oplossen

Opschonen

Zie ook

Feedback

Aanvullende resources

Delen via

Quickstart: Generatieve zoekopdrachten (RAG) met grondgegevens uit Azure AI Search

Vereisten

Bestand downloaden

Toegang configureren

Een index maken

Service-eindpunten ophalen

Een virtuele omgeving maken

Aanmelden bij Azure

De query- en chatthread instellen

Een complexe RAG-query verzenden

Fouten oplossen

Opschonen

Zie ook

Feedback

Aanvullende resources