MaxKB 全维度使用手册

一、平台介绍

1. 产品基础信息

MaxKB（Max Knowledge Brain）是由飞致云（FIT2CLOUD）自研的开源企业级智能体（Agent）平台，主打“开箱即用、伴随成长”的产品理念。

• 核心定位：解决企业 AI 落地门槛高、部署贵、迭代慢、数据不可控的痛点。
• 技术底座：基于 PostgreSQL + pgvector 向量库，原生集成 RAG 知识库、可视化工作流 Workflow、Agent 智能体、多模型接入、第三方系统嵌入五大核心架构，支持私有化本地部署，确保全数据自主可控。
• 成长路线：从基础 RAG 知识库问答 → 流程自动化工作流 → 全功能智能体，三级渐进升级，适配企业不同阶段 AI 需求。
• 开源数据：GitHub 20K+ Star、500+ 开源贡献者，全球累计 100 万 + 安装量、1000+ 付费企业客户，覆盖 20+ 国家/地区，用户好评率 98%。

2. 落地核心逻辑（三步落地 AI）

1. 接入大模型：私有环境对接通义千问、DeepSeek、OpenAI、Claude、Llama 等 20+ 主流大模型（云端 API/本地私有化模型均可）。
2. 搭建专属知识库：批量导入企业文档，自动拆分、向量化构建私有知识库。
3. 能力迭代升级：从简单问答逐步升级业务自动化、全场景智能体应用。

二、主要功能

（一）核心五大模块（后台主界面）

1. 模型管理（模型接入）

• 兼容性：兼容公有云 API 模型、本地 Ollama 私有化部署模型、国产开源大模型。
• 灵活性：支持多模型自由切换，无厂商锁定；可单独配置 Embedding 向量模型、对话大模型。
• 成本优化：支持拆分计费，优化使用成本。

2. 知识库管理（RAG 核心）

• 多格式导入：支持 PDF/Word/TXT/Markdown/Excel/网页 URL/飞书文档等 10+ 格式，支持单文件上传、批量模板导入（CSV/Excel）。
• 智能处理：自动文本拆分、向量化入库；支持自定义高级分段（正则配置标题/目录拆分规则，适配说明书、规章制度）。
• 知识库权限：分目录管理、用户读写权限隔离，支持多知识库独立隔离调用。
• RAG 检索优化：精准召回文档片段，大幅降低大模型“幻觉”，问答结果绑定原文来源。

3. 工作流 Workflow（零代码业务自动化）

• 可视化编排：支持 BPMN2.0 标准，非开发人员通过拖拽配置业务逻辑（知识库查询→接口调用→数据筛选→自动回复全链路自动化）。
• 工具库集成：内置 MCP 工具库（数据库查询、HTTP 接口、文件解析、数据计算），可自定义函数对接企业 CRM/ERP 系统。

4. 智能体 Agent（高阶 AI 应用）

• 预制模板：内置客服、校园助手、政务咨询等预制模板，一键生成专属 AI 智能体。
• 组合能力：组合知识库 + 工作流 + 工具，实现自主思考、主动调用系统数据、完成复杂业务操作。

5. 应用&嵌入（对外输出 AI 能力）

• 前端对话组件：一键生成悬浮聊天窗口，零代码嵌入官网、企业微信、钉钉、飞书、H5、小程序。
• 开放 API：全量 AI 能力对外开放，业务系统通过 API 调用 MaxKB 实现智能审核、自动决策、知识库问答。
• 多端适配：支持网页端、移动端 H5、企业 IM 一站式接入。

（二）落地应用场景

1. 智能客服：如华莱士、深圳通落地案例，实现 7×24 小时自动答疑，降低人工客服成本、提升自助解决率。
2. 智慧办公：用于企业内部制度、产品手册、员工培训知识库，实现员工自助查资料。
3. 校园服务：如中国农业大学 AI 助手，实现教务、后勤、学术资源智能问答。
4. 政企/制造/医疗：应用于政策知识库、设备维保知识库、病历资料智能检索。

三、适用人群

1. 免费社区版适用

• 个人开发者/AI 爱好者：用于自建本地知识库、私人文档问答机器人。
• 小微团队（≤10 人）：初创公司、个体户搭建产品客服、内部知识库。
• 高校/科研：师生搭建论文资料库、院系咨询助手。
• 技术运维：适配 1Panel、JumpServer 老用户配套内部 AI 知识库。

2. 付费专业版适用

• 目标客群：中小型企业（10~500 人），涵盖零售、连锁、教培、中小企业 IT 部门。
• 需求场景：需要正式落地客服 + 内部知识库，需要官方技术支持、单点登录 SSO、LDAP 权限管理。

3. 企业版适用

• 目标客群：中大型集团、政府单位。
• 需求场景：多分支机构、多租户隔离、集群部署、7×24 小时技术服务，政务、央企、大型医疗机构定制化 AI 项目。

四、免费&付费版本明细

官网定价参考：https://www.maxkb.cn/price

1. 社区版（开源免费 GPL v3）

• 费用：永久免费。
• 核心权限：
• 全量基础功能（无限制知识库/应用/用户数）。
• RAG、基础工作流、API、全部嵌入能力。
• 社区论坛答疑。
• 限制说明：无官方一对一技术支持。
• 适用场景：个人、小微团队、测试验证场景。

2. 专业版

