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

技术栈

类别	技术
后端框架	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`	文档分块

条件比较器:

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 开源智能体搭建平台技术文档

MaxKB4j 技术文档

项目概述

核心特性

技术栈

项目结构

核心模块详解

1. maxkb4j-common (公共模块)

2. maxkb4j-core (核心模块)

Assistant (AI 助手接口)

Event (事件系统)

LangChain4j 集成

3. maxkb4j-service-api (服务 API 层)

主要实体

数据库表结构

4. maxkb4j-service (服务实现层)

4.1 maxkb4j-application (应用服务)

4.2 maxkb4j-knowledge (知识库服务)

4.3 maxkb4j-model (模型服务)

4.4 maxkb4j-workflow (工作流服务)

4.5 maxkb4j-tool (工具服务)

5. maxkb4j-start (启动模块)

配置类

监听器

数据库迁移

6. ui (前端项目)

技术栈

目录结构

主要页面

API 接口

认证接口

应用接口

知识库接口

文档接口

模型接口

部署指南

系统要求

Docker 部署

Docker Compose 部署

本地开发

配置说明

application.yml 主要配置

扩展开发

添加新的模型提供商

添加新的工作流节点

添加新的文档解析器

许可证

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具