MaxKB4j 开源智能体搭建平台技术文档
MaxKB4j 是一个基于 Java 和 Spring Boot 构建的开源 RAG 知识库及 LLM 工作流平台。支持多模型集成、可视化工作流编排、知识库问答及多模态能力。技术栈涵盖 LangChain4j、PostgreSQL、MongoDB、Vue3 等。提供完整的模块结构、API 接口及部署指南,适用于企业级智能问答系统构建。支持 Docker 及本地开发环境快速部署。

MaxKB4j 是一个基于 Java 和 Spring Boot 构建的开源 RAG 知识库及 LLM 工作流平台。支持多模型集成、可视化工作流编排、知识库问答及多模态能力。技术栈涵盖 LangChain4j、PostgreSQL、MongoDB、Vue3 等。提供完整的模块结构、API 接口及部署指南,适用于企业级智能问答系统构建。支持 Docker 及本地开发环境快速部署。

MaxKB4j (Max Knowledge Base for Java) 是一个基于 Java/Spring Boot 和 LangChain4j 构建的开源的 RAG(检索增强生成)知识库和 LLM 工作流平台,支持多模型集成、可视化工作流编排、知识库问答和多模态能力,专为构建企业级智能问答系统而设计。
| 类别 | 技术 |
|---|---|
| 后端框架 | 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 应用
路径: 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 权限工具路径: maxkb4j-core/src/main/java/com/maxkb4j/core/
核心 AI 能力实现:
| 类名 | 功能 |
|---|---|
Assistant | 基础聊天助手接口 |
CompressingQueryAssistant | 压缩查询助手 |
ExpandingQueryAssistant | 扩展查询助手 |
IntentClassifyAssistant | 意图分类助手 |
NL2SqlAssistant | 自然语言转 SQL 助手 |
ParameterExtractionAssistant | 参数提取助手 |
ProblemGenerateAssistant | 问题生成助手 |
RouterAssistant | 路由助手 |
| 事件 | 触发时机 |
|---|---|
DocumentIndexEvent | 文档索引事件 |
GenerateProblemEvent | 问题生成事件 |
ParagraphIndexEvent | 段落索引事件 |
AppChatMemory - 应用聊天记忆管理AssistantServices - 助手服务工厂路径: 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,...)
路径: maxkb4j-service/
核心功能:
关键类:
ApplicationService - 应用管理服务ChatSimpleServiceImpl - 简单聊天实现ChatFlowServiceImpl - 工作流聊天实现ChatServiceBuilder - 聊天服务构建器Pipeline 架构:
PipelineManage
├── GenerateHumanMessageStep # 生成用户消息
├── ResetProblemStep # 重置问题
├── SearchDatasetStep # 搜索知识库
└── ChatStep # 聊天步骤
核心功能:
文档解析器:
| 解析器 | 支持格式 |
|---|---|
PdfParser | |
DocParser | Word (doc/docx) |
TxtParser | 纯文本 |
MDParser | Markdown |
HtmlParser | HTML |
ExcelParser | Excel |
PptParser | PowerPoint |
CsvParser | CSV |
UrlParser | 网页 URL |
检索策略:
FullTextRetriever - 全文检索HybridRetriever - 混合检索(向量 + 全文)PgVectorIndexService - PostgreSQL 向量索引核心功能:
支持的模型提供商:
| 提供商 | 类名 | 支持模型 |
|---|---|---|
| OpenAI | OpenAiModelProvider | GPT 系列 |
| Anthropic | AnthropicProvider | Claude 系列 |
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 |
模型类型:
核心架构:
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 | 文档分块 |
条件比较器:
EqualCompare - 等于ContainCompare - 包含GTCompare/GECompare - 大于/大于等于LTCompare/LECompare - 小于/小于等于IsNullCompare/IsNotNullCompare - 空值判断IsTrueCompare/IsNotTrueCompare - 布尔判断LengthEqualCompare 等 - 长度比较核心功能:
关键类:
ToolService - 工具服务ToolProviderService - 工具提供者服务McpToolUtil - MCP 工具工具类SkillsToolUtil - 技能工具工具类路径: 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 - 触发器表路径: ui/
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 | 系统配置 |
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 # 获取提供商列表
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
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
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() - 构建嵌入模型NodeType 枚举中添加节点类型AbsNode)INodeHandler)@NodeHandlerType 注解DocumentParser 接口GNU General Public License v3.0 (GPLv3)

微信公众号「极客日志」,在微信中扫描左侧二维码关注。展示文案:极客日志 zeeklog
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具,Keycode 信息在线工具,online
JavaScript 字符串转义/反转义;Java 风格 \uXXXX(Native2Ascii)编码与解码。 在线工具,Escape 与 Native 编解码在线工具,online
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具,JavaScript / HTML 格式化在线工具,online
Terser 压缩、变量名混淆,或 javascript-obfuscator 高强度混淆(体积会增大)。 在线工具,JavaScript 压缩与混淆在线工具,online
生成新的随机RSA私钥和公钥pem证书。 在线工具,RSA密钥对生成器在线工具,online
基于 Mermaid.js 实时预览流程图、时序图等图表,支持源码编辑与即时渲染。 在线工具,Mermaid 预览与可视化编辑在线工具,online
DocumentSpiltHandlerVARIABLE_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 |