MaxKB4j 开源 RAG 知识库平台技术架构解析

MaxKB4j 技术文档

项目概述

MaxKB4j (Max Knowledge Base for Java) 是一个基于 Java/Spring Boot 和 LangChain4j 构建的开源 RAG（检索增强生成）知识库与 LLM 工作流平台。它专为构建企业级智能问答系统而设计，支持多模型集成、可视化工作流编排、知识库问答以及语音、图像等多模态能力。

核心特性

• 开箱即用的知识库问答: 支持上传本地文档或自动抓取网页内容，自动完成文本分块 → 向量化 → 向量数据库存储 → RAG 流程构建。
• 模型无关的灵活集成: 支持多种主流大语言模型（OpenAI、Claude、Gemini、DeepSeek、Qwen、Ollama 等），方便切换。
• 可视化工作流编排: 内置低代码 AI 工作流引擎，支持条件分支、函数调用、多轮对话记忆等复杂逻辑。
• MCP 协议支持: 实现 Model Context Protocol，使 AI 能够理解代码上下文和项目结构。
• 多模态能力: 支持语音识别 (ASR)、语音合成 (TTS)、OCR、图像生成。

---

技术栈

类别	技术
后端框架	Java 21, Spring Boot 3.5.1
AI 框架	LangChain4j 1.12.1
数据库	PostgreSQL 15+ (pgvector 扩展)
全文搜索	MongoDB 6.0+
缓存	Caffeine
认证授权	Sa-Token 1.39.0
ORM	MyBatis-Plus 3.5.9
API 文档	Knife4j (OpenAPI 3)
前端	Vue 3.5, TypeScript, Element Plus, LogicFlow
构建工具	Maven, Vite

---

项目结构

MaxKB4j/
├── maxkb4j-common/          # 公共模块 - 通用工具、常量、异常处理
├── maxkb4j-core/            # 核心模块 - AI 助手、事件处理、LangChain4j 集成
├── maxkb4j-service-api/     # 服务 API 定义层 - 实体、DTO、Mapper 接口
│   ├── maxkb4j-application-api/   # 应用相关 API
│   ├── maxkb4j-knowledge-api/     # 知识库相关 API
│   ├── maxkb4j-model-api/         # 模型相关 API
│   ├── maxkb4j-user-api/          # 用户相关 API
│   ├── maxkb4j-workflow-api/      # 工作流相关 API
│   ├── maxkb4j-tool-api/          # 工具相关 API
│   ├── maxkb4j-chat-api/          # 聊天相关 API
│   ├── maxkb4j-folder-api/        # 文件夹相关 API
│   ├── maxkb4j-oss-api/           # 对象存储相关 API
│   ├── maxkb4j-system-api/        # 系统相关 API
│   └── maxkb4j-trigger-api/       # 触发器相关 API
├── maxkb4j-service/             # 服务实现层 - 业务逻辑实现
│   ├── maxkb4j-application/     # 应用服务实现
│   ├── maxkb4j-knowledge/       # 知识库服务实现
│   ├── maxkb4j-model/           # 模型服务实现
│   ├── maxkb4j-workflow/        # 工作流服务实现
│   ├── maxkb4j-tool/            # 工具服务实现
│   ├── maxkb4j-chat/            # 聊天服务实现
│   ├── maxkb4j-oss/             # 对象存储服务实现
│   ├── maxkb4j-system/          # 系统服务实现
│   └── maxkb4j-trigger/         # 触发器服务实现
├── maxkb4j-start/               # 启动模块 - 配置、监听器、入口
└── ui/                          # 前端项目 - Vue 3 应用

---

核心模块详解

1. maxkb4j-common (公共模块)

路径: maxkb4j-common/src/main/java/com/maxkb4j/common/

这一层是项目的基石，提供通用的基础设施。比如统一响应封装 R.java 和全局异常处理 GlobalExceptionHandler.java，确保整个系统的交互规范一致。Sa-Token 权限工具 StpKit.java 也在这里集中管理。

