深度解析Spring AI：請求與響應機制的核心邏輯

我們在前面的兩個章節中基本上對Spring Boot 3版本的新變化進行了全面的回顧，以確保在接下來研究Spring AI時能夠避免任何潛在的問題。今天，我們終於可以直接進入主題：Spring AI是如何發起請求並將資訊返回給使用者的。

在接下來的內容中，我們將專注於這一過程，而流式回答和函式回撥的相關內容我們可以在下次的講解中詳細探討。

開始解析

首先，對於還沒有專案的同學，請務必安裝所需的POM依賴項。請注意，JDK的版本要求為17。因此，你可以在IDEA中輕鬆下載和配置這個版本。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.3.1</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.example</groupId>
    <artifactId>demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>demo</name>
    <description>Demo project for Spring Boot</description>
    <url/>
    <licenses>
        <license/>
    </licenses>
    <developers>
        <developer/>
    </developers>
    <scm>
        <connection/>
        <developerConnection/>
        <tag/>
        <url/>
    </scm>
    <properties>
        <java.version>17</java.version>
<!--        <spring-ai.version>1.1.0</spring-ai.version>-->
        <spring-ai.version>1.0.0-M2</spring-ai.version>
    </properties>
    <dependencies>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-actuator</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
            <version>4.1.0</version>
        </dependency>
        <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>javax.servlet-api</artifactId>
            <version>4.0.1</version>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>
    <dependencyManagement>
        <dependencies>
            <dependency>
