# SpringRAG

**Repository Path**: jeanngo/SpringRAG

## Basic Information

- **Project Name**: SpringRAG
- **Description**: AI 个人助手（RAG 知识库 + 分层记忆）
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-12
- **Last Updated**: 2026-06-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: SpringAI, RAG

## README

# SpringRAG

[![Spring Boot](https://img.shields.io/badge/Spring_Boot-3.5-6DB33F?logo=spring)](https://spring.io/projects/spring-boot)
[![Spring AI](https://img.shields.io/badge/Spring_AI-1.0.0-6DB33F)](https://spring.io/projects/spring-ai)
[![Java](https://img.shields.io/badge/Java-21-ED8B00?logo=openjdk)](https://www.oracle.com/java/)
[![Qdrant](https://img.shields.io/badge/Vector_DB-Qdrant-000000?logo=qdrant)](https://qdrant.tech)

**智能知识库问答系统** — 基于 Spring AI 构建，集成大语言模型、向量数据库和 RAG（检索增强生成）全链路，实现文档驱动的精准问答。

---

## 项目背景

大语言模型的知识截止日期和幻觉问题是企业级应用的普遍痛点。SpringRAG 通过 RAG 架构，让 AI 在回答问题时实时检索私有知识库，将回答建立在可控的文档依据之上，而非依赖模型内置知识。

---

## 核心架构

```
用户问题 → 查询重写(LLM) → 向量召回(Qdrant) → MMR 去重 → 拼 Prompt → LLM 回答
                                              ↑
                                       文件上传 → 分块 → 向量化
```

### 关键设计

| 层级 | 技术选型 | 职责 |
|------|---------|------|
| **LLM** | DeepSeek | 对话生成、查询重写、知识分类 |
| **向量存储** | Qdrant | 文档向量化存储与语义检索 |
| **持久化** | H2 Database + Redis | 短期记忆 Redis（TTL 自动过期），长期记忆 H2 |
| **消息队列** | RabbitMQ | 异步文件解析、审计日志落库、LLM 并发削峰 |
| **Embedding** | nomic-embed-text (Ollama) | 文本向量化 |

### RAG 优化链

1. **文本清洗 + 递归分块** — 按 Markdown/HTML 层级边界分割，优先保语义完整性
2. **LLM 查询重写** — 将用户问题转写为 1-3 个搜索 query，多角度提升召回
3. **MMR 去重** — 平衡相关性与多样性，避免重复内容
4. **自动元数据分类** — 上传时 AI 自动识别文档类别、打标签、生成摘要

---

## 快速开始

### 前置条件

- JDK 21+、Docker、DeepSeek API Key

```bash
# 启动 Qdrant 向量数据库
docker run -d --name qdrant -p 6333:6333 -p 6334:6334 qdrant/qdrant

# 启动 Ollama 并拉取 embedding 模型
docker run -d --name ollama ollama/ollama
docker exec ollama ollama pull nomic-embed-text

# 启动 Redis（短期记忆持久化）
docker run -d --name redis -p 6379:6379 -v D:\docker-data\redis:/data redis --appendonly yes

# 启动 RabbitMQ（异步任务处理）
docker run -d --name rabbitmq -p 5672:5672 -p 15672:15672 -v D:\docker-data\rabbitmq\data:/var/lib/rabbitmq -v D:\docker-data\rabbitmq\log:/var/log/rabbitmq rabbitmq:management
```

> 所有容器数据统一挂载至 `D:\docker-data\` 下，方便统一管理。
> RabbitMQ 管理界面访问：http://localhost:15672（默认账号密码：guest/guest）

### 配置与运行

```bash
# 配置环境变量
set DEEPSEEK_API_KEY=sk-your-key

# 启动
mvn spring-boot:run
```

---

## API 接口

### 聊天

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/ai/generate?message=xxx` | 对话（带持久化记忆） |
| GET | `/ai/generateStream?message=xxx` | 流式对话 |

### 知识库

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/knowledge/upload` | 上传知识文档（.txt/.md 等） |
| GET | `/api/knowledge/search?q=xxx&topK=3` | 语义搜索知识库 |

---

## 项目结构

```
src/main/java/com/springrag/
├── agent/              # 多 Agent + IntentRouter（规则 70% + LLM 30% 统一路由）
├── common/             # 通用枚举（模型、角色等）
├── config/             # ChatClient + Redis + H2 记忆持久化 + Session 管理
├── controller/         # REST 接口层
├── service/            # 业务逻辑（聊天、知识库、Function Calling）
└── vectorstore/        # RAG 搜索链路（重写器、分块器、重排器、分类器）
```

---

## 技术亮点

### 1. 分层记忆设计

借鉴认知科学的分层思路：短期记忆（当前对话上下文） + 实体记忆（用户关键信息持久化到 H2）。每次只加载相关记忆，避免无关历史干扰 LLM 判断。

### 2. 双模型架构

主力模型 DeepSeek（远程 API）用于生产，Ollama 本地模型用于链路验证和冒烟测试。兼顾性能与开发效率。

### 3. 分层 RAG 优化

从基础向量搜索逐层叠加：文本清洗 → 递归分块 → LLM 查询重写 → MMR 去重 → 自动元数据分类，每层解决一个具体痛点，不一步到位过度设计。

### 4. Redis 短期记忆层

对话记忆从项目内存迁移至 Redis，利用 Redis 的 TTL 机制实现短期记忆自动过期，`appendonly` 持久化保证重启不丢。`MessageCodec` 确保序列化/反序列化正确还原为 Spring AI 原生 Message 类型，避免下游强转异常。

### 5. RabbitMQ 异步处理层

引入 RabbitMQ 将耗时操作异步化：文件上传后先落盘再发 MQ，消费者异步完成清洗→分块→向量化存储；审计日志异步落库不阻塞接口响应。通过 `prefetch=1 + max-concurrency=3` 控制 LLM API 并发，天然削峰。

**异步上传流程：**
```
Controller（文件落盘 → 发 MQ）→ 立即返回 → 消费者异步（读取 → 清洗 → 分块 → 存 Qdrant）
```

**全链路会话追溯：**
```
TenantFilter → TenantContext（ThreadLocal）→ Controller → MQ 消息（携带 sessionId）→ 消费者
```

---

## 功能状态

- ✅ 双模型对话（DeepSeek + Ollama），会话隔离
- ✅ H2 持久化记忆，重启不丢失
- ✅ 文件上传 → 清洗分块 → 向量化存储
- ✅ 语义搜索 + RAG 问答链路
- ✅ LLM 查询重写 + MMR 去重
- ✅ 自动元数据识别（分类、标签、摘要）
- ✅ 多 Agent 路由（闲聊 / 知识问答 / 工具调用）
- ✅ 统一意图路由（规则引擎 70% + LLM 兜底 30%）
- ✅ Redis 短期记忆持久化（重启不丢、多会话隔离）
- ✅ MessageCodec 序列化修复（Spring AI 原生 Message 类型支持）
- ✅ 统一 sessionId 管理（TenantFilter + TenantContext 全链路追溯）
- ✅ RabbitMQ 异步处理（文档解析、审计日志落库、削峰）
- ✅ 文件异步上传流程（落盘 → MQ → 消费者 → 向量化）
- 🏗 PDF/Word 解析（规划中）
- 🏗 流式输出集成知识库问答

---

## 技术栈

| 技术 | 用途 |
|------|------|
| Spring Boot 3.5 + Spring AI 1.0.0 | 应用框架 |
| Java 21 + Maven | 开发语言与构建 |
| DeepSeek API | 主力大语言模型 |
| Qdrant | 向量数据库 |
| H2 Database + Redis | 对话记忆持久化（短期 → Redis，长期 → H2） |
| RabbitMQ | 异步任务处理（文件解析、审计日志、并发削峰） |
| Ollama + nomic-embed-text | 本地 Embedding |