Show HN：Spring AI Playground – 無程式碼MCP工具工作室與代理聊天

Spring AI Playground

Spring AI Playground 是一個自託管的 Web UI 平台，用於建構低程式碼工具，並透過內建的 MCP 伺服器動態地將其暴露給 AI 代理。

與大多數僅專注於提示測試和聊天視覺化的 AI playground 不同，它透過讓您建立 AI 代理可以使用之可執行工具，來彌合靜態 AI 對話與真實世界動作之間的差距。

它將大型語言模型 (LLMs)、檢索增強生成 (RAG) 和低程式碼工具開發整合在單一環境中。在工具工作室 (Tool Studio) 中建立的工具會在執行階段動態評估和載入，然後自動註冊並作為模型上下文協議 (MCP) 工具暴露。這使得它們無需重新啟動或重新部署即可立即供 MCP 相容的客戶端使用。

主要功能

工具工作室與內建 MCP 伺服器

直接在瀏覽器中使用JavaScript (ECMAScript 2023) 建立 AI 工具。這些工具由GraalVM Polyglot 提供支援，在 JVM (Polyglot) 中運行，具有可設定的安全限制，並透過內建 MCP 伺服器立即暴露。體驗無需重新啟動、無需重新部署的工作流程：只需編寫、測試和發布。

MCP 伺服器與工具檢查

連接到外部MCP 伺服器，檢查可用工具，並驗證工具執行行為。在統一的介面中測試您的自訂工具工作室工具和第三方 MCP 服務。

向量資料庫與 RAG 管道

上傳文件，設定分塊 (chunking) 和嵌入 (embeddings)，並測試檢索管道。針對選定的 RAG 來源評估提示執行，以驗證知識基礎的回應。

代理式聊天與代理工作流程

在聊天介面中與 LLMs 互動，模型可以在其中進行推理、選擇工具並執行動作。結合MCP 工具和RAG 增強的上下文來驗證端到端的代理工作流程。

為何選擇 Spring AI Playground？

• 動態 MCP 託管: 即時建構和暴露工具，具有即時的 MCP 伺服器暴露且無部署開銷。
• 統一測試中心: 在單一、連貫的環境中驗證提示、RAG 管道和代理工作流程。
• 供應商無關: 可輕鬆在 Ollama、OpenAI 和其他 LLM 供應商（包括 OpenAI 相容 API）之間切換。
• 專為現代 AI 設計: 專為 Spring AI 生態系統、MCP 協議和面向代理的架構而設計。

目錄

• 概述
• 主要功能
  • 工具工作室與內建 MCP 伺服器
  • MCP 伺服器與工具檢查
  • 向量資料庫與 RAG 管道
  • 代理式聊天與代理工作流程
• 為何選擇 Spring AI Playground？
• 快速入門
  • 先決條件
  • 開始使用
  • 運行應用程式
    • 使用 Docker 運行 (建議)
    • 清理 Docker
    • 本地運行 (可選)
  • PWA 安裝
• 自動配置
• AI 模型
  • 支援的主要 AI 模型供應商
  • 配置 Ollama 模型
  • 使用 OpenAI
  • OpenAI 相容伺服器
• 工具工作室
  • 內建 MCP 伺服器
  • 動態工具註冊
  • JavaScript 運行時
  • 低程式碼工具開發工作流程
  • 預建範例工具
  • 在代理式聊天中使用工具
  • 連接外部 MCP 客戶端
• MCP Playground
  • 主要功能
  • MCP 入門
• 向量資料庫
  • 支援的主要向量資料庫供應商
  • 向量資料庫 Playground 功能
• 代理式聊天
  • 兩個整合的範式
    • RAG：基於鏈的工作流程
    • MCP：透過代理推理進行動作
  • 工作流程整合
  • 代理推理的模型要求
  • 代理式聊天架構概覽
• 即將推出的功能
  • 進階代理工具 (能力工廠)
  • 基礎設施與企業功能

快速入門

先決條件

• 已安裝 Java 21 或更高版本（建構專案所需）。
• 您的電腦上正在運行 Ollama（請參閱 AI 模型）。
• 您的電腦上已安裝並正在運行 Docker。（僅當您選擇使用 Docker 運行應用程式時）

開始使用

首先，從 GitHub 克隆 Spring AI Playground 專案：

