Übung – Entwickeln einer RAG-Anwendung mit Spring AI und Azure OpenAI

Abgeschlossen

In dieser Einheit erstellen Sie eine Retrieval-Augmented-Generation-Anwendung (RAG) mit Spring AI, Azure OpenAI und VectorStore von Spring AI.

Einrichten von Umgebungsvariablen

Für diese Übung benötigen Sie einige Umgebungsvariablen aus vorherigen Übungen. Wenn Sie dasselbe Bash-Fenster verwenden, sollten diese Variablen weiterhin vorhanden sein. Wenn die Variablen nicht mehr verfügbar sind, verwenden Sie die folgenden Befehle, um sie neu zu erstellen. Ersetzen Sie die <...> Platzhalter unbedingt durch Ihre eigenen Werte, und verwenden Sie dieselben Werte, die Sie zuvor verwendet haben.

export RESOURCE_GROUP=<resource-group>
export LOCATION=<location>
export DB_SERVER_NAME=<server-name>
export PGHOST=$(az postgres flexible-server show \
    --resource-group $RESOURCE_GROUP \
    --name $DB_SERVER_NAME \
    --query fullyQualifiedDomainName \
    --output tsv \
    | tr -d '\r')

Sie benötigen auch eine neue Umgebungsvariable für diese Einheit. Verwenden Sie den folgenden Befehl, um diese Variable zu definieren:

export OPENAI_RESOURCE_NAME=OpenAISpringAI

Bereitstellen der Azure OpenAI-Modelle

Für Ihre Anwendung müssen Sie zuerst ein Chatmodell gpt-4o – und ein Einbettungsmodell – text-embedding-ada-002bereitstellen. Um diese Modelle bereitzustellen, müssen Sie zuerst eine Azure OpenAI-Ressource erstellen.

Erstellen eines Azure OpenAI-Kontos

Führen Sie den folgenden Befehl aus, um ein Azure OpenAI-Konto zu erstellen:

az cognitiveservices account create \
    --resource-group $RESOURCE_GROUP \
    --name $OPENAI_RESOURCE_NAME \
    --kind OpenAI \
    --sku S0 \
    --location $LOCATION \
    --yes

Bereitstellen eines Azure OpenAI-Chatmodells

Verwenden Sie den folgenden Befehl, um ein Chatmodell mit dem Namen gpt-4obereitzustellen:

az cognitiveservices account deployment create \
    --resource-group $RESOURCE_GROUP \
    --name $OPENAI_RESOURCE_NAME \
    --deployment-name gpt-4o \
    --model-name gpt-4o \
    --model-version 2024-11-20 \
    --model-format OpenAI \
    --sku-capacity "15" \
    --sku-name GlobalStandard

Bereitstellen eines Azure OpenAI-Einbettungsmodells

Sie können nun ein eingebettetes Modell bereitstellen, das mit dem folgenden Befehl benannt ist text-embedding-ada-002 :

az cognitiveservices account deployment create \
    --resource-group $RESOURCE_GROUP \
    --name $OPENAI_RESOURCE_NAME \
    --deployment-name text-embedding-ada-002 \
    --model-name text-embedding-ada-002 \
    --model-version 2 \
    --model-format OpenAI \
    --sku-capacity 120 \
    --sku-name Standard

Erstellen einer Spring AI-Anwendung

Verwenden Sie den folgenden curl Befehl, um ein neues Spring Boot Start-Projekt mit allen erforderlichen Abhängigkeiten zu generieren:

curl https://start.spring.io/starter.zip \
    -d groupId=com.example \
    -d artifactId=spring-ai-app \
    -d name=spring-ai-app \
    -d description="Spring AI Azure Integration" \
    -d version=0.0.1-SNAPSHOT \
    -d bootVersion=3.4.3 \
    -d javaVersion=17 \
    -d dependencies=web,jdbc,azure-support,spring-ai-azure-openai,spring-ai-vectordb-pgvector \
    -d type=maven-project \
    -d packageName=com.example.springaiapp \
    --output spring-ai-app.zip

