Handleiding: Een informatieopvraag- en generatie-app bouwen in Azure App Service met Azure OpenAI en Azure AI Search (Spring Boot)

In deze zelfstudie maakt u een Rag-toepassing (Java Retrieval Augmented Generation) met behulp van Spring Boot, Azure OpenAI en Azure AI Search en implementeert u deze in Azure App Service. Deze toepassing laat zien hoe u een chatinterface implementeert die informatie ophaalt uit uw eigen documenten en gebruikmaakt van Azure AI-services om nauwkeurige, contextbewuste antwoorden te bieden met de juiste bronvermeldingen. De oplossing maakt gebruik van beheerde identiteiten voor verificatie zonder wachtwoord tussen services.

Aanbeveling

Hoewel deze zelfstudie gebruikmaakt van Spring Boot, zijn de belangrijkste concepten van het bouwen van een RAG-toepassing met Azure OpenAI en Azure AI Search van toepassing op elke Java-webtoepassing. Als u een andere hostingoptie in App Service gebruikt, zoals Tomcat of JBoss EAP, kunt u de verificatiepatronen en het Azure SDK-gebruik dat hier wordt weergegeven, aanpassen aan uw voorkeursframework.

In deze handleiding leer je hoe je:

Implementeer een Spring Boot-toepassing die gebruikmaakt van EEN RAG-patroon met Azure AI-services.
Configureer Azure OpenAI en Azure AI Search voor hybride zoekopdrachten.
Upload en indexeer documenten voor gebruik in uw AI-toepassing.
Beheerde identiteiten gebruiken voor beveiligde service-naar-service-communicatie.
Test uw RAG-implementatie lokaal met productieservices.

Overzicht van architectuur

Voordat u begint met de implementatie, is het handig om inzicht te krijgen in de architectuur van de toepassing die u gaat bouwen. Het volgende diagram is afkomstig van een aangepast RAG-patroon voor Azure AI Search:

In deze zelfstudie zorgt de Blazer-toepassing in App Service voor zowel de app-UX als de app-server. Er wordt echter geen afzonderlijke kennisquery gemaakt voor Azure AI Search. In plaats daarvan geeft Azure OpenAI opdracht om kennisquery's uit te voeren die Azure AI Search als gegevensbron opgeven. Deze architectuur biedt verschillende belangrijke voordelen:

Integrated Vectorization: met de geïntegreerde vectorisatiemogelijkheden van Azure AI Search kunt u eenvoudig en snel al uw documenten opnemen om te zoeken, zonder dat er meer code nodig is voor het genereren van insluitingen.
Vereenvoudigde API-toegang: Door het Azure OpenAI-patroon te gebruiken voor uw gegevenspatroon met Azure AI Search als gegevensbron voor Azure OpenAI-voltooiingen, hoeft u geen complexe vectorzoekopdrachten of het genereren van insluitingen te implementeren. Het is slechts één API-aanroep en Azure OpenAI verwerkt alles, inclusief prompt engineering en queryoptimalisatie.
Geavanceerde zoekmogelijkheden: De geïntegreerde vectorisatie biedt alles wat nodig is voor geavanceerde hybride zoekopdrachten met semantische rerankering, waarbij de sterke punten van trefwoordmatching, vectorgelijkheid en door AI aangedreven classificatie worden gecombineerd.
Volledige ondersteuning voor bronvermeldingen: antwoorden bevatten automatisch bronvermeldingen naar brondocumenten, waardoor informatie verifieerbaar en traceerbaar is.

Vereiste voorwaarden

Een Azure-account met een actief abonnement: maak gratis een account.
GitHub-account voor het gebruik van GitHub Codespaces - Meer informatie over GitHub Codespaces.

1. Open het voorbeeld met Codespaces

De eenvoudigste manier om aan de slag te gaan is door GitHub Codespaces te gebruiken. Dit biedt een volledige ontwikkelomgeving met alle vereiste hulpprogramma's die vooraf zijn geïnstalleerd.

