MaxKB4j 基于 Java 的 RAG 知识库与 LLM 工作流平台技术解析

核心模块详解

1. maxkb4j-common（公共模块）

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

这里提供了项目通用的基础设施，比如统一响应封装 R.java、全局异常处理 GlobalExceptionHandler.java 以及 Sa-Token 权限工具 StpKit.java。包结构清晰，涵盖了从注解、切面到类型处理器的各个层面。

2. maxkb4j-core（核心模块）

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

这是 AI 能力的核心所在。除了基础的 Assistant 接口外，还实现了压缩查询、意图分类、NL2SQL 等多种专用助手。事件系统（如 DocumentIndexEvent）负责在关键节点触发逻辑，配合 LangChain4j 的 AppChatMemory 管理会话状态。

3. maxkb4j-service-api（服务 API 层）

路径：maxkb4j-service-api/

定义了服务接口、实体、DTO 和 Mapper。主要实体包括应用配置、知识库、文档、段落、向量嵌入等。数据库表结构方面，重点在于 embedding 表，用于存储向量数据以支持语义检索。

4. maxkb4j-service（服务实现层）

4.1 应用服务

核心功能涵盖应用管理、聊天服务（简单聊天与工作流聊天）、访问令牌及 API Key 管理。聊天 Pipeline 架构设计得很巧妙，包含生成用户消息、重置问题、搜索知识库和最终聊天步骤，保证了流程的可控性。

4.2 知识库服务

支持 PDF、Word、TXT、Markdown、HTML、URL 等多种格式的文档解析。检索策略上提供全文检索、混合检索（向量 + 全文）以及 PostgreSQL 向量索引，满足不同精度需求。

4.3 模型服务

支持 OpenAI、Anthropic、Google、DeepSeek、阿里云、腾讯、字节、百度、智谱、Kimi、Ollama 等多种提供商。模型类型覆盖 ChatModel、EmbeddingModel、ImageModel 等，甚至包括 STT/TTS 模型。

4.4 工作流服务

工作流执行器 (WorkFlowActuator) 是调度中心，支持 START、AI_CHAT、SEARCH_KNOWLEDGE、CONDITION、HTTP_CLIENT、TOOL、MCP 等丰富的节点类型。条件比较器也做得很细致，支持等于、包含、大小判断、空值判断等多种逻辑。

4.5 工具服务

提供工具管理、连接验证及导入导出功能，通过 McpToolUtil 和 SkillsToolUtil 实现 MCP 协议和技能工具的集成。

5. maxkb4j-start（启动模块）

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

负责配置类（MyBatis-Plus、Sa-Token、MongoDB 等）和监听器（应用启动、数据索引、问题生成）。数据库迁移脚本位于 V1__init_tables.sql 等文件中，确保环境初始化一致。

6. ui（前端项目）

路径：ui/

基于 Vue 3.5 + TypeScript，使用 Element Plus 组件库和 LogicFlow 工作流编辑器。页面视图涵盖登录、应用概览、聊天、知识库、文档、模型、工具及系统设置等功能。

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

相关资源

• Gitee Issues