<!--                <groupId>group.springframework.ai</groupId>-->
                <groupId>org.springframework.ai</groupId>
                <artifactId>spring-ai-bom</artifactId>
                <version>${spring-ai.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <build>
        <plugins>
            <plugin>
                <groupId>org.graalvm.buildtools</groupId>
                <artifactId>native-maven-plugin</artifactId>
                <configuration>
                    <!-- imageName用於設定生成的二進位制檔名稱 -->
                    <imageName>${project.artifactId}</imageName>
                    <!-- mainClass用於指定main方法類路徑 -->
                    <mainClass>com.example.demo.DemoApplication</mainClass>
                    <buildArgs>
                        --no-fallback
                    </buildArgs>
                </configuration>
                <executions>
                    <execution>
                        <id>build-native</id>
                        <goals>
                            <goal>compile-no-fork</goal>
                        </goals>
                        <phase>package</phase>
                    </execution>
                </executions>
            </plugin>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
        </plugins>
    </build>
    <repositories>
        <repository>
            <id>spring-milestones</id>
            <name>Spring Milestones</name>
            <url>https://repo.spring.io/milestone</url>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </repository>
    </repositories>

</project>

基本用法在之前的講解中已經覆蓋過，因此這裡就不再詳細說明。為了更好地理解這一概念，我們將透過兩個具體的例子來進行演示。

第一個例子將展示阻塞回答的實現，而第二個例子則會涉及帶有上下文資訊記憶的回答。這兩種方式將幫助我們更深入地瞭解如何在實際應用中靈活運用這些技術。

基本用法

這裡將提供一個阻塞回答的用法示例，以便更好地理解其應用場景和具體實現方式。

@PostMapping("/ai")
ChatDataPO generationByText(@RequestParam("userInput")  String userInput) {
    String content = this.myChatClientWithSystem.prompt()
                .user(userInput)
                .call()
                .content();
    log.info("content: {}", content);
    ChatDataPO chatDataPO = ChatDataPO.builder().code("text").data(ChildData.builder().text(content).build()).build();;
    return chatDataPO;
}

在這個示例中，我們將展示如何實現一個等待 AI 完成回答的機制，並將結果直接返回給介面呼叫端。這一過程實際上非常簡單，您只需將問題傳遞給 user 引數即可。接下來，我們將進行原始碼解析。

為了節省時間，我們不會詳細逐行分析中間過程的程式碼，因為這可能會顯得冗長而複雜。相反，我們將直接聚焦於關鍵原始碼，以便更高效地理解其核心邏輯和實現細節。

原始碼解析——構建請求

我們現在直接進入 content 方法進行深入分析。在前面的步驟中，所有方法的引數呼叫主要是為了構建一個物件，為後續的操作做準備。而真正的核心呼叫邏輯則集中在 content 方法內部。

private ChatResponse doGetChatResponse(DefaultChatClientRequestSpec inputRequest, String formatParam) {

            Map<String, Object> context = new ConcurrentHashMap<>();
            context.putAll(inputRequest.getAdvisorParams());
            DefaultChatClientRequestSpec advisedRequest = DefaultChatClientRequestSpec.adviseOnRequest(inputRequest,
                    context);

            var processedUserText = StringUtils.hasText(formatParam)
                    ? advisedRequest.getUserText() + System.lineSeparator() + "{spring_ai_soc_format}"
                    : advisedRequest.getUserText();

            Map<String, Object> userParams = new HashMap<>(advisedRequest.getUserParams());
            if (StringUtils.hasText(formatParam)) {
                userParams.put("spring_ai_soc_format", formatParam);
            }

            var messages = new ArrayList<Message>(advisedRequest.getMessages());
            var textsAreValid = (StringUtils.hasText(processedUserText)
                    || StringUtils.hasText(advisedRequest.getSystemText()));
            if (textsAreValid) {
                if (StringUtils.hasText(advisedRequest.getSystemText())
                        || !advisedRequest.getSystemParams().isEmpty()) {
                    var systemMessage = new SystemMessage(
                            new PromptTemplate(advisedRequest.getSystemText(), advisedRequest.getSystemParams())
                                .render());
                    messages.add(systemMessage);
                }
                UserMessage userMessage = null;
                if (!CollectionUtils.isEmpty(userParams)) {
                    userMessage = new UserMessage(new PromptTemplate(processedUserText, userParams).render(),
                            advisedRequest.getMedia());
                }
                else {
                    userMessage = new UserMessage(processedUserText, advisedRequest.getMedia());
                }
                messages.add(userMessage);
            }

            if (advisedRequest.getChatOptions() instanceof FunctionCallingOptions functionCallingOptions) {
                if (!advisedRequest.getFunctionNames().isEmpty()) {
                    functionCallingOptions.setFunctions(new HashSet<>(advisedRequest.getFunctionNames()));
                }
                if (!advisedRequest.getFunctionCallbacks().isEmpty()) {
                    functionCallingOptions.setFunctionCallbacks(advisedRequest.getFunctionCallbacks());
                }
            }
            var prompt = new Prompt(messages, advisedRequest.getChatOptions());
            var chatResponse = this.chatModel.call(prompt);

            ChatResponse advisedResponse = chatResponse;
            // apply the advisors on response
            if (!CollectionUtils.isEmpty(inputRequest.getAdvisors())) {
                var currentAdvisors = new ArrayList<>(inputRequest.getAdvisors());
                for (RequestResponseAdvisor advisor : currentAdvisors) {
                    advisedResponse = advisor.adviseResponse(advisedResponse, context);
                }
            }

            return advisedResponse;
        }

這段程式碼沒有任何註釋，確實令人感到意外，充分說明了Spring程式碼的設計初衷——更多是為開發者所用，而非為人類閱讀。其核心思想是，能夠有效使用就足夠了。儘管這段程式碼顯得簡潔明瞭，但其重要性不容忽視。所有的實現都非常精煉，沒有冗餘的程式碼，因此我決定不進行刪減，而是將其完整呈現出來。

為了幫助大家更好地理解其中的邏輯和結構，我將使用虛擬碼來進行講解。

初始化上下文：建立一個空的上下文。

請求調整：請求調整的邏輯是基於上下文對輸入請求進行動態處理。首先，我們需要判斷請求物件是否已經被 advisor 包裝。如果需要那麼我們將返回一個經過 advisor 包裝後的請求物件。

下面是相關的原始碼實現，展示了這一邏輯的具體細節：

public static DefaultChatClientRequestSpec adviseOnRequest(DefaultChatClientRequestSpec inputRequest,
                Map<String, Object> context) {

//....此處省略一堆程式碼
        var currentAdvisors = new ArrayList<>(inputRequest.advisors);
                for (RequestResponseAdvisor advisor : currentAdvisors) {
                    adviseRequest = advisor.adviseRequest(adviseRequest, context);
                }
                advisedRequest = new DefaultChatClientRequestSpec(adviseRequest.chatModel(), adviseRequest.userText(),
                        adviseRequest.userParams(), adviseRequest.systemText(), adviseRequest.systemParams(),
                        adviseRequest.functionCallbacks(), adviseRequest.messages(), adviseRequest.functionNames(),
                        adviseRequest.media(), adviseRequest.chatOptions(), adviseRequest.advisors(),
                        adviseRequest.advisorParams(), inputRequest.getObservationRegistry(),
                        inputRequest.getCustomObservationConvention());
            }

            return advisedRequest;
        }

