MaxKB 接入 OpenAI 兼容 API：模型、知识库与智能体完整教程¶

最后核验：2026-07-14

适用范围：MaxKB v2 当前社区版；部分权限与系统 API 能力以具体版本/授权为准

推荐路径：大语言模型、向量模型、命中测试、智能体逐步验证

← 返回教程目录

[!NOTE] 本文适用于任何符合对应协议的 API。还没有测试 Key 时，可查看教程配套 API。

1. 官方确认的接入方式¶

MaxKB 官方“对接 OpenAI”文档允许在模型表单中填写：模型类型、可自定义基础模型、API 域名 和 API Key，并明确 API 域名使用版本根路径格式。可分别添加大语言模型和向量模型。

需要区分：

大语言模型负责生成答案；
向量模型负责文档与问题的向量化；
重排模型是独立模型类型，OpenAI 兼容并不自动意味着支持 Rerank；
智能体 API Key 用于调用已发布智能体，不是模型 API Key。

2. 部署要求与安装¶

官方在线安装页当前建议 4 核/8 GiB 以上、100 GiB 磁盘；生产环境官方更推荐离线安装。在线测试部署：

docker run -d \
  --name=maxkb \
  --restart=always \
  -p 8080:8080 \
  -v <宿主机持久化目录>:/opt/maxkb \
  registry.fit2cloud.com/maxkb/maxkb:<固定版本>

访问：

http://<服务器地址>:8080

首次登录立即修改默认管理员密码。生产环境使用固定版本、HTTPS、反向代理与防火墙；数据库不应对公网开放。

若使用官方离线安装包：

bash install.sh
mkctl status

运行目录默认在 /opt/maxkb，安装时可调整。

3. 准备模型信息¶

API 域名: https://<你的-api-域名>/v1
大语言模型: <聊天模型ID>
向量模型: <Embedding模型ID>
模型 API Key: <你的API-Key>

正确的 API 域名停在根路径：

正确： https://<你的-api-域名>/v1
错误： https://<你的-api-域名>/v1/chat/completions
错误： https://<你的-api-域名>/v1/embeddings

4. 添加大语言模型¶

登录 MaxKB，进入 模型；
点击添加模型，供应商选择 OpenAI；
模型名称填写便于识别的名称；
模型类型选择 大语言模型；
基础模型手填 <聊天模型ID>；
API 域名填 https://<你的-api-域名>/v1；
API Key 填 <聊天专用API-Key>；
保存并执行模型校验。

最小验证只使用短文本。视觉、语音、图片生成和工具调用是不同能力，必须分别添加对应类型并单测。

5. 添加向量模型¶

再次添加模型：

字段	值
模型供应商	`OpenAI`
模型类型	`向量模型`
基础模型	`<Embedding模型ID>`
API 域名	`https://<你的-api-域名>/v1`
API Key	`<Embedding专用API-Key>`

向量模型保存成功后，先新建测试知识库，不要直接重建生产库。更换不同维度模型需要重新向量化全部文档，且应在维护窗口进行。

6. Rerank 独立链路¶

MaxKB 的模型体系支持重排模型，但官方 OpenAI 接入页没有把 重排模型 列为 OpenAI 模型类型。因此本教程不声称 OpenAI API 域名可直接配置 Rerank。

如需 Rerank：

在 MaxKB 当前版本的官方模型文档中选择明确支持 重排模型 的供应商；
使用该供应商独立凭据与正式端点；
在知识库命中测试中先对比启用前后的排序；
再用于生产智能体。

无法从官方文档确认时就跳过。基础知识库可仅用向量与关键词检索。

7. 创建最小知识库¶

进入 知识库，新建通用知识库；
选择已验证的向量模型；
上传一份短文档，写入“测试代号是 <唯一测试词>”；
检查文本解析结果；
采用自然段或标题边界分段；
等待向量化完成；
打开 命中测试；
输入对应问题，查看命中分段和分数；
再调整 Top K、阈值或独立 Rerank。

若命中错误，先处理文档解析、分段与向量模型，不要先修改聊天提示词。

8. 创建最小智能体与工作流¶

简易知识库问答：

创建智能体；
选择已验证的大语言模型；
绑定测试知识库；
要求“仅根据检索内容回答，无法确认时明确说明”；
用命中和未命中问题分别测试；
查看对话日志与引用。

