AI Agent Platform

基于 Spring Boot 3 + LangChain4j 构建的企业级 AI Agent 平台，集成 ReAct 推理循环、多路召回 RAG、语义缓存和工具调用框架。

Open Source Quality Baseline

• Test lifecycle: mvn test / mvn verify
• Coverage report: target/site/jacoco/index.html
• Metrics endpoints: /actuator/health, /actuator/metrics, /actuator/prometheus
• Monitoring stack: docker compose up -d app prometheus grafana
• Details: docs/observability.md

🎯 适用人群

• 正在准备大厂 Java / AI 岗位面试的求职者（覆盖高频面试考点）
• 需要快速搭建 AI 客服系统的中小企业或独立开发者
• 想学习 RAG + Agent 完整落地实践的技术爱好者
• 需要可扩展 AI Agent 框架的产品开发者

功能特性

• ReAct Agent 循环 — Thought → Action → Observation → Final Answer 推理循环，含死循环防护和超时控制
• 多路召回 RAG — 向量检索（Milvus）+ BM25 关键词检索 + RRF 融合排序
• 语义缓存 — 基于 embedding 余弦相似度，自动缓存相似问题回答，降低 API 成本
• 多模型支持 — 策略模式动态切换（DeepSeek / 通义千问 / 豆包 / Qwen3-Flash / Ollama 本地）
• 工具调用框架 — 数据库查询、外部 API 调用，注册表模式自动发现
• 流式输出 — SSE 实时推送，5 分钟超时保护
• 会话管理 — Redis 存储会话上下文，24 小时 TTL 自动过期
• Docker 一键部署 — 4 个服务编排（MySQL + Redis + Milvus + App）

技术栈

快速开始

前置条件

• JDK 17+
• Docker & Docker Compose (推荐)
• Maven 3.9+

1. 克隆项目

git clone https://github.com/888newstep/ai-agent-platform.git
cd ai-agent-platform

2. 配置环境变量

cp .env.example .env
# 编辑 .env 填入你的 API 密钥

3. 启动（Docker 一键部署）

docker compose up -d

4. 验证

curl http://localhost:8081/api/v1/agent/health
# 返回: {"status":"UP","mode":"react"}

API 使用示例

创建会话

curl -X POST http://localhost:8081/api/v1/agent/session

普通聊天

curl -X POST "http://localhost:8081/api/v1/agent/chat?sessionId={sessionId}&question=你好&useRag=true"

ReAct 模式聊天（推理 + 工具调用）

curl -X POST "http://localhost:8081/api/v1/agent/react/chat?sessionId={sessionId}&question=查询数据库中的用户数量&useRag=true"

流式聊天

curl -N "http://localhost:8081/api/v1/agent/chat/stream?sessionId={sessionId}&question=请详细介绍RAG技术"

上传文档

curl -X POST -F "file=@文档.pdf" http://localhost:8081/api/v1/agent/document/upload

架构设计