在這裡，我想詳細講解一下 advisor.adviseRequest(adviseRequest, context) 這一方法的功能和重要性。由於我們已經配置了增強類，比如引入了一個聊天記憶功能，該方法的作用就顯得尤為關鍵。具體來說，它負責對傳入的請求進行增強處理，以滿足特定的業務需求。

值得注意的是，這個增強請求的方法是與增強響應方法相對應的，它們通常成對出現。接下來，深入檢視 adviseRequest 方法的具體實現：

String content = this.myChatClientWithSystem.prompt()
                .advisors(new MessageChatMemoryAdvisor(chatMemory))
                .user(userInput)
                .call()
                .content();

我們配置了 MessageChatMemoryAdvisor 類，其核心方法的具體實現是，在接收到相應的資訊後，將該資訊儲存到一個聊天記憶中。這樣一來，下一次處理請求時，就可以直接從聊天記憶中提取相關內容。

public AdvisedRequest adviseRequest(AdvisedRequest request, Map<String, Object> context) {

    //此處省略一堆程式碼
    // 4. Add the new user input to the conversation memory.
    UserMessage userMessage = new UserMessage(request.userText(), request.media());
    this.getChatMemoryStore().add(this.doGetConversationId(context), userMessage);

    return advisedRequest;
}

處理使用者文字、構建使用者引數：需要依據 formatParam 方法來對使用者的輸入進行處理。具體而言，這個步驟不僅涉及到對使用者文字的格式化，還需要更新相應的使用者引數。

接下來，我們將展示具體的實現示例，以便更清晰地理解這一過程的操作細節：

.user(u -> u.text("""
                Generate the filmography for a random actor.
                {format}
              """)
            .param("format", converter.getFormat()))

上面的程式碼段會將 {format} 替換為實際的格式化資訊。除了使用者提供的引數外，系統資訊中同樣包含了一些需要解析的引數，這些引數也必須在處理過程中正確地傳入。

構建訊息列表：根據系統文字和使用者文字的有效性，構建訊息的過程將兩者進行整合。我們可以將所有有效的訊息新增到一個 List 集合中，以便於後續處理。此外，系統還會建立一個資訊物件，用於儲存這些訊息的相關資訊，以確保在需要時可以方便地訪問和管理它們。

是否有函式回撥：如果有，則設定一下具體的函式。（下一章節細講）

生成聊天提示：建立一個提示new Prompt()物件並呼叫聊天模型api獲取返回資訊。

返回增強：如果當前請求物件配置了 advisor，那麼將會呼叫相應的增強方法。此外，系統會自動將對應的問答內容儲存到資訊列表中，因此相應的資訊也需要被一併記錄下來。

public ChatResponse adviseResponse(ChatResponse chatResponse, Map<String, Object> context) {

    List<Message> assistantMessages = chatResponse.getResults().stream().map(g -> (Message) g.getOutput()).toList();

    this.getChatMemoryStore().add(this.doGetConversationId(context), assistantMessages);

    return chatResponse;
}

