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

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、图像生成

技术栈

项目结构

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/

提供项目通用的基础设施：

关键类:

• 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 \-eSPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/MaxKB4j \-eSPRING_DATASOURCE_USERNAME=postgres \-eSPRING_DATASOURCE_PASSWORD=123456\-eSPRING_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:123456volumes:- postgres_data:/var/lib/postgresql/data mongo:image: mongo:6.0environment:MONGO_INITDB_ROOT_USERNAME: admin MONGO_INITDB_ROOT_PASSWORD:123456volumes:- mongo_data:/data/db volumes:postgres_data:mongo_data:

本地开发

# 后端cd MaxKB4j mvn spring-boot:run -pl maxkb4j-start # 前端cd ui npminstallnpm run dev 

配置说明

application.yml 主要配置

spring:datasource:url: jdbc:postgresql://localhost:5432/MaxKB4j username: postgres password:123456data:mongodb:uri: mongodb://admin:123456@localhost:27017/MaxKB4j?authSource=admin # Sa-Token 配置sa-token:token-name: Authorization timeout:2592000active-timeout:-1is-concurrent:trueis-share:truetoken-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)

相关资源

• 开源模型库
• MCP 广场
• Gitee Issues