Spring AI 課程起步：Kotlin Notebook 環境設定完整指南

為什麼選擇 Kotlin Notebook + Spring AI？

在生成式 AI 應用開發的浪潮中，Spring AI^[1] 為 Java/Kotlin 開發者提供了一個熟悉且強大的框架，無縫整合 OpenAI、Azure OpenAI、Anthropic 等主流 AI 服務。而 Kotlin Notebook^[2] 則讓我們能像 Python Jupyter Notebook 一樣，以互動式、即時反饋的方式學習與實驗。

這個組合的優勢在於：

• 類型安全 — Kotlin 的強型別系統在編譯期就能捕捉錯誤
• Spring 生態系 — 直接整合 Spring Boot、Spring Security、Spring Data
• 互動式開發 — Notebook 環境讓學習曲線更平緩，即時看到結果
• 企業級應用 — 從 Notebook 原型到正式 Spring Boot 專案的無縫轉換

環境需求總覽

注意： IntelliJ IDEA 2025.2 以上版本已經內建 Kotlin Notebook 插件，不需要額外安裝。如果你使用較舊的版本，需要手動從 Marketplace 安裝。

Step 1：安裝 JDK 21

Java Development Kit (JDK) 21 是 Spring AI 的基礎運行環境。Spring AI 專案需要 Java 17 以上，我們選擇 JDK 21 以獲得最新的語言特性與效能改善。

1.1 macOS 安裝（使用 Homebrew）

如果你已經安裝 Homebrew，這是最快速的方式：

# 安裝 JDK 21
brew install openjdk@21

# 設定 JAVA_HOME（加入 ~/.zshrc）
echo 'export JAVA_HOME=/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home' >> ~/.zshrc
echo 'export PATH="$JAVA_HOME/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Apple Silicon 注意事項： 如果使用 M1/M2/M3/M4 晶片，Homebrew 路徑為 /opt/homebrew/。如果使用 Intel Mac，路徑為 /usr/local/，請自行替換上述指令中的路徑。

1.2 Windows 安裝

Windows 用戶建議使用 Adoptium（前身為 AdoptOpenJDK）：

1. 前往 Adoptium 官網
2. 下載 JDK 21 (LTS) Windows 安裝程式（.msi 檔案）
3. 執行安裝程式，務必勾選「Set JAVA_HOME variable」
4. 安裝完成後開啟 CMD 或 PowerShell 驗證

1.3 Linux 安裝

不同發行版的安裝指令：

# Ubuntu / Debian
sudo apt update
sudo apt install openjdk-21-jdk

# Fedora / RHEL
sudo dnf install java-21-openjdk-devel

# Arch Linux
sudo pacman -S jdk21-openjdk

1.4 驗證安裝

在終端機（Terminal / CMD / PowerShell）執行：

java -version

預期輸出類似：

openjdk version "21.0.x" 2024-xx-xx
OpenJDK Runtime Environment (build 21.0.x+xx)
OpenJDK 64-Bit Server VM (build 21.0.x+xx, mixed mode, sharing)

如果看到 openjdk version "21.x.x"，代表安裝成功！

Step 2：安裝 IntelliJ IDEA

IntelliJ IDEA 是 JetBrains 開發的旗艦 IDE，對 Kotlin 的支援最為完善。Community Edition（社群版）是免費且開源的，已足夠本課程使用。

2.1 macOS 安裝（使用 Homebrew）

brew install --cask intellij-idea-ce

2.2 手動下載安裝（所有平台）

1. 前往 IntelliJ IDEA 下載頁面
2. 選擇 Community Edition（黑色圖示，完全免費）
3. 下載對應平台的安裝程式
4. 執行安裝程式，保持預設設定即可

2.3 驗證 Kotlin Notebook 插件

IntelliJ IDEA 2025.2 以上版本已內建 Kotlin Notebook 插件^[2]。驗證方式：

1. 開啟 IntelliJ IDEA
2. 進入 Settings → Plugins → Installed
3. 搜尋 Kotlin Notebook，確認狀態為「已啟用」

如果你使用較舊的版本（2025.1 或更早），需要手動安裝：

1. 進入 Settings → Plugins → Marketplace
2. 搜尋 Kotlin Notebook
3. 點擊 Install 並重啟 IDE

Step 3：開啟 Spring AI 課程專案

假設你已經克隆或下載了課程的 Git 專案（例如 springAI-course），現在要在 IntelliJ IDEA 中開啟它。

3.1 方法一：從命令列啟動

# macOS / Linux
open -a "IntelliJ IDEA CE" /path/to/springAI-course

# 或使用 Homebrew 安裝的 CLI
idea-ce /path/to/springAI-course

3.2 方法二：從 IntelliJ 開啟

1. 啟動 IntelliJ IDEA
2. 選擇 Open
3. 導航至課程專案資料夾（如 springAI-course）
4. 點擊 Open

3.3 開啟 Lesson 0 Notebook

1. 在左側專案面板找到 Lesson0 → Lesson0_Setup.ipynb
2. 雙擊打開，IntelliJ 會自動以 Kotlin Notebook 模式開啟
3. 你會看到類似 Jupyter Notebook 的介面，包含 Markdown 區塊與程式碼 Cell

Step 4：測試 Kotlin Notebook 環境

在 Notebook 中執行第一個 Cell，確認環境正常運作。在任何 Code Cell 上按 Shift + Enter 執行：

println("Hello Kotlin Notebook!")
println("JDK 版本: ${System.getProperty("java.version")}")
println("作業系統: ${System.getProperty("os.name")} ${System.getProperty("os.arch")}")
println("環境準備完成，可以開始學習 Spring AI！")

