# Support Bot - AI智能客服系统

> 🤖 基于 Spring AI 和阿里云通义千问的智能客服机器人  
> 🧠 支持 RAG 知识库检索 · 多种对话模式 · 结构化数据提取 · 知识库管理  
> 🧱 技术栈：Java 17 · Spring Boot 3.4.4 · Spring AI Alibaba · PGVector

## 📌 项目简介

本项目是一个 AI 驱动的智能客服系统，结合大语言模型与企业知识库（RAG），支持多轮对话、上下文记忆持久化以及高质量的问题检索应答能力，广泛适用于网站客服、内部知识助手、文档问答等场景。


## 🚀 功能特性

- **💬 智能对话**: 基于阿里云通义千问模型的自然语言对话
- **🔍 RAG检索**: 文档检索增强生成，从知识库中精准检索相关信息
- **📺 多模式交互**: 支持同步、SSE流式、ServerSentEvent等多种API接口
- **🧠 记忆管理**: 完整的会话上下文记忆，支持数据库持久化存储
- **🏷️ 结构化提取**: 从自然语言中智能提取商品信息等结构化数据
- **⚡ 向量搜索**: 基于PGVector的高性能语义相似度搜索
- **🔧 查询优化**: 多种预检索优化策略提升问答质量
- **📖 API文档**: 集成Knife4j提供完整的交互式API文档
- **📚 知识库管理**: 完整的文档生命周期管理（上传、查看、删除、重新处理）、分类管理、语义搜索测试、统计面板

## 🛠 技术栈

| 技术分类 | 技术组件 | 版本 | 用途说明 |
|---------|---------|------|---------|
| **后端框架** | Spring Boot | 3.4.4 | 主框架，提供依赖注入和自动配置 |
| **AI框架** | Spring AI Alibaba | 1.0.0-M6.1 | AI集成框架，简化大模型调用 |
| **大语言模型** | 阿里云通义千问 | qwen-turbo | 对话生成和文本理解 |
| **Embedding模型** | 阿里云DashScope | text-embedding-v2 | 文本向量化（1536维） |
| **数据库** | PostgreSQL + PGVector | 12+ | 关系数据存储 + 向量存储 |
| **ORM框架** | MyBatis Plus | 3.5.12 | 数据库操作和对象映射 |
| **API文档** | Knife4j | 4.4.0 | Swagger UI增强版 |
| **工具库** | Hutool | 5.8.37 | 常用工具类集合 |
| **序列化** | Kryo | 5.6.2 | 高性能序列化框架 |
| **文档解析** | Apache Tika | 1.0.0 | 多格式文档内容提取 |

## 🗃️ 数据库设计

### 核心表结构

#### 1. 聊天消息表 (`chat_message`)
```sql
CREATE TABLE chat_message (
    id              BIGSERIAL    PRIMARY KEY,      -- 消息唯一ID
    conversation_id VARCHAR(64)  NOT NULL,         -- 会话标识符
    message_type    VARCHAR(20)  NOT NULL,         -- 消息类型: USER/ASSISTANT/SYSTEM
    content         TEXT         NOT NULL,         -- 消息内容
    metadata        JSONB        DEFAULT '{}',     -- 消息元数据(JSON格式)
    create_time     TIMESTAMP    DEFAULT NOW(),    -- 创建时间
    update_time     TIMESTAMP    DEFAULT NOW(),    -- 更新时间
    is_delete       BOOLEAN      DEFAULT FALSE     -- 逻辑删除标识
);
```
**功能**: 存储用户与AI助手的完整对话历史，支持多轮对话上下文维护

#### 2. 向量存储表 (`vector_store`)
```sql
CREATE TABLE vector_store (
    id          UUID         DEFAULT uuid_generate_v4() PRIMARY KEY, -- 向量记录ID
    content     TEXT         NOT NULL,                              -- 原始文档内容
    metadata    JSONB        DEFAULT '{}',                          -- 文档元数据
    embedding   VECTOR(1536) NOT NULL,                              -- 1536维向量嵌入
    create_time TIMESTAMP    DEFAULT NOW(),                         -- 创建时间
    update_time TIMESTAMP    DEFAULT NOW()                          -- 更新时间
);
```
**功能**: 存储知识库文档的向量表示，支持语义相似度搜索和RAG检索

#### 3. 知识库分类表 (`knowledge_category`)
```sql
CREATE TABLE knowledge_category (
    id              BIGSERIAL       PRIMARY KEY,
    name            VARCHAR(100)    NOT NULL,          -- 分类名称
    description     TEXT,                              -- 分类描述
    parent_id       BIGINT          DEFAULT 0,         -- 父分类ID（0为顶级）
    sort_order      INTEGER         DEFAULT 0,         -- 排序权重
    document_count  INTEGER         DEFAULT 0,         -- 关联文档数量
    create_time     TIMESTAMP       DEFAULT NOW(),
    is_delete       BOOLEAN         DEFAULT FALSE
);
```
**功能**: 支持树形结构的知识库分类体系

