# Easy-RAG

**Repository Path**: dxycc/easy-rag

## Basic Information

- **Project Name**: Easy-RAG
- **Description**: Easy-RAG 是一个基于 DDD、LangChain4j 与 JuiceFS 构建的轻量级 RAG 知识库系统，利用 JuiceFS 文件通知机制实时同步文档变更并自动更新向量索引，支持多种文档格式解析与低延迟检索增强生成，内置 RAG 评估体系，可对检索与生成效果进行多维度自动评分，帮助持续优化知识库质量。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 5
- **Forks**: 1
- **Created**: 2026-07-02
- **Last Updated**: 2026-07-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Easy-RAG

> 基于 LangChain4j + JuiceFS + DDD 架构的轻量级 RAG 知识库系统

## 介绍

Easy-RAG 是一个轻量级的检索增强生成（RAG）知识库系统，采用 DDD 分层架构，专为企业文档问答场景设计。支持文档内容预览与分块管理，内置 RAG 评估体系，支持对检索质量进行多维度自动评分。

**核心特性：**
- **实时同步**：JuiceFS Webhook 推送 → RabbitMQ → 自动向量索引，毫秒级感知文档变更
- **文档预览**：从 S3 实时提取文本内容，支持分页预览、分块查看、原文下载
- **DDD 架构**：9 个模块清晰分层，types / domain / infrastructure / application / trigger / ai / admin / app，拆分为两个独立服务（app: 8080 MVC + ai: 8081 WebFlux）
- **多格式支持**：Tika 解析 PDF、Word、Markdown、TXT 等 20+ 格式
- **向量检索**：DashScope embedding + Redis Stack 向量搜索，毫秒级响应
- **管理后台**：菜单/文档管理 API，对接前端 Vue3 管理界面
- **RAG 评估**：LLM-as-Judge 多维度自动评分（忠实度/相关性/精确度/召回率/综合分），雷达图+柱状图可视化

## 系统架构

```
                         ┌─────────────────────────────────────────────┐
                         │              用户 / 前端界面                 │
                         └──────────────────┬──────────────────────────┘
                                            │
                    ┌───────────────────────▼───────────────────────┐
                    │       easy-rag-app (主入口, 端口 8080)         │
                    │       AiProxyFilter / AiProxyFilter           │
                    └──────┬────────────┬────────────┬──────────────┘
                           │            │            │
              ┌────────────▼──┐   ┌─────▼──────┐   ┌▼──────────────────┐
              │ easy-rag-     │   │ easy-rag-  │   │  easy-rag-        │
              │ trigger       │   │ admin      │   │  ai               │
              │               │   │            │   │  (WebFlux, 8081)  │
              │ WebhookCtrl   │   │ MenuCtrl   │   │                   │
              │ KnowledgeBase │   │            │   │ ChatController    │
              │ HealthCtrl    │   │            │   │ (SSE 流式)        │
              └───────┬───────┘   └────────────┘   └─────────┬─────────┘
                      │                                       │
                      ▼                                       ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                        easy-rag-application (核心流程)                   │
│                                                                         │
│   FileEventHandler                    DocumentAppService                │
│   ┌─────────────────────────┐        ┌─────────────────────────┐       │
│   │ 1. 接收文件事件          │        │ 文档元数据管理            │       │
│   │ 2. S3读取 → Tika解析    │───────▶│ upsert / markIndexed    │       │
│   │ 3. 分块 → 嵌入 → 存储   │        │ markFailed / delete     │       │
│   └─────────────────────────┘        └─────────────────────────┘       │
└────────────────────────────────────┬────────────────────────────────────┘
                                     │
        ┌────────────────────────────┼────────────────────────────┐
        │                            │                            │
        ▼                            ▼                            ▼
┌────────────────┐       ┌────────────────────┐       ┌────────────────┐
│  easy-rag-     │       │   easy-rag-        │       │  easy-rag-     │
│  infrastructure│       │   domain           │       │  types         │
│                │       │                    │       │                │
│  S3FileText    │       │  RagEvaluator      │       │  PO / DTO / VO │
│  Extractor     │       │  (端口接口)         │       │  枚举 / Result  │
│  LlmRagEvaluator       │                    │       │                │
│  RabbitMQ      │       └────────────────────┘       └────────────────┘
│  EventPublisher│
│  DocumentMapper│
└───────┬────────┘
        │
        ▼
┌────────────────────────────────────────────────────────────────────────┐
│                            基础设施层                                    │
│                                                                        │
│   ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐│
│   │  Redis   │  │  MySQL   │  │  MinIO   │  │ RabbitMQ │  │JuiceFS ││
│   │ 向量存储  │  │ 元数据    │  │ S3存储   │  │ 消息队列  │  │文件系统 ││
│   │ :6380    │  │ :3307    │  │ :9000    │  │ :5672    │  │ :9100  ││
│   └──────────┘  └──────────┘  └──────────┘  └──────────┘  └────────┘│
└────────────────────────────────────────────────────────────────────────┘
```

