# java-ai-demo

**Repository Path**: zbyredeemer/java-ai-demo

## Basic Information

- **Project Name**: java-ai-demo
- **Description**: Java
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-28
- **Last Updated**: 2026-03-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Java AI Demos

一个面向 Java / Spring 开发者的 AI demo playground，主线是 `Spring Boot 3.5.x + Spring AI 1.1.x`。

这个仓库不是单个“大而全”的 AI 项目，而是一个长期积累型、多模块、可教程化的 demo 集合：

- 每个 demo 都是独立 Spring Boot 应用
- 每个 demo 都有单独 README
- 默认采用 `stub-first` 策略，不要求你先配 API Key / PGVector 才能启动
- 需要真实模型或外部系统时，再通过 profile 和环境变量切换

当前已经补齐 `demo-10` 到 `demo-13` 的 live 模式，支持直接接 OpenAI 或 OpenAI-compatible 网关。详细配置见 [docs/live-mode.md](docs/live-mode.md)。

## 模块列表

| 模块 | 主题 | 默认端口 |
| --- | --- | --- |
| `demo-01-chat-basic` | 最小聊天调用 | `8081` |
| `demo-02-chat-stream` | 流式输出 / SSE | `8082` |
| `demo-03-structured-output` | 结构化输出 | `8083` |
| `demo-04-tool-calling` | 工具调用 | `8084` |
| `demo-05-chat-memory` | 会话记忆 | `8085` |
| `demo-06-rag-pgvector` | RAG + PGVector 兼容接入 | `8086` |
| `demo-07-mcp-server` | MCP 服务端 | `8097` |
| `demo-08-mcp-client` | MCP 客户端 | `8088` |
| `demo-09-observability` | 可观测性 | `8089` |
| `demo-10-langchain4j-basic` | LangChain4j 最小接入 | `8090` |
| `demo-11-spring-ai-core` | Spring AI 核心抽象 / PromptTemplate | `8091` |
| `demo-12-function-calling` | 多函数编排 | `8092` |
| `demo-13-tool-use-agent` | Tool-Use Agent | `8093` |

说明：

- `demo-10-langchain4j-basic` 到 `demo-13-tool-use-agent` 已验证 `stub / live / live-unavailable` 三种路径
- `demo-01` 到 `demo-09` 继续保持 `stub-first` 主线，后续再逐步补统一 live 配置

## 快速开始

### 1. 构建

本项目要求 JDK 21。仓库内脚本会优先自动发现本机的 JDK 21。

```bash
./scripts/run-local.sh demo-01-chat-basic
```

或者直接用 Maven：

```bash
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
mvn -pl demo-01-chat-basic spring-boot:run
```

### 2. 默认运行模式

默认配置会启用 `app.stub.enabled=true`，因此你可以直接调用接口查看行为：

```bash
curl 'http://127.0.0.1:8081/ai/chat?message=帮我介绍一下这个仓库'
```

### 3. 切换到真实模型

本轮已补齐并验证的是 `demo-10` 到 `demo-13`。以 Spring AI 模块为例：

```bash
export SPRING_AI_MODEL_CHAT=openai
export SPRING_AI_OPENAI_API_KEY=your-key
export SPRING_AI_OPENAI_CHAT_OPTIONS_MODEL=gpt-4o-mini

./scripts/run-local.sh demo-11-spring-ai-core --app.stub.enabled=false
```

LangChain4j 模块可以直接复用同一套环境变量：

```bash
export SPRING_AI_OPENAI_API_KEY=your-key
export SPRING_AI_OPENAI_CHAT_OPTIONS_MODEL=gpt-4o-mini

./scripts/run-local.sh demo-10-langchain4j-basic --app.stub.enabled=false
```

如果你走兼容 OpenAI 的第三方网关，再补一个 `SPRING_AI_OPENAI_BASE_URL=https://your-host/v1` 即可。`demo-10` 也会自动复用这个地址。

### 4. Live 模式说明

- `demo-10-langchain4j-basic`：live 时走 LangChain4j `OpenAiChatModel`
- `demo-11-spring-ai-core`：live 时走 `PromptTemplate + SystemPromptTemplate + ChatClient.create(ChatModel)`
- `demo-12-function-calling`：live 时不仅会调用真实模型，还会记录实际函数调用 trace
- `demo-13-tool-use-agent`：live 时会记录实际 tool-use step trace
- 如果关闭了 stub 但没有配好 API Key，这四个模块会返回 `mode=live-unavailable`，而不是静默退回 stub

更完整的变量说明、兼容网关配置和排障说明见 [docs/live-mode.md](docs/live-mode.md)。

## 仓库结构

```text
java-ai-demo/
├─ README.md
├─ pom.xml
├─ docs/
├─ scripts/
├─ demo-common/
├─ demo-01-chat-basic/
├─ demo-02-chat-stream/
├─ demo-03-structured-output/
├─ demo-04-tool-calling/
├─ demo-05-chat-memory/
├─ demo-06-rag-pgvector/
├─ demo-07-mcp-server/
├─ demo-08-mcp-client/
├─ demo-09-observability/
├─ demo-10-langchain4j-basic/
├─ demo-11-spring-ai-core/
├─ demo-12-function-calling/
└─ demo-13-tool-use-agent/
```

## 设计约束

- 代码以 Spring AI 抽象为主，而不是绑定单一厂商 SDK
- 每个 demo 除了“最小可用版”，还预留扩展点
- 文档和脚本与代码同等重要
- 默认必须能在本地无外部依赖启动

## 推荐学习顺序

1. `demo-01-chat-basic`
2. `demo-02-chat-stream`
3. `demo-03-structured-output`
4. `demo-04-tool-calling`
5. `demo-05-chat-memory`
6. `demo-06-rag-pgvector`
7. `demo-07-mcp-server`
8. `demo-08-mcp-client`
9. `demo-09-observability`
10. `demo-10-langchain4j-basic`
11. `demo-11-spring-ai-core`
12. `demo-12-function-calling`
13. `demo-13-tool-use-agent`