MaxKB4j 基于 Java 的开源 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/

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

包名	功能
`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`	工具类集合

关键类:

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

2. maxkb4j-core (核心模块)

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

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

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。

主要实体

实体	所属模块	描述
`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 - MCP 工具工具类
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 -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

扩展开发

添加新的模型提供商

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

添加新的工作流节点

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

添加新的文档解析器

实现 DocumentParser 接口
注册为 Spring Bean

许可证

GNU General Public License v3.0 (GPLv3)

MaxKB4j 技术文档

项目概述

核心特性

开箱即用的知识库问答: 支持上传本地文档或自动抓取网页内容，自动完成文本分块 → 向量化 → 向量数据库存储 → 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/

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

包名	功能
`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`	工具类集合

关键类:

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

2. maxkb4j-core (核心模块)

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

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

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。

主要实体

实体	所属模块	描述
`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 - MCP 工具工具类
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 -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

扩展开发

添加新的模型提供商

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

添加新的工作流节点

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

添加新的文档解析器

实现 DocumentParser 接口
注册为 Spring Bean

许可证

GNU General Public License v3.0 (GPLv3)