Open WebUI 外部连接配置

先说结论:管理员设置里加一个连接

以管理员身份打开管理员设置,进入外部连接,在 OpenAI 接口板块点添加连接。两个字段最关键:URL 填 https://api.kkaiapi.com/v1,再填 API 密钥。保存之后,Open WebUI 会查询这个端点的 /v1/models 列表来填充模型选择器,用连接自带的检测按钮确认一下,然后就能在新对话里选目录里的任意 ID。 这样添加的连接是整个工作区共享的:你这个 Open WebUI 实例的所有用户都能看到这些模型,具体受你配置的模型权限控制约束。同样的值也能在部署时以环境变量的形式提供,OPENAI_API_BASE_URL 和 OPENAI_API_KEY,如果实例是靠 compose 文件而不是手动点出来的,这条路更干净。

URL:      https://api.kkaiapi.com/v1
API 密钥: sk-你的kkaiapi密钥

保存 → 模型从 /v1/models 自动填充
(可选)用模型 ID 白名单精简选择器

Open WebUI 怎么用 OpenAI 连接

Open WebUI(约 14.5 万星标)是最主流的自建 AI 对话前端:带用户和权限体系的全功能网页客户端,支持 RAG 与知识库、工具调用、模型管理,经典搭配是配合 Ollama 跑本地模型,同样能顺畅地对接远程 API。 它的连接模型是叠加式的。Ollama 板块覆盖本地运行时,OpenAI 接口板块覆盖任何说标准 chat-completions 方言的端点,你可以并排添加好几个连接。每个连接把自己的模型列表贡献给共享的选择器,各自有自己的 Key,各自可以在不删除配置的情况下单独关闭。请求把模型 ID 按纯字符串带上,发给提供这个模型的那个连接。 这个设计意味着接入网关不会替代任何东西:本地模型继续通过 Ollama 免 token 成本运行,而 claude-sonnet-5、gpt-5.5、gemini-3.5-flash、deepseek-v4-pro 会成为选择器里的条目,给那些需要旗舰质量的对话用。一个 Key 覆盖全部云端模型,管理员这边的用量也保持清楚,因为云端流量只从一个地方出去。

部署时配置:环境变量

对 docker-compose 和 Kubernetes 部署来说,这个连接可以直接写进部署清单。OPENAI_API_BASE_URL 填端点,OPENAI_API_KEY 填密钥,实例启动时连接就已经就绪。如果要接多个远程来源,复数形式(OPENAI_API_BASE_URLS 和 OPENAI_API_KEYS,用分号分隔多个值)也支持。 有两个运维细节。第一,通过界面设置的值会持久化进 Open WebUI 的数据库,首次启动之后会优先于环境变量默认值,这是文档记录在案的行为,经常让运维人员困惑地发现改了环境变量却什么都没变;要调整就在管理员设置里改现有连接,或者设置 ENABLE_PERSISTENT_CONFIG=false 让环境变量保持权威。第二,如果端点的模型列表很长,用连接自带的模型 ID 白名单来精简用户看到的内容;一个四项的选择器会被用起来,两百项的会被划过去。 版本提示:这个项目发版节奏很快,菜单文案有过漂移(设置 vs 管理员设置,外部连接内部的板块命名),旧版本上如果找不到这里写的文案,找 OpenAI 接口 base URL 和密钥这一对字段所在的位置就行。

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    environment:
      - OPENAI_API_BASE_URL=https://api.kkaiapi.com/v1
      - OPENAI_API_KEY=sk-你的kkaiapi密钥
    ports:
      - "3000:8080"

多用户工作区怎么选模型

每个云端模型都通过一个 Key 计费,A/B 测试就变成了选择器里的一次选择:同一支团队的工作负载隔两周分别跑两个候选默认值,让 kkaiapi 控制台里按模型、按天的用量视图来裁决,而不是靠跑分猜测。

• 共享实例里默认模型的选择做的功课最多。把 claude-haiku-4-5-20251001 或 gemini-3.5-flash 设成工作区默认值,能让日常随手用的单次对话成本保持平稳
• claude-sonnet-5 和 gpt-5.5 该出现在选择器里,给写作、分析、代码问题用;需要的时候用户自己会升级
• RAG 管线会放大输入 token:每条回答都带着检索出来的片段,deepseek-v4-pro 值得测试作为 RAG 主力,长上下文处理的单 token 性价比是决定性特质
• 真正私密的内容留在本地 Ollama 模型上,其余的都经网关路由;选择器如实地保留了这两条通道
• 把模型 ID 白名单当成策略来用:不在选择器里的东西不会突然出现在用量日志上

主力模型价格

价格按 kkaiapi 中文区实时价格计算,单位 ¥/1M tokens(输入/输出)。

Open WebUI 专属的翻车点

加完连接后模型列表空白是最常见的报告。原因排序:Key 没通过 /v1/models 的验证(用连接自带的检测控件确认一下)、URL 漏了 /v1 后缀、或者连接开关是关的。Open WebUI 用列表返回的内容来构建选择器,所以空选择器意味着列表调用失败或者什么都没返回。 环境变量改了却看不出变化,就是上面说的持久化配置规则:首次启动之后,界面管理的设置里数据库会赢过环境变量。在管理员设置里改连接,或者显式设置 ENABLE_PERSISTENT_CONFIG=false。 一个能列出来但聊天报错的模型,通常是列表里暴露了但你的 Key 用不了的 ID,或者手动编辑模型 ID 白名单时引入的拼写错误,对照原始的 /v1/models 输出核对一下。 排查时把通道分清楚:Ollama 连接的问题和 OpenAI 连接的问题在聊天窗口看起来一模一样。外部连接页面能看出一个模型属于哪条通道,先直接测试出问题的那条通道,别急着断定整个实例都挂了。

谁会经网关接入 Open WebUI

• 给团队自建一个对话前端、又不想给每个人都发厂商 Key 的人,想让旗舰模型直接可用
• Ollama 用户,私密工作继续留本地模型,同一个选择器里想要 Claude、GPT 质量的对话
• 需要账目清楚的管理员:一个连接、一个 Key、按模型的用量日志,而不是四家厂商各自的账单
• 一些地区厂商注册比较麻烦的用户;支付宝微信充值免翻墙,省掉逐个厂商开户的依赖
• 为家里跑 Open WebUI 的个人用户,一份预付余额比任何订阅都更好算账

验证接入与排查首次对话

先在服务器层面证明端点通,尤其是容器化部署里容器的网络环境和你笔记本不一样。从宿主机内部跑一次模型列表和一次聊天补全,能在 Open WebUI 介入之前确认网关这一半没问题。 然后加连接,看着选择器填充。鉴权错误对应 Key 字段;空选择器对应列表调用;服务器日志里出现重复路径(/v1/v1/...)说明 URL 字段本身已经带了 /v1,又被拼了一次,照着保存的原样精确读一遍 URL。 对话跑通之后,kkaiapi 控制台会显示每次请求的模型、token 数和花费。对多用户实例来说这才是真正重要的数字:用户实际选了哪些模型,一周下来工作区真实花了多少钱,按模型、按天,一页看完。

curl -s https://api.kkaiapi.com/v1/models \
  -H "Authorization: Bearer sk-你的kkaiapi密钥" | head -50

curl -s https://api.kkaiapi.com/v1/chat/completions \
  -H "Authorization: Bearer sk-你的kkaiapi密钥" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-haiku-4-5-20251001","messages":[{"role":"user","content":"ping"}]}'

常见问题