MaxKB：飞致云开源的企业级智能体平台，全流程RAG支持与多模态智能交互

一、MaxKB是什么？

MaxKB是由飞致云（Fit2Cloud）团队开发的开源企业级智能体平台。作为一款专注于知识管理与智能交互的工具，它的核心目标是解决企业在知识沉淀、智能问答、业务流程自动化等场景中的痛点，让企业无需深厚的AI技术积累，就能快速构建属于自己的智能体应用。

从定位来看，MaxKB并非单一的“问答工具”，而是一个“平台级解决方案”：它整合了知识获取、处理、存储、检索、生成等全流程能力，同时支持与大模型、第三方系统无缝对接，形成从“知识输入”到“智能输出”的完整闭环。无论是中小微企业的简单知识库需求，还是大型企业的复杂业务流程自动化场景，MaxKB都能通过灵活配置满足需求。

作为飞致云生态的重要组成部分，MaxKB与该公司旗下的1Panel（服务器管理面板）、JumpServer（堡垒机）等项目形成协同，为企业提供从基础设施到上层AI应用的全栈支持。其开源特性（基于GPLv3协议）确保了代码透明、可定制化，企业可根据自身需求修改源码，避免“锁定效应”。

二、功能特色

MaxKB的功能设计围绕“降低AI应用门槛”和“提升业务适配性”展开，核心特色可概括为以下五点：

1. 全流程RAG流水线，解决大模型“幻觉”问题

RAG（检索增强生成）是当前解决大模型“知识过时”“幻觉输出”的核心技术，MaxKB将其封装为开箱即用的流水线，无需人工编写复杂逻辑：

• 文档获取自动化：支持本地文档（PDF、Word、Markdown、TXT等）直接上传，或通过URL自动爬取在线文档（如官网帮助中心、博客文章），爬取时可配置过滤规则（如排除广告、指定域名）。

• 智能文本分割：内置多种分割策略（按章节、按段落、按Token数量），结合语义分析避免“断句割裂语义”——例如，一篇关于“产品保修政策”的文档，会自动按“保修范围”“期限”“流程”等语义单元分割，确保检索时获取完整信息。

• 高效向量化处理：集成Sentence-BERT、m3e等开源向量模型，也支持调用OpenAI Embeddings等API，将文本转化为向量后存储于pgvector（PostgreSQL的向量扩展），实现毫秒级相似性检索。

• 检索增强生成：当用户提问时，系统先从向量库中检索最相关的知识片段，再将其作为“上下文”传递给大模型，确保回答基于企业真实知识，而非大模型的“臆测”。

2. 可视化智能体工作流，适配复杂业务场景

除了基础问答，MaxKB通过工作流引擎支持“多步骤智能交互”，让智能体具备处理复杂任务的能力：

• 拖拽式流程编排：通过Web界面拖拽节点（如“提问用户”“调用工具”“条件判断”“调用函数”），即可搭建工作流。例如，“售后工单处理”工作流可设计为：用户提问→检索知识库→若无法解决→自动创建工单→分配给对应部门→反馈处理进度。

• 丰富函数库与工具集成：预置常用函数（如“发送邮件”“查询数据库”“调用API”），也支持自定义函数（通过Python脚本编写）。同时集成MCP（Multi-Component Processing）工具体系，可协同调用计算器、翻译工具、数据查询接口等，例如让智能体自动查询订单系统后回复用户“物流状态”。

• 动态上下文管理：工作流执行过程中，系统会自动记录上下文（如用户历史提问、工具返回结果），确保多轮交互的连贯性。例如，用户先问“产品A的价格”，再问“它的保修期”，智能体无需重复确认产品信息即可直接回答。

3. 零代码集成能力，快速赋能现有系统

MaxKB设计了轻量化的集成方案，无需改造现有业务系统即可赋予其智能能力：

• API接口全覆盖：提供RESTful API，支持通过HTTP请求调用智能体问答、触发工作流、同步知识库等功能。例如，企业可在自己的CRM系统中嵌入API，当客服人员与客户沟通时，系统自动调用MaxKB获取产品知识并实时展示。

