使用说明

AI 对话应用 - Spring AI 实现

一个基于 Spring AI 的智能对话应用，集成了 RAG（检索增强生成）、MCP（模型上下文协议）和 Agent 功能，使用 PostgreSQL 作为向量数据库。

📋 目录

项目概述
技术栈
功能特性
系统架构
快速开始
Ollama 配置
项目结构
开发指南
部署说明
API 文档
常见问题

🎯 项目概述

本项目是一个企业级 AI 对话应用，支持：

RAG（检索增强生成）：通过向量数据库检索相关文档，增强 AI 回答的准确性和相关性
MCP（模型上下文协议）：提供标准化的模型上下文管理
Agent 功能：支持多轮对话、工具调用和任务规划
向量数据库：使用 PostgreSQL + pgvector 存储和检索文档向量
现代化前端：美观的 Web 界面，提供流畅的对话体验

🛠 技术栈

后端

Java 21+
Spring Boot 3.x
Spring AI：AI 集成框架
PostgreSQL 15+：关系型数据库
pgvector：PostgreSQL 向量扩展
MyBatis：数据访问层
Spring WebFlux：响应式 Web 框架（可选）
Maven/Gradle：构建工具

前端

React 18+ 或 Vue 3+
TypeScript
Tailwind CSS：样式框架
Vite：构建工具
Axios：HTTP 客户端
React Query 或 Vue Query：数据获取

AI 模型

OpenAI GPT-4 / Claude / Ollama（本地模型）（通过 Spring AI 抽象层支持）

✨ 功能特性

1. RAG（检索增强生成）

文档上传和解析（支持 PDF、Word、TXT、Markdown 等）
文档分块和向量化
语义相似度搜索
上下文增强的 AI 回答

2. MCP（模型上下文协议）

统一的模型上下文管理
上下文持久化
上下文共享和复用

3. Agent 功能

多轮对话管理
工具调用（Tool Calling）
任务规划和执行
记忆管理

4. 用户界面

实时对话界面
文档管理界面
对话历史查看
响应式设计，支持移动端

🏗 系统架构

┌─────────────────────────────────────────────────────────┐
│                        前端层                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐              │
│  │ 对话界面  │  │ 文档管理  │  │ 历史记录  │              │
│  └──────────┘  └──────────┘  └──────────┘              │
└─────────────────────────────────────────────────────────┘
                            │
                            │ HTTP/REST API
                            ▼
┌─────────────────────────────────────────────────────────┐
│                      API 网关层                            │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐              │
│  │ 对话 API  │  │ 文档 API  │  │ 管理 API  │              │
│  └──────────┘  └──────────┘  └──────────┘              │
└─────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────┐
│                      业务逻辑层                             │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐              │
│  │ RAG 服务  │  │ Agent 服务 │  │ MCP 服务  │              │
│  └──────────┘  └──────────┘  └──────────┘              │
└─────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────┐
│                      数据访问层                             │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐              │
│  │ 向量检索  │  │ 文档存储  │  │ 对话历史  │              │
│  └──────────┘  └──────────┘  └──────────┘              │
└─────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────┐
│                      数据存储层                             │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐              │
│  │ PostgreSQL│  │ pgvector │  │ 文件存储  │              │
│  └──────────┘  └──────────┘  └──────────┘              │
└─────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────┐
│                      AI 模型层                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐              │
│  │ OpenAI   │  │ Claude   │  │ 本地模型  │              │
│  └──────────┘  └──────────┘  └──────────┘              │
└─────────────────────────────────────────────────────────┘

🚀 快速开始

前置要求

JDK 21 或更高版本
Maven 3.8+ 或 Gradle 7+
PostgreSQL 15+（已安装 pgvector 扩展）
Node.js 18+ 和 npm/yarn（前端开发）

1. 克隆项目

git clone <repository-url>
cd Ai-agent

2. 数据库设置

安装 pgvector 扩展

-- 连接到 PostgreSQL
CREATE EXTENSION IF NOT EXISTS vector;

-- 创建数据库
CREATE DATABASE ai_agent_db;

-- 连接到新数据库
\c ai_agent_db

-- 验证扩展
SELECT * FROM pg_extension WHERE extname = 'vector';

初始化数据库表

手动执行 src/main/resources/db/migration/ 下的 SQL 脚本创建表结构，或使用 Flyway/Liquibase 进行数据库版本管理。

