MaxKB4j 基于 Java 的开源 RAG 知识库平台技术解析

核心模块详解

1. maxkb4j-common (公共模块)

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

提供项目通用的基础设施，包括统一响应封装、全局异常处理及权限切面等。

关键类:

• R.java - 统一 API 响应封装
• GlobalExceptionHandler.java - 全局异常处理
• StpKit.java - Sa-Token 权限工具

2. maxkb4j-core (核心模块)

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

这里实现了核心的 AI 能力，主要包括助手接口与事件系统。

Assistant (AI 助手接口)

Event (事件系统)

LangChain4j 集成

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

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

路径: maxkb4j-service-api/

定义服务接口、实体、DTO、VO 和 Mapper。

主要实体

数据库表结构

主要数据表：

-- 用户表 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 等）
• 文档分块
• 向量索引
• 检索服务

文档解析器:

检索策略:

• FullTextRetriever - 全文检索
• HybridRetriever - 混合检索（向量 + 全文）
• PgVectorIndexService - PostgreSQL 向量索引

4.3 maxkb4j-model (模型服务)

核心功能:

• 模型提供商管理
• 模型实例构建
• 多种模型类型支持

支持的模型提供商:

模型类型:

• ChatModel - 对话模型
• StreamingChatModel - 流式对话模型
• EmbeddingModel - 嵌入模型
• ImageModel - 图像生成模型
• ScoringModel - 重排序模型
• STTModel - 语音转文字
• TTSModel - 文字转语音

4.4 maxkb4j-workflow (工作流服务)

核心架构:

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

节点类型 (NodeType 枚举):

条件比较器:

• EqualCompare - 等于
• ContainCompare - 包含
• GTCompare/GECompare - 大于/大于等于
• LTCompare/LECompare - 小于/小于等于
• IsNullCompare/IsNotNullCompare - 空值判断
• IsTrueCompare/IsNotTrueCompare - 布尔判断
• LengthEqualCompare 等 - 长度比较

4.5 maxkb4j-tool (工具服务)

核心功能:

• 工具管理
• 工具连接验证
• 工具导入导出

关键类:

• ToolService - 工具服务
• ToolProviderService - 工具提供者服务
• McpToolUtil - MCP 工具工具类
• SkillsToolUtil - 技能工具工具类

5. maxkb4j-start (启动模块)

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

配置类

监听器

数据库迁移

• 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/          # 公共组件

主要页面

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 -p8080: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

扩展开发

添加新的模型提供商

1. 继承 AbsModelProvider 类
2. 实现必要的方法：
   • getModelList() - 返回支持的模型列表
   • buildChatModel() - 构建对话模型
   • buildEmbeddingModel() - 构建嵌入模型
3. 注册为 Spring Bean

添加新的工作流节点

1. 在 NodeType 枚举中添加节点类型
2. 创建节点数据类（继承 AbsNode）
3. 创建节点处理器（实现 INodeHandler）
4. 添加 @NodeHandlerType 注解

添加新的文档解析器

1. 实现 DocumentParser 接口
2. 注册为 Spring Bean

许可证

GNU General Public License v3.0 (GPLv3)