• Web组件即插即用：提供可嵌入的前端组件（如问答弹窗、知识搜索框），通过简单的JS代码即可集成到官网、APP或内部系统。组件支持自定义样式（颜色、尺寸、位置），确保与原有界面风格一致。

• 第三方系统适配：已预置与主流系统的对接模板，如Helpdesk系统（自动生成工单）、企业微信/钉钉（推送智能问答结果）、OA系统（查询流程进度）等，减少集成开发量。

4. 模型无关性，灵活适配各类大模型

MaxKB不绑定特定大模型，企业可根据成本、隐私性、性能需求自由选择：

无论是私有模型（需自行部署）还是公共模型（通过API调用），MaxKB均提供统一的配置界面，只需填写模型地址、API密钥等信息即可快速接入，无需修改代码。

5. 原生多模态支持，打破数据格式限制

不同于仅支持文本的工具，MaxKB可处理多种类型的输入输出，让智能交互更自然：

• 多模态输入：支持文本（提问、文档）、图像（如产品图片识别型号）、音频（语音提问转文字）、视频（提取字幕或分析画面内容）。例如，用户上传一张“设备故障照片”，智能体可识别故障部件并给出维修建议。

• 多模态输出：除文本回答外，可生成图像（如根据描述生成产品示意图）、音频（文字转语音播报）、结构化数据（如JSON格式的订单信息）。例如，智能体回答“产品安装步骤”时，可同时生成图文教程和语音指导。

三、技术细节

MaxKB的技术架构以“稳定性、可扩展性、易用性”为核心，各组件分工明确且协同高效：

1. 技术栈组成

2. 核心技术亮点

• 分布式向量检索优化：当知识库规模较大（如百万级文档）时，系统会自动对向量库进行分片，结合Redis缓存热点数据，确保检索延迟控制在100ms以内。

• 动态负载均衡：支持同时配置多个大模型实例（如多个GPT-4o API密钥），系统会根据模型响应速度自动分配请求，避免单模型过载。

• 数据安全机制：所有文档数据加密存储（AES-256），API调用需通过Token认证，支持细粒度权限控制（如“部门A只能访问部门A的知识库”），并提供操作审计日志（记录谁在何时修改了智能体配置）。

• 可扩展性设计：采用插件化架构，新增功能（如自定义向量模型、新的文档格式解析）可通过插件实现，无需修改核心代码。

3. 性能指标（官方测试数据）

• 文档处理速度：单节点支持每秒处理100页PDF文档（约5万字）的分割与向量化；

• 问答响应时间：简单问题（单轮检索+生成）平均响应时间<2秒，复杂工作流（多工具调用）平均响应时间<5秒；

• 并发支持：单节点可支持100并发用户请求（通过Docker横向扩展可提升至数千并发）。

四、应用场景

MaxKB的灵活性使其能适配多行业、多场景的需求，以下为典型应用场景说明：

1. 企业智能客服

痛点：传统客服需人工查询知识库，响应慢且易出错；高峰期排队严重，用户体验差。
MaxKB解决方案：

• 构建“产品知识+售后流程”知识库，支持用户通过文本、语音提问，智能体实时回复（如“如何申请退款”“产品保修期多久”）；

• 配置工作流：若问题复杂（如“退款未到账”），自动调用订单系统查询状态，若确认异常则创建工单并分配给售后专员，同时向用户推送“工单进度查询链接”；

• 集成到企业官网、APP、微信公众号，实现全渠道智能应答，降低80%的重复咨询工作量。

2. 企业内部知识库

痛点：企业内部制度、流程、技术文档分散在共享盘、Wiki等系统，员工查询效率低；新人培训依赖人工，成本高。
MaxKB解决方案：

• 批量导入内部文档（如“员工手册”“IT故障处理流程”“代码规范”），支持按部门、岗位权限隔离知识；