**模块职责：**
- **easy-rag-app**：主入口（端口 8080），接收所有外部请求，通过 AiProxyFilter 代理 `/api/ai/**` 到 ai 模块
- **easy-rag-ai**：独立 WebFlux 服务（端口 8081），专注 SSE 流式聊天，被 app 模块代理调用
- **easy-rag-trigger**：REST 控制器层，处理 Webhook、评估、健康检查等外部接口
- **easy-rag-admin**：管理后台 API（菜单管理等）

## 核心流程

### 文档索引流程（写入链路）

```
JuiceFS 文件变更
    │
    ▼
Webhook POST ──▶ JuiceFSWebhookController (trigger)
    │
    ▼
RabbitMQEventPublisher (infrastructure) ──▶ 发送消息到 RabbitMQ
    │
    ▼
FileEventHandler (application) 消费消息
    │
    ├──▶ S3FileTextExtractor (infrastructure) ──▶ S3 API 读取文件
    │       │
    │       ▼
    │    Tika 解析文本
    │
    ├──▶ DocumentSplitters.recursive(300, 50) ──▶ 文本分块
    │
    ├──▶ DashScope Embedding (text-embedding-v3) ──▶ 向量嵌入
    │
    ├──▶ Redis Stack ──▶ 存储向量 + 元数据
    │
    └──▶ DocumentAppService ──▶ MySQL 更新文档状态
```

### RAG 对话流程（查询链路）

```
用户提问
    │
    ▼
easy-rag-app (端口 8080)
    │
    ├──▶ AiProxyFilter 代理 /api/ai/chat/** ──▶ easy-rag-ai (端口 8081)
    │       │
    │       ▼
    │    ChatController → 问题文本 → DashScope Embedding → 问题向量
    │       │
    │       ▼
    │    Redis 向量相似度搜索 → Top-K 相关文档片段
    │       │
    │       ▼
    │    拼接上下文 → DeepSeek V4 Flash → 生成回答
    │       │
    │       ▼
    │    返回 JSON / SSE 流式响应
    │
    └──▶ 直接返回前端
```

## RAG 评估系统

### 概述

基于 LLM-as-Judge 模式的 RAG 评估系统，通过大语言模型对检索增强生成结果进行多维度自动评分。

### 评估维度

| 指标 | 说明 |
|------|------|
| Faithfulness（忠实度） | 回答是否基于检索上下文，无幻觉 |
| Answer Relevancy（相关性） | 回答是否切题，直接回答用户问题 |
| Context Precision（精确度） | 检索内容中与问题相关的比例 |
| Context Recall（召回率） | 回答所需信息是否被检索到 |
| Overall Score（综合评分） | 以上指标的加权平均 |

### 评估流程

```
用户输入评估用例（问题 + 期望答案）
    │
    ▼
KnowledgeBaseController (trigger, MVC)
    │
    ├──▶ ContentRetriever 检索上下文
    ├──▶ ChatModel 生成回答
    └──▶ RagEvaluator (LLM-as-Judge) 评分
    │
    ▼
保存结果到 MySQL → 返回评估报告（雷达图 + 柱状图 + 明细）
```

### DDD 分层设计

```
Domain:    RagEvaluator 接口（端口契约）
    │
Infra:     LlmRagEvaluator 实现（适配器，依赖 ChatModel）
    │
Trigger:   KnowledgeBaseController（进程内直接注入，无 HTTP 转发）
```

### 评估页面

![评估页面](docs/img/eval-page.png)

### 评估详情

![评估详情](docs/img/eval-detail.png)

## 文档管理

### 文档列表

支持分页查询、按文件名/状态筛选，统计卡片实时展示文档状态分布。

### 文档预览

点击「详情」打开抽屉，支持三个 Tab 页：

- **基本信息**：文件名、路径、类型、大小、分块数、状态、错误信息、时间等
- **内容预览**：从 S3 实时提取文本内容，支持分页浏览
- **分块列表**：查看文本分块结果，每块标注序号和字符数

![文档预览](docs/img/doc-preview.png)

**支持的文件格式：**
PDF、Word（doc/docx）、Excel（xls/xlsx）、PowerPoint（ppt/pptx）、TXT、Markdown（md）、CSV、JSON、XML、HTML、RTF、ODT、ODS、ODP

## DDD 模块说明