Das generierte Startprojekt "Spring Boot" enthält die folgenden Konfigurationen und Abhängigkeiten:

  • Spring Boot Version: 3.4.3
  • Java-Version: 17
  • Abhängigkeiten:
    • web: fügt Unterstützung für das Erstellen von Webanwendungen hinzu, einschließlich RESTful-Diensten mit Spring Model View Controller (MVC).
    • jdbc: stellt Unterstützung für Java Database Connectivity (JDBC) für den Datenbankzugriff bereit.
    • azure-support: fügt Unterstützung für die Integration in Azure-Dienste hinzu.
    • spring-ai-azure-openai: fügt Unterstützung für die Integration in Azure OpenAI-Dienste hinzu.
    • spring-ai-vectordb-pgvector: fügt Unterstützung für die Verwendung pgvectoreiner PostgreSQL-Erweiterung für Vektoreinbettungen hinzu.

Verwenden Sie die folgenden Befehle, um die heruntergeladene Datei zu entzippen und zum erstellten Verzeichnis zu navigieren:

unzip -u spring-ai-app.zip -d spring-ai-app
cd spring-ai-app

Als Nächstes müssen Sie die pom.xml-Datei ändern, um eine Abhängigkeit für die kennwortlose Authentifizierung für PostgreSQL einzuschließen. Öffnen Sie die pom.xml Datei, suchen Sie den <dependencies> Abschnitt, und fügen Sie dann die folgende Abhängigkeit hinzu:

<dependency>
  <groupId>com.azure.spring</groupId>
  <artifactId>spring-cloud-azure-starter-jdbc-postgresql</artifactId>
</dependency>

Verwenden Sie dann den folgenden Befehl, um die Anwendung zu kompilieren und Tests zu überspringen:

mvn clean package -DskipTests

Die Ausgabe sollte eine Erfolgsmeldung enthalten, die dem folgenden Beispiel ähnelt:

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  25.392 s
[INFO] Finished at: 2025-03-02T15:53:07-05:00
[INFO] ------------------------------------------------------------------------

Projektstruktur

Verwenden Sie im Spring-ai-App-Verzeichnis die folgenden Befehle, um neue Verzeichnisse für neue Quelldateien zu erstellen:

mkdir -p src/main/java/com/example/springaiapp/controller
mkdir -p src/main/java/com/example/springaiapp/service

Überprüfen Sie den Code mithilfe von Visual Studio Code oder Ihrer bevorzugten IDE. Der Startcode enthält die folgende Struktur:

src/
├── main/
│   ├── java/
│   │   └── com/example/springaiapp/
│   │       ├── controller/
│   │       ├── service/
│   │       └── SpringAiAppApplication.java
│   └── resources/
│       └── application.properties
├── test/
│   └── java/
│       └── com/example/springaiapp/
│           └── SpringAiAppApplicationTests.java
└── pom.xml

Konfigurieren von Spring AI

Bevor Sie die Anwendung erfolgreich ausführen können, müssen Sie die folgende erforderliche Konfiguration hinzufügen:

  • Ein Azure OpenAI-Endpunkt.
  • Ein Azure OpenAI-API-Schlüssel.
  • Eine PostgreSQL-URL.

Rufen Sie den Azure OpenAI-Endpunkt mithilfe des folgenden Befehls ab:

export AZURE_OPENAI_ENDPOINT=$(az cognitiveservices account show \
    --resource-group $RESOURCE_GROUP \
    --name $OPENAI_RESOURCE_NAME \
    --query "properties.endpoint" \
    --output tsv \
    | tr -d '\r')

Rufen Sie den Azure OpenAI-API-Schlüssel mithilfe des folgenden Befehls ab:

