开源智能体搭建平台MaxKB4j 技术文档

洛阳泰山2026-03-18 14:58

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 文件夹
数据库表结构

主要数据表：

sql 复制代码 
-- 用户表
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 部署

bash 复制代码 
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 部署

yaml 复制代码 
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:

本地开发

bash 复制代码 
# 后端
cd MaxKB4j
mvn spring-boot:run -pl maxkb4j-start

# 前端
cd ui
npm install
npm run dev

配置说明

application.yml 主要配置

yaml 复制代码 
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)

相关资源

相关推荐
我命由我123452 小时前
Android 开发 - UriMatcher（一个 URI 分类器）
android·java·java-ee·kotlin·android studio·android-studio·android runtime
sinat_255487812 小时前
为 System.out 编写我们自己的包装类
java·开发语言·算法
a8a3022 小时前
Springboot中CommandLineRunner的用法以及执行顺序的控制
java·spring boot·spring
小小小小小鹿2 小时前
Claude Code Agent Skills 入门指南（下）：理解Skill的工作机制
llm·ai编程·claude
代码探秘者2 小时前
【大模型应用】1.了解RAG
java·人工智能·python·spring
sevenlin2 小时前
Spring Boot 经典九设计模式全览
java·spring boot·设计模式
Barkamin2 小时前
快速排序非递归实现
java·算法·排序算法
认真的小羽❅2 小时前
0-1手写通用的 Excel 导入/导出工具类
java·excel
zone77392 小时前
008-01：RAG 入门-向量存储与企业级向量数据库 milvus
后端·面试·agent
热门推荐
01GitHub 镜像站点02Qwen3.5 开源全解析：从 0.8B 到 397B，代际升级 + 全场景选型指南03OpenClaw 使用和管理 MCP 完全指南04UV安装并设置国内源05OpenClaw Control UI安全上下文访问配置06OpenClaw macOS 完整安装与本地模型配置教程（实战版）07Claude Code + GLM4.7 避坑指南：解决 Unable to connect to Anthropic services08本地部署 OpenClaw + DeepSeek-R1 完全指南09小黑课堂计算机二级WPSoffice题库软件下载安装教程（2026年3月最新版）10让 Trae IDE 智能体 “读懂”文档 Excel+PDF+DOCX ：mcp-documents-reader 工具使用指南