Übung – Entwickeln einer RAG-Anwendung mit Spring AI und Azure OpenAI
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 Verwendungpgvectoreiner 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.