RAG4J 项目架构说明

作者：ZhiMy
版本：0.1.0-SNAPSHOT
环境：Java 21+ / Spring Boot 3.5 / Spring AI 1.0.3

📁 项目结构概览

rag4j/
├── rag4j-app/                    # 应用层 - Web服务入口
├── rag4j-framework/              # 框架层 - 核心抽象与通用能力
├── rag4j-project/                # 实现层 - 具体技术实现
└── test/                         # 测试模块

🏗️ 模块架构

1. rag4j-app（应用层）

应用服务入口，提供 REST API 接口，负责业务编排。

包名	功能说明
`cn.rag4j.agent`	Agent 智能体管理（基础信息、工作流）
`cn.rag4j.chunk`	文档切片管理
`cn.rag4j.document`	文档管理
`cn.rag4j.directory`	目录管理
`cn.rag4j.file`	文件上传与存储
`cn.rag4j.knowledgebase`	知识库管理
`cn.rag4j.model`	模型配置管理
`cn.rag4j.config`	应用配置（异步、MyBatis、上下文等）

2. rag4j-framework（框架层）

核心框架抽象，定义接口规范与通用能力。

rag4j-framework/
├── rag4j-framework-common/           # 通用工具与基础类
├── rag4j-framework-chunk/            # 文档切片抽象
├── rag4j-framework-document/         # 文档处理抽象
├── rag4j-framework-dag/              # DAG 工作流引擎
├── rag4j-framework-model-suppliers/  # 模型供应商抽象
├── rag4j-framework-vector-store/     # 向量存储抽象
├── rag4j-framework-recall/           # RAG 召回抽象
├── rag4j-framework-knowledgebase/    # 知识库抽象
├── rag4j-framework-file/             # 文件处理抽象
└── rag4j-framework-system/           # 系统级功能

2.1 rag4j-framework-common

通用基础模块，提供：

BaseEntity - 实体基类
ApiResponse - 统一响应封装
GlobalExceptionHandler - 全局异常处理
JacksonUtil - JSON 工具类
IdGenerator - ID 生成器
SpringContextHolder - Spring 上下文持有者
MyBatis TypeHandler - 自定义类型处理器

2.2 rag4j-framework-chunk

文档切片框架，核心接口：

/**
 * 文档切分接口
 */
public interface DocumentChunk<T extends BaseChunkConfig, C extends Chunk> {
    
    // 执行切片
    List<C> chunk(String text, T chunkConfig);
    
    // 获取切片类型
    String getType();
    
    // 保存切片
    List<Chunk> saveChunk(List<C> chunks);
}

ChunkRegistry - 切片策略注册中心
BaseChunkConfig - 切片配置基类

2.3 rag4j-framework-document

文档处理框架：

RagDocument - 文档实体
RagDocumentReader - 文档读取器
DocumentAnalysisRegistry - 文档解析注册中心
TikaUtils - Apache Tika 文档解析工具
TextClean - 文本清洗工具

2.4 rag4j-framework-dag(TODO)

DAG（有向无环图）工作流引擎，支持可视化编排：

dag/
├── engine/
│   ├── WorkflowEngine.java      # 工作流执行引擎
│   └── Router.java              # 节点路由器
├── executor/
│   ├── NodeExecutor.java        # 节点执行器接口
│   ├── StartNodeExecutor.java   # 开始节点
│   ├── EndNodeExecutor.java     # 结束节点
│   ├── LlmExecutor.java         # LLM 节点
│   ├── ConditionNodeExecutor.java # 条件分支节点
│   └── ExecutorFactory.java     # 执行器工厂
├── model/
│   ├── def/                     # 工作流定义（节点、边、条件）
│   ├── conf/                    # 节点配置
│   ├── run/                     # 运行时状态
│   └── entity/                  # 变量实体
└── store/
    └── RunStore.java            # 运行状态存储

工作流执行流程：

从 START 节点开始
按 DAG 拓扑顺序执行节点
支持条件分支路由
支持重试与超时控制
到达 END 节点结束

2.5 rag4j-framework-vector-store

classDiagram
direction BT
class BaseSearchResponse
class ElasticsearchBm25Search
class ElasticsearchVectorSearch
class ISearch~Q, R~
class PGVectorSearch

ElasticsearchBm25Search  -->  ISearch~Q, R~ 
ElasticsearchVectorSearch  -->  ISearch~Q, R~ 
ISearch~Q, R~  ..>  BaseSearchResponse 
PGVectorSearch  -->  ISearch~Q, R~

classDiagram
direction BT
class ElasticsearchVectorDocument
class ElasticsearchVectorStore
class IVectorStore~D~ {
<<Interface>>

}
class PGVectorDocument
class PGVectorStore {
<<Interface>>

}
class VDocument

ElasticsearchVectorDocument  -->  VDocument 
ElasticsearchVectorStore  ..>  IVectorStore~D~ 
IVectorStore~D~  ..>  VDocument 
PGVectorDocument  -->  VDocument 
PGVectorStore  -->  IVectorStore~D~

向量存储抽象层：