Navigeer naar de GitHub-opslagplaats op https://github.com/Azure-Samples/app-service-rag-openai-ai-search-java.
Selecteer de knop Code, selecteer het tabblad Codespaces en klik op Codespace aanmaken op main.
Wacht even totdat uw Codespace is geïnitialiseerd. Wanneer u klaar bent, ziet u een volledig geconfigureerde VS Code-omgeving in uw browser.

2. De voorbeeldarchitectuur implementeren

Meld u in de terminal aan bij Azure met behulp van Azure Developer CLI:
```
azd auth login
```
Volg de instructies om het verificatieproces te voltooien.
Stel de Azure-resources in met de AZD-sjabloon:
```
azd provision
```

Geef de volgende antwoorden wanneer u hierom wordt gevraagd:

Vraag	Antwoord
Voer een nieuwe omgevingsnaam in:	Voer een unieke naam in.
Selecteer een Azure-abonnement dat u wilt gebruiken:	Selecteer het abonnement.
Kies een resourcegroep die u wilt gebruiken:	Selecteer Een nieuwe resourcegroep maken.
Selecteer een locatie waarin u de resourcegroep wilt maken in:	Selecteer een regio. De resources zullen daadwerkelijk worden gecreëerd in East US 2.
Voer een naam in voor de nieuwe resourcegroep:	Typ Enter.

Wacht tot de implementatie is voltooid. Dit proces doet het volgende:
- Maak alle vereiste Azure-resources.
- Implementeer de toepassing in Azure App Service.
- Configureer beveiligde service-naar-service-verificatie met behulp van beheerde identiteiten.
- Stel de benodigde roltoewijzingen in voor beveiligde toegang tussen services.
Opmerking

Zie Wat zijn beheerde identiteiten voor Azure-resources en hoe u beheerde identiteiten gebruikt met App Service voor meer informatie over hoe beheerde identiteiten werken.
Na een geslaagde implementatie ziet u een URL voor uw geïmplementeerde toepassing. Noteer deze URL, maar open deze nog niet omdat u de zoekindex nog moet instellen.

3. Documenten uploaden en een zoekindex maken

Nu de infrastructuur is geïmplementeerd, moet u documenten uploaden en een zoekindex maken die door de toepassing wordt gebruikt:

Navigeer in Azure Portal naar het opslagaccount dat is gemaakt door de implementatie. De naam begint met de omgevingsnaam die u eerder hebt opgegeven.
Selecteer Data Storage>Containers in het linkernavigatiemenu en open de container documenten .
Upload voorbeelddocumenten door te klikken op Uploaden. U kunt de voorbeelddocumenten uit de sample-docs map in de opslagplaats of uw eigen PDF-, Word- of tekstbestanden gebruiken.
Navigeer naar uw Azure AI Search-service in Azure Portal.
Selecteer Gegevens importeren (nieuw) om het proces voor het maken van een zoekindex te starten.
In de stap Verbinding maken met uw gegevens :
- Selecteer Azure Blob Storage als de gegevensbron.
- Selecteer RAG.
- Kies uw opslagaccount en de documentencontainer.
- Selecteer Verifiëren met beheerde identiteit.
- Kies Volgende.
In de stap Vectorize uw tekst :
- Selecteer uw Azure OpenAI-service.
- Kies tekst-insluiten-ada-002 als het insluitmodel . De AZD-sjabloon heeft dit model al voor u geïmplementeerd.
- Selecteer Door het systeem toegewezen identiteit voor verificatie.
- Vink het selectievakje voor erkenning van extra kosten aan.
- Kies Volgende.
Aanbeveling

Meer informatie over Vector search in Azure AI Search en Text embeddings in Azure OpenAI.
In de stap Vectorize en verrijkt u uw afbeeldingen :
- Behoud de standaardinstellingen.
- Kies Volgende.
In de stap Geavanceerde instellingen :
- Zorg ervoor dat semantische rangschikking inschakelen is geselecteerd.
- (Optioneel) Selecteer een indexeringsschema. Dit is handig als u de index regelmatig wilt vernieuwen met de meest recente bestandswijzigingen.
- Kies Volgende.
In de stap Beoordelen en aanmaken:
- Kopieer de waarde van het voorvoegsel voor de objectnaam . Dit is de naam van uw zoekindex.
- Selecteer Maken om het indexeringsproces te starten.
Wacht totdat het indexeringsproces is voltooid. Dit kan enkele minuten duren, afhankelijk van de grootte en het aantal documenten.
Als u het importeren van gegevens wilt testen, selecteert u Zoeken starten en probeert u een zoekquery zoals 'Vertel me over uw bedrijf'.
Stel in uw Codespace-terminal de naam van de zoekindex in als een AZD-omgevingsvariabele:
```
azd env set SEARCH_INDEX_NAME <your-search-index-name>
```
Vervang door <your-search-index-name> de indexnaam die u eerder hebt gekopieerd. AZD gebruikt deze variabele in volgende implementaties om de App Service-app-instelling in te stellen.

