🌟 Spring AI 实战项目（Azer）

本项目以 Spring AI 开发框架实战 为核心，融合多种主流 AI 客户端、工具库与 Serverless 技术，完整展示 RAG 知识库 + Agent + 工具调用 + MCP 在 Java 生态中的工程化落地。

😍项目预览

🚀 技术栈概览

🧩 系统架构图（Mermaid）

🗂️ 后端项目分层（按你当前目录）

src
├─ main
│  ├─ java
│  │  └─ com.azer.azerall
│  │     ├─ advisor        # 统一建议/拦截/增强（如校验、异常、切面）
│  │     ├─ agent          # 智能体（ReAct 策略、工具编排、调用计划）
│  │     ├─ app            # 业务应用入口/场景层（聚合服务、用例驱动）
│  │     ├─ chatmemory     # 对话记忆（MCP/数据库/缓存策略）
│  │     ├─ config         # Spring 配置（Bean、AOP、Kryo、Knife4j 等）
│  │     ├─ constant       # 常量定义（模型名、工具名、错误码、路由）
│  │     ├─ controller     # API 接口（REST；对接前端/Knife4j 注解）
│  │     ├─ demo           # 示例与演示（样例接口/脚本/对接样板）
│  │     ├─ rag            # RAG 管线（解析→向量化→PGvector→检索/重排）
│  │     ├─ tools          # 工具实现（SearchAPI/Pexels/Jsoup/PDF 等）
│  │     └─ AzerAllApplication  # Spring Boot 启动类
│  └─ resources
│     ├─ application.yml   # 环境配置（DB、API Key、模型参数）
│     ├─ application-loacl.yml   # 本地私有配置(私密key设置)
│     └─ document/         # RAG文档
└─ test                    # 单元/集成测试

🖥️ 前端技术（与当前 package.json 一致）

• 构建工具：Vite ^4.3.9
• 框架：Vue ^3.2.47
• 路由：vue-router ^4.1.6
• 网络：axios ^1.3.6
• 实用工具：@vueuse/head ^2.0.0

可按需新增 UI 库（Element Plus/Naive UI）、状态管理（Pinia）等。

⚙️ 环境要求

• JDK 21+
• Maven 3.9+
• PostgreSQL 15+ 且安装 PGvector 插件
• Spring Boot 3.x
• Node.js 18+ / pnpm 或 npm
• 推荐 IDE：IntelliJ IDEA（后端） / VSCode 或 Cursor（前端）

🔧 配置示例（application.yml）

spring:
  application:
    name: azer-all
  profiles:
    active: local
  datasource:
    url: jdbc:postgresql://你的外网公开地址:5432/azer-ai-agent?sslmode=require
    username: 你的账号
    password: 你的密码
  ai:
    mcp:
      client:
        stdio:
          servers-configuration: classpath:mcp-servers.json
    vectorstore:
      pgvector:
        index-type: HNSW
        dimensions: 1536
        distance-type: COSINE_DISTANCE
        max-document-batch-size: 10000

server:
  port: 8123
  servlet:
    context-path: /api

springdoc:
    swagger-ui:
      path: /swagger-ui.html
      tags-sorter: alpha
      operations-sorter: alpha
    api-docs:
      path: /v3/api-docs
    group-configs:
      - group: 'default'
        paths-to-match: '/**'
        packages-to-scan: com.azer.azerall.controller

knife4j:
  enable: true
  setting:
    language: zh_cn

search-api:
  api-key: "你自己的key"

🚦 启动顺序（按你的流程）

1. 打包 MCP 服务（图片搜索工具服务）

   # 进入 azer-image-search-mcp-server 目录
   cd azer-image-search-mcp-server
   mvn clean package -DskipTests
   # 或根据子模块实际命令进行构建
   

2. 启动后端 Spring Boot

   # 回到后端根目录（含 AzerAllApplication）
   mvn clean package -DskipTests
   java -jar target/*.jar
   # 或直接在 IDE 中运行 com.azer.azerall.AzerAllApplication
   

3. 启动前端

   # 进入前端目录
   npm i
   npm run dev
   # 默认访问地址（示例）：http://localhost:5173
   

顺序要点：先构建/启动 azer-image-search-mcp-server → 再启动 Spring Boot → 最后启动前端。

🧪 API 与调试

• Knife4j 文档：浏览器打开 http://localhost:8080/doc.html
• RAG 示例：POST /api/qa，请求体包含 question/topK
• Agent 规划：POST /api/agent/plan，请求体包含 goal（会触发工具编排）

🔁 RAG 流程（Workflow）

1. 文档入库：解析（PDF/HTML/Markdown/文本）→ 分块 → 生成向量（Embedding）
2. 向量写入：批量写入 PGvector（cosine/L2 相似度）
3. 查询召回：根据问题向量检索相似片段
4. 重排融合：可选 BM25/语义重排，多源证据融合
5. 上下文构造：拼接检索片段与系统 Prompt
6. 结果生成：返回答案，可附引用片段与位置（可选）

🧠 Agent & Tool 设计要点

• ReAct 策略：先“思考”再“行动”，结合观察结果迭代计划
• 工具规范：以 JSON Schema 约束入参，输出结构化结果
• 鲁棒性：超时/重试/回退与边界检查
• 审计与观测：记录每次计划-行动-观测，便于复盘与排障

🌈 项目亮点

• ✅ RAG + Agent + Tool + MCP 一体化落地
• ✅ 支持 百炼 / Ollama / 本地模型 多后端
• ✅ PGvector + Kryo 兼顾检索性能与服务吞吐
• ✅ 前后端分离，Knife4j 开箱即用

💬 联系方式

• 作者：Azer

备注：本仓库目前为“非开源/内部使用”，如需对外发布将另行提供开源协议与说明。