export AZURE_OPENAI_API_KEY=$(az cognitiveservices account keys list \
    --resource-group $RESOURCE_GROUP \
    --name $OPENAI_RESOURCE_NAME \
    --query "key1" \
    --output tsv \
    | tr -d '\r')

Rufen Sie die PostgreSQL-URL mithilfe des folgenden Befehls ab:

az postgres flexible-server show \
    --resource-group $RESOURCE_GROUP \
    --name $DB_SERVER_NAME \
    --query fullyQualifiedDomainName \
    --output tsv

Aktualisieren der Datei "application.properties"

Suchen und öffnen Sie die Datei "application.properties " im Verzeichnis "src/main/resources ". Es gibt drei Eigenschaften, die mithilfe von Werten aus den folgenden Umgebungsvariablen initialisiert werden: AZURE_OPENAI_API_KEY, , AZURE_OPENAI_ENDPOINTund PGHOST. Ersetzen Sie den Inhalt der Datei durch den folgenden Inhalt:

spring.application.name=spring-ai-app
spring.ai.azure.openai.api-key=${AZURE_OPENAI_API_KEY}
spring.ai.azure.openai.endpoint=${AZURE_OPENAI_ENDPOINT}
spring.ai.azure.openai.chat.model=gpt-4o
spring.ai.azure.openai.embedding.model=text-embedding-ada-002

spring.datasource.url=jdbc:postgresql://${PGHOST}/postgres?sslmode=require
spring.datasource.username=azureuser
spring.datasource.azure.passwordless-enabled=true
spring.ai.vectorstore.pgvector.initialize-schema=true
spring.ai.vectorstore.pgvector.schema-name=postgres

Implementieren eines RAG-Diensts

Erstellen des Diensts

Erstellen Sie im Dienstverzeichnis eine neue Datei namens RagService.java , und fügen Sie den folgenden Code hinzu:

package com.example.springaiapp.service;

import java.util.List;
import java.util.stream.Collectors;

import org.springframework.ai.document.Document;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.vectorstore.SearchRequest;
import org.springframework.ai.vectorstore.VectorStore;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

@Service
public class RagService {
    private static final Logger logger = LoggerFactory.getLogger(RagService.class);

    private final ChatClient chatClient;

    @Autowired
    VectorStore vectorStore;

    public RagService(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder.build();
    }

    public String processQuery(String query) {
        List<Document> similarContexts = vectorStore.similaritySearch(
            SearchRequest.builder()
                .query(query)
                .similarityThreshold(0.8)
                .topK(3)
                .build()
        );
        String context = similarContexts.stream()
                .map(ch -> String.format("Q: %s\nA: %s", ch.getMetadata().get("prompt"), ch.getText()))
                .collect(Collectors.joining("\n\n"));
        logger.debug("Found {} similar contexts", similarContexts.size());
        String promptText = String.format("""
            Use these previous Q&A pairs as context for answering the new question:

            Previous interactions:
            %s

            New question: %s

            Please provide a clear and educational response.""",
            context,
            query
        );
        return this.chatClient.prompt()
            .user(promptText)
            .call()
            .content();
    }
}

Mit diesem Code wird RAG implementiert, indem eine Antwort auf eine bestimmte Abfrage generiert wird und das Wissen im Modell mithilfe ähnlicher Kontexte aus dem VectorStoreModell erweitert wird.

Erstellen des RAG-Controllers

Als Nächstes müssen Sie einen REST-Endpunkt für Ihre RAG-Anwendung verfügbar machen. Erstellen Sie eine neue Datei namens RagController.java im Controllerverzeichnis , und fügen Sie dann den folgenden Code hinzu:

package com.example.springaiapp.controller;

import com.example.springaiapp.service.RagService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/rag")
public class RagController {

    @Autowired
    private RagService ragService;

    @GetMapping
    public String processQuery(@RequestParam String query) {
        return ragService.processQuery(query);
    }
}

Testen der RAG-Anwendung