4. De toepassing testen en implementeren

Als u de toepassing liever lokaal vóór of na de implementatie test, kunt u deze rechtstreeks vanuit uw Codespace uitvoeren:

Haal in uw Codespace-terminal de AZD-omgevingswaarden op:
```
azd env get-values
```
Open src/main/resources/application.properties. Werk met behulp van de terminaluitvoer de volgende waarden bij in de respectieve tijdelijke aanduidingen <input-manually-for-local-testing>:
- azure.openai.endpoint
- azure.search.url
- azure.search.index.name
Meld u aan bij Azure met de Azure CLI:
```
az login
```
Hierdoor kan de Azure Identity-clientbibliotheek in de voorbeeldcode een verificatietoken ontvangen voor de aangemelde gebruiker.
Voer de toepassing lokaal uit:
```
mvn spring-boot:run
```
Wanneer u ziet dat uw toepassing beschikbaar is op poort 8080, selecteert u Openen in de browser.
Probeer een paar vragen te stellen in de chatinterface. Als u een antwoord krijgt, maakt uw toepassing verbinding met de Azure OpenAI-resource.
Stop de ontwikkelserver met Ctrl+C.
Pas de nieuwe SEARCH_INDEX_NAME configuratie in Azure toe en implementeer de voorbeeldtoepassingscode:
```
azd up
```

5. De geïmplementeerde RAG-toepassing testen

Nu de toepassing volledig is geïmplementeerd en geconfigureerd, kunt u de RAG-functionaliteit testen:

Open de toepassings-URL die aan het einde van de implementatie is opgegeven.
U ziet een chatinterface waarin u vragen kunt invoeren over de inhoud van uw geüploade documenten.
Stel vragen die specifiek zijn voor de inhoud van uw documenten. Als u bijvoorbeeld de documenten in de map sample-docs hebt geüpload, kunt u deze vragen proberen:
- Hoe gebruikt Contoso mijn persoonlijke gegevens?
- Hoe dien je een garantieclaim in?
U ziet hoe de antwoorden bronvermeldingen bevatten die verwijzen naar de brondocumenten. Met deze bronvermeldingen kunnen gebruikers de nauwkeurigheid van de informatie controleren en meer informatie vinden in het bronmateriaal.
Test de hybride zoekmogelijkheden door vragen te stellen die kunnen profiteren van verschillende zoekmethoden:
- Vragen met specifieke terminologie (goed voor zoeken op trefwoorden).
- Vragen over concepten die kunnen worden beschreven met behulp van verschillende termen (goed voor vectorzoekopdrachten).
- Complexe vragen die inzicht in context vereisen (goed voor semantische rangschikking).

De hulpbronnen opschonen

Wanneer u klaar bent met de toepassing, kunt u alle resources verwijderen om verdere kosten te voorkomen:

azd down --purge

Met deze opdracht worden alle resources verwijderd die aan uw toepassing zijn gekoppeld.

Veelgestelde vragen

Hoe haalt de voorbeeldcode bronvermeldingen op uit voltooiingen van de Azure OpenAI-chat?
Wat is het voordeel van het gebruik van beheerde identiteiten in deze oplossing?
Hoe wordt de door het systeem toegewezen beheerde identiteit gebruikt in deze architectuur en voorbeeldtoepassing?
Hoe wordt hybride zoeken met semantische ranker geïmplementeerd in de voorbeeldtoepassing?
Waarom worden alle resources aangemaakt in Oost VS 2?
Kan ik mijn eigen OpenAI-modellen gebruiken in plaats van de modellen van Azure?
Hoe kan ik de kwaliteit van reacties verbeteren?