3. 后端配置

创建配置文件

复制 src/main/resources/application.example.yml 为 application.yml：

spring:
  application:
    name: ai-agent
  datasource:
    url: jdbc:postgresql://localhost:5432/ai_agent_db
    username: your_username
    password: your_password
    driver-class-name: org.postgresql.Driver
  
  # MyBatis 配置
  mybatis:
    mapper-locations: classpath:mapper/*.xml
    type-aliases-package: com.aiagent.model
    configuration:
      map-underscore-to-camel-case: true
      log-impl: org.apache.ibatis.logging.stdout.StdOutImpl

spring.ai:
  # OpenAI 配置（可选）
  openai:
    api-key: ${OPENAI_API_KEY}
    chat:
      options:
        model: gpt-4
        temperature: 0.7
        max-tokens: 2000
  
  # Ollama 配置（本地模型，推荐）
  ollama:
    base-url: http://localhost:11434
    chat:
      options:
        model: llama2  # 或其他模型，如 mistral, codellama 等
        temperature: 0.7
        num-predict: 2000
  
  # Embedding 配置（如果使用 Ollama 的 embedding 模型）
  embedding:
    ollama:
      base-url: http://localhost:11434
      options:
        model: nomic-embed-text  # Ollama embedding 模型
  
  vectorstore:
    postgresql:
      index-type: HNSW
      distance-type: COSINE_DISTANCE
      dimensions: 768  # Ollama embedding 维度（nomic-embed-text 为 768，OpenAI 为 1536）

server:
  port: 8080

logging:
  level:
    org.springframework.ai: DEBUG
    com.yourpackage: DEBUG

设置环境变量

使用 OpenAI：

export OPENAI_API_KEY=your_openai_api_key

使用 Ollama（本地模型，无需 API Key）：

# 确保 Ollama 已安装并运行
# macOS 通过 Docker 安装后，Ollama 默认运行在 http://localhost:11434
# 验证 Ollama 是否运行：
curl http://localhost:11434/api/tags

# 下载模型（如未下载）：
# docker exec -it <ollama-container> ollama pull llama2
# 或直接在主机上：ollama pull llama2

4. 运行后端

# 使用 Maven
mvn spring-boot:run

# 或使用 Gradle
./gradlew bootRun

5. 前端设置

cd frontend
npm install
npm run dev

前端将在 http://localhost:3000 运行。

🤖 Ollama 配置

如果您已经在 macOS 上通过 Docker 安装了 Ollama，可以按照以下步骤配置：

快速配置

验证 Ollama 运行：

curl http://localhost:11434/api/tags

下载模型（如果未下载）：

# 如果 Ollama 在 Docker 容器中
docker exec -it <ollama-container> ollama pull llama2

# 推荐模型：
# ollama pull mistral        # Mistral 7B
# ollama pull qwen2.5        # 中文支持好

配置 application.yml：

spring.ai:
  ollama:
    base-url: http://localhost:11434
    chat:
      options:
        model: llama2
        temperature: 0.7

详细配置说明请参考：Ollama 配置指南

📁 项目结构

Ai-agent/
├── backend/
│   ├── src/
│   │   ├── main/
│   │   │   ├── java/
│   │   │   │   └── com/
│   │   │   │       └── aiagent/
│   │   │   │           ├── AiAgentApplication.java
│   │   │   │           ├── config/
│   │   │   │           │   ├── AiConfig.java          # AI 配置
│   │   │   │           │   ├── VectorStoreConfig.java # 向量存储配置
│   │   │   │           │   └── WebConfig.java          # Web 配置
│   │   │   │           ├── controller/
│   │   │   │           │   ├── ChatController.java    # 对话 API
│   │   │   │           │   ├── DocumentController.java # 文档 API
│   │   │   │           │   └── AgentController.java    # Agent API
│   │   │   │           ├── service/
│   │   │   │           │   ├── RAGService.java        # RAG 服务
│   │   │   │           │   ├── AgentService.java      # Agent 服务
│   │   │   │           │   ├── MCPService.java        # MCP 服务
│   │   │   │           │   └── DocumentService.java   # 文档服务
│   │   │   │           ├── mapper/                    # MyBatis Mapper 接口
│   │   │   │           │   ├── DocumentMapper.java
│   │   │   │           │   ├── ChatHistoryMapper.java
│   │   │   │           │   └── VectorMapper.java
│   │   │   │           ├── model/
│   │   │   │           │   ├── Document.java
│   │   │   │           │   ├── ChatMessage.java
│   │   │   │           │   └── VectorEmbedding.java
│   │   │   │           └── dto/
│   │   │   │               ├── ChatRequest.java
│   │   │   │               ├── ChatResponse.java
│   │   │   │               └── DocumentUploadRequest.java
│   │   │   └── resources/
│   │   │       ├── application.yml
│   │   │       ├── mapper/                # MyBatis XML 映射文件
│   │   │       │   ├── DocumentMapper.xml
│   │   │       │   ├── ChatHistoryMapper.xml
│   │   │       │   └── VectorMapper.xml
│   │   │       └── db/migration/
│   │   └── test/
│   └── pom.xml 或 build.gradle
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── Chat/
│   │   │   ├── Document/
│   │   │   └── History/
│   │   ├── pages/
│   │   ├── services/
│   │   ├── hooks/
│   │   └── utils/
│   ├── public/
│   ├── package.json
│   └── vite.config.ts
├── docs/
│   ├── architecture.md      # 架构设计文档
│   ├── api.md              # API 文档
│   └── deployment.md       # 部署文档
├── docker/
│   ├── Dockerfile
│   └── docker-compose.yml
└── README.md

📖 开发指南

后端开发

1. RAG 服务实现

RAG 服务的核心流程：

文档上传：接收用户上传的文档
文档解析：提取文本内容
文档分块：将长文档分割成小块
向量化：使用 Embedding 模型生成向量
存储：将向量存储到 PostgreSQL
检索：根据用户问题检索相关文档块
生成：将检索到的文档作为上下文，生成回答

2. Agent 服务实现

Agent 服务支持：

对话状态管理
工具调用（如搜索、计算等）
多步骤任务规划
记忆持久化

3. MCP 服务实现

MCP 服务提供：

上下文创建和管理
上下文更新和查询
上下文版本控制

前端开发

技术选型建议

React 版本：

React 18
TypeScript
Tailwind CSS
React Query
Zustand（状态管理）
React Router

Vue 版本：

Vue 3 + Composition API
TypeScript
Tailwind CSS
Vue Query
Pinia（状态管理）
Vue Router

UI 组件库推荐

shadcn/ui（React）
Radix Vue（Vue）
Headless UI

🚢 部署说明

Docker 部署

1. 构建镜像

docker build -t ai-agent-backend ./backend
docker build -t ai-agent-frontend ./frontend

2. 使用 Docker Compose

version: '3.8'
services:
  postgres:
    image: pgvector/pgvector:pg15
    environment:
      POSTGRES_DB: ai_agent_db
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  ollama:
    image: ollama/ollama:latest
    container_name: ai-agent-ollama
    ports:
      - "11434:11434"
    volumes:
      - ollama_data:/root/.ollama
    networks:
      - ai-agent-network
    restart: unless-stopped

  backend:
    build: ./backend
    ports:
      - "8080:8080"
    environment:
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/ai_agent_db
      # 使用 OpenAI（可选）
      OPENAI_API_KEY: ${OPENAI_API_KEY}
      # 使用 Ollama（推荐本地开发）
      SPRING_AI_OLLAMA_BASE_URL: http://ollama:11434
    depends_on:
      - postgres
      - ollama

  frontend:
    build: ./frontend
    ports:
      - "3000:3000"
    depends_on:
      - backend

volumes:
  postgres_data:
  ollama_data:

运行：

docker-compose up -d

生产环境部署

后端：使用 Spring Boot 打包为 JAR，部署到服务器或容器
前端：构建静态文件，部署到 Nginx 或 CDN
数据库：使用云数据库服务（如 AWS RDS、Azure Database）

📚 API 文档

对话 API

POST /api/chat

发送消息并获取 AI 回复

请求体：

{
  "message": "用户消息",
  "conversationId": "可选，对话ID",
  "useRAG": true,
  "useAgent": false
}

响应：

{
  "message": "AI 回复",
  "conversationId": "对话ID",
  "sources": ["相关文档引用"],
  "timestamp": "2024-01-01T00:00:00Z"
}

文档 API

POST /api/documents/upload

上传文档

请求： multipart/form-data

file: 文件
title: 文档标题（可选）