┌─────────────────────────────────────────────────────────────┐
│                    AI Agent Platform                         │
├─────────────────────────────────────────────────────────────┤
│  Controller Layer                                           │
│  ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐     │
│  │ Chat API     │ │ ReAct API    │ │ Document API     │     │
│  └──────┬───────┘ └──────┬───────┘ └────────┬─────────┘     │
├─────────┼────────────────┼──────────────────┼───────────────┤
│  Service Layer           │                  │               │
│  ┌──────┴────────┐ ┌─────┴──────┐ ┌────────┴──────────┐    │
│  │ AiAgentService│ │ ReActAgent  │ │ DocumentService   │    │
│  └──────┬────────┘ └─────┬──────┘ └────────┬──────────┘    │
│         │                │                  │               │
│  ┌──────┴────────────────┴──────────────────┴──────────┐    │
│  │              SemanticCacheService                    │    │
│  └──────────────────────┬──────────────────────────────┘    │
├─────────────────────────┼──────────────────────────────────┤
│  Retrieval Layer        │                                   │
│  ┌──────────────────────┴──────────────────────────────┐    │
│  │              MultiRecallService                     │    │
│  │  ┌────────────────┐  ┌──────────────────────────┐   │    │
│  │  │ Vector Search  │  │  BM25 Keyword Search     │   │    │
│  │  │ (Milvus)       │  │  (Bm25Search)            │   │    │
│  │  └────────┬───────┘  └──────────┬───────────────┘   │    │
│  │           └──────────┬──────────┘                    │    │
│  │                  RRF Fusion                          │    │
│  └──────────────────────────────────────────────────────┘    │
├──────────────────────────────────────────────────────────────┤
│  Tool Layer                                                   │
│  ┌──────────────────────────────────────────────────────┐    │
│  │  ToolService (query_database / call_external_api)    │    │
│  └──────────────────────────────────────────────────────┘    │
├──────────────────────────────────────────────────────────────┤
│  Infrastructure Layer                                        │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐    │
│  │  MySQL   │ │  Redis   │ │  Milvus  │ │  AI Models   │    │
│  └──────────┘ └──────────┘ └──────────┘ └──────────────┘    │
└──────────────────────────────────────────────────────────────┘

详细架构设计请参阅 docs/ARCHITECTURE.md

ReAct Agent 详解

核心循环

Thought: 分析问题，决定下一步行动
    ↓
Action: 选择工具（query_database / call_external_api）
    ↓
Action Input: 工具参数
    ↓
Observation: 工具执行结果
    ↓
（重复以上步骤，直到得到足够信息）
    ↓
Final Answer: 给出最终回答

安全机制

多路召回 RAG

召回流程

1. 向量检索 — Milvus 语义相似度检索，捕获语义相近的文档
2. BM25 关键词检索 — 关键词精确匹配，捕获包含特定术语的文档
3. RRF 融合 — 倒数排名融合算法，合并两路结果

RRF 公式

score(d) = Σ 1/(k + rank_i(d))

其中 k=60，rank_i(d) 是文档 d 在第 i 路检索中的排名。

项目结构

src/main/java/com/aiagent/
├── agent/
│   ├── AiAgentService.java      # AI 聊天服务（集成长上下文管理 + ReAct + 语义缓存）
│   ├── ReActAgent.java          # ReAct 推理循环
│   └── MultiAgentService.java   # 多智能体协作（Supervisor + Worker）
├── cache/
│   └── SemanticCacheService.java # 语义缓存（降低 API 成本）
├── config/
│   ├── AiModelConfig.java       # 多模型配置（策略模式）
│   ├── AiProperties.java        # 配置属性绑定
│   └── MilvusInitConfig.java    # Milvus 初始化
├── controller/
│   └── AiAgentController.java   # REST API 控制器
├── document/
│   ├── DocumentService.java     # 文档上传与检索
│   └── parser/                  # 多格式文档解析器
├── evaluation/
│   └── RagEvaluationService.java # RAG 效果评估（召回率/准确率/延迟）
├── memory/
│   └── LongContextManager.java  # 长上下文管理（滑动窗口 + 摘要压缩 + 历史检索）
├── retrieval/
│   ├── MultiRecallService.java  # 多路召回 + RRF 融合
│   └── Bm25Search.java          # BM25 关键词检索
├── tool/
│   └── ToolService.java         # 工具调用框架
└── vectorstore/
    └── MilvusVectorStoreService.java  # Milvus 向量存储

配置说明

模型切换

在 application.yml 中修改 ai.model.provider：

ai:
  model:
    provider: deepseek   # 可选: deepseek, qianwen, doubao, qwen3-flash, local

嵌入模型切换

ai:
  embedding:
    provider: siliconflow  # 可选: local, local-qwen3, siliconflow

环境变量

参考 .env.example 文件，所有敏感配置通过环境变量注入。

面试价值

该项目适用于以下面试场景：

Java 后端岗

AI 应用岗

License

Apache License 2.0