預期輸出：

Hello Kotlin Notebook!
JDK 版本: 21.0.x
作業系統: Mac OS X aarch64
環境準備完成,可以開始學習 Spring AI！

如果看到類似輸出，恭喜你已經成功運行了第一個 Kotlin Notebook Cell！

Step 5：測試引入外部依賴

Kotlin Notebook 可以使用 @file:DependsOn 標註直接引入 Maven 依賴，這是後續課程引入 Spring AI 函式庫的基礎。

執行以下 Cell 測試依賴管理：

@file:DependsOn("com.google.code.gson:gson:2.11.0")

import com.google.gson.Gson

data class Student(val name: String, val lesson: String)

val student = Student("學員", "Spring AI 課程")
val json = Gson().toJson(student)

println("序列化結果: $json")
println("如果看到 JSON 輸出，代表外部依賴引入成功！")

預期輸出：

序列化結果: {"name":"學員","lesson":"Spring AI 課程"}
如果看到 JSON 輸出，代表外部依賴引入成功！

這證明 Kotlin Notebook 已經能夠自動下載並載入 Maven 依賴，後續課程將使用相同機制引入 Spring AI 函式庫。

Step 6：Kotlin Notebook 常用快捷鍵

熟悉這些快捷鍵能大幅提升學習效率：

Cell 類型（Code / Markdown）可以在 Cell 上方的下拉選單切換。

Step 7：設定 OpenAI API Key（重要）

後續所有 Lesson 都需要 OpenAI API Key^[3]。只需要設定一次，所有 Notebook 都會自動讀取。

7.1 取得 API Key

1. 前往 OpenAI API Keys 頁面
2. 登入你的 OpenAI 帳號（沒有帳號的話需要先註冊）
3. 點擊 Create new secret key
4. 為 Key 命名（例如 "Spring AI Course"）
5. 複製 Key 並妥善保管（只會顯示一次，遺失需重新建立）

安全提醒： API Key 相當於你的帳號密碼，絕對不要提交到 Git、分享到公開網站，或寫死在程式碼中。

7.2 設定 .env 檔案

在課程專案根目錄找到 .env 檔案（如果沒有就新建一個）：

1. 在 IntelliJ 左側檔案列表找到專案根目錄的 .env 檔案
2. 雙擊打開，編輯內容為：

OPENAI_API_KEY=sk-你的真正API-Key

3. 儲存檔案（Cmd + S / Ctrl + S）
4. 重新啟動 IntelliJ IDEA（環境變數需要重新載入）

安全保障： .env 檔案已加入 .gitignore，不會被提交到 Git，你的 API Key 是安全的。

7.3 驗證 API Key 設定

在 Notebook 中執行以下 Cell 驗證：

val apiKey = System.getenv("OPENAI_API_KEY")

if (apiKey != null && apiKey.startsWith("sk-") && apiKey.length > 10) {
    println("✓ OPENAI_API_KEY 已設定成功（長度: ${apiKey.length}）")
} else if (apiKey == null) {
    println("✗ 尚未設定 OPENAI_API_KEY 環境變數")
    println("  請依照上方說明設定後，重新啟動 IntelliJ IDEA")
} else {
    println("⚠ OPENAI_API_KEY 格式可能不正確，請確認")
}

如果看到「✓ OPENAI_API_KEY 已設定成功」，代表設定正確！

環境檢查清單

完成所有設定後，使用這個清單進行最終驗證：

全部通過即代表環境準備完成！

常見問題排解

Q1：IntelliJ 無法識別 .ipynb 檔案

原因： Kotlin Notebook 插件未啟用或版本過舊。
解決：

• 確認 IntelliJ IDEA 版本 ≥ 2025.2
• 進入 Settings → Plugins → Installed，確認「Kotlin Notebook」已啟用
• 如果沒有，去 Marketplace 搜尋並安裝

Q2：執行 Cell 時出現「SDK not found」

原因： IntelliJ 沒有正確偵測到 JDK。
解決：

• 進入 File → Project Structure → Project
• 確認 SDK 欄位已選擇 JDK 21
• 如果列表中沒有，點擊「Add SDK → Download JDK」或手動指定路徑

Q3：環境變數 OPENAI_API_KEY 讀取不到

原因： .env 檔案設定後未重啟 IDE。
解決：

• 確認 .env 檔案內容格式正確（OPENAI_API_KEY=sk-...）
• 完全關閉 IntelliJ IDEA 並重新開啟（Restart 不夠）
• 重新開啟專案後再執行驗證 Cell

Q4：@file:DependsOn 下載依賴失敗

原因： Maven Central 連線問題或網路代理設定。
解決：

• 確認網路連線正常
• 如果在中國大陸，可能需要設定 Maven 鏡像源
• 檢查 IntelliJ 的 HTTP Proxy 設定（Settings → Appearance & Behavior → System Settings → HTTP Proxy）

下一步：開始學習 Spring AI

環境設定完成後，你已經準備好開始 Spring AI 的學習之旅！後續課程將涵蓋：

• Lesson 1 — 用 Spring AI 呼叫你的第一個 AI 模型
• Lesson 2 — Prompt 工程：如何寫出有效的提示詞
• Lesson 3 — 結構化輸出：讓 AI 回傳 JSON 物件
• Lesson 4 — 多輪對話：實作聊天機器人
• Lesson 5+ — RAG、Function Calling、向量資料庫整合...

準備好了嗎？Let's build something amazing with Spring AI! 🎉