Hoe haalt de voorbeeldcode bronvermeldingen op uit voltooiingen van de Azure OpenAI-chat?

Het voorbeeld haalt bronvermeldingen op met behulp van de AzureSearchChatExtensionConfiguration gegevensbron voor de chatclient. Wanneer een chat is voltooid, bevat het antwoord een Citations object in de berichtcontext. De code extraheert deze bronvermeldingen als volgt:

public static ChatResponse fromChatCompletions(ChatCompletions completions) {
    ChatResponse response = new ChatResponse();
    
    if (completions.getChoices() != null && !completions.getChoices().isEmpty()) {
        var message = completions.getChoices().get(0).getMessage();
        if (message != null) {
            response.setContent(message.getContent());

            if (message.getContext() != null && message.getContext().getCitations() != null) {
                var azureCitations = message.getContext().getCitations();
                for (int i = 0; i < azureCitations.size(); i++) {
                    var azureCitation = azureCitations.get(i);
                    
                    Citation citation = new Citation();
                    citation.setIndex(i + 1);
                    citation.setTitle(azureCitation.getTitle());
                    citation.setContent(azureCitation.getContent());
                    citation.setFilePath(azureCitation.getFilepath());
                    citation.setUrl(azureCitation.getUrl());
                    
                    response.getCitations().add(citation);
                }
            }
        }
    }
    
    return response;
}

