# Open WebUI 自定义 API：连接模型与排查功能差异

> 在 Open WebUI 添加兼容 API，区分模型发现与真实生成，分别核对聊天、向量、附件和后台任务，避免误判连接成功。

_发布 2026-09-29 · 更新 2026-09-29 · [KeepRouter Editorial](https://keeprouter.com/editorial-policy#editorial-team) · 5 分钟阅读_

![应用、AI Gateway 与模型供应商之间的分层责任图](https://keeprouter.com/editorial/blog/ai-gateway-guide.png)

_应用通过明确的请求边界连接模型 API。概念示意图。_

在 Open WebUI 的管理员 Connections 中添加兼容 API，填写服务的基础地址与 Key。模型列表发现和真实聊天生成是两项检查，不能因为模型出现在列表里，就认定向量、工具、图片或语音都能用。

本文针对已有 Open WebUI 实例增加 KeepRouter 聊天连接，不涉及把新服务开放成无需认证的公网入口。

## 添加独立连接

按[官方兼容服务文档](https://docs.openwebui.com/getting-started/quick-start/connect-a-provider/starting-with-openai-compatible/)进入 Settings、Admin、Connections。保留旧连接，新增一个测试项。

| 设置 | 起步值 |
| --- | --- |
| 协议 | OpenAI 兼容聊天 |
| 地址 | `https://keeprouter.com/v1` |
| 凭证 | 管理员保存的 KeepRouter Key |
| 型号 | 先用 `free` 检查文本访问 |
| 额外能力 | 每项验证后再开启 |

通用兼容服务使用默认 provider 提示。不要选择本地模型服务器专属模式；托管 API 不会因为 UI 显示按钮，就支持下载或卸载本地模型。

## 分别确认列表与回答

官方文档说明，连接验证通常调用模型列表端点。某些服务需要手工填写型号；保存成功、列表成功和生成成功不是同一回事。

新建聊天，明确选择测试连接中的 `free`，输入“项目代码是 cedar-17，请只返回代码”。检查正常完成。相同模型来自多个连接时，给显示名加上清楚区别，避免不知道请求发往哪里。

这只验证文本路径，不证明代码、视觉或推理质量。付费候选还需核对准确 ID、价格和账户余额，再做针对性测试。

## 界面功能要对应真实后端

| 功能 | 要单独确认 |
| --- | --- |
| 聊天 | 消息与流式返回 |
| 文档检索 | 解析服务与向量模型 |
| 语音 | 对应 speech 端点 |
| 图像生成 | 请求格式与图片 API |
| 工具 | 谁执行、怎样授权 |
| 标题 | 使用哪个后台模型 |

文件上传成功，不等于检索成功；出现工具按钮，也不代表模型会返回正确工具参数。每次新增一项能力：用唯一句子检查文档检索，用中性短句检查语音，用只读操作检查工具。

## 确认实际从哪里发请求

普通部署由 Open WebUI 后端访问 API。本机能访问，不代表容器中的 DNS、代理和证书配置也正常，应检查真正发送请求的进程。

[Direct Connections 文档](https://docs.openwebui.com/features/chat-conversations/direct-connections/)描述了浏览器直连模式，会改变凭证与网络要求。不要只为绕开后端问题而随意切换架构。

本地服务器的 `localhost` 指向当前机器或容器，与公网 HTTPS 服务是另一种情况。给托管 API 换成容器主机名并不能通用地解决连接错误。

## 计入后台调用

对话标题、标签、检索等配置可能触发额外模型。十位用户每人发送二十条消息，是二百条可见消息；标题通常按新会话产生，应根据真实会话数量另计，不能默认每条消息都有一次标题请求。

最终检查有用的完整对话，而非只统计 HTTP 成功。快速回答但忽略附件证据，对用户仍然无效。

用[目录](/models)和[快速开始](/docs/quickstart)确认基本访问；加入文档后参考 [RAG 费用指南](/zh/blog/rag-api-cost-per-query)。新连接通过实际依赖的功能之前，保留旧连接。

## 常见问题

### Verify Connection 会测试真实生成吗？

它主要检查文档所述的模型列表连接。还要单独发送聊天请求，并验证工作流实际使用的功能。

### 浏览器测试成功，应用为什么失败？

服务器或容器可能使用不同网络路径。应排查实际发送 API 请求的组件。

### 一个聊天连接能支持所有媒体功能吗？

不能。语音、图片和向量需要对应端点与型号，应分别配置和测试。

## 参考的一手资料

_本文最近复核 2026-09-29_

1. [Open WebUI compatible providers](https://docs.openwebui.com/getting-started/quick-start/connect-a-provider/starting-with-openai-compatible/)
2. [Open WebUI direct connections](https://docs.openwebui.com/features/chat-conversations/direct-connections/)

## 继续阅读

- [LibreChat 自定义端点：模型、标题与 API 费用](https://keeprouter.com/zh/blog/librechat-custom-endpoint.md)
- [RAG 每次查询多少钱：别只计算生成 token](https://keeprouter.com/zh/blog/rag-api-cost-per-query.md)
- [quickstart](https://keeprouter.com/docs/quickstart.md)
- [Ollama 本地模型与托管 API：成本、容量与盈亏平衡](https://keeprouter.com/zh/blog/ollama-vs-hosted-api-cost.md)

## 用一条小请求试用接入配置

按步骤设置，把密钥保留在服务端，并检查返回的答案与用量。

[打开接入指南](https://keeprouter.com/docs/quickstart)

[创建 Key，测试免费模型](https://keeprouter.com/login?returnTo=%2Fconsole%2Fkeys%3Fmodel%3Dfree)

免费测试使用 free 模型；其他付费型号需要足够预付额度。

[全部文章](https://keeprouter.com/zh/blog.md) · [模型与价格](https://keeprouter.com/models.md)