返回結果：返回最終的聊天響應。

原始碼解析——請求OpenAI

接下來，我們將詳細探討如何透過請求物件來呼叫 OpenAI 介面的具體過程。為此，我們將以 OpenAI 的原始碼為基礎進行分析。如果您使用的是其他 AI 產品，那麼在這一環節的流程將會有所不同，系統會根據具體的產品進行相應的跳轉。如圖所示：

我們將對 OpenAI 的請求呼叫過程進行全面的解析，以深入理解其背後的機制和實現細節：

public ChatResponse call(Prompt prompt) {

    ChatCompletionRequest request = createRequest(prompt, false);

    ChatModelObservationContext observationContext = ChatModelObservationContext.builder()
        .prompt(prompt)
        .provider(OpenAiApiConstants.PROVIDER_NAME)
        .requestOptions(buildRequestOptions(request))
        .build();

    ChatResponse response = ChatModelObservationDocumentation.CHAT_MODEL_OPERATION
        .observation(this.observationConvention, DEFAULT_OBSERVATION_CONVENTION, () -> observationContext,
                this.observationRegistry)
        .observe(() -> {

            ResponseEntity<ChatCompletion> completionEntity = this.retryTemplate
                .execute(ctx -> this.openAiApi.chatCompletionEntity(request, getAdditionalHttpHeaders(prompt)));

            var chatCompletion = completionEntity.getBody();

            if (chatCompletion == null) {
                logger.warn("No chat completion returned for prompt: {}", prompt);
                return new ChatResponse(List.of());
            }

            List<Choice> choices = chatCompletion.choices();
            if (choices == null) {
                logger.warn("No choices returned for prompt: {}", prompt);
                return new ChatResponse(List.of());
            }

            List<Generation> generations = choices.stream().map(choice -> {
        // @formatter:off
                Map<String, Object> metadata = Map.of(
                        "id", chatCompletion.id() != null ? chatCompletion.id() : "",
                        "role", choice.message().role() != null ? choice.message().role().name() : "",
                        "index", choice.index(),
                        "finishReason", choice.finishReason() != null ? choice.finishReason().name() : "",
                        "refusal", StringUtils.hasText(choice.message().refusal()) ? choice.message().refusal() : "");
                // @formatter:on
                return buildGeneration(choice, metadata);
            }).toList();

            // Non function calling.
            RateLimit rateLimit = OpenAiResponseHeaderExtractor.extractAiResponseHeaders(completionEntity);

            ChatResponse chatResponse = new ChatResponse(generations, from(completionEntity.getBody(), rateLimit));

            observationContext.setResponse(chatResponse);

            return chatResponse;

        });

    if (response != null && isToolCall(response, Set.of(OpenAiApi.ChatCompletionFinishReason.TOOL_CALLS.name(),
            OpenAiApi.ChatCompletionFinishReason.STOP.name()))) {
        var toolCallConversation = handleToolCalls(prompt, response);
        // Recursively call the call method with the tool call message
        // conversation that contains the call responses.
        return this.call(new Prompt(toolCallConversation, prompt.getOptions()));
    }

    return response;
}

雖然這些內容都很有價值，刪減並不是一個好的選擇，但由於缺乏註釋，我們可能需要仔細分析。讓我們一起來看看這些資訊，逐步理清其中的邏輯和要點。

createRequest 函式的主要作用是構建在實際呼叫 API 時所需的請求物件。由於不同服務提供商的介面設計各有特點，因此我們需要根據具體的 API 規範自行實現這一過程。例如，在呼叫 OpenAI 的介面時，我們需要構建特定的引數結構，這一過程大家應該已經非常熟悉。如下圖所示，我們可以看到構建請求時所需的各項引數及其格式。

ChatModelObservationContext 主要用於配置與請求相關的其他限制和要求。這包括多個關鍵引數，例如本次請求的最大 token 數量限制、所使用的 OpenAI 問答模型的具體型別、以及請求的頻率限制等。如程式碼所示：