In het chatantwoord maakt de inhoud gebruik van [doc#] notatie om te verwijzen naar de overeenkomstige referentie in de lijst, waarna gebruikers de informatie kunnen herleiden naar de oorspronkelijke brondocumenten. Voor meer informatie, zie:

Wat is het voordeel van het gebruik van beheerde identiteiten in deze oplossing?

Beheerde identiteiten elimineren de noodzaak om referenties op te slaan in uw code of configuratie. Door beheerde identiteiten te gebruiken, heeft de toepassing veilig toegang tot Azure-services zoals Azure OpenAI en Azure AI Search zonder geheimen te beheren. Deze benadering volgt de zero Trust-beveiligingsprincipes en vermindert het risico op blootstelling aan referenties.

Hoe wordt de door het systeem toegewezen beheerde identiteit gebruikt in deze architectuur en voorbeeldtoepassing?

De AZD-implementatie maakt door het systeem toegewezen beheerde identiteiten voor Azure App Service, Azure OpenAI en Azure AI Search. Het maakt ook respectieve roltoewijzingen voor elk van hen (zie het main.bicep-bestand ). Raadpleeg Netwerk- en toegangsconfiguratie voor Azure OpenAI op uw gegevens voor meer informatie over de vereiste roltoewijzingen.

In de Java-voorbeeldtoepassing gebruiken de Azure SDK's deze beheerde identiteit voor beveiligde verificatie, zodat u nergens referenties of geheimen hoeft op te slaan. De OpenAIAsyncClient wordt bijvoorbeeld geïnitialiseerd met DefaultAzureCredential, waarmee automatisch de beheerde identiteit wordt gebruikt bij uitvoering in Azure.

@Bean
public TokenCredential tokenCredential() {
   return new DefaultAzureCredentialBuilder().build();
}

@Bean
public OpenAIAsyncClient openAIClient(TokenCredential tokenCredential) {
   return new OpenAIClientBuilder()
         .endpoint(openAiEndpoint)
         .credential(tokenCredential)
         .buildAsyncClient();
}

Op dezelfde manier wordt bij het configureren van de gegevensbron voor Azure AI Search de beheerde identiteit opgegeven voor verificatie:

AzureSearchChatExtensionConfiguration searchConfiguration =
   new AzureSearchChatExtensionConfiguration(
      new AzureSearchChatExtensionParameters(appSettings.getSearch().getUrl(), appSettings.getSearch().getIndex().getName())
         .setAuthentication(new OnYourDataSystemAssignedManagedIdentityAuthenticationOptions())
         // ...
   );

Met deze installatie kunt u veilige, wachtwoordloze communicatie tussen uw Spring Boot-app en Azure-services, volgens de aanbevolen procedures voor Zero Trust-beveiliging. Meer informatie over DefaultAzureCredential en de Azure Identity-clientbibliotheek voor Java.

Hoe wordt hybride zoeken met semantische ranker geïmplementeerd in de voorbeeldtoepassing?

De voorbeeldtoepassing configureert hybride zoekopdrachten met semantische classificatie met behulp van de Azure OpenAI- en Azure AI Search Java SDK's. In de back-end wordt de gegevensbron als volgt ingesteld:

AzureSearchChatExtensionParameters parameters = new AzureSearchChatExtensionParameters(
   appSettings.getSearch().getUrl(),
   appSettings.getSearch().getIndex().getName())
    // ...
    .setQueryType(AzureSearchQueryType.VECTOR_SEMANTIC_HYBRID)
    .setEmbeddingDependency(new OnYourDataDeploymentNameVectorizationSource(appSettings.getOpenai().getEmbedding().getDeployment()))
    .setSemanticConfiguration(appSettings.getSearch().getIndex().getName() + "-semantic-configuration");

Met deze configuratie kan de toepassing vectorzoekopdrachten (semantische gelijkenis), trefwoordkoppeling en semantische rangschikking in één query combineren. De semantische rangschikking wijzigt de volgorde van de resultaten om de meest relevante en contextafhankelijke antwoorden te retourneren, die vervolgens door Azure OpenAI worden gebruikt voor het genereren van antwoorden.

De semantische configuratienaam wordt automatisch gedefinieerd door het geïntegreerde vectorisatieproces. Hierbij wordt de naam van de zoekindex gebruikt als voorvoegsel en als achtervoegsel toegevoegd -semantic-configuration . Dit zorgt ervoor dat de semantische configuratie uniek is gekoppeld aan de bijbehorende index en een consistente naamconventie volgt.

Waarom worden alle resources gemaakt in Oost-VS 2?

In het voorbeeld worden de modellen gpt-4o-mini en text-embedding-ada-002 gebruikt, die beide beschikbaar zijn met het standaardimplementatietype in VS - oost 2. Deze modellen worden ook gekozen omdat ze niet binnenkort buiten gebruik worden gesteld, waardoor de voorbeeldimplementatie stabiliteit biedt. De beschikbaarheid van modellen en implementatiemethoden kunnen per regio variëren, dus East US 2 is geselecteerd om ervoor te zorgen dat het voorbeeld direct bruikbaar is. Als u een andere regio of modellen wilt gebruiken, moet u ervoor zorgen dat u modellen selecteert die beschikbaar zijn voor hetzelfde implementatietype in dezelfde regio. Wanneer u uw eigen modellen kiest, controleert u zowel de beschikbaarheid als de buitengebruikstellingsdatum om onderbrekingen te voorkomen.

Model beschikbaarheid: Azure OpenAI-servicemodellen
Datums van buitengebruikstelling model: afschaffingen en buitengebruikstelling van Azure OpenAI-servicemodellen.

Kan ik mijn eigen OpenAI-modellen gebruiken in plaats van de modellen van Azure?

Deze oplossing is ontworpen voor gebruik met de Azure OpenAI-service. Hoewel u de code kunt wijzigen om andere OpenAI-modellen te gebruiken, verliest u de geïntegreerde beveiligingsfuncties, ondersteuning voor beheerde identiteiten en de naadloze integratie met Azure AI Search die deze oplossing biedt.

Hoe kan ik de kwaliteit van reacties verbeteren?

U kunt de responskwaliteit verbeteren door:

Uploaden van hogere kwaliteit, relevantere documenten.
Segmenteringsstrategieën aanpassen in de Indexeringspijplijn van Azure AI Search. U kunt segmentering echter niet aanpassen met de geïntegreerde vectorisatie die in deze zelfstudie wordt weergegeven.
Experimenteren met verschillende promptsjablonen in de toepassingscode.
Verfijn de zoekopdracht met andere eigenschappen in de klasse AzureSearchChatExtensionParameters.
Meer gespecialiseerde Azure OpenAI-modellen gebruiken voor uw specifieke domein.

Meer middelen

Feedback

Is deze pagina nuttig?

Last updated on 2025-11-18