#### 4. 知识文档表 (`knowledge_document`)
```sql
CREATE TABLE knowledge_document (
    id              BIGSERIAL       PRIMARY KEY,
    title           VARCHAR(500)    NOT NULL,          -- 文档标题
    source_name     VARCHAR(500),                      -- 原始文件名
    file_type       VARCHAR(20)     NOT NULL,          -- 文件类型
    file_size       BIGINT          DEFAULT 0,         -- 文件大小(字节)
    content         TEXT,                              -- 原文内容(截断预览)
    category_id     BIGINT          DEFAULT 0,         -- 所属分类ID
    tags            JSONB           DEFAULT '{}',      -- 标签(JSON对象)
    chunk_count     INTEGER         DEFAULT 0,         -- 分块数量
    status          VARCHAR(20)     DEFAULT 'PROCESSING', -- 处理状态
    error_message   TEXT,                              -- 失败时的错误信息
    create_time     TIMESTAMP       DEFAULT NOW(),
    update_time     TIMESTAMP       DEFAULT NOW(),
    is_delete       BOOLEAN         DEFAULT FALSE
);
```
**功能**: 记录上传文档的完整元信息，与向量表通过 metadata.documentId 关联

## 📡 API 接口

### AI 对话接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/ai/assistant_app/chat/sync` | 同步对话 |
| GET | `/ai/assistant_app/chat/sse` | SSE 流式对话 (Flux) |
| GET | `/ai/assistant_app/chat/server_sent_event` | SSE 流式对话 (ServerSentEvent) |
| GET | `/ai/assistant_app/chat/sse_emitter` | SSE 流式对话 (SseEmitter) |
| GET | `/ai/assistant_app/chat/rag/sync` | RAG 知识库对话（支持查询重写策略） |
| GET | `/ai/product_info_app/chat/sync` | 商品信息结构化提取 |

### 知识库管理接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/document/list` | 文档列表（分页 + 分类/状态过滤） |
| GET | `/document/{id}` | 文档详情 |
| GET | `/document/{id}/chunks` | 文档分块列表 |
| DELETE | `/document/{id}` | 删除文档（级联删除向量） |
| PUT | `/document/{id}` | 更新文档元信息 |
| PUT | `/document/{id}/reprocess` | 重新处理文档 |
| POST | `/document/search` | 语义搜索 |
| GET | `/document/stats` | 知识库统计面板 |
| POST | `/upload/file` | 上传文件（Tika多格式解析） |
| POST | `/upload/string` | 上传文本内容 |
| POST | `/upload/markdown` | 上传 Markdown 文件 |
| POST | `/upload/json/basic` | 上传 JSON（整体解析） |
| POST | `/upload/json/fields` | 上传 JSON（按字段提取） |
| POST | `/upload/json/pointer` | 上传 JSON（按指针拆分） |

### 分类管理接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/category/tree` | 获取分类树 |
| GET | `/category/list` | 获取分类列表 |
| POST | `/category` | 创建分类 |
| PUT | `/category/{id}` | 更新分类 |
| DELETE | `/category/{id}` | 删除分类 |

## 📁 项目架构