| 模块 | 包名 | 职责 | 关键类 |
|------|------|------|--------|
| **easy-rag-types** | `types` | 基础类型 | `DocumentPo`, `FileEventMessage`, `Result`, 枚举 |
| **easy-rag-domain** | `domain` | 领域层 | RagEvaluator（端口接口）、EvaluationResult |
| **easy-rag-infrastructure** | `infrastructure` | 基础设施适配 | `S3FileTextExtractor`, `RabbitMQEventPublisher`, `DocumentMapper`, `LlmRagEvaluator`, `ContentRetrieverConfig` |
| **easy-rag-application** | `application` | 核心业务编排 | `FileEventHandler`, `DocumentAppService`, `DLQHandler` |
| **easy-rag-trigger** | `trigger` | 入口触发层 | `JuiceFSWebhookController`, `KnowledgeBaseController`, `HealthController` |
| **easy-rag-ai** | `ai` | AI 对话入口 | `ChatController`（SSE 流式聊天）、`KnowledgeBaseController`（RAG 评估端点） |
| **easy-rag-admin** | `admin` | 管理后台 | `MenuController`（菜单 API） |
| **easy-rag-app** | `easyrag` | 启动配置 | `EasyRagApplication`, `application.yml`, Flyway |

## 核心组件

| 组件 | 版本 | 用途 | 端口 |
|------|------|------|------|
| **Spring Boot** | 3.5.16 | 应用框架 | 8080 |
| **LangChain4j** | 1.17.0 | RAG 引擎 | - |
| **MyBatis-Plus** | 3.5.5 | ORM 持久层 | - |
| **Redis Stack** | latest | 向量数据库 | 6380 |
| **MySQL** | 8.0 | 元数据存储 | 3307 |
| **MinIO** | latest | S3 对象存储 | 9000, 9001 |
| **RabbitMQ** | 3-management | 消息队列 | 5672, 15672 |
| **JuiceFS** | CE 1.2.0 | 分布式文件系统 | 9100 (S3), 9101 (控制台) |

## 快速开始

### 环境要求

- Docker & Docker Compose
- Java 17+
- Maven 3.8+

### 1. 启动基础设施

```bash
docker-compose up -d
```

### 2. 配置 API Key

**获取步骤：**

**① DeepSeek API Key**

1. 注册/登录：https://platform.deepseek.com/sign_up
2. 进入 API Keys 页面：https://platform.deepseek.com/api_keys
3. 点击「创建 API Key」，复制保存
4. 新用户注册通常赠送免费额度

**② 阿里云百炼 DashScope API Key**

1. 注册/登录阿里云：https://dashscope.console.aliyun.com/
2. 进入 API Key 管理：https://dashscope.console.aliyun.com/apiKey
3. 点击「创建」，复制保存
4. 新用户同样有免费额度

**配置环境变量：**

```bash
# Windows PowerShell
$env:DEEPSEEK_API_KEY="your-deepseek-api-key"
$env:API-KEY="your-dashscope-api-key"

# Linux/Mac
export DEEPSEEK_API_KEY=your-deepseek-api-key
export API-KEY=your-dashscope-api-key
```
### 3. 构建运行

```bash
mvn clean package -DskipTests
java -jar easy-rag-app/target/easy-rag-app-0.0.1-SNAPSHOT.jar
```

应用启动后访问：http://localhost:8080

## 存储与日志

### S3 存储（JuiceFS）

![S3存储](docs/img/s3-storage.png)

### 应用日志

![应用日志](docs/img/app-logs.png)

## 服务控制台

| 服务 | 地址 | 用户名 | 密码 |
|------|------|--------|------|
| **应用** | http://localhost:8080 | - | - |
| **MinIO 控制台** | http://localhost:9001 | root | 12345678 |
| **RabbitMQ 管理** | http://localhost:15672 | root | 12345678 |
| **JuiceFS Gateway** | http://localhost:9101 | root | 12345678 |
| **MySQL** | localhost:3307 | root | 12345678 |
| **Redis** | localhost:6380 | - | 12345678 |

## 配置说明

### AI 模型配置

| 配置项 | 说明 |
|--------|------|
| `DEEPSEEK_API_KEY` | DeepSeek API 密钥（对话模型） |
| `API-KEY` | 阿里云百炼 DashScope API 密钥（嵌入模型） |

### 存储配置

| 服务 | 配置文件位置 |
|------|-------------|
| Redis Stack | `docker-compose.yml` / `.env` |
| MinIO | `docker-compose.yml` / `.env` |
| JuiceFS | `docker-compose.yml` |
| RabbitMQ | `docker-compose.yml` / `.env` |

## 常用命令

```bash
# 启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看服务日志
docker-compose logs -f [service-name]

# 停止所有服务
docker-compose down

# 停止并删除数据（谨慎）
docker-compose down -v

# 重启特定服务
docker-compose restart juicefs
```

## 文档

- [部署文档](DEPLOY.md) - 详细的部署指南
- [JuiceFS 文档](https://juicefs.com/docs/zh/community/introduction/)
- [LangChain4j 文档](https://docs.langchain4j.dev/)
- [MinIO 文档](https://min.io/docs/minio/linux/index.html)

## 参与贡献

1. Fork 本仓库
2. 新建 Feat_xxx 分支
3. 提交代码
4. 新建 Pull Request

## 许可证

本项目基于 [Apache License 2.0](LICENSE) 开源。

---

**让知识管理更智能、更敏捷！**