private ChatOptions buildRequestOptions(OpenAiApi.ChatCompletionRequest request) {
    return ChatOptionsBuilder.builder()
        .withModel(request.model())
        .withFrequencyPenalty(request.frequencyPenalty())
        .withMaxTokens(request.maxTokens())
        .withPresencePenalty(request.presencePenalty())
        .withStopSequences(request.stop())
        .withTemperature(request.temperature())
        .withTopP(request.topP())
        .build();
}

剩下的 ChatResponse 大方法負責實際執行 API 請求並處理響應。在這一過程中，有幾個關鍵細節值得注意。

請求物件使用的是 retryTemplate，這是一個具有重試機制的請求 API 工具。它的設計旨在增強請求的可靠性，特別是在面對暫時性故障或網路問題時，能夠自動進行重試，從而提高成功率。更為靈活的是，retryTemplate 允許使用者進行配置，以滿足不同應用場景的需求。

使用者可以根據實際需要調整重試次數、重試間隔時間以及其他相關引數，所有這些配置都可以透過 spring.ai.retry 這一字首進行自定義設定。具體大家可以看這個類：

@AutoConfiguration
@ConditionalOnClass(RetryTemplate.class)
@EnableConfigurationProperties({ SpringAiRetryProperties.class })
public class SpringAiRetryAutoConfiguration {
  //此處省略一堆程式碼
}

接著，如果 OpenAI 的介面正常返回響應，那麼系統將開始格式化回答。在這一過程中，涉及到多個關鍵欄位，這些欄位對於程式設計師們而言應該都是相當熟悉的，尤其是那些有過介面對接經驗的開發者。

Map<String, Object> metadata = Map.of(
                            "id", chatCompletion.id() != null ? chatCompletion.id() : "",
                            "role", choice.message().role() != null ? choice.message().role().name() : "",
                            "index", choice.index(),
                            "finishReason", choice.finishReason() != null ? choice.finishReason().name() : "",
                            "refusal", StringUtils.hasText(choice.message().refusal()) ? choice.message().refusal() : "");

接著，在接收到所有返回引數後，系統將這些引數整合並返回給 response 物件。然而，在這一階段，我們又進行了一個重要的判斷，檢查是否為 isToolCall。這個判斷實際上涉及到函式回撥的機制，這一部分的實現邏輯非常關鍵，但今天我們就不深入探討這個細節，留待下次再進行講解。

至此，整個呼叫流程已經圓滿完成。我們的介面順利而愉快地將處理後的資訊返回給了呼叫端，確保了使用者請求的高效響應。

總結

在這次探討中，我們聚焦於Spring AI如何有效地發起請求並將響應資訊傳遞給使用者。這一過程不僅是開發者與AI互動的橋樑，更是最佳化使用者體驗的關鍵。透過明確的請求結構和響應機制，Spring AI能夠靈活地處理各種使用者輸入，並根據上下文調整回答策略。

然後，我們深入分析了這一機制的核心，關注具體實現與業務邏輯。在此過程中，我們透過例項演示阻塞回答與帶上下文記憶的回答如何在實際應用中發揮作用。這樣的實操不僅能幫助我們更好地理解Spring AI的工作原理，也為將來深入探討流式回答和函式回撥埋下了伏筆。

理解這一過程的背後邏輯，將為我們在日常開發中應用Spring AI提供有力支援。隨著技術的不斷進步，開發者們面臨的挑戰也在日益增加，但透過這種清晰的請求與響應架構，我們可以更從容地應對複雜性，實現更加智慧化的解決方案。

---

我是努力的小雨，一名 Java 服務端碼農，潛心研究著 AI 技術的奧秘。我熱愛技術交流與分享，對開源社群充滿熱情。同時也是一位騰訊雲創作之星、阿里雲專家博主、華為云云享專家、掘金優秀作者。

💡 我將不吝分享我在技術道路上的個人探索與經驗，希望能為你的學習與成長帶來一些啟發與幫助。

🌟 歡迎關注努力的小雨！🌟