vector-store/
├── store/
│   ├── IVectorStore.java        # 向量存储接口
│   ├── VDocument.java           # 向量文档实体
│   └── hybrid/                  # 混合存储（多存储协同）
│       ├── HybridVectorStore.java
│       ├── insert/              # 插入操作
│       └── delete/              # 删除操作
└── search/
    ├── ISearch.java             # 搜索接口
    ├── HybridSearch.java        # 混合搜索
    └── request/response/        # 请求响应实体

2.6 rag4j-framework-recall

RAG 召回框架，实现检索增强生成的核心流程：

/**
 * RAG 召回核心类
 */
public class RagRecall {
    
    public List<Chunk> recall(RagRecallDTO ragRecallDTO) {
        // 1. 搜索策略执行
        List<BaseSearchResponse> search = searchStrategy.search(...);
        // 2. 重排序
        List<SearchRerankResponse> rerank = rerankStrategy.rerank(...);
        // 3. 召回扩展
        return recallExpansion.expansion(rerank);
    }
}

召回流程：

Search - 向量/关键词/混合搜索
Rerank - 结果重排序（支持 RRF 等算法）
Expansion - 召回扩展

2.7 rag4j-framework-model-suppliers

classDiagram
direction BT
class ChatRag4jModelFactory~CM, C~ {
<<Interface>>

}
class EmbeddingRag4jModelFactory~M, C~ {
<<Interface>>

}
class ModelSupplierDetails {
<<Interface>>
   String name
   ModelVendorInfo modelVendorInfo
  + supportTypes() Set~ModelType~
  + modelList() List~IModelInfo~
  + modelInfoByType() Map~ModelType, List~IModelInfo~~
}
class ModelVendorFactory {
<<Interface>>
   Map~Class~Model~?, ?~~, Rag4jModelFactory~?, ?~~ modelFactories
  + isSupported(ModelType) boolean
  + check(String) boolean
  + getFactoryByModelType(Class~M~) Rag4jModelFactory~M, C~
}
class OpenAiChatRag4jModelFactory {
  - OpenAiChatRag4jModelFactory INSTANCE
   OpenAiChatRag4jModelFactory INSTANCE
  + createModel(ChatModelConfig) OpenAiChatModel
}
class OpenAiEmbeddingRag4jModelFactory {
  - OpenAiEmbeddingRag4jModelFactory INSTANCE
   OpenAiEmbeddingRag4jModelFactory INSTANCE
  + createModel(EmbeddingModelConfig) OpenAiEmbeddingModel
}
class OpenAiModelFactory {
  - ModelVendorInfo modelVendorInfo
   String name
   ModelVendorInfo modelVendorInfo
   Map~Class~Model~?, ?~~, Rag4jModelFactory~?, ?~~ modelFactories
  + supportTypes() Set~ModelType~
  + check(String) boolean
  + modelList() List~IModelInfo~
  + modelInfoByType() Map~ModelType, List~IModelInfo~~
}
class Rag4jModelFactory~M, C~ {
<<Interface>>
  + createModel(C) M
}
class TongYiChatRag4jModelFactory {
  - TongYiChatRag4jModelFactory INSTANCE
   TongYiChatRag4jModelFactory INSTANCE
  + createModel(ChatModelConfig) OpenAiChatModel
}
class TongYiEmbeddingRag4jModelFactory {
  - TongYiEmbeddingRag4jModelFactory INSTANCE
   TongYiEmbeddingRag4jModelFactory INSTANCE
  + createModel(EmbeddingModelConfig) OpenAiEmbeddingModel
}
class TongYiModelFactory {
  - ModelVendorInfo modelVendorInfo
   String name
   ModelVendorInfo modelVendorInfo
   Map~Class~Model~?, ?~~, Rag4jModelFactory~?, ?~~ modelFactories
  + getFactoryByModelType(Class~M~) Rag4jModelFactory~M, C~
  + check(String) boolean
  + modelInfoByType() Map~ModelType, List~IModelInfo~~
  + supportTypes() Set~ModelType~
  + modelList() List~IModelInfo~
}

ChatRag4jModelFactory~CM, C~  -->  Rag4jModelFactory~M, C~ 
EmbeddingRag4jModelFactory~M, C~  -->  Rag4jModelFactory~M, C~ 
ModelVendorFactory  -->  ModelSupplierDetails 
OpenAiChatRag4jModelFactory  ..>  ChatRag4jModelFactory~CM, C~ 
OpenAiEmbeddingRag4jModelFactory  ..>  EmbeddingRag4jModelFactory~M, C~ 
OpenAiModelFactory  ..>  ModelVendorFactory 
OpenAiModelFactory "1" *--> "factories *" Rag4jModelFactory~M, C~ 
TongYiChatRag4jModelFactory  ..>  ChatRag4jModelFactory~CM, C~ 
TongYiEmbeddingRag4jModelFactory  ..>  EmbeddingRag4jModelFactory~M, C~ 
TongYiModelFactory  ..>  ModelVendorFactory 
TongYiModelFactory "1" *--> "factories *" Rag4jModelFactory~M, C~

模型供应商抽象，基于 Spring AI：

统一的模型调用接口
支持多供应商切换
集成 Spring Security