包名	功能
annotation	自定义注解（如权限检查 @SaCheckPerm）
api	统一响应封装（R, ResultCode, IResultCode）
aspect	AOP 切面（权限检查切面）
cache	缓存实现（认证码缓存、聊天缓存、系统缓存）
constant	常量定义（应用常量、登录类型、权限、角色类型）
domain	领域对象（DTO、VO、表单对象）
enums	枚举类型
exception	自定义异常
handler	全局处理器（异常处理、字段填充）
mp	MyBatis-Plus 配置（实体基类、设置实体）
props	配置属性类
typehandler	自定义类型处理器（JSONB、List、Set 等）
util	工具类集合

2. maxkb4j-core (核心模块)

路径: maxkb4j-core/src/main/java/com/maxkb4j/core/

这里是 AI 能力的核心所在。我们定义了各种类型的助手接口，比如意图分类助手 IntentClassifyAssistant 或自然语言转 SQL 助手 NL2SqlAssistant。事件系统则负责处理文档索引、问题生成等异步操作。

Assistant (AI 助手接口)

类名	功能
Assistant	基础聊天助手接口
CompressingQueryAssistant	压缩查询助手
ExpandingQueryAssistant	扩展查询助手
IntentClassifyAssistant	意图分类助手
NL2SqlAssistant	自然语言转 SQL 助手
ParameterExtractionAssistant	参数提取助手
ProblemGenerateAssistant	问题生成助手
RouterAssistant	路由助手

Event (事件系统)

事件	触发时机
DocumentIndexEvent	文档索引事件
GenerateProblemEvent	问题生成事件
ParagraphIndexEvent	段落索引事件

LangChain4j 集成

• AppChatMemory - 应用聊天记忆管理
• AssistantServices - 助手服务工厂

3. maxkb4j-service-api (服务 API 层)

路径: maxkb4j-service-api/

定义服务接口、实体、DTO、VO 和 Mapper。这里主要关注数据模型的设计，比如知识库表 KnowledgeEntity、文档表 DocumentEntity 以及向量嵌入表 EmbeddingEntity。

主要实体

实体	所属模块	描述
ApplicationEntity	application-api	应用配置
ApplicationChatEntity	application-api	聊天会话
ApplicationChatRecordEntity	application-api	聊天记录
KnowledgeEntity	knowledge-api	知识库
DocumentEntity	knowledge-api	文档
ParagraphEntity	knowledge-api	段落
ProblemEntity	knowledge-api	问题
EmbeddingEntity	knowledge-api	向量嵌入
FolderEntity	folder-api	文件夹

数据库表结构

主要数据表：

-- 用户表 user(id, email, phone, nickname, username, password, role, is_active)
-- 知识库表 knowledge (id, name,type, source_type, embedding_model_id,...)
-- 文档表 document (id, knowledge_id, name,type, content,...)
-- 段落表 paragraph (id, document_id, content, title,...)
-- 向量嵌入表 embedding (id, paragraph_id, embedding vector(1536),...)
-- 应用表 application (id, name,type, model_id, workflow,...)
-- 聊天记录表 application_chat_record (id, application_id, chat_id, problem_text, answer_text,...)

4. maxkb4j-service (服务实现层)

路径: maxkb4j-service/

4.1 maxkb4j-application (应用服务)

核心功能: 应用管理、聊天服务（简单聊天、工作流聊天）、访问令牌管理、API Key 管理及聊天记录管理。

关键类: ApplicationService, ChatSimpleServiceImpl, ChatFlowServiceImpl, ChatServiceBuilder。

Pipeline 架构:

PipelineManage
├── GenerateHumanMessageStep # 生成用户消息
├── ResetProblemStep         # 重置问题
├── SearchDatasetStep        # 搜索知识库
└── ChatStep                 # 聊天步骤

4.2 maxkb4j-knowledge (知识库服务)

