引言

在這篇文章中，我將介紹如何使用 Spring AI 建立一個簡易的 OpenAI 聊天模型應用程式。我們會從專案的初始化開始，依序說明 OpenAI API 金鑰的設定、Controller 的撰寫，以及基本 HTTP 請求的測試。這個基礎範例將會為日後更進階的應用情境打下良好的根基。

• GitHub：kehao-chen/spring-ai-playground: This is a personal Spring AI playground project.

一、專案初始化

首先，讓我們來談談專案的初始化。雖然你可以透過 Spring 官方網站的 Spring Initializr 來完成，但如果你使用的是 IntelliJ IDEA Ultimate 版本，那麼恭喜你，這個過程將變得更加簡單！在 IntelliJ IDEA 中建立新專案時，選擇 Spring Boot 專案，接著會進入一個選項介面，與 Spring Initializer 完全一致。

在這裡，你可以根據需求選擇相關的 Dependencies，例如 Spring Reactive Web、Spring AI 等，快速建立一個功能齊全的 Spring Boot 專案。這種初始化方式不僅節省時間，還能讓你更專注於開發本身。

• Ref.：Spring Boot project wizard | IntelliJ IDEA Documentation

二、配置 OpenAI API 金鑰

專案建立後，我的目標是創建一個簡單的 OpenAI 聊天模型應用。為了與 OpenAI 互動，首先需要配置對應的 API 金鑰。我偏好使用 YAML 格式來儲存應用配置，因此在 application.yml 檔案中，加入以下內容：

spring:
  ai:
    openai:
      api-key: ENC(YOUR_API_KEY)
      chat:
        options:
          model: gpt-4o-mini

在這裡，spring.ai.openai.api-key 是你的 OpenAI 金鑰，而 spring.ai.openai.chat.options.model 則指定了使用的模型。由於這些資料屬於機密資訊，我使用了 Jasypt 進行加密。你可以參考 Jasypt integration for Spring boot 的專案說明來學習如何加密敏感資料。

特別提醒：千萬不要將 API 金鑰、密碼等機密資訊直接提交到版本控制系統上！ 即使是私人專案，也應該進行一層加密防護。在企業應用開發上，更推薦使用像 Hashicorp Vault 這樣的專業工具來管理機密資料，以提升系統的安全性。

• Ref.：OpenAI Chat :: Spring AI Reference

三、撰寫 Controller

接下來，我依據 Spring AI 的官方文件範例，添加了兩組 API 端點：一個基本的聊天回應端點和一個串流回應端點。

1. 基本聊天回應 API 端點

第一個端點是一個 GET API，接受一個名為 message 的查詢參數。如果使用者沒有傳入參數，則使用預設訊息 "Tell me a joke" 作為請求，並返回包含 AI 回應的 Map 物件。以下是實現範例：

@GetMapping("/ai/generate")
fun generate(
    @RequestParam(
        value = "message",
        defaultValue = "Tell me a joke"
    ) message: String?
): Map<*, *> {
    return mapOf("generation" to chatModel.call(message))
}

在這個範例中，message 是使用者傳入的聊天訊息，而回應則是 Chat Model 處理後的結果，最終以 JSON 格式（Map）返回。

2. 串流聊天回應 API 端點

第二個端點同樣接受 message 參數，但返回的是一個 Flux 物件。Flux 是 Reactor 庫中的資料結構，代表一個可以隨時間持續發送資料的流。這非常適合即時聊天應用的場景，可以逐步向使用者回傳回應，而不是一次性返回所有資料。

@GetMapping("/ai/generateStream")
fun generateStream(
    @RequestParam(
        value = "message",
        defaultValue = "Tell me a joke"
    ) message: String?
): Flux<ChatResponse> {
    val prompt = Prompt(UserMessage(message))
    return chatModel.stream(prompt)
}

在這個端點中，首先建立一個 Prompt 物件，將使用者的訊息作為輸入，然後透過 Chat Model 處理並返回串流回應。這種方式不僅提供更即時的回應體驗，也能顯著提升使用者體驗。

3. 解決 RestClient.Builder 錯誤

如果你在撰寫完 Controller 後直接運行 Spring Boot 應用，可能會遇到一個錯誤提示，指出 OpenAI Chat Model 初始化失敗。通常是因為應用無法找到依賴的 RestClient.Builder Spring Bean。

為了解決這個問題，需要在配置類中手動創建一個 RestClient.Builder Bean，確保應用能正確啟動。以下是 Bean 的定義：

@Bean
fun restClientBuilder(): RestClient.Builder {
    return RestClient.builder()
}

透過這樣的配置，便能成功地啟動了應用，以進行後續的測試。

四、使用 IntelliJ IDEA 進行測試

完成應用的開發後，我們需要對 API 進行測試。IntelliJ IDEA 提供了強大的 HTTP Client 功能，允許你直接在 IDE 中撰寫 HTTP 請求並運行測試。

你可以建立一個 .http 檔案，描述如何發送 HTTP 請求，並透過不同的環境（例如開發環境、測試環境）進行測試。以下是一個簡單的範例：

### /ai/generate
GET http://{{host}}/ai/generate

### /api/generateStream
GET http://{{host}}/ai/generateStream

此外，HTTP Client 還支援撰寫 JavaScript 測試用例。你可以驗證回應的狀態碼、Content-Type 等，以下是測試範例：

client.test("The request executed successfully.", () => {
    const status = response.status;
    client.assert(status === 200, `The response code expected 200, but received ${status}.`);
});

client.test("The response content type is JSON.", () => {
    const type = response.contentType.mimeType;
    client.assert(type === "application/json", `The content type expected 'application/json', but received ${type}.`);
});

透過這種方式，你可以快速撰寫測試並直接在 IntelliJ IDEA 中運行，對於快速迭代和驗證應用行為非常有幫助。

• Ref.：HTTP Client | IntelliJ IDEA Documentation

總結

今天，簡單介紹了如何使用 Spring AI 建立一組簡單的 OpenAI 聊天模型 API 端點，並利用 IntelliJ IDEA 的 HTTP Client 功能進行測試。我們從專案初始化、OpenAI API 金鑰配置、Controller 開發到測試，一步步完成了整個流程。

接下來，我將繼續探索更進階的應用場景，討論如何進一步優化和擴展這個聊天應用。如果你對 Spring AI 或 OpenAI 的整合有任何疑問或想法，歡迎在下方留言，一起交流討論！