• 员工通过聊天界面提问（如“报销流程是什么”“服务器重启步骤”），智能体直接返回精准答案及原文链接；

• 配置“新员工培训”工作流：自动推送学习清单→定期提问考核→生成学习报告，缩短新人上岗时间。

3. 学术研究辅助

痛点：研究人员需阅读大量文献，筛选关键信息耗时；跨语言文献翻译、数据整理效率低。
MaxKB解决方案：

• 上传领域内文献（支持PDF、LaTeX格式），智能体自动提取核心观点、实验数据、参考文献；

• 配置“文献分析”工作流：输入研究主题→检索相关文献→总结研究现状→生成研究空白点建议；

• 集成翻译工具，支持中英日韩等多语言文献互译，同时生成结构化笔记（如“研究方法”“结论”分类）。

4. 电商行业产品咨询

痛点：电商平台产品SKU多，客服难以记住所有细节（如尺寸、材质、兼容性）；促销活动规则复杂，易解答错误。
MaxKB解决方案：

• 对接电商数据库，实时同步产品信息（价格、库存、参数）和促销规则；

• 用户提问“这件衣服适合175cm的人穿吗”时，智能体自动检索产品尺寸表并结合用户身高给出建议；

• 支持图像输入：用户上传“穿搭照片”，智能体推荐搭配的其他产品，提升交叉销售率。

五、使用方法

MaxKB提供Docker一键部署方案，同时支持源码编译，以下为快速上手步骤：

1. 环境准备

• 操作系统：Linux（推荐Ubuntu 20.04+）、Windows（需安装WSL2）、macOS；

• 依赖工具：Docker 20.10+、Docker Compose 2.0+；

• 硬件要求：最低2核4G内存（生产环境建议4核8G以上，向量处理对内存需求较高）。

2. 快速部署（Docker方式）

# 拉取并启动MaxKB容器
docker run -d \
 --name=maxkb \
 --restart=always \
 -p 8080:8080 \ # 映射容器8080端口到主机8080（可修改主机端口，如-p 9000:8080）
 -v ~/.maxkb:/opt/maxkb \ # 挂载数据目录到主机，确保数据持久化
 1panel/maxkb # 官方镜像

启动后，通过浏览器访问 http://服务器IP:8080，使用默认账号登录：

• 用户名：admin

• 密码：MaxKB@123..（首次登录需强制修改密码）

3. 创建第一个智能体

步骤1：新建智能体

登录后进入“智能体管理”→“新建智能体”，填写名称（如“公司产品客服”）、描述，选择图标和语言（支持多语言应答）。

步骤2：配置知识库

• 进入“知识库”标签，点击“添加数据源”：

• 选择“本地文档”：上传PDF/Word等文件（单文件最大支持100MB，支持批量上传）；

• 选择“在线文档”：输入URL（如https://www.example.com/help），设置爬取深度（如只爬取当前页面或包含子页面）；

• 文档上传后，系统自动进行分割和向量化（可在“任务中心”查看进度）。

步骤3：选择大模型

进入“模型配置”标签，选择模型类型：

• 若用公共模型（如GPT-4o）：填写OpenAI API密钥、API地址（默认https://api.openai.com/v1），设置最大Token（如4096）；

• 若用私有模型（如Qwen）：填写模型部署地址（如http://localhost:8000/v1），无需密钥（若模型有认证则填写）。

步骤4：设置工作流（可选）

简单问答场景可跳过，复杂场景进入“工作流”标签，拖拽节点搭建流程：

• 例如“售后问题处理”：添加“检索知识库”节点→“条件判断”节点（若检索结果匹配度>80%则直接回答，否则进入下一步）→“创建工单”节点→“回复用户”节点。

步骤5：测试与发布

• 点击“测试”按钮，输入问题（如“产品A的保修期是多久”），查看智能体回答是否准确；

• 测试通过后，点击“发布”，智能体即可通过API或Web组件对外提供服务。

4. 集成到第三方系统

方式1：API调用

通过以下代码示例（Python）调用智能体问答：

import requests

