# 通过 OpenAI 供应商把 MaxKB 接到 Router One

> https://router.one/zh/integrations/maxkb 的 Markdown 镜像，供 AI 助手与爬虫使用。Router One 是 OpenAI 兼容的统一 LLM API 网关。
> 最后更新：2026-09-20

MaxKB 用于搭建知识库助手与智能体工作流。它的 OpenAI 供应商可以把兼容的聊天模型请求发给 Router One；知识库、检索、工具与工作流执行仍由 MaxKB 负责。本指南面向 MaxKB v2.10.6-lts 的模型表单与 OpenAI 适配器。

## 把 MaxKB 配置到 Router One base URL

打开「模型」，选择 OpenAI 供应商添加模型。「模型名称」是显示标签，「基础模型」才是发给 API 的 ID。在「基础模型」中输入 /models 里当前可用的完整聊天模型 ID，保留厂商前缀，即使预设下拉列表没有也可以手动输入。「模型类型」选「大语言模型」，API URL 填 https://api.router.one/v1；官方文档也把这个字段叫「API 域名」。API Key 填专用 Router One Key。这个供应商使用 Chat Completions 客户端，因此 API URL 后面不要再加 /chat/completions。保存成功后，在简易智能体的 AI 模型或 AI 对话节点中选用新建模型。

`maxkb-openai-model`

```text
# MaxKB → 模型 / Models → OpenAI → 添加模型 / Add model
模型名称 / Model name:      Router One chat
模型类型 / Model type:      大语言模型 / LLM
基础模型 / Base model:      <exact-model-id-from-/models>
API URL:                    https://api.router.one/v1
API Key:                    sk-your-router-one-key

# 保存后，在智能体中选用这个模型 / Select this model in your agent after saving
# 向量模型另配 / Configure the knowledge-base embedding model separately
```

## 两个名称，只有一个是真正的模型 ID

模型名称方便你在 MaxKB 中区分资源，改名不会改变网关实际调用的模型。「基础模型」是可输入的下拉框，不是从 Router One 拉取的目录。v2.10.6-lts 适配器把它直接作为 model 参数发送，不去掉厂商前缀。供应商名称 OpenAI 选择的是兼容协议，不要求必须使用 OpenAI 系列模型；从 Router One 详情页选择支持 Chat Completions 的 ID 即可。

| MaxKB 字段 | 填写内容 | 实际作用 |
| --- | --- | --- |
| 供应商 | OpenAI | 选择 OpenAI 兼容聊天适配器 |
| 模型名称 | Router One chat | 只在 MaxKB 内使用的显示标签 |
| 模型类型 | 大语言模型 / LLM | 聊天模型的位置 |
| 基础模型 | /models 中的精确 ID | 原样发给 API |
| API URL / API 域名 | https://api.router.one/v1 | 基础地址，不是完整的生成端点 |
| API Key | 专用 Router One Key | 验证与后续请求所用的凭据 |

## 保存时会真实调用模型验证

v2.10.6-lts 的凭据验证器会用一句问候调用所选模型，因此最终用户尚未聊天，保存测试就可能产生 token 用量。该版本 OpenAI 大语言模型的参数表单默认提供 temperature 0.7 和最大输出 8192 tokens；这是 MaxKB 默认值，不是 Router One 的推荐参数，也不是上下文窗口。若错误点名 temperature 或输出 token 参数，先在「高级设置」或「模型参数设置」中删除或调整不支持的参数，再重试。保留完整错误；换 Key 或修改 base URL 不能解决模型对某个参数的拒绝。

## 把知识检索与模型计费分开核对

知识库需要单独选择向量模型。让它使用本地模型或其他供应商：Router One 不提供 embeddings 或 reranking 端点。大语言模型验证成功，不代表文档索引已通过验证。「问题优化」、知识库文档的「生成问题」和 AI 对话节点都可能在最终回答之外增加模型调用。使用设了 maxSpend 的专用 Key，先用一份小文档验证，再在 Dashboard → Logs 按时间、模型和 request_id 核对请求。MaxKB 的对话历史和 token 估算不是网关结算记录。

## MaxKB 该填哪个模型 ID？

从 /models 页复制精确的模型 ID，保留大小写、连字符和版本后缀，不要用展示名称代替。打开该模型的详情页，核对支持的 API 端点、上下文窗口和工具调用等能力，再与 MaxKB 当前选择的 provider 和功能对应。模型出现在目录里，不等于当前客户端能调用它的所有功能。建议为每个工具单独建 API Key，并设置 maxSpend 消费上限。

## MaxKB 用的是哪种 API 协议？

OpenAI 兼容描述的是接口格式，不能据此推断 Chat Completions（/v1/chat/completions）、Responses（/v1/responses）和 Anthropic Messages（/v1/messages）可以互换。先核对工具当前版本、provider 配置和实际请求路径，再查模型详情与 API 兼容性事实页。一次普通对话成功，也不能证明服务端工具、历史状态或文件编辑功能都受支持。

