# 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-01

## 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 | 对话记忆持久化，重启不丢失 |
| **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
```

### 配置与运行

```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 路由（CHAT / KNOWLEDGE / TOOL）
├── common/             # 通用枚举（模型、角色等）
├── config/             # ChatClient 配置、H2 记忆持久化、Session 管理
├── controller/         # REST 接口层
├── service/            # 业务逻辑（聊天、知识库、Function Calling）
└── vectorstore/        # RAG 搜索链路（重写器、分块器、重排器、分类器）
```

---

## 技术亮点

### 1. 分层记忆设计

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

### 2. 双模型架构

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

### 3. 分层 RAG 优化

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

---

## 功能状态

- ✅ 双模型对话（DeepSeek + Ollama），会话隔离
- ✅ H2 持久化记忆，重启不丢失
- ✅ 文件上传 → 清洗分块 → 向量化存储
- ✅ 语义搜索 + RAG 问答链路
- ✅ LLM 查询重写 + MMR 去重
- ✅ 自动元数据识别（分类、标签、摘要）
- ✅ 多 Agent 路由（闲聊 / 知识问答 / 工具调用）
- 🏗 PDF/Word 解析（规划中）
- 🏗 流式输出集成知识库问答

---

## 技术栈

| 技术 | 用途 |
|------|------|
| Spring Boot 3.5 + Spring AI 1.0.0 | 应用框架 |
| Java 21 + Maven | 开发语言与构建 |
| DeepSeek API | 主力大语言模型 |
| Qdrant | 向量数据库 |
| H2 Database | 对话记忆持久化 |
| Ollama + nomic-embed-text | 本地 Embedding |