MaxKB 私有化部署及高级应用配置指南

1. 创建站点

在宝塔面板的 网站 部分，点击 添加站点。创建一个纯静态站点，域名填写你准备好的域名（如 ai.xxx.com），根目录会自动生成（如 /www/wwwroot/ai.xxx.com），直接创建即可。

2. 修改 Nginx 配置文件

回到网站列表，点击你刚创建站点右侧的 设置，切换到 配置文件 选项卡。找到 root /www/wwwroot/ai.xxx.com; 这一行，在它的正下方，粘贴以下已经为你准备好的配置代码：

# CORS 跨域设置
add_header Access-Control-Allow-Origin '*' always;
add_header Access-Control-Allow-Methods 'GET,POST,OPTIONS' always;
add_header Access-Control-Allow-Headers 'DNT,X-Mx-ReqToken,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Authorization,Access-Token,Token,formhash,shebei,token' always;

# 处理 OPTIONS 预检请求
if ($request_method = 'OPTIONS') {
    return 204;
}

# 规则 1: 优先处理静态 UI 文件
location /ui {
    try_files $uri $uri/ @backend_proxy;
}

# 规则 2: 捕获所有其他请求转发至后端
location @backend_proxy {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Real-Port $remote_port;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Port $server_port;
    proxy_set_header REMOTE-HOST $remote_addr;
    proxy_connect_timeout 60s;
    proxy_send_timeout 600s;
    proxy_read_timeout 600s;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
}

3. 添加 Docker 卷映射（关键一步）

这一步的目的是让 Nginx 能直接访问到 MaxKB 容器内部的前端界面文件，实现动静分离，可以大大加快页面的加载速度。

• 进入宝塔面板 docker -> 容器 -> 找到 maxkb 容器 -> 点击 管理 -> 编辑容器。 • 点击 更多设置，点击查看，找到 挂载/映射 部分。 • 点击 本机目录，新增一条映射规则： • 本机目录：填入 /www/wwwroot/ai.xxx.com/ui (也就是你在第 1 步创建的那个 ui 文件夹) • 容器目录：填入 /opt/maxkb/app/ui/dist/ui (这是 MaxKB 容器内 UI 文件的固定路径，直接复制粘贴即可)

• 将页面拉到最底部，点击保存。容器会自动重启以应用新的设置。

一切就绪！现在，打开浏览器，输入你的域名 http://ai.xxx.com/ui，你应该就能看到 MaxKB 的登录界面了。

三、使用自定义向量模型：m3e-base

什么是向量模型？ 简单来说，它就像一个'翻译官'，能把我们的文字（比如你的文档和用户的问题）翻译成计算机能理解的数学语言（向量）。只有翻译得准，计算机才能准确地在你的知识库里找到最相关的内容。

虽然 MaxKB 自带了向量模型，但我们可以换一个在中文处理上更优秀的模型，比如 m3e-base。

1. 下载模型文件

访问 Hugging Face 模型页面 https://huggingface.co/moka-ai/m3e-base/tree/main ，将页面上看到的所有文件都下载到你的电脑上。

2. 在服务器上创建并上传模型

• 在宝塔面板的 文件 管理中，进入 / 根目录，然后依次创建 /opt/maxkb/model 这两层目录。

• 在 /opt/maxkb/model 目录下，按照这个层级 models--moka-ai--m3e-base 创建新的文件夹，然后将你第一步下载的所有 m3e-base 模型文件，全部上传到这个新建的 m3e-base 文件夹里。

• （可选但推荐）回到终端，执行 cd /opt/maxkb && docker cp maxkb:/opt/maxkb/model . 命令，将容器内的默认模型复制出来作为备份。

如果你觉的一个个下载模型太麻烦，可以直接使用脚本下载。必须保证服务器已安装 python3.8+版本和 git 工具，然后依次执行下列命令。

如果你的机器配置比较高，也可以使用 m3e-small 模型，效果会更好，只需要将上述示例中的 base 字符都改成 small。

3. 将模型目录挂载到容器

和上一步类似，再次编辑 maxkb 容器，添加一条新的卷映射：

• 本机目录：/opt/maxkb/model • 容器目录：/opt/maxkb/model

保存并等待容器重启。

4. 在 MaxKB 后台添加新模型

登录 MaxKB，进入 系统设置 -> 模型设置 -> 添加模型，选择 本地模型。

• 模型名称：可以随意取，比如 m3e。 • 模型类型：务必选择 向量模型。 • 基础模型 和 模型目录：都填写你上传模型的绝对路径 /opt/maxkb/model/models--moka-ai--m3e-base。为避免出错，建议直接复制粘贴这个路径。

点击保存。如果没有报错，就说明添加成功了！如果报错，99% 的可能是你填写的路径和服务器上的实际路径不符，请仔细检查。

成功后效果如图：

四、添加 DeepSeek 大语言模型

如果说向量模型是帮你找资料的'图书管理员'，那大语言模型（LLM）就是阅读资料并组织语言回答你的'专家'。这里我们添加一个性价比很高的 DeepSeek 模型。

在 模型设置 中，点击 添加模型，选择 DeepSeek。填写一个自定义名称（如 deepseek-chat），模型选择 deepseek-chat，然后将在 DeepSeek 官网获取的 API Key 填入即可。

五、创建知识库及注意事项

这是最核心的一环，知识库的质量直接决定了你的 AI 助手的'智商'。