Verwenden Sie bei diesen Änderungen den folgenden Befehl, um den Code zu kompilieren und auszuführen:

mvn spring-boot:run

Testen Sie den neuen REST-Endpunkt entweder über einen Browser oder mithilfe des folgenden Befehls:

curl -G "http://localhost:8080/api/rag" \
    --data-urlencode "query=What is pgvector?"

Es sollte eine gültige Antwort wie im folgenden Beispiel angezeigt werden:

pgvector is an open-source PostgreSQL extension that enables efficient storage, indexing,
and querying of vector embeddings within a PostgreSQL database.

Versuchen Sie als Nächstes den folgenden Befehl:

curl -G "http://localhost:8080/api/rag" \
    --data-urlencode "query=How does QuestionAnswerAdvisor work in Spring AI?"

Obwohl die Antwort möglicherweise gültig erscheint, kann es Ausdrücke enthalten, die darauf hindeuten, dass es sich um eine begründete Vermutung ist.

Testen der Anwendung mit zusätzlichem Wissen

Stellen Sie als Nächstes zusätzliche Kenntnisse bereit, indem Sie dem Vektorspeicher Dokumente hinzufügen. Erstellen Sie eine neue Datei namens DocumentService.java im Dienstverzeichnis , und fügen Sie dann den folgenden Code hinzu:

package com.example.springaiapp.service;

import java.util.List;
import java.util.Map;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.ai.document.Document;
import org.springframework.ai.vectorstore.VectorStore;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import jakarta.annotation.PostConstruct;

@Service
public class DocumentService {

    private static final Logger logger = LoggerFactory.getLogger(DocumentService.class);

    @Autowired
    VectorStore vectorStore;

    @PostConstruct
    private void init() {
        vectorStore.add(documents);
        logger.info("DocumentService initialized with. Document count: {}", documents.size());
    }

    List<Document> documents = List.of(
        new Document("3e1a1af7-c872-4e36-9faa-fe53b9613c69",
                    """
                    The Spring AI project aims to streamline the development of applications that
                    incorporate artificial intelligence functionality without unnecessary complexity.
                    The project draws inspiration from notable Python projects, such as LangChain
                    and LlamaIndex, but Spring AI is not a direct port of those projects.
                    The project was founded with the belief that the next wave of Generative AI
                    applications will not be only for Python developers but will be ubiquitous
                    across many programming languages.
                    """,
                     Map.of("prompt", "What is Spring AI?")),
        new Document("7a7c2caf-ce9c-4dcb-a543-937b76ef1098",
                    """
                    A vector database stores data that the AI model is unaware of. When a user
                    question is sent to the AI model, a QuestionAnswerAdvisor queries the vector
                    database for documents related to the user question.
                    The response from the vector database is appended to the user text to provide
                    context for the AI model to generate a response. Assuming you have already
                    loaded data into a VectorStore, you can perform Retrieval Augmented Generation
                    (RAG) by providing an instance of QuestionAnswerAdvisor to the ChatClient.
                    """,
                     Map.of("prompt", "How does QuestionAnswer Advisor work?"))
        );
}

Verwenden Sie zum Testen dieser Änderungen den folgenden Befehl, um den Code zu kompilieren und auszuführen:

mvn spring-boot:run

Stellen Sie dann mithilfe des folgenden Befehls eine Frage:

curl -G "http://localhost:8080/api/rag" \
    --data-urlencode "query=How does QuestionAnswerAdvisor work in Spring AI?"

Nun sollte eine Antwort angezeigt werden, die die Rolle von QuestionAnswerAdvisor innerhalb von Spring AI deutlich erklärt.

Zusammenfassung der Einheit

In dieser Einheit haben Sie erfolgreich eine RAG-Anwendung mit Spring AI, Azure OpenAI und Spring AI erstellt VectorStore. Das Modul macht die RAG-Funktion über einen dedizierten REST-Endpunkt über die RagController Klasse verfügbar.