### 代码结构
```
src/main/java/com/wok/supportbot/
├── SupportBotApplication.java          # 主启动类
├── advisor/                            # AI对话增强器
│   ├── MyLoggerAdvisor.java           # 日志记录顾问
│   └── ReReadingAdvisor.java          # 重读机制顾问
├── app/                               # 核心应用服务
│   ├── AssistantApp.java              # 智能客服应用
│   └── ProductInfoApp.java            # 商品信息提取应用
├── chatmemory/                        # 聊天记忆管理
│   ├── DatabaseChatMemory.java        # 数据库记忆存储
│   └── FileBasedChatMemory.java       # 文件记忆存储
├── config/                            # 系统配置
│   ├── CorsConfig.java                # 跨域请求配置
│   ├── MybatisPlusConfig.java         # MyBatis Plus 配置
│   └── DatabaseInitConfig.java        # 数据库自动初始化
├── controller/                        # REST API控制器
│   ├── AiController.java              # AI对话接口
│   └── DocumentController.java        # 文档与分类管理接口
├── converter/                         # 类型转换器
│   └── MessageConverter.java          # 消息类型转换
├── dao/                               # 数据访问层
│   ├── ChatMessageMapper.java         # 聊天消息 Mapper
│   ├── KnowledgeDocumentMapper.java   # 知识文档 Mapper
│   └── KnowledgeCategoryMapper.java   # 知识分类 Mapper
├── document/                          # 文档处理管道
│   ├── extract/                       # 文档提取器
│   │   ├── TikaDocumentReader.java   # Tika 多格式解析
│   │   ├── MarkdownDocumentLoader.java # Markdown 解析
│   │   ├── JsonDocumentLoader.java    # JSON 解析（3种模式）
│   │   └── SimpleStringDocumentReader.java # 纯文本读取
│   └── transform/                     # 文档转换器
│       ├── MyTokenTextSplitter.java   # Token 分块器
│       └── MyKeywordEnricher.java     # AI 关键词提取
├── entity/                            # 数据实体类
│   ├── ChatMessage.java               # 聊天消息实体
│   ├── ProductInfo.java               # 商品信息实体
│   ├── KnowledgeDocument.java         # 知识文档实体
│   ├── KnowledgeCategory.java         # 知识分类实体
│   ├── CategoryNode.java              # 分类树节点 DTO
│   └── SearchResult.java              # 语义搜索结果 DTO
├── handler/                           # MyBatis 处理器
│   ├── MyMetaObjectHandler.java       # 自动填充处理器
│   └── PostgresJsonTypeHandler.java   # JSONB 类型处理器
├── rag/                               # RAG检索增强
│   ├── config/                        # RAG配置
│   ├── load/                          # 文档加载器
│   │   ├── PgVectorStoreConfig.java  # PGVector 存储配置
│   │   └── InMemoryVectorStoreConfig.java # 内存存储配置
│   └── preretrieval/                  # 预检索优化
│       ├── RewriteQueryRewriter.java      # 查询重写
│       ├── MultiQueryExpanderRewriter.java # 多查询扩展
│       ├── CompressionQueryRewriter.java   # 压缩查询
│       └── TranslationQueryRewriter.java   # 翻译查询
├── repository/                        # 数据仓库
│   └── ChatMessageRepository.java     # 聊天消息仓库
└── service/                           # 业务服务层
    └── DocumentService.java           # 知识库文档管理服务

src/main/resources/
├── application.yml                     # 应用配置文件
├── support-bot.sql                     # 数据库初始化脚本
├── knowledge-base.sql                  # 知识库增量迁移脚本
└── static/
    └── frontend.html                   # 前端管理页面
```

## 🧩 文档处理管道

```
上传文件/文本
    ↓
[文档提取器] Tika / Markdown / JSON / 纯文本
    ↓
[Token 分块] MyTokenTextSplitter (200 token / 100 overlap)
    ↓
[关键词提取] MyKeywordEnricher (AI 提取 Top-5 关键词)
    ↓
[向量化存储] DashScope text-embedding-v2 → PGVector
    ↓
[元数据关联] metadata.documentId / chunkIndex / sourceName / title
```

## 🖥️ 前端管理页面

访问 `http://localhost:9090/frontend.html`，包含三个标签页：

| 标签页 | 功能 |
|--------|------|
| 💬 智能客服对话 | 同步/流式对话、RAG 知识库检索（4种查询优化策略） |
| 🏷️ 商品信息提取 | AI 结构化提取商品信息 |
| 📄 知识库文档管理 | 文档上传（6种格式）、分类管理、文档列表、语义搜索测试、统计面板、文档详情查看 |

## ⚡ 快速开始

### 1. 环境准备

- JDK 17+
- PostgreSQL 12+（需安装 PGVector 扩展）
- Maven 3.6+
- 阿里云 DashScope API Key

### 2. 数据库初始化

```sql
-- 创建数据库
CREATE DATABASE support_bot;

-- 连接后执行初始化脚本
\c support_bot;
\i src/main/resources/support-bot.sql;
\i src/main/resources/knowledge-base.sql;
```

> 注：知识文档表和分类表会在应用启动时自动创建（`DatabaseInitConfig`），无需手动执行 `knowledge-base.sql`。

### 3. 配置

修改 `src/main/resources/application.yml`：

```yaml
spring:
  ai:
    dashscope:
      api-key: your-api-key-here    # 替换为你的 DashScope API Key
  datasource:
    url: jdbc:postgresql://localhost:5432/support_bot
    username: postgres
    password: your-password-here     # 替换为你的数据库密码
```

### 4. 启动

```bash
./mvnw spring-boot:run
```

### 5. 访问

- 前端管理页面：http://localhost:9090/frontend.html
- API 文档：http://localhost:9090/doc.html

## 📋 查询优化策略

| 策略 | 说明 | 适用场景 |
|------|------|---------|
| NONE | 不做查询优化 | 简单查询 |
| REWRITE | 查询重写 | 优化模糊/口语化提问 |
| TRANSLATION | 翻译扩展 | 跨语言检索场景 |
| COMPRESSION | 查询压缩 | 结合上下文压缩冗余信息 |
| MULTI_QUERY | 多路查询扩展 | 需要多角度检索的复杂问题 |