git clone https://github.com/spring-ai-community/spring-ai-playground.git
cd spring-ai-playground

運行應用程式

使用 Docker 運行 (建議)

1. 建構 Docker 映像：

   ./mvnw spring-boot:build-image -Pproduction -DskipTests=true \
   -Dspring-boot.build-image.imageName=jmlab/spring-ai-playground:latest

2. 運行 Docker 容器：

   docker run -d -p 8282:8282 --name spring-ai-playground \
   -e SPRING_AI_OLLAMA_BASE_URL=http://host.docker.internal:11434 \
   -v spring-ai-playground:/home \
   --restart unless-stopped \
   jmlab/spring-ai-playground:latest

3. 存取應用程式：在瀏覽器中開啟 http://localhost:8282。

注意事項：

• 資料持久化：應用程式資料儲存在 spring-ai-playground Docker 磁碟區中，確保即使容器被移除，資料也能持久保存。
• Ollama 連線：環境變數 SPRING_AI_OLLAMA_BASE_URL 設定為 http://host.docker.internal:11434。如果 Ollama 在不同的主機或埠上運行，請調整 URL。
• 自動重新啟動：--restart unless-stopped 選項確保容器自動重新啟動，除非手動使用 docker stop 停止。
• 適用於 Linux 使用者： host.docker.internal DNS 名稱可能在所有 Linux 發行版上都不可用。如果您遇到連線問題，您可能需要在 docker run 命令中使用 --network="host"，或將 host.docker.internal 替換為主機在 Docker 橋接網路上的 IP 位址（例如 172.17.0.1）。

⚠️ MCP STDIO 傳輸限制
雖然 Docker 對於大多數情況是建議的，但它不適用於測試 MCP STDIO 傳輸。MCP STDIO 傳輸需要直接的進程間通訊，而容器化環境無法可靠地提供。

如果您計劃測試 MCP STDIO 傳輸，請改用 本地運行 (可選)。

清理 Docker

• 要停止並移除 Docker 容器、映像和磁碟區：

  docker stop spring-ai-playground
  docker rm spring-ai-playground
  docker rmi jmlab/spring-ai-playground:latest
  docker volume rm spring-ai-playground

本地運行 (可選)

1. 建構並運行應用程式：

   ./mvnw clean install -Pproduction -DskipTests=true
   ./mvnw spring-boot:run

2. 存取應用程式：在瀏覽器中開啟 http://localhost:8282。

PWA 安裝

注意：在繼續進行 PWA 安裝之前，請完成上述任一 Docker 或本地安裝步驟。

Spring AI Playground 具有 Progressive Web App (PWA) 功能，允許您將其安裝為裝置上的獨立應用程式，以獲得類似原生應用程式的體驗。

安裝為 PWA

1. 在您的網頁瀏覽器中於 http://localhost:8282 開啟應用程式。
2. 使用以下方法之一進行安裝：
   • 瀏覽器 PWA 安裝彈出視窗：大多數現代瀏覽器將自動顯示 PWA 安裝彈出視窗或在網址列中顯示提示。
   • 安裝 PWA 按鈕：尋找應用程式主頁上的「安裝 PWA」按鈕並點擊它。
3. 按照安裝精靈完成設定並將應用程式新增到您的裝置。

自動配置

Spring AI Playground 預設使用 Ollama 作為本地 LLM 和嵌入模型。無需 API 金鑰，這使得入門變得容易。

AI 模型

要啟用 Ollama，請確保它已在您的系統上安裝並運行。有關設定詳細資訊，請參閱 Spring AI Ollama Chat 先決條件。

支援的主要 AI 模型供應商

Spring AI Playground 透過 Spring AI 整合支援主要的 AI 模型供應商，包括 Anthropic、OpenAI、Microsoft、Amazon、Google 和 Ollama。有關可用實作的更多詳細資訊，請參閱 Spring AI Chat Models 參考文件。

配置 Ollama 模型

當使用 ollama 設定檔運行 Spring AI Playground 時，您可以透過更新您的設定檔 (application.yaml) 來配置預設的聊天和嵌入模型，以及 playground UI 中可用模型的列表。

注意事項：

• pull-model-strategy: when_missing 可確保在首次使用模型時，如果本地尚未提供配置的模型，則會自動從 Ollama 中提取。
• playground.chat.models 控制哪些模型出現在網頁 UI 的模型選擇下拉選單中。
• 在此處更改 chat.options.model 或 embedding.options.model 會更新應用程式使用的預設值。

建議預先提取 Ollama 模型，以避免首次使用模型時的延遲。在啟動 Spring AI Playground 之前，請使用 Ollama 預先提取模型。

切換到 OpenAI

切換到 OpenAI 是如何使用不同 AI 模型與 Spring AI Playground 的主要範例。要探索 Spring AI 支援的其他模型，請參閱 Spring AI 文件。

預設情況下，Spring AI Playground 使用 Ollama 作為主要的 AI 模型供應商。要在執行階段切換到 OpenAI（無需修改 pom.xml 或 application.yaml 等檔案），請啟用 openai 設定檔並透過環境變數提供 API 金鑰。

要切換到 OpenAI，請按照以下步驟操作：

• 在執行階段啟用 OpenAI 設定檔：

  • 運行應用程式時指定 --spring.profiles.active=openai。這將覆蓋預設的 Ollama 設定檔。

• 透過環境變數提供 OpenAI API 金鑰：

  • 預設的 application.yaml 使用 ${OPENAI_API_KEY} 作為 API 金鑰的預留位置。

  • 在運行之前設定環境變數：

    • Unix/Mac：

    export OPENAI_API_KEY=your-openai-api-key

    • Windows：

    set OPENAI_API_KEY=your-openai-api-key

  • 或者，直接在運行命令中傳遞（如果已設定，則覆蓋環境變數）。

• 使用 OpenAI 設定運行應用程式：

  • 對於 Docker 運行（結合設定檔和 API 金鑰）：

    docker run -d -p 8282:8282 --name spring-ai-playground \
    -e SPRING_PROFILES_ACTIVE=openai \
    -e OPENAI_API_KEY=your-openai-api-key \
    -e SPRING_AI_OLLAMA_BASE_URL=http://host.docker.internal:11434 \ # 混合使用時可選
    -v spring-ai-playground:/home \
    --restart unless-stopped \
    jmlab/spring-ai-playground:latest

  • 對於本地運行（使用 Maven，結合設定檔和 API 金鑰）：

    ./mvnw spring-boot:run --spring.profiles.active=openai --spring.ai.openai.api-key=your-openai-api-key

切換到 OpenAI 相容伺服器

您可以透過在 application.yml 中配置以下屬性或透過環境變數/運行參數，將 Spring AI 連接到 OpenAI 相容伺服器，例如 llama.cpp、TabbyAPI、LM Studio、vLLM、Ollama 或其他公開 OpenAI 相容端點（例如 /v1/chat/completions）的伺服器。這利用了 Spring AI 的 OpenAI Chat Client，它支援與這些伺服器的無縫整合。

# 快速入門範例 - Ollama 作為 OpenAI 相容伺服器
spring:
ai:
openai:
api-key: "not-used" # 本地 Ollama 不需要驗證
base-url: "http://localhost:11434/v1"
chat:
options:
model: "llama3.2"

# 更多範例（llama.cpp、TabbyAPI、LM Studio、vLLM），
# 請參閱下方的詳細配置部分。

配置詳細資訊：

• api-key：Spring AI 對所有請求都必需。如果伺服器啟用驗證（例如 TabbyAPI），請使用真實的金鑰。對於未驗證的伺服器（例如本地 llama.cpp、Ollama），使用「not-used」之類的預留位置即可。支援環境變數以確保安全（例如 ${OPENAI_API_KEY} 或透過 export OPENAI_API_KEY=your-key 設定）。
• base-url：指向伺服器的根端點。如果您的伺服器需要，請包含 /v1（例如，Ollama 通常使用 http://localhost:11434/v1）。Spring AI 會自動附加 /chat/completions 等路徑。透過 curl <base-url>/v1/models 進行測試以進行驗證。
• model：必須與伺服器上註冊的模型名稱完全匹配（例如，vLLM 的「meta-llama/Llama-3-8B-Instruct」）。使用伺服器的 /models 端點列出可用模型。
• completions-path：僅在伺服器偏離 OpenAI 標準時覆寫（預設值：「/v1/chat/completions」）。大多數相容伺服器都遵循此規則。
• extra-body：用於傳遞非標準參數（例如，採樣控制）的金鑰。