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; metrics require authentication by default, while the local .env.example enables public scraping for Compose.
• 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 推理循环，含死循环防护和超时控制
• Adaptive RAG — Query Router、查询改写、自适应多轮检索与 Self-RAG 结果验证
• 多路召回 RAG — 向量检索（Milvus）+ BM25 关键词检索 + RRF 融合排序
• 语义缓存 — 基于 embedding 余弦相似度，自动缓存相似问题回答，降低 API 成本
• API 保护 — Redis 分布式固定窗口限流 + 估算 Token 预算，按认证主体/IP 隔离高成本请求
• 多模型支持 — 策略模式动态切换（DeepSeek / 通义千问 / 豆包 / Qwen3-Flash / Ollama 本地）
• 工具调用框架 — 数据库查询、外部 API 调用，注册表模式自动发现
• 流式输出 — SSE 实时推送，5 分钟超时保护
• 会话管理 — Redis 存储会话上下文，24 小时 TTL 自动过期
• Docker 一键部署 — 核心 4 个服务编排（MySQL + Redis + Milvus + App），Prometheus/Grafana 可选

技术栈

快速开始

前置条件

• 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","service":"AI Customer Service Agent","version":"1.0.0"}

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

评测报告历史

评测接口需要管理员凭证。导出报告后，可以列出最近报告并比较两次评测的指标变化：

curl -H "X-Admin-Api-Key: ${ADMIN_API_KEY}" \
  "http://localhost:8081/api/v1/agent/evaluate/history?limit=20"

curl -H "X-Admin-Api-Key: ${ADMIN_API_KEY}" \
  "http://localhost:8081/api/v1/agent/evaluate/history/compare?baseline={fileName}&candidate={fileName}"

比较结果中的 metricDeltas 使用 candidate - baseline，并在数据集来源、样本数或 topKs 不一致时标记为不可直接比较。

可复现 RAG 评测

仓库提供最小示例数据集 examples/evaluation-datasets/rag-sample.json，默认配置已指向该目录。详细的双配置真实评测流程见 docs/RAG_BENCHMARK.md，运行脚本为 scripts/run-rag-evaluation.ps1。数据集中的 relevantDocIds 是评测基准的 chunk ID；只有先导入包含这些 ID 的文档，召回率和准确率才具有业务意义。若复用已有 ecommerce_qa collection，请先设置 AI_VECTOR_STORE_MODE=qa、MILVUS_COLLECTION_NAME=ecommerce_qa 和 MILVUS_READ_ONLY=true；真实数据请通过 AI_EVALUATION_DATASET_DIRECTORY 指向本地私有目录，避免提交到 GitHub。

curl -X POST \
  -H "X-Admin-Api-Key: ${ADMIN_API_KEY}" \
  "http://localhost:8081/api/v1/agent/evaluate/export?datasetPath=examples/evaluation-datasets/rag-sample.json&topKs=1,3,5"

架构设计

┌─────────────────────────────────────────────────────────────┐
│                    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/
│   ├── api/                         # Agent REST API
│   ├── application/                 # 普通聊天、ReAct、Multi-Agent 编排
│   └── infrastructure/tool/         # 数据库与外部 API 工具
├── infrastructure/
│   ├── cache/                       # 语义缓存与 RAG 缓存
│   ├── config/                      # 模型、Milvus、安全与限流配置
│   └── metrics/                     # Micrometer 业务指标
├── knowledge/
│   ├── application/                 # 文档上传、解析与入库
│   └── infrastructure/              # Parser、Splitter、VectorStore
├── rag/application/                 # Adaptive RAG、Multi-Recall、评测
├── chat/                            # 会话与 SSE 流式响应
└── shared/                          # 公共响应体与异常处理

配置说明

安全提示：启动前必须通过环境变量设置 JWT_SECRET 和 ADMIN_API_KEY。仓库中的 .env.example 仅是占位模板，不要直接用于生产环境。

模型切换

在 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