1. 创建时务必选对向量模型

点击 知识库 -> 新建知识库。在创建界面，最重要的一步是 向量模型 的选择，请选择我们刚刚添加的 m3e。一旦知识库创建并导入了文档，再想更换模型，就意味着所有文档都要删掉重来，非常耗时耗力！

2. 知识库上传法则

• 法则一：小文件，分批传。 虽然系统提示可以上传很大的文件，但除非你的服务器是'天河二号'，否则请务必将大文档（比如一个超过 20MB 的文件）手动拆分成多个小文件。单次上传的文件数量也最好控制在 5 个以内，否则下一步的预览可能会失败，造成无法导入。 • 法则二：忽略'假失败'，查看真进度。 当你上传了稍大的文件并开始导入后，前端页面可能会因为等待超时而显示红色的 失败 提示。别慌！这通常是假象！ 后端的向量化任务其实还在勤勤恳恳地运行。你可以忽略这个提示，直接到知识库的文件列表页面，那里会显示真实的处理进度。当然，最好的策略还是遵守第一条法则，从源头上避免这个问题。 • 法则三：开启'混合检索'。 在知识库的设置里，强烈建议开启'混合检索'。它会同时使用语义（像人一样理解）和关键词（像传统搜索一样）两种方式来查找，能大大提高找到正确信息的概率。

六、创建高级应用：给你的 AI 装上'大脑'

高级应用是 MaxKB 的精髓所在。它让你能像搭积木一样，设计 AI 的工作流程。

进入编辑界面后，你会看到一个流程图画布。

操作铁律：对画布的任何修改，都必须点击右上角的 保存。保存后，必须点击 发布，你的改动才能在聊天窗口真正生效。

核心概念：节点与变量

• 节点：画布上的每一个方块都是一个'节点'，代表一个功能，比如'开始'、'知识库检索'。每个节点左上角都有一个中文名字，我们可以修改它。 • 变量：节点之间通过'变量'来传递信息。变量的格式是固定的：{{节点名。输出变量名}}。 • 举例说明：{{开始.question}} 的意思是：找到名为 开始 的那个节点，获取它输出的一个名为 question 的变量的值。在默认流程里，这个值就是用户输入的问题。同理，{{知识库检索.data}} 就是获取 知识库检索 节点找到的知识片段。

默认流程详解

1. 开始：这是起点。用户输入一句话，这个节点就把它打包成一个名为 question 的变量。
2. 知识库检索：这是'图书管理员'。它的'检索问题'栏里需要填入 {{开始.question}}，告诉它要根据用户的问题去知识库里找资料。它找到的资料会打包成 data 变量。
3. 判断器：这是'交通警察'。它根据条件指挥流程走向。例如，它可以判断 知识库检索.data 是否为空，如果找到了资料就走 IF 分支，没找到就走 ELSE 分支。
4. AI 对话：这是'专家'。它最重要的设置是 提示词 (Prompt)，也就是给 AI 下达的指令。

一个优秀的提示词模板：

你是 XX 公司的专业客服。请严格根据下面 [已知信息] 来回答用户的 [问题]，禁止使用任何你自己的知识或进行编造。如果 [已知信息] 中没有答案，就回复："抱歉，关于您的问题，我暂时没有找到相关信息。"
[已知信息]：{{知识库检索.data}}
[问题]：{{开始.question}} 

这个模板清晰地告诉 AI 它的角色、信息来源、回答的依据以及找不到答案时的标准回复。

玩法升级：使用'函数'组件

假如你想在每个回答后面都自动加上一个时间戳，怎么办？'函数'节点可以帮你实现！

实战：为 AI 的回答添加时间戳

1. 添加节点：在'AI 对话'节点之后，从右侧组件列表拖入一个'函数'节点，并用鼠标将它们连接起来。
2. 编写代码：点击'函数'节点进行设置。在代码编辑器里，粘贴以下 Python 代码：

import datetime

# 这是固定的函数入口，ai_answer 是我们自己定义的输入参数名
def process(ai_answer: str) -> dict:
    # 获取 AI 的原始回答
    # ai_answer 这个变量名可以自己取，但要和下面的输入参数设置保持一致
    
    # 获取当前北京时间并格式化
    beijing_time = datetime.datetime.utcnow() + datetime.timedelta(hours=8)
    time_str = beijing_time.strftime("%Y-%m-%d %H:%M:%S")
    
    # 将原始回答和时间戳拼接成新的文本
    final_response = f"{ai_answer}\n\n—\n*该回答由 AI 生成于 {time_str}*"
    
    # 将处理结果以字典形式返回
    # "response_with_timestamp" 将成为这个函数节点的输出变量名
    return {"response_with_timestamp": final_response}

3. 配置输入参数：在函数节点的'输入参数'部分，点击'添加'，参数名填写 ai_answer（与代码中保持一致），参数值填写 {{AI 对话.answer}}。这一步是告诉函数，它的输入数据来自哪里。
4. 使用函数输出：这个函数执行后，会产生一个名为 response_with_timestamp 的新变量。现在，在流程最后的'结束'节点里，将它的 answer 字段的值从原来的 {{AI 对话.answer}} 改为 {{函数.response_with_timestamp}}。

通过以上步骤，你就成功地对 AI 的输出进行了自定义加工！MaxKB 的强大之处就在于此，通过这些节点的自由组合，你可以创造出满足各种复杂需求的智能应用。