核心功能: 知识库管理、文档解析（PDF、Word、TXT、Markdown、HTML、URL 等）、文档分块、向量索引及检索服务。

文档解析器:

解析器	支持格式
PdfParser	PDF
DocParser	Word (doc/docx)
TxtParser	纯文本
MDParser	Markdown
HtmlParser	HTML
ExcelParser	Excel
PptParser	PowerPoint
CsvParser	CSV
UrlParser	网页 URL

检索策略: FullTextRetriever (全文检索), HybridRetriever (混合检索), PgVectorIndexService (PostgreSQL 向量索引)。

4.3 maxkb4j-model (模型服务)

核心功能: 模型提供商管理、模型实例构建、多种模型类型支持。

支持的模型提供商:

提供商	类名	支持模型
OpenAI	OpenAiModelProvider	GPT 系列
Anthropic	AnthropicProvider	Claude 系列
Google	GeminiModelProvider	Gemini 系列
DeepSeek	DeepSeekModelProvider	DeepSeek 系列
阿里云百炼	AliYunBaiLianModelProvider	通义千问
腾讯	TencentModelProvider	混元
字节跳动	VolcanicEngineModelProvider	豆包
百度	WenXinModelProvider	文心一言
智谱	ZhiPuModelProvider	GLM 系列
Kimi	KimiModelProvider	Moonshot
Ollama	OLlamaModelProvider	本地模型
Azure	AzureModelProvider	Azure OpenAI
SiliconFlow	SiliconFlowModelProvider	SiliconFlow
Xinference	XInferenceModelProvider	Xinference

模型类型: ChatModel, StreamingChatModel, EmbeddingModel, ImageModel, ScoringModel, STTModel, TTSModel。

4.4 maxkb4j-workflow (工作流服务)

核心架构:

WorkFlowActuator (工作流执行器)
├── ChatWorkflowHandler (聊天工作流处理器)
└── KnowledgeWorkflowHandler (知识库工作流处理器)

节点类型 (NodeType 枚举):

节点类型	描述	处理器
START	开始节点	StartNodeHandler
AI_CHAT	AI 聊天节点	LLMNodeHandler
SEARCH_KNOWLEDGE	知识库搜索	SearchKnowledgeNodeHandler
CONDITION	条件节点	ConditionNodeHandler
HTTP_CLIENT	HTTP 请求	HttpNodeHandler
TOOL	工具节点	ToolNodeHandler
MCP	MCP 节点	McpNodeHandler
FORM	表单节点	FormNodeHandler
QUESTION	问题节点	QuestionNodeHandler
REPLY	回复节点	DirectReplyNodeHandler
RERANKER	重排序节点	RerankerNodeHandler
INTENT_CLASSIFY	意图分类	IntentClassifyNodeHandler
PARAMETER_EXTRACTION	参数提取	ParameterExtractionNodeHandler
NL2SQL	自然语言转 SQL	NL2SqlNodeHandler
IMAGE_GENERATE	图像生成	ImageGenerateNodeHandler
IMAGE_UNDERSTAND	图像理解	-
TEXT_TO_SPEECH	文字转语音	TextToSpeechNodeHandler
SPEECH_TO_TEXT	语音转文字	SpeechToTextNodeHandler
DOCUMENT_EXTRACT	文档提取	DocumentExtractNodeHandler
DOCUMENT_SPLIT	文档分块	DocumentSpiltHandler
VARIABLE_ASSIGN	变量赋值	VariableAssignNodeHandler
VARIABLE_AGGREGATE	变量聚合	VariableAggregationNodeHandler
APPLICATION	应用节点	ApplicationNodeHandler
LOOP	循环节点	LoopNodeHandler
LOOP_START	循环开始	LoopStartNodeHandler
LOOP_BREAK	循环跳出	LoopBreakNodeHandler
LOOP_CONTINUE	循环继续	LoopContinueNodeHandler
KNOWLEDGE_WRITE	知识库写入	KnowledgeWriteHandler
DATA_SOURCE_LOCAL	本地数据源	DataSourceLocalHandler
DATA_SOURCE_WEB	Web 数据源	DataSourceWebHandler
USER_SELECT	用户选择	UserSelectNodeHandler