url = "http://服务器IP:8080/api/v1/agents/{agent_id}/chat"
headers = {
 "Content-Type": "application/json",
 "Authorization": "Token your_api_token" # 在“系统设置→API密钥”中获取
}
data = {
 "query": "产品A的价格是多少？",
 "user_id": "user123" # 区分不同用户的上下文
}

response = requests.post(url, json=data, headers=headers)
print(response.json()["answer"]) # 输出智能体回答

方式2：Web组件嵌入

在官网页面添加以下代码，嵌入问答弹窗：

<!-- 引入组件JS -->
<script src="http://服务器IP:8080/static/js/maxkb-widget.js"></script>
<!-- 初始化组件 -->
<script>
 MaxKBWidget.init({
  agentId: "your_agent_id", // 智能体ID
  apiUrl: "http://服务器IP:8080/api/v1",
  theme: { // 自定义样式
   primaryColor: "#165DFF",
   title: "产品咨询助手"
  }
 });
</script>
<!-- 触发按钮（点击打开弹窗） -->
<button onclick="MaxKBWidget.open()">点击咨询</button>

六、常见问题解答（FAQ）

1. 部署后无法访问Web界面，怎么办？

• 检查Docker容器是否启动：执行docker ps | grep maxkb，若未显示则执行docker start maxkb；

• 检查端口是否占用：若主机8080端口被占用，重新启动时修改端口（如-p 9000:8080）；

• 查看容器日志排查错误：docker logs maxkb，常见错误包括权限不足（需确保~/.maxkb目录有读写权限）、内存不足（需增加主机内存）。

2. 智能体回答不准确，可能的原因是什么？

• 知识库数据不足：需补充相关文档（如产品信息不全导致无法回答价格问题）；

• 文本分割不合理：进入“知识库→文档详情”，手动调整分割策略（如将“按Token分割”改为“按章节分割”）；

• 模型选择不当：若用小参数私有模型（如7B模型），可能理解能力有限，可尝试切换至更大模型或公共模型（如GPT-4o）。

3. 上传文档时提示“格式不支持”，如何解决？

• 检查文档格式：目前支持PDF、Word（.docx）、Markdown（.md）、TXT、PPTX，不支持加密或损坏的文件；

• 转换格式：若为特殊格式（如PDF扫描件，本质是图片），需先通过OCR工具转为可编辑文本，再上传；

• 拆分大文件：单文件超过100MB时，建议拆分后上传（如将1GB的PDF按章节拆分为多个小文件）。

4. 如何确保企业数据安全？

• 本地化部署：通过Docker在企业内网部署，数据存储在自有服务器，不泄露至第三方；

• 权限控制：在“用户管理”中创建角色（如“只读用户”“管理员”），限制对知识库、智能体的操作权限；

• 数据加密：系统默认对文档内容、API密钥进行加密存储，可在“系统设置→安全”中开启传输加密（HTTPS）。

5. 大模型调用耗时过长，如何优化？

• 启用缓存：在“系统设置→性能”中开启“问答缓存”，重复问题直接返回历史结果；

• 调整模型参数：减少“最大生成Token”（如从4096改为2048）、提高“温度参数”（加速生成，牺牲部分精确性）；

• 增加模型实例：若用私有模型，可部署多个模型节点，在MaxKB中配置“模型集群”实现负载均衡。

七、相关链接

• GitHub仓库：https://github.com/1Panel-dev/MaxKB

• 官方文档：https://maxkb.cn/docs/

八、总结

MaxKB作为一款开源企业级智能体平台，通过整合RAG流水线、可视化工作流、多模态处理、多模型兼容等核心能力，为企业提供了从知识管理到智能交互的一站式解决方案。其优势在于零代码门槛（无需AI技术背景即可使用）、高度可定制（开源特性支持二次开发）、无缝集成（快速赋能现有系统），适用于智能客服、内部知识库、学术辅助等多场景。无论是中小微企业还是大型组织，都能通过MaxKB低成本、高效率地落地AI应用，实现知识价值的最大化。