高级智能体最小流程：

开始 → 知识库检索 → AI 对话 → 结束/回复

画布节点必须连入流程，节点重命名后重新核对变量引用。每次只新增一个判断、工具、循环或外部请求节点，避免故障范围过大。

9. API 与 Webhook 触发¶

MaxKB 发布的智能体可生成对话 API Key，并兼容 OpenAI 风格调用。使用智能体概览页给出的 Base URL 和 API Key；不要把模型 Key 用作智能体 Key。

当前官方触发器文档说明，事件触发器会生成 Webhook URL 与 Bearer Token。调用方应在 Header 携带 Token。

生产安全：

每个应用、环境和调用方使用独立智能体 API Key/Token；
设置有效期、跨域白名单和最小权限（具体能力依版本/授权）；
Webhook 校验 Bearer Token、时间戳、请求大小和幂等键；
反向代理启用 HTTPS、限流和访问日志脱敏；
不在前端代码、URL、提示词、工具输出或截图中放 Key；
原始异常、内部服务地址和完整执行详情不得返回外部用户。

10. Docker 网络与持久化¶

MaxKB 数据默认挂载在 /opt/maxkb。容器内访问模型服务时：

同一 Docker 网络使用目标容器服务名；
Docker Desktop 访问宿主机可用 host.docker.internal；
Linux 配置 host-gateway 或可达网关；
容器内 127.0.0.1 只指 MaxKB 容器。

用容器内请求验证 DNS、TLS 和路径。不要为了排错把 PostgreSQL 绑定到所有公网地址。

11. 权限与密钥安全¶

模型设为私有或公用前评估工作空间范围；
聊天、Embedding、Rerank 使用独立 Key 与额度；
工具的启动参数用于保存 Key，避免写入输入参数和代码；
自定义 Python 工具能访问网络和数据，应限制创建与启用权限；
管理员、工作空间管理员、普通成员按最小权限分配；
定期检查对话日志、触发器执行详情和异常用量；
删除 MaxKB 中的模型配置不会吊销外部 Key，仍需到密钥签发端处理。

12. 常见错误¶

模型校验 401 / 403¶

检查 Key、模型权限、API 域名、基础模型 ID，以及是否误用了智能体 API Key。

路径不存在：404¶

API 域名多写了具体端点、漏 /v1、代理路径改写或目标服务没有对应聊天/Embedding 接口。

大语言模型可用但向量模型失败¶

聊天成功不能证明 /embeddings 存在。检查向量模型 ID、Key 权限、输入长度和模型服务日志。

文档一直向量化或命中为空¶

检查文档解析、分段是否为空、向量模型、后台任务、磁盘和数据库状态。先在命中测试定位，不要直接重建全部生产索引。

容器升级后显示空系统¶

通常是新容器挂载了不同宿主机目录。立即停止写入，用 docker inspect maxkb 对比原挂载；不要在空实例继续配置。

429 / 超时¶

降低文档批量、工作流并发与检索候选量；限制循环；对临时错误使用有上限的退避。

13. 备份、升级、回滚与卸载¶

官方备份文档说明，MaxKB 主要运行数据位于安装运行目录，默认 /opt/maxkb。一致性备份建议：

记录当前版本、镜像和安装参数；
mkctl stop 或停止容器，避免写入；
备份完整运行目录、环境配置和外部存储；
在同版本隔离环境恢复并测试；
mkctl restart 后验证模型、知识库与智能体。

在线镜像升级前先备份，再 docker inspect maxkb 保存持久化目录，拉取固定新版本，并用完全相同的挂载创建新容器。升级后验证登录、模型、向量化、命中、智能体、API 和触发器。

回滚使用旧版本程序/镜像与升级前完整运行目录快照。不要让旧版本直接读取已被新版本迁移的数据。

卸载前确认备份。删除容器不会自动删除宿主机持久化目录；只有明确不再需要数据时才删除该目录。

14. 官方资料¶

核验结论：截至 2026-07-14，MaxKB 官方文档明确允许 OpenAI 模型填写自定义 API 域名，并支持大语言与向量模型；OpenAI 入口未确认 Rerank，因此重排只按独立官方模型文档配置。