条件比较器: EqualCompare, ContainCompare, GTCompare/GECompare, LTCompare/LECompare, IsNullCompare/IsNotNullCompare, IsTrueCompare/IsNotTrueCompare, LengthEqualCompare 等。

4.5 maxkb4j-tool (工具服务)

核心功能: 工具管理、连接验证、导入导出。

关键类: ToolService, ToolProviderService, McpToolUtil, SkillsToolUtil。

5. maxkb4j-start (启动模块)

路径: maxkb4j-start/src/main/java/com/maxkb4j/start/

配置类

配置类	功能
MybatisPlusConfig	MyBatis-Plus 配置
SaTokenConfigure	Sa-Token 认证配置
WebConfig	Web MVC 配置
MongoConfig	MongoDB 配置
ThreadPoolConfig	线程池配置
Knife4jConfiguration	API 文档配置
ThymeleafConfig	模板引擎配置

监听器

监听器	功能
StartedListener	应用启动监听器
DataIndexListener	数据索引监听器
GenerateProblemListener	问题生成监听器

数据库迁移

• V1__init_tables.sql - 初始化表结构
• V2__add_table.sql - 新增表
• V3__add_trigger.sql - 触发器表

6. ui (前端项目)

路径: ui/

技术栈

• 框架: Vue 3.5 + TypeScript
• UI 组件: Element Plus 2.12
• 状态管理: Pinia 3.0
• 路由: Vue Router 4.5
• 工作流编辑器: LogicFlow 1.2
• 图表: ECharts 5.6
• Markdown: md-editor-v3
• 构建工具: Vite 6.2

目录结构

ui/src/
├── App.vue              # 根组件
├── main.ts              # 入口文件
├── components/          # 公共组件
│   ├── ai-chat/         # AI 聊天组件
│   ├── dynamics-form/   # 动态表单组件
│   ├── markdown/        # Markdown 组件
│   └── ...
├── layout/              # 布局组件
├── views/               # 页面视图
│   ├── application/     # 应用管理
│   ├── application-overview/ # 应用概览
│   ├── chat/            # 聊天页面
│   ├── chat-log/        # 聊天日志
│   ├── chat-user/       # 聊天用户
│   ├── document/        # 文档管理
│   ├── knowledge/       # 知识库管理
│   ├── login/           # 登录页面
│   ├── model/           # 模型管理
│   ├── paragraph/       # 段落管理
│   ├── problem/         # 问题管理
│   ├── system/          # 系统管理
│   ├── system-chat-user/ # 系统聊天用户
│   ├── system-setting/  # 系统设置
│   ├── tool/            # 工具管理
│   └── workflow/        # 工作流编辑
└── workflow/            # 工作流相关
    ├── nodes/           # 节点组件
    ├── icons/           # 节点图标
    └── common/          # 公共组件

主要页面

页面	路径	功能
登录	/login	用户登录
应用概览	/application	应用列表和管理
聊天	/chat	智能问答
知识库	/knowledge	知识库管理
文档	/document	文档管理
模型	/model	模型配置
工具	/tool	工具管理
系统设置	/system	系统配置

---

API 接口

认证接口

POST /api/user/login      # 用户登录
POST /api/user/logout     # 用户登出
GET  /api/user/info       # 获取用户信息

应用接口

GET  /api/application          # 获取应用列表
POST /api/application          # 创建应用
PUT  /api/application/{id}     # 更新应用
DELETE /api/application/{id}   # 删除应用
GET  /api/application/{id}     # 获取应用详情
POST /api/application/chat     # 聊天接口

知识库接口