• 费用：4.8 万元/套（永久授权）。
• 维保政策：首年维保免费，次年维保 9600 元/年。
• 核心权限（包含社区全部功能）：
• 高级权限：SSO/LDAP/细粒度 RBAC 权限。
• 数据管理：单机冷备份、数据审计。
• 技术支持：5×8 小时官方技术支持、专属升级服务。
• 适用场景：中小企业商用落地生产环境。

3. 企业版

• 费用：按需报价（联系销售）。
• 核心权限（包含专业版 +）：
• 集群部署、多租户架构。
• 定制开发、7×24 全天候售后。
• 私有化定制部署、现场技术服务。
• 适用场景：大型集团、政府项目。

4. 额外成本提醒

• 模型调用费：MaxKB 软件本身免费/付费，但对接第三方大模型 API 会产生 token 计费（如 OpenAI、通义千问按量扣费）。
• 硬件成本：本地部署私有大模型需自备 GPU 硬件成本（Ollama 本地模型无 API 费用）。

五、详细使用指南（从零落地三步法）

第一步：部署安装（2 种主流方式）

方式 1：Docker 一键部署（新手首选）

• 适用范围：Windows/Linux/国产系统通用。
• 操作步骤：

1. 执行部署命令：
2. bash

docker run -d --name=maxkb --restart=always -p 8080:8080 registry.cn-guangzhou.aliyuncs.com/maxkb/maxkb:latest
docker run -d --name=maxkb --restart=always -p 8080:8080 registry.cn-guangzhou.aliyuncs.com/maxkb/maxkb:latest

1. 访问入口：浏览器访问 http://服务器 IP:8080。
2. 首次登录：使用默认管理员账号登录，强制修改密码。
3. 注意：云服务器需在安全组开放 8080 端口。

方式 2：Linux 离线安装包（生产环境推荐）

• 适用范围：适配麒麟、统信等国产操作系统。
• 操作步骤：

1. 从官网下载 Linux 安装包。
2. 在服务器进行解压。
3. 执行 bash install.sh 脚本安装。

第二步：初始化配置（3 步搭建第一个 AI 问答）

1. 接入大模型

• 路径：模型→新增模型。
• 新手优选：云端 API（通义千问免费额度、DeepSeek 免费 API），填入 API 地址 + 密钥。
• 隐私优先：本地 Ollama 部署 Qwen/Llama，填写内网 IP 地址对接（禁止填 localhost/127.0.0.1）。

1. 创建知识库+导入文档

• 路径：知识库→新建知识库→上传 PDF/产品手册。
• 智能处理：系统自动拆分向量化。
• 高级配置：格式杂乱文档用高级自定义分段（正则）优化切片。

1. 创建 AI 应用（智能体）

• 路径：智能体→新建应用。
• 绑定资源：绑定已建知识库 + 已接入大模型。
• 生成测试：一键生成对话机器人，预览测试问答效果。

第三步：系统嵌入落地

• 网页嵌入进入应用设置→获取 JS 嵌入代码。
• 粘贴到官网前端，自动生成悬浮客服按钮。
• 企业 IM在企业微信/钉钉应用配置中，填写 MaxKB 域名 +API Key。
• 一键接入内部机器人。
• 系统对接后台 API 页面获取访问密钥。
• 业务系统调用 API 实现问答集成。

六、避坑指南（高频踩坑点 + 解决方案）

1. 部署访问类坑

• 部署后打不开 8080 页面原因：防火墙/云安全组未放行端口、8080 被其他程序占用。
• 解决：更换端口 -p 9000:8080 重新部署，开放服务器防火墙端口；执行 docker logs maxkb 查看启动日志定位异常。
• 虚拟机对接本机 Ollama 提示 API 无效原因：模型地址填 localhost/127.0.0.1。
• 解决：填写宿主机局域网 IP:11434，开启 OLLAMA_HOST=0.0.0.0 允许外网访问。

2. 知识库&问答类坑

• 文档上传成功但不显示/一直在处理中原因：Nginx 反向代理限制文件大小、缺少 OCR 解析组件、文档损坏。
• 解决：修改代理上传限制，PDF 图片文档开启 OCR 识别，拆分超大文件分批上传。
• AI 回答和知识库内容不符、胡乱编造（幻觉）原因：文档拆分过粗/过细、模型参数不合适、知识库缺相关内容。
• 解决：高级分段优化切片，小参数 7B 模型换更大参数模型，补充缺失文档；开启 RAG 引用原文溯源开关。
• 批量 Excel 导入知识库全报错原因：表格合并单元格、单元格以=开头（被识别公式）、多问题用回车换行。
• 解决：使用官方 CSV 模板，多问题 Alt+Enter 换行，清除特殊公式字符。

3. 成本&版本选型坑

• 社区版够用盲目买专业版避坑：小微团队先用社区版跑通业务，生产上线、需要官方售后再升级付费；社区版无功能阉割，仅缺少企业级运维功能。
• 全量用付费云端 API 导致高额账单避坑：高频内部知识库问答搭配本地 Ollama 免费开源模型，对外客服用按量付费云端模型，分流成本。

4. 生产环境安全坑

• 公网裸奔 8080 端口无加密避坑：生产环境配置 Nginx 反向代理 +HTTPS 证书，隐藏原生 8080 端口，避免接口被恶意调用；定期修改管理员密码、限制 API 密钥访问 IP。