3. rag4j-project（实现层）

具体技术实现，可插拔式设计。

rag4j-project/
├── rag4j-chunk/                 # 切片策略实现
├── rag4j-document/              # 文档处理实现
├── rag4j-models-suppliers/      # 模型供应商实现
│   ├── rag4j-models-suppliers-openai/           # OpenAI
│   ├── rag4j-models-suppliers-openai-compatible/ # OpenAI 兼容接口
│   └── rag4j-models-suppliers-tongyi/           # 通义千问
├── rag4j-vector-store/          # 向量存储实现
│   ├── rag4j-vector-store-pgvector/      # PostgreSQL + pgvector
│   └── rag4j-vector-store-elasticsearch/ # Elasticsearch
└── rag4j-system/                # 系统功能实现

🔄 核心流程

RAG 检索增强生成流程

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   用户查询   │───▶│  Embedding  │───▶│  向量检索   │
└─────────────┘    └─────────────┘    └─────────────┘
                                             │
                                             ▼
┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   LLM 回答  │◀───│ Prompt 组装 │◀───│  Rerank    │
└─────────────┘    └─────────────┘    └─────────────┘

文档入库流程

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  文件上传   │───▶│  文档解析   │───▶│  文本切片   │
└─────────────┘    └─────────────┘    └─────────────┘
                                             │
                                             ▼
┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  入库完成   │◀───│  向量存储   │◀───│  Embedding  │
└─────────────┘    └─────────────┘    └─────────────┘

⚙️ 技术栈

组件	技术选型
语言	Java 21+
框架	Spring Boot 3.5
AI 框架	Spring AI 1.0.3
ORM	MyBatis-Plus 3.5
向量数据库	PostgreSQL + pgvector / Elasticsearch
文档解析	Apache Tika 3.2
对象映射	MapStruct 1.5
LLM 供应商	OpenAI / 通义千问 / Ollama
文件存储	MinIO

📐 设计原则

分层架构 - app（应用）→ framework（框架）→ project（实现）
接口抽象 - 核心能力通过接口定义，实现可插拔
策略模式 - 切片、搜索、重排序等均支持多策略
注册中心 - 通过 Registry 模式管理策略实现
混合存储 - 支持多向量存储协同工作
工作流引擎 - DAG 编排支持复杂业务流程

🚀 扩展指南

添加新的切片策略

实现 DocumentChunk 接口
继承 BaseChunkConfig 定义配置
注册到 ChunkRegistry

添加新的向量存储

实现 IVectorStore 接口
实现 ISearch 接口
在 rag4j-project/rag4j-vector-store 下创建新模块

添加新的模型供应商

在 rag4j-project/rag4j-models-suppliers 下创建新模块
实现 Spring AI 的模型接口
配置自动装配

📝 目录结构

rag4j/
├── rag4j-app/
│   └── src/main/java/cn/rag4j/
│       ├── RagApplication.java          # 启动类
│       ├── agent/                       # Agent 模块
│       ├── chunk/                       # 切片模块
│       ├── config/                      # 配置
│       ├── directory/                   # 目录模块
│       ├── document/                    # 文档模块
│       ├── file/                        # 文件模块
│       ├── knowledgebase/               # 知识库模块
│       └── model/                       # 模型模块
├── rag4j-framework/
│   ├── rag4j-framework-chunk/           # 切片框架
│   ├── rag4j-framework-common/          # 通用模块
│   ├── rag4j-framework-dag/             # DAG 引擎
│   ├── rag4j-framework-document/        # 文档框架
│   ├── rag4j-framework-file/            # 文件框架
│   ├── rag4j-framework-knowledgebase/   # 知识库框架
│   ├── rag4j-framework-model-suppliers/ # 模型供应商框架
│   ├── rag4j-framework-recall/          # 召回框架
│   ├── rag4j-framework-system/          # 系统框架
│   └── rag4j-framework-vector-store/    # 向量存储框架
├── rag4j-project/
│   ├── rag4j-chunk/                     # 切片实现
│   ├── rag4j-document/                  # 文档实现
│   ├── rag4j-models-suppliers/          # 模型供应商实现
│   ├── rag4j-system/                    # 系统实现
│   └── rag4j-vector-store/              # 向量存储实现
├── pom.xml                              # 父 POM
├── README.md                            # 项目说明
└── ARCHITECTURE.md                      # 架构说明（本文档）

RAG4J

RAG4J 项目架构说明

📁 项目结构概览

🏗️ 模块架构

1. rag4j-app（应用层）

2. rag4j-framework（框架层）

2.1 rag4j-framework-common

2.2 rag4j-framework-chunk

2.3 rag4j-framework-document

2.4 rag4j-framework-dag(TODO)

2.5 rag4j-framework-vector-store

2.6 rag4j-framework-recall

2.7 rag4j-framework-model-suppliers

3. rag4j-project（实现层）

🔄 核心流程

RAG 检索增强生成流程

文档入库流程

⚙️ 技术栈

📐 设计原则

🚀 扩展指南

添加新的切片策略

添加新的向量存储

添加新的模型供应商

📝 目录结构

搜索帮助