GET  /api/knowledge          # 获取知识库列表
POST /api/knowledge          # 创建知识库
PUT  /api/knowledge/{id}     # 更新知识库
DELETE /api/knowledge/{id}   # 删除知识库
GET  /api/knowledge/{id}     # 获取知识库详情

文档接口

GET  /api/document          # 获取文档列表
POST /api/document          # 上传文档
DELETE /api/document/{id}   # 删除文档
POST /api/document/split    # 文档分块
POST /api/document/index    # 文档索引

模型接口

GET  /api/model          # 获取模型列表
POST /api/model          # 创建模型
PUT  /api/model/{id}     # 更新模型
DELETE /api/model/{id}   # 删除模型
GET  /api/provider       # 获取提供商列表

---

部署指南

系统要求

• Java 21+
• Maven 3.8+
• PostgreSQL 12+ (启用 pgvector 扩展)
• MongoDB 6.0+ (可选，用于全文搜索)
• Node.js 20+ (前端构建)

Docker 部署

使用官方镜像快速启动服务，注意环境变量配置：

docker run --name maxkb4j -d \
  --restart always \
  -p 8080:8080 \
  -e SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/MaxKB4j \
  -e SPRING_DATASOURCE_USERNAME=postgres \
  -e SPRING_DATASOURCE_PASSWORD=123456 \
  -e SPRING_DATA_MONGODB_URI=mongodb://admin:123456@localhost:27017/MaxKB4j?authSource=admin \
  registry.cn-hangzhou.aliyuncs.com/tarzanx/maxkb4j

Docker Compose 部署

如果需要同时启动数据库依赖，可以使用以下配置：

version: '3'
services:
  maxkb4j:
    image: registry.cn-hangzhou.aliyuncs.com/tarzanx/maxkb4j
    ports:
      - "8080:8080"
    environment:
      - SPRING_DATASOURCE_URL=jdbc:postgresql://postgres:5432/MaxKB4j
      - SPRING_DATASOURCE_USERNAME=postgres
      - SPRING_DATASOURCE_PASSWORD=123456
      - SPRING_DATA_MONGODB_URI=mongodb://admin:123456@mongo:27017/MaxKB4j?authSource=admin
    depends_on:
      - postgres
      - mongo

  postgres:
    image: pgvector/pgvector:pg15
    environment:
      POSTGRES_DB: MaxKB4j
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: 123456
    volumes:
      - postgres_data:/var/lib/postgresql/data

  mongo:
    image: mongo:6.0
    environment:
      MONGO_INITDB_ROOT_USERNAME: admin
      MONGO_INITDB_ROOT_PASSWORD: 123456
    volumes:
      - mongo_data:/data/db

volumes:
  postgres_data:
  mongo_data:

本地开发

# 后端
cd MaxKB4j
mvn spring-boot:run -pl maxkb4j-start

# 前端
cd ui
npm install
npm run dev

---

配置说明

application.yml 主要配置

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/MaxKB4j
    username: postgres
    password: 123456
  data:
    mongodb:
      uri: mongodb://admin:123456@localhost:27017/MaxKB4j?authSource=admin

# Sa-Token 配置
sa-token:
  token-name: Authorization
  timeout: 2592000
  active-timeout: -1
  is-concurrent: true
  is-share: true
  token-style: uuid
  is-log: false

---

扩展开发

添加新的模型提供商

如果你需要接入其他模型，只需继承 AbsModelProvider 类，然后实现必要的方法即可。比如 getModelList() 返回支持的模型列表，buildChatModel() 构建对话模型，最后记得注册为 Spring Bean。

添加新的工作流节点

在 NodeType 枚举中添加新类型，创建对应的节点数据类（继承 AbsNode），编写节点处理器（实现 INodeHandler），并加上 @NodeHandlerType 注解。这样前端就能识别并渲染这个新节点了。

添加新的文档解析器

实现 DocumentParser 接口，注册为 Spring Bean，系统就会自动识别并支持该格式的文档解析。

---

许可证

GNU General Public License v3.0 (GPLv3)