Open WebUI 自定义 API：连接模型与排查功能差异
在 Open WebUI 添加兼容 API，区分模型发现与真实生成，分别核对聊天、向量、附件和后台任务，避免误判连接成功。
发布 2026-09-29 · 更新 2026-09-29 · KeepRouter Editorial · 5 分钟阅读
在 Open WebUI 的管理员 Connections 中添加兼容 API，填写服务的基础地址与 Key。模型列表发现和真实聊天生成是两项检查，不能因为模型出现在列表里，就认定向量、工具、图片或语音都能用。
本文针对已有 Open WebUI 实例增加 KeepRouter 聊天连接，不涉及把新服务开放成无需认证的公网入口。
添加独立连接
按官方兼容服务文档进入 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 文档描述了浏览器直连模式，会改变凭证与网络要求。不要只为绕开后端问题而随意切换架构。
本地服务器的 localhost 指向当前机器或容器，与公网 HTTPS 服务是另一种情况。给托管 API 换成容器主机名并不能通用地解决连接错误。
计入后台调用
对话标题、标签、检索等配置可能触发额外模型。十位用户每人发送二十条消息，是二百条可见消息；标题通常按新会话产生，应根据真实会话数量另计，不能默认每条消息都有一次标题请求。
最终检查有用的完整对话，而非只统计 HTTP 成功。快速回答但忽略附件证据，对用户仍然无效。
用目录和快速开始确认基本访问；加入文档后参考 RAG 费用指南。新连接通过实际依赖的功能之前，保留旧连接。
常见问题
Verify Connection 会测试真实生成吗？
它主要检查文档所述的模型列表连接。还要单独发送聊天请求，并验证工作流实际使用的功能。
浏览器测试成功，应用为什么失败？
服务器或容器可能使用不同网络路径。应排查实际发送 API 请求的组件。
一个聊天连接能支持所有媒体功能吗？
不能。语音、图片和向量需要对应端点与型号，应分别配置和测试。
参考的一手资料
本文最近复核 2026-09-29