# Neat-RAG

**Repository Path**: JackMacros/Neat-RAG

## Basic Information

- **Project Name**: Neat-RAG
- **Description**: Neat-RAG 是一个功能强大的 RAG（Retrieval Augmented Generation）平台，结合了知识库管理与 AI 对话能力。支持多种文档格式解析、向量化存储、语义搜索，以及与多个 AI 模型提供商的集成。
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 4
- **Created**: 2026-01-29
- **Last Updated**: 2026-02-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Neat-RAG

<div align="center">

<img src="./platform-web/src/assets/neat-rag-logo.png" alt="Neat-RAG Logo" width="200"/>

<br/>
<br/>

一个现代化的检索增强生成（RAG）知识库管理与对话平台

![Java](https://img.shields.io/badge/Java-21-brightgreen.svg)
![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.5.5-blue.svg)
![Vue](https://img.shields.io/badge/Vue-3.4-green.svg)
![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)
![License](https://img.shields.io/badge/license-MIT-blue.svg)

[功能特性](#-功能特性) • [技术栈](#-技术栈) • [快速开始](#-快速开始) • [系统架构](#-系统架构) • [项目结构](#-项目结构) • [配置说明](#-配置说明)

</div>

---

## 预览图片
![首页](platform-web/src/assets/home.png)
![多模型配置](platform-web/src/assets/model.png)
![输入图片说明](platform-web/src/assets/mcp.png)
![知识库页面](platform-web/src/assets/know.png)
![聊天](platform-web/src/assets/chat.png)
![向量检索](platform-web/src/assets/search.png)

---

## 简介

Neat-RAG 是一个功能强大的 RAG（Retrieval Augmented Generation）平台，结合了知识库管理与 AI 对话能力。支持多种文档格式解析、向量化存储、语义搜索，以及与多个 AI 模型提供商的集成。

### 核心能力

- 知识库创建与管理
- 文档上传、解析与向量化（支持 PDF、Word、Excel、HTML 等）
- 基于 Milvus 的语义搜索
- AI 智能对话（自由对话 + 知识库上下文对话）
- 多 AI 模型提供商支持（OpenAI、Azure、阿里云、智谱、Anthropic、DeepSeek、Ollama）
- MCP（Model Context Protocol）服务器集成
- 团队协作与权限管理

---

## ✨ 功能特性

### 知识库管理
- 创建、编辑、删除知识库
- 为知识库配置 AI 模型
- 向量集合自动管理
- 团队级别的资源隔离

### 文档处理
- 支持多种文档格式：PDF、Word（.doc/.docx）、Excel（.xls/.xlsx）、HTML、TXT
- 自动文档解析与分块（Chunking）
- 文档解析状态追踪（待解析、解析中、已完成、失败）
- 文档向量化与存储

### 智能对话
- 创建多个 AI 助手
- 支持两种对话模式：
  - 自由对话：通用 AI 问答
  - 知识库对话：基于知识库内容的上下文对话
- 实时流式响应（Server-Sent Events）
- 对话历史持久化

### 语义搜索
- 基于向量相似度的语义搜索
- 可配置 Top-K 结果数量
- 跨知识库搜索支持

### AI 模型集成
- 支持多个 AI 模型提供商：
  - OpenAI
  - Azure OpenAI
  - 阿里云百炼（DashScope）
  - 智谱 AI
  - Anthropic Claude
  - DeepSeek
  - Ollama（本地模型）
- 动态模型配置
- API Key 安全管理

### 用户与团队
- 用户注册与登录（基于邮箱）
- JWT Token 认证
- 多团队支持
- 团队资源隔离

### 文件管理
- MinIO 对象存储集成
- 文件上传、下载、删除
- 文件元数据管理

---

## 🛠 技术栈

### 后端技术

| 技术 | 版本     | 说明 |
|------|--------|------|
| Java | 21     | 编程语言 |
| Spring Boot | 3.5.5  | 应用框架 |
| MyBatis Plus | 3.5.9  | ORM 框架 |
| MySQL | 8.0+   | 关系型数据库 |
| Redis | 7.0      | 缓存与会话 |
| Milvus | 2.6.9      | 向量数据库 |
| MinIO | 8.5.7  | 对象存储 |
| Sa-Token | 1.40.0 | 权限认证 |
| Spring AI | 1.0.0  | AI 模型集成 |
| Hutool | 5.8.26 | Java 工具库 |
| Apache POI | 5.2.5  | Office 文档处理 |
| PDFBox | 2.0.30 | PDF 处理 |
| JSoup | 1.16.1 | HTML 解析 |
| Druid | 1.2.20 | 数据库连接池 |

### 前端技术

| 技术 | 版本 | 说明 |
|------|------|------|
| Vue | 3.4+ | 前端框架 |
| TypeScript | 5.3+ | 编程语言 |
| Vite | 5.0+ | 构建工具 |
| Pinia | 2.1+ | 状态管理 |
| Vue Router | 4.2+ | 路由管理 |
| Naive UI | 2.38+ | UI 组件库 |
| Axios | 1.6.5 | HTTP 客户端 |
| @vueuse/core | - | Vue 组合式工具库 |
| v-md-editor | 2.3.15 | Markdown 编辑器 |

---

## 🏗 系统架构

```
┌─────────────────────────────────────────────────────────────┐
│                         前端层 (Vue 3)                       │
│  知识库管理 │ 文档管理 │ 聊天对话 │ 语义搜索 │ 模型配置      │
└──────────────────────────┬──────────────────────────────────┘
                           │ RESTful API / SSE
┌──────────────────────────▼──────────────────────────────────┐
│                      后端服务层 (Spring Boot)                │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────────┐     │
│  │ 知识库服务  │  │  文档服务    │  │   聊天服务     │     │
│  └─────────────┘  └──────────────┘  └────────────────┘     │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────────┐     │
│  │ 向量存储服务│  │  文件服务    │  │   认证服务     │     │
│  └─────────────┘  └──────────────┘  └────────────────┘     │
└──────────────────────────┬──────────────────────────────────┘
                           │
         ┌─────────────────┼─────────────────┬────────────────┐
         │                 │                 │                │
┌────────▼────────┐ ┌──────▼──────┐ ┌────────▼────────┐ ┌────▼────┐
│  MySQL          │ │   Redis     │ │    Milvus       │ │  MinIO  │
│  (结构化数据)   │ │   (缓存)    │ │  (向量数据库)   │ │ (文件)  │
└─────────────────┘ └─────────────┘ └─────────────────┘ └─────────┘
                                             │
                                    ┌────────▼────────┐
                                    │   AI 模型服务   │
                                    │ OpenAI/Azure/等 │
                                    └─────────────────┘
```

### 数据流程

1. **文档上传流程**：用户上传 → MinIO 存储 → 文档解析 → 文本分块 → 向量化 → Milvus 存储
2. **对话流程**：用户提问 → 向量化 → Milvus 检索相似文档 → 构建上下文 → AI 生成回答 → SSE 流式返回
3. **搜索流程**：用户查询 → 向量化 → Milvus 相似度搜索 → 返回 Top-K 结果

---

## 🚀 快速开始

### 环境要求

- **JDK**: 21+
- **Node.js**: 18+
- **Maven**: 3.6+
- **MySQL**: 8.0+
- **Redis**: 6.0+
- **Milvus**: 2.0+
- **MinIO**: 最新版

### 1. 克隆项目

```bash
git clone <repository-url>
cd Neat-RAG
```

### 2. 数据库初始化

创建 MySQL 数据库：

```sql
CREATE DATABASE neat_rag CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

运行 SQL 脚本（如果提供）或启动项目自动创建表（需配置 MyBatis Plus）。

### 3. 配置后端

编辑 `src/main/resources/application-dev.yml`：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/neat_rag
    username: your_username
    password: your_password

  data:
    redis:
      host: localhost
      port: 6379

  ai:
    vectorstore:
      milvus:
        client:
          host: localhost
          port: 19530

# MinIO 配置
minio:
  endpoint: http://localhost:9000
  access-key: your_access_key
  secret-key: your_secret_key
  bucket-name: neat-rag

# AI 模型配置（按需配置）
spring.ai.openai.api-key: sk-xxxxx
```

### 4. 启动后端

```bash
mvn clean install
mvn spring-boot:run
```

后端服务运行在 `http://localhost:8080`

### 5. 启动前端

```bash
cd platform-web
npm install
npm run dev
```

前端服务运行在 `http://localhost:3000`

### 6. 访问应用

打开浏览器访问：`http://localhost:3000`

---

## 📁 项目结构

```
Neat-RAG/
├── src/main/java/com/zhulin/rag/
│   ├── controller/              # REST API 控制器
│   │   ├── ChatController.java
│   │   ├── KnowledgeBaseController.java
│   │   ├── DocumentController.java
│   │   └── ...
│   ├── service/                 # 业务逻辑接口
│   │   └── impl/                # 业务逻辑实现
│   ├── entity/                  # 数据库实体
│   ├── mapper/                  # MyBatis Mapper
│   ├── common/
│   │   ├── dto/                 # 数据传输对象
│   │   ├── vo/                  # 视图对象
│   │   ├── enums/               # 枚举类
│   │   └── util/                # 工具类
│   ├── config/                  # 配置类
│   ├── factory/                 # 工厂类（AI 客户端、向量存储等）
│   ├── exception/               # 异常处理
│   └── ZhulinRagApplication.java
├── src/main/resources/
│   ├── application.yml          # 主配置文件
│   ├── application-dev.yml      # 开发环境配置
│   ├── application-prod.yml     # 生产环境配置
│   └── mapper/                  # MyBatis XML 映射文件
├── platform-web/                # 前端项目
│   ├── src/
│   │   ├── api/                 # API 接口
│   │   ├── views/               # 页面组件
│   │   ├── layouts/             # 布局组件
│   │   ├── router/              # 路由配置
│   │   ├── stores/              # 状态管理
│   │   └── utils/               # 工具函数
│   ├── package.json
│   └── vite.config.ts
├── pom.xml                      # Maven 配置
└── README.md                    # 本文件
```

---

## ⚙️ 配置说明

### 数据库配置

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/neat_rag?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai
    username: root
    password: your_password
    driver-class-name: com.mysql.cj.jdbc.Driver
    type: com.alibaba.druid.pool.DruidDataSource
```

### Redis 配置

```yaml
spring:
  data:
    redis:
      host: localhost
      port: 6379
      password: # 如果有密码
      database: 0
```

### Milvus 配置

```yaml
spring:
  ai:
    vectorstore:
      milvus:
        client:
          host: localhost
          port: 19530
          database-name: default
```

### MinIO 配置

```yaml
minio:
  endpoint: http://localhost:9000
  access-key: minioadmin
  secret-key: minioadmin
  bucket-name: neat-rag
```
### Sa-Token 配置

```yaml
sa-token:
  token-name: Authorization
  timeout: 604800 # 7天，单位：秒
  active-timeout: -1
  is-concurrent: true
  is-share: false
  token-style: uuid
```

---

## 📖 API 文档

### 主要接口

#### 知识库管理

- `POST /api/knowledge-base/add` - 创建知识库
- `GET /api/knowledge-base/list` - 获取知识库列表
- `GET /api/knowledge-base/{id}` - 获取知识库详情
- `PUT /api/knowledge-base/update` - 更新知识库
- `DELETE /api/knowledge-base/delete/{id}` - 删除知识库

#### 文档管理

- `POST /api/document/upload` - 上传文档
- `GET /api/document/list` - 获取文档列表
- `DELETE /api/document/delete/{id}` - 删除文档
- `GET /api/document/chunks/{documentId}` - 获取文档分块

#### 聊天对话

- `POST /api/chat/session/create` - 创建聊天会话
- `GET /api/chat/session/list` - 获取会话列表
- `POST /api/chat/send` - 发送消息（SSE 流式响应）
- `GET /api/chat/messages/{sessionId}` - 获取会话消息历史

#### 语义搜索

- `POST /api/search/semantic` - 语义搜索

#### 用户认证

- `POST /api/auth/register` - 用户注册
- `POST /api/auth/login` - 用户登录
- `POST /api/auth/logout` - 用户登出

---

## 🚢 部署指南

### Docker 部署（推荐）

**待补充** - 将提供 Docker Compose 配置文件

### 手动部署

#### 1. 打包后端

```bash
mvn clean package -DskipTests
```

生成的 JAR 文件位于 `target/neat-rag-1.0.0.jar`

#### 2. 打包前端

```bash
cd platform-web
npm run build
```

生成的静态文件位于 `platform-web/dist`

#### 3. 部署

- 将后端 JAR 部署到服务器，使用 `java -jar` 启动
- 将前端静态文件部署到 Nginx 或其他 Web 服务器
- 配置 Nginx 反向代理到后端服务

示例 Nginx 配置：

```nginx
server {
    listen 80;
    server_name your-domain.com;

    # 前端静态文件
    location / {
        root /path/to/platform-web/dist;
        try_files $uri $uri/ /index.html;
    }

    # 后端 API 代理
    location /api {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

---

## 🧪 开发指南

### 代码规范

- **后端**：遵循阿里巴巴 Java 开发规范
- **前端**：使用 TypeScript 严格模式，Composition API，`<script setup>` 语法

### Git 提交规范

- `feat`: 新功能
- `fix`: 修复 Bug
- `docs`: 文档更新
- `style`: 代码格式调整
- `refactor`: 重构
- `test`: 测试
- `chore`: 构建/工具链

### 分支管理

- `main`: 主分支，生产环境代码
- `dev`: 开发分支
- `feature/*`: 功能分支
- `fix/*`: 修复分支

---

## 🤝 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'feat: Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 提交 Pull Request

请确保：
- 代码通过所有测试
- 遵循项目代码规范
- 提交信息清晰明确

---

## 📝 待完善功能

- [ ] Docker Compose 一键部署
- [ ] 更多文档格式支持（Markdown、PPT 等）
- [ ] 文档解析队列优化
- [ ] 更多向量数据库支持（Pinecone、Weaviate）
- [ ] 用户权限细粒度控制
- [ ] API 接口文档（Swagger/OpenAPI）
- [ ] 单元测试与集成测试
- [ ] 性能监控与日志分析
- [ ] 多语言支持

---

## 📄 开源协议

本项目采用 [MIT License](LICENSE) 开源协议。

---

## 📧 联系方式

- 提交 Issue: [GitHub Issues](https://gitee.com/JackMacros/Neat-RAG/issues)
- 邮件: 1544240523@qq.com

---

## 致谢

感谢以下开源项目：

- [Spring Boot](https://spring.io/projects/spring-boot)
- [Spring AI](https://spring.io/projects/spring-ai)
- [Vue.js](https://vuejs.org/)
- [Naive UI](https://www.naiveui.com/)
- [Milvus](https://milvus.io/)
- [MinIO](https://min.io/)

---

<div align="center">

**[⬆ 回到顶部](#neat-rag)**

Made with ❤️ by Neat-RAG Team

</div>