## 在 trace 里验证 MaxKB 的调用

先在 MaxKB 发出一次简单文本请求，再到 Dashboard → Logs 按时间、模型和 request_id 核对 trace：tokens、花费、延迟和状态码。成功后再分别验证流式输出、工具调用和多轮历史。失败时保留实际请求路径、完整错误消息及 request_id；没有对应日志时，先查客户端配置和网络，不能仅凭客户端报错认定是网关或上游故障。

## 常见问题

### 基础模型下拉列表没有 Router One 的精确 ID，还能添加吗？

可以。官方 OpenAI 接入文档允许自定义输入，v2.10.6-lts 表单也为「基础模型」下拉框开启了 allow-create。把完整 ID 输在这里并确认新选项；只把它填进「模型名称」会修改显示标签，不会改变实际请求。本指南走 Chat Completions，即使目录 ID 以 anthropic/ 或 google/ 开头，供应商仍选 OpenAI。

### 添加模型时报连接或验证失败，应该先查什么？

先看原始错误和 MaxKB 服务端日志。请求路径只有 /chat/completions、缺少 /v1，说明 API URL 没填完整；路径重复出现生成端点，说明把完整 endpoint 当成了 base URL。401 检查 Key，400 检查精确模型 ID 或错误点名的参数。请求由 MaxKB 服务器或容器发出，因此要检查它的出站 HTTPS 与 DNS。Dashboard 没有日志本身不能证明网络失败：部分记录可能尚待定价，应优先依据实际响应或服务端日志判断。

### 聊天模型可用，但文档向量化失败，能否复用这组连接？

不能。MaxKB 把大语言模型与向量模型作为不同资源管理。新建或选择提供 Embedding API 的模型，再到知识库设置中选用。OpenAI 供应商表单里有「向量模型」这个类型，不代表 Router One 实现了相应端点。语音等其他模型类型也不属于本篇聊天接入范围，需要另外核对端点兼容性。

### MaxKB 能通过网关用哪些模型？

选用当前目录中同时支持 MaxKB 所用端点和所需功能的模型。精确 ID、当前单价与能力以 /models 及模型详情为准；不要仅按 GPT、Claude 等系列名判断兼容性。客户端能列出模型，只证明模型发现成功，仍需验证实际调用。

### 能列出模型，但调用报 400 或 404，怎么办？

先记录实际请求路径和错误消息，再核对精确模型 ID。400 可能是参数、工具类型或模型与端点不匹配；404 可能是请求路径或资源不存在，不能直接判定模型下线。若错误提示 must be called via，按它指明的端点调整客户端 provider，或换用支持当前端点的模型。不要在所有工具里统一增删 /v1 或 /chat/completions。

### 中国大陆能直连吗？

能。网关在大陆可直连、无需 VPN，配置与全球环境完全一致。

### 报 401/402/403/429 怎么排查？

先到 Dashboard → Logs 核对请求及错误消息。401 查 Key 是否传入和有效；402 查钱包余额与 maxSpend；403 查 Key 权限和访问限制；429 查请求频率、token 限额及上游限流，按错误来源处理。保留 request_id，再按错误码速查页逐项排查。

## 相关页面

- 全部接入指南：https://router.one/zh/integrations
- MaxKB 的 API 错误排查：https://router.one/zh/llm-api-error-codes
- API 兼容性：端点与功能对照：https://router.one/zh/facts/api-compatibility.md
- Responses API 配置与限制：https://router.one/zh/codex-responses-api
- Pi Agent 接入：https://router.one/zh/integrations/pi
- Cline 接入：https://router.one/zh/integrations/cline
- RAGFlow 接入与 Embedding 边界：https://router.one/zh/integrations/ragflow
- FastGPT 接入：另一种知识库应用：https://router.one/zh/integrations/fastgpt
- 连接与 API 路径排查：https://router.one/zh/api-connection-troubleshooting
- MaxKB 官方文档：对接 OpenAI：https://maxkb.cn/docs/v2/user_manual/model/openai_model.html
- MaxKB 官方文档：模型参数设置：https://maxkb.cn/docs/v2/user_manual/model/model_param.html
- MaxKB v2.10.6-lts 源码：模型凭据与验证：https://github.com/1Panel-dev/MaxKB/blob/v2.10.6-lts/apps/models_provider/impl/openai_model_provider/credential/llm.py
- MaxKB 官方文档：知识库模型选择：https://maxkb.cn/docs/v2/user_manual/dataset/dataset.html
- 网关层负责什么：https://router.one/zh/llm-api-gateway
- OpenAI 兼容 API：https://router.one/zh/openai-compatible-api
- API 文档：https://router.one/zh/docs
- 本页规范地址：https://router.one/zh/integrations/maxkb
- 模型与每模型 token 价格：https://router.one/zh/models （markdown：https://router.one/zh/models.md ）
- 定价：https://router.one/zh/pricing
- API 文档（markdown）：https://router.one/zh/docs.md
- 公司事实（markdown）：https://router.one/zh/facts/company.md