# kaleido-ai-study

**Repository Path**: andy1234/kaleido-ai-study

## Basic Information

- **Project Name**: kaleido-ai-study
- **Description**: 面向 Java 开发者的 AI 实战学习项目，基于 Spring Boot 3、Java 21，横向对比 Spring AI、Spring AI Alibaba、LangChain4j 三大框架。
内置 Chat、RAG、Tool Calling、MCP、Agent、多模态、Memory、可观测性全套案例，直观展现各框架实现区别，助力快速掌握 Java AI 开发与框架选型。
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 9
- **Created**: 2026-07-07
- **Last Updated**: 2026-07-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🎨 Kaleido AI Study

> 面向开发者的 Java AI 框架实战学习项目，系统对比 Spring AI、Spring AI Alibaba 与 LangChain4j 在 OpenAI 兼容模型接入、RAG、Tool Calling、Agent 编排、MCP 与可观测性等场景下的工程实现差异。

<div align="center">

![Java](https://img.shields.io/badge/Java-21-007396?logo=openjdk&logoColor=white)
![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.5.6-6DB33F?logo=springboot&logoColor=white)
![Spring AI](https://img.shields.io/badge/Spring%20AI-1.1.0-6DB33F)
![Spring AI Alibaba](https://img.shields.io/badge/Spring%20AI%20Alibaba-1.1.2.0-FF6A00)
![LangChain4j](https://img.shields.io/badge/LangChain4j-1.16.3-1C7ED6)
![Maven](https://img.shields.io/badge/Maven-Multi--Module-C71A36?logo=apachemaven&logoColor=white)

</div>

---

## 📍 项目定位

**Kaleido AI Study** 是一款面向 Java 开发者的 AI 框架实战学习项目。项目不是单点 Demo，而是围绕真实 AI 应用开发中的核心问题，使用同一套 Spring Boot 3 / Java 21 工程基线，对三大主流 Java AI 开发框架进行横向拆解与实操对比：

- **🌱 Spring AI**：从 ChatClient、Advisor、MCP、RAG 到手写 Agent 引擎，适合理解 Spring 原生 AI 抽象。
- **🚀 Spring AI Alibaba**：基于 ReactAgent、StateGraph、Hook、Skill 与 Multi-Agent，适合理解框架级 Agent 编排。
- **⚡ LangChain4j**：基于 AI Services、Agentic Services、RAG、Tool、Memory 与多模态，适合理解声明式 Java AI 应用开发。

项目目标是让开发者可以通过源码、接口和本地文档快速回答这些问题：

> 💡 同一个能力在不同 Java AI 框架中分别怎么写？  
> 💡 Spring AI 的 Advisor 链、MCP 客户端、RAG Pipeline 与手写 Agent 如何组合？  
> 💡 Spring AI Alibaba 的 ReactAgent、StateGraph、Hook 与 Skill 体系如何落地？  
> 💡 LangChain4j 的 AI Service、Agentic Workflow、Memory、RAG 和 Tool Calling 有哪些工程化写法？

---

## ✨ 核心亮点

| 亮点 | 说明 |
|:---:|:---|
| 🎯 **三大 Java AI 框架横向对照** | 完整包含 **LangChain4j、Spring AI、Spring AI Alibaba** 三大主流 Java AI 开发框架，并通过独立模块展示同类能力的不同实现方式。 |
| 🔗 **OpenAI 兼容模型统一接入** | 三个框架模块均围绕 OpenAI 兼容 API 设计，便于替换不同模型网关与国产模型服务。 |
| 🤖 **Agent 能力多范式覆盖** | 包含手写 ReAct / Reflection / Plan-Execute / HITL，也包含框架原生 ReactAgent、StateGraph、Multi-Agent 与 LangChain4j Agentic Workflow。 |
| 📚 **RAG 从入门到进阶** | 覆盖文档摄入、文本切分、向量检索、混合检索、查询重写、查询路由、重排序、多模态 RAG 与来源归因。 |
| 🌐 **MCP 独立服务与客户端联动** | 内置 MCP Server，并在 Spring AI 模块中以 Streamable HTTP 方式调用远程工具与资源。 |
| 🛠️ **工程化基础设施齐全** | 集成 MySQL、Milvus、MinIO、Prometheus、Grafana、Zipkin，可观察 token、trace、metrics 与应用健康状态。 |
| 📖 **离线文档完整** | `docs/` 下沉淀 Spring AI、Spring AI Alibaba、LangChain4j 中文学习文档，适合离线学习与源码对照。 |

---

## 🔄 框架对比

| 能力维度 | 🌱 Spring AI | 🚀 Spring AI Alibaba | ⚡ LangChain4j |
|:---|:---|:---|:---|
| **核心抽象** | ChatClient、ChatModel、Advisor | ReactAgent、StateGraph、Hook、Skill | ChatModel、AI Services、Agentic Services |
| **API 风格** | Spring 风格的 Builder 与 Advisor 链 | Agent 与图编排优先 | 接口声明式 AI Service |
| **Agent 实现** | 手写 ReAct / Reflection / Plan-Execute / HITL / Multi-Agent | 框架原生 ReactAgent、Graph、Supervisor、Routing | `@AiService`、Agentic Workflow、Loop、Conditional、HITL |
| **RAG 实现** | Naive RAG、Advisor RAG、Composable RAG、Hybrid RAG | Agentic RAG、Graph/Hook 驱动 RAG | Easy RAG、Naive RAG、Advanced RAG、Filter、Re-ranking |
| **Tool Calling** | Spring AI `@Tool` 与 ToolCallback | Agent 工具、Agent as Tool、Tool Interceptor | LangChain4j `@Tool`、ToolProvider、动态工具 |
| **Memory** | JDBC ChatMemory | MySQL 会话、Checkpoint、上下文优化 | MessageWindow、TokenWindow、ChatMemoryStore |
| **MCP** | Spring AI MCP Client | 默认禁用，可按需扩展 | 预留 MCP 学习方向 |
| **可观测性** | Actuator、Micrometer、Prometheus、Zipkin | Graph Observation、Prometheus、Zipkin | Listener、Micrometer、工具级观测 |
| **适合学习** | Spring 原生 AI 抽象和底层组合能力 | Agent 框架化编排与图工作流 | 声明式 AI 应用与 Agentic 模式 |

---

## 📦 模块总览

父 POM 为 `com.kaleido:kaleido-ai-study:1.0.0-SNAPSHOT`，当前包含 4 个独立 Spring Boot 应用模块。

| 模块 | 路径 | 端口 | 框架 | 定位 |
|:---:|:---|:---:|:---|:---|
| **springai** | `modules/springai` | 9010 / 9011 | Spring AI 1.1.0 | Spring AI 核心能力、MCP Client、RAG、手写 Agent |
| **mcp-server** | `modules/mcp-server` | 9012 | Spring AI MCP Server | Streamable HTTP MCP 工具与资源服务 |
| **spring-ai-alibaba** | `modules/spring-ai-alibaba` | 9020 / 9021 | Spring AI Alibaba 1.1.2.0 | ReactAgent、StateGraph、Multi-Agent、Hook、Skill |
| **langchain4j** | `modules/langchain4j` | 9030 / 9031 | LangChain4j 1.16.3 | AI Services、Agentic、RAG、Tool、Memory、多模态 |

---

## 🎯 功能全景

### 🌱 `modules/springai`

Spring AI 主学习模块，重点展示 Spring AI 原生抽象和手写 Agent 引擎。

| 功能域 | 入口 | 内置能力 |
|:---|:---|:---|
| 💬 **Chat 基础** | `/chat-model`、`/chat-client` | ChatModel / ChatClient 同步调用、流式输出、推理/非推理模型切换 |
| 📝 **Prompt 工程** | `/prompt` | 角色提示、结构化提示、few-shot、step-by-step、外部模板文件 |
| 📋 **结构化输出** | `/structure` | Bean、实体、列表、Map 结构化响应 |
| 🧠 **Chat Memory** | `/chat-memory` | 多轮对话、Prompt + Memory、JDBC 会话记忆 |
| 🔗 **Advisor** | `/advisor-chain`、`/advisor/custom`、`/advisor/recursive` | 自定义 Advisor、链式 Advisor、递归工具循环、条件重试 |
| 🔧 **Tool Calling** | `/tool-call` | `@Tool` 工具定义、工具调用流式输出、上下文透传 |
| 🌐 **MCP Client** | `/mcp/tool`、`/mcp/resource`、`/mcp/chat` | 工具发现、工具调用、资源读取、AI + MCP 联动 |
| 📚 **RAG 基础** | `/rag/basic`、`/rag/advisor`、`/rag/modular` | Naive RAG、Advisor RAG、模块化 RAG |
| 📥 **RAG 摄入** | `/rag/ingest`、`/rag/split`、`/rag/splitter` | 文本/文件摄入、清洗、切分、MinIO 原文存储、Milvus 向量化 |
| 🔍 **RAG 进阶** | `/rag/hybrid`、`/rag/query`、`/rag/router` | 混合检索、查询重写、Step-back、Decompose、Diversify、路由分类 |
| 🖼️ **多模态** | `/multimodal`、`/rag/multimodal` | 图片输入、多模态文档摄入、多模态 RAG |
| 🤖 **Agent** | `/agent/react`、`/agent/reflection`、`/agent/plan-execute`、`/agent/hitl`、`/agent/multi` | 手写 ReAct、Reflection、Plan-Execute、HITL、Multi-Agent 调度 |
| 📊 **模型评估** | `/evaluation`、`/evaluation/usage` | 相关性评估、事实检查、ChatModel / ChatClient 用量观察 |

---

### 🌐 `modules/mcp-server`

独立 MCP 服务端模块，为 `springai` 提供远程工具与资源。

| 功能域 | 说明 |
|:---|:---|
| 🔧 **工具服务** | 提供实时数据、外部数据、业务服务等 MCP Tool |
| 📦 **资源服务** | 提供可被 MCP Client 读取的 Server Resource |
| 🔄 **传输协议** | Spring AI MCP Server，Streamable HTTP，端口 `9012` |
| 🔗 **客户端关系** | `springai` 是 MCP Client，默认连接 `http://localhost:9012` |

---

### 🚀 `modules/spring-ai-alibaba`

Spring AI Alibaba 学习模块，重点展示框架原生 Agent、图编排与扩展机制。

| 功能域 | 入口 | 内置能力 |
|:---|:---|:---|
| 🤖 **ReactAgent** | `/agent`、`/agent/config`、`/agent/structured`、`/agent/tool` | Agent 调用、流式输出、运行时配置、结构化输出、工具调用 |
| 🕸️ **StateGraph** | `/graph`、`/graph/hitl` | Plan Graph、Reflection Graph、子图、并行节点、HITL 图流程 |
| 👥 **Multi-Agent** | `/multiagent` | 顺序执行、并行执行、路由分发、Supervisor、混合工作流 |
| 🔧 **Agent as Tool** | `/agent/tool` | 将 Agent 封装为工具参与更复杂的任务编排 |
| 🪝 **Hook / Interceptor** | `/hook`、`/interceptor` | 消息裁剪、执行日志、性能统计、工具重试 |
| 🎯 **Skills** | `/skills` | 内置 `code-reviewer`、`data-analyzer`、`content-writer` 技能示例 |
| 💾 **Memory** | `/memory` | 会话创建、消息查询、上下文对话、MySQL 持久化 |
| 📊 **可观测性** | Actuator / Prometheus / Zipkin | Graph 节点、边、执行结果指标观测 |

---

### ⚡ `modules/langchain4j`

LangChain4j 学习模块，重点展示 AI Services、Agentic Workflow 和 LangChain4j 原生 RAG 体系。

| 功能域 | 入口 | 内置能力 |
|:---|:---|:---|
| 💬 **ChatModel** | `/chat/model/basic`、`/chat/model/stream`、`/chat/model/prompt` | 底层模型调用、SSE 流式、few-shot、ChatRequest、Token 统计 |
| 🎯 **AI Services** | `/chat/ai/basic`、`/chat/ai/stream`、`/chat/ai/prompt`、`/chat/ai/system-message` | 声明式接口代理、流式 AI Service、模板变量、动态系统消息 |
| 💾 **Memory** | `/memory/window`、`/memory/persistent` | MessageWindow、TokenWindow、多轮对话、序列化、JDBC 持久化 |
| 📋 **结构化能力** | `/structured/output`、`/structured/input`、`/classification` | POJO、Enum、JSON Mode、结构化 Prompt、LLM/Embedding 分类 |
| 🖼️ **多模态** | `/structured/multimodal` | 图片、音频、视频、PDF 输入 |
| 🔧 **Tool Calling** | `/tool/basics`、`/tool/advanced` | `@Tool`、多工具、返回行为、工具记忆、动态工具、错误处理、幻觉工具名处理 |
| 📚 **RAG** | `/rag/easy`、`/rag/ingest`、`/rag/advanced`、`/rag/filter` | Easy RAG、Naive RAG、文档加载、切分、摄入、查询转换、路由、重排序、元数据过滤、Web/SQL RAG |
| 🤖 **Agentic** | `/agent/basic`、`/agent/workflow`、`/agent/hitl`、`/agent/composition` | 单 Agent、顺序/并行工作流、Loop、Conditional、Supervisor、HITL、Agent + RAG、Agent + Tool、A2A、Voting、GOAP |

---

## 🏗️ 架构视图

```mermaid
flowchart TB
    Dev[Developer] --> SpringAI[modules/springai<br/>Spring AI]
    Dev --> Alibaba[modules/spring-ai-alibaba<br/>Spring AI Alibaba]
    Dev --> LC4J[modules/langchain4j<br/>LangChain4j]

    SpringAI --> MCPClient[MCP Client]
    MCPClient --> MCPServer[modules/mcp-server<br/>Streamable HTTP MCP Server]

    SpringAI --> Milvus[(Milvus)]
    Alibaba --> Milvus
    LC4J --> Milvus

    SpringAI --> MySQL[(MySQL)]
    Alibaba --> MySQL
    LC4J --> MySQL

    SpringAI --> MinIO[(MinIO)]

    SpringAI --> Observability[Prometheus / Grafana / Zipkin]
    Alibaba --> Observability
    LC4J --> Observability
```

---

## 🚀 快速开始

### 📋 环境要求

| 依赖 | 建议版本 | 说明 |
|:---:|:---:|:---|
| JDK | 21+ | 项目统一使用 Java 21 |
| Maven | 3.9+ | 通过父 POM reactor 构建 |
| MySQL | 8.x | ChatMemory、会话与检查点持久化 |
| Docker / Docker Compose | 20.10+ / 2.x+ | 启动 Milvus、MinIO、Prometheus、Grafana、Zipkin |

---

### 1️⃣ 克隆并构建

```bash
git clone <repo-url>
cd kaleido-ai-study
mvn clean package -DskipTests
```

> 💡 当前项目没有 `src/test` 测试目录，常规构建命令使用 `-DskipTests`。

---

### 2️⃣ 设置环境变量

不同模块对环境变量的要求不同。最小启动配置建议参考 `deploy/.env.example`。

| 模块 | 必需变量 |
|:---|:---|
| **springai** | `AI_API_KEY`、`AI_BASE_URL`、`DB_HOST`、`DB_PORT`、`DB_USERNAME`、`DB_PASSWORD`、`MINIO_ENDPOINT`、`MINIO_ACCESS_KEY`、`MINIO_SECRET_KEY` |
| **spring-ai-alibaba** | `AI_API_KEY`、`AI_BASE_URL`、`DB_HOST`、`DB_PORT`、`DB_USERNAME`、`DB_PASSWORD` |
| **langchain4j** | `DB_HOST`、`DB_PORT`、`DB_USERNAME`、`DB_PASSWORD` |
| **mcp-server** | 无必需变量 |

**Windows PowerShell 示例：**

```powershell
$env:AI_API_KEY="sk-xxxxxxxx"
$env:AI_BASE_URL="https://your-api-provider.com"
$env:DB_HOST="localhost"
$env:DB_PORT="3306"
$env:DB_USERNAME="root"
$env:DB_PASSWORD="your_password"
$env:MINIO_ENDPOINT="http://localhost:9000"
$env:MINIO_ACCESS_KEY="minioadmin"
$env:MINIO_SECRET_KEY="minioadmin"
```

---

### 3️⃣ 准备基础设施

`deploy/docker-compose.yml` 提供 Milvus、etcd、MinIO、Zipkin、Prometheus、Grafana，并会构建运行 `springai` 应用。MySQL 不在 compose 中，需要使用本机或外部 MySQL。

**如果希望通过 compose 启动完整 Spring AI 演示环境：**

```bash
cd deploy
docker compose up -d --build
```

**如果只想先启动本地开发依赖，再用 Maven 手动运行各模块：**

```bash
cd deploy
docker compose up -d etcd minio-storage milvus zipkin
```

---

### 4️⃣ 启动模块

```bash
# Spring AI 主模块
mvn -pl modules/springai spring-boot:run

# MCP Server
mvn -pl modules/mcp-server spring-boot:run

# Spring AI Alibaba
mvn -pl modules/spring-ai-alibaba spring-boot:run

# LangChain4j
mvn -pl modules/langchain4j spring-boot:run
```

---

### 📍 服务地址

| 服务 | 应用地址 | 管理端口 |
|:---|:---|:---|
| Spring AI | `http://localhost:9010` | `http://localhost:9011/actuator` |
| MCP Server | `http://localhost:9012` | 无独立管理端口 |
| Spring AI Alibaba | `http://localhost:9020` | `http://localhost:9021/actuator` |
| LangChain4j | `http://localhost:9030` | `http://localhost:9031/actuator` |
| Prometheus | `http://localhost:9090` | - |
| Grafana | `http://localhost:3000` | - |
| Zipkin | `http://localhost:9411` | - |

---

## 🗺️ 推荐学习路线

| 阶段 | 学习目标 | 推荐模块 |
|:---:|:---|:---|
| 1️⃣ | 掌握模型调用、Prompt、流式输出、结构化输出 | `springai`、`langchain4j` |
| 2️⃣ | 掌握 Chat Memory、Tool Calling、Advisor / ToolProvider | `springai`、`langchain4j` |
| 3️⃣ | 理解 MCP 工具发现、远程调用与资源读取 | `mcp-server`、`springai` |
| 4️⃣ | 实现 RAG 文档摄入、向量检索、混合检索与查询重写 | `springai`、`langchain4j` |
| 5️⃣ | 对比手写 Agent、框架 Agent、Agentic Workflow | `springai`、`spring-ai-alibaba`、`langchain4j` |
| 6️⃣ | 学习 StateGraph、Hook、Skill、HITL 与 Multi-Agent | `spring-ai-alibaba` |
| 7️⃣ | 接入可观测性，观察 token、trace、metrics 与调用链路 | 全部业务模块 |

---

## 🔮 下一步计划

项目后续会继续扩展 Agent 框架与工程化能力对比，计划集成 **AgentScope** 与 **Harness**。

| 方向 | 计划 |
|:---|:---|
| 🤖 **AgentScope 集成** | 补充 AgentScope 在多 Agent 协作、任务编排与工具调用场景下的示例，用于和现有 Java AI 框架实现做横向对照。 |
| 🎯 **Harness 集成** | 增加 Harness 相关工程实践，重点覆盖 Agent 运行流程、评测验证与可观测性集成，完善端到端实验闭环。 |

---

## 📁 目录结构

```text
kaleido-ai-study/
├── modules/
│   ├── springai/                  # Spring AI 实战模块
│   ├── mcp-server/                # MCP Streamable HTTP 服务端
│   ├── spring-ai-alibaba/         # Spring AI Alibaba Agent / Graph 模块
│   └── langchain4j/               # LangChain4j AI Services / Agentic 模块
├── docs/
│   ├── spring-ai/                 # Spring AI 离线中文文档
│   ├── spring-ai-alibaba/         # Spring AI Alibaba 离线中文文档
│   ├── langchain4j/               # LangChain4j 离线中文文档
│   └── images/                    # 监控、链路、框架示意图
├── deploy/
│   ├── docker-compose.yml         # 基础设施与部分服务编排
│   ├── prometheus/                # Prometheus 配置
│   └── grafana/                   # Grafana 数据源与看板
├── pom.xml                        # Maven 父 POM
└── README.md
```

---

## 📖 本地文档

项目支持离线学习，框架资料优先查看本仓库 `docs/`：

| 文档目录 | 内容 |
|:---|:---|
| 📗 `docs/spring-ai` | Spring AI 核心概念、ChatClient、Advisor、RAG、MCP、Milvus、Observability |
| 📙 `docs/spring-ai-alibaba` | Spring AI Alibaba Agent、Graph、Workflow、Memory、RAG、Hook、Skill |
| 📘 `docs/langchain4j` | LangChain4j Chat Model、AI Services、Memory、Tools、RAG、Agentic、MCP、多模态 |

---

## 📐 开发约定

- ✅ 所有模块默认使用 `dev` profile。
- ✅ Java 代码统一使用 Lombok 构造器注入，优先 `@AllArgsConstructor` + `final` 字段。
- ✅ JavaDoc 使用 `@description` / `@author` / `@date` 标签。
- ✅ 系统提示词使用中文，便于学习与本地调试。
- ✅ RAG 向量维度默认 1024，嵌入模型为 `bge-m3`。
- ✅ ChatMemory / 会话持久化后端为 JDBC / MySQL，不是 Redis。
- ✅ 外部网络文档不可用时，优先查阅本仓库 `docs/` 下的离线文档。

---

## 👥 适合人群

- 🧑‍💻 想系统学习 Java AI 应用开发的后端工程师。
- 📊 想对比 Spring AI、Spring AI Alibaba、LangChain4j 选型差异的技术负责人。
- 🔬 想理解 RAG、MCP、Agent、Tool Calling、Memory、Observability 如何落地到 Spring Boot 工程的开发者。
- 🏢 想把 OpenAI 兼容模型接入 Java 服务并进行工程化封装的团队。

---

<div align="center">

**🌟 如果这个项目对你有帮助，请给一个 Star 支持！ 🌟**

</div>

---