返回博客
OpenWebUIOpenWebUI API自托管 AI本地 LLMOpenAI 兼容自定义 AI

OpenWebUI API:用你自己的模型和任意网页聊天

•阅读需 17 分钟
OpenWebUI API:用你自己的模型和任意网页聊天

如果你在用 OpenWebUI,那最费功夫的配置工作已经完成了。模型都配好了,key 也集中在一处管理——可能是家里服务器上跑着的 Ollama,再加一两个云服务商,外加几个你亲手调过的自定义工作区模型。

OpenWebUI 做不到的,是在你正在浏览的网页里直接干活。想就眼前这篇文章、这份 PDF 或这页文档问问模型,你还是得把内容复制、粘贴到另一个标签页里。

这正是 SurfMind 的用武之地。OpenWebUI 不只是一个聊天界面。通过 OpenWebUI API,它还能充当 API 服务器,所以 SurfMind 可以把它当作后端来用。模型照旧在 OpenWebUI 里管理,SurfMind 则成了它们在浏览器里的前端。

这篇指南会讲清楚 OpenWebUI API 是什么、它和 SurfMind 是什么关系、该粘贴哪些确切的 URL,以及大家实际遇到的报错该怎么解决。

OpenWebUI 和 SurfMind:表面相似,分工不同

乍一看,两者像是竞争对手。都是 AI 界面,都能连接多家 LLM 服务商,也都能和模型聊天。但它们面向的场景并不一样:

SurfMind OpenWebUI
主要界面 浏览器扩展(每个页面都有侧边栏) 自托管的 Web 应用
连接多家 AI 服务商 支持 支持
本地模型 通过任意兼容端点(Ollama、LM Studio、OpenWebUI……) 原生集成 Ollama,也支持其他端点
处理你正在读的页面 核心强项:页面、标签页、PDF、YouTube 不是它的重点
自托管 通过自定义 API 完整支持 整套应用和后端都由你自己运行
通过 API 为其他应用提供模型 不支持 支持
知识库与检索 浏览器上下文:你打开的页面和标签页 服务端知识库与 RAG

OpenWebUI 是一个自托管的 AI 工作台,SurfMind 则是装进你常用浏览器里的 AI。 最关键的是加粗的那一行。正因为 OpenWebUI 能通过 API 对外提供模型,两者正好可以配合使用。

为什么要把 OpenWebUI 接入 SurfMind?

设想一个典型的配置:你在家里的服务器或一台小 VPS 上跑着 OpenWebUI,背后接着:

  • 通过 Ollama 在本地运行的 Llama、Qwen 或 Gemma
  • 通过云端 API key 调用的 GPT 或 Claude 模型
  • 在你自己 GPU 上由 vLLM 提供服务的模型
  • 几个你在 OpenWebUI 里搭建的工作区模型(workspace models),各有各的系统提示词和参数设置

这些在 OpenWebUI 的聊天页面里都能用。现在你还想要浏览器助手最擅长的那些事:就当前页面提问、总结一条长长的讨论串、跨标签页对比信息,或者不离开网站就起草一条回复。

你当然可以把每个服务商在 SurfMind 里重新添加一遍:先加 Ollama,再加 OpenAI key,再加 vLLM 端点。但这样既繁琐,又让 key 散落两处,而且你搭好的工作区模型也带不过来。

或者,你只加一条连接:SurfMind → OpenWebUI。OpenWebUI 能看到的每个模型,都会出现在 SurfMind 的模型选择器里。模型、用户和权限依旧在你熟悉的 OpenWebUI 里管理,SurfMind 只是在上面加了一层浏览器能力。

团队共用一套配置时,这种方式也很方便。如果团队共用一个 OpenWebUI 实例,每个人都可以创建自己的 API key,在自己的浏览器里使用团队的模型。他们拥有的权限和在 OpenWebUI 里完全一样,而且谁都不需要接触服务商的 key。

第 1 步:创建 OpenWebUI API key

API key 功能默认是关闭的,所以第一次配置要多花一分钟。

如果你是管理员,先开启 API key:

  1. 以管理员身份登录 OpenWebUI。
  2. 进入 Settings → Admin → Authentication。
  3. 打开 API Keys 开关,然后点击 Save。

如果你不是管理员,请让管理员给你开通 API Keys 功能权限。管理员可以在 Admin Panel → Users → Groups 中设置:要么在 Default Permissions 里对所有人开放,要么只对某个特定分组开放。

然后生成你的 key:

  1. 点击左下角的头像。
  2. 打开 Settings → Account。
  3. 在 API keys 区域,点击 Secrets 旁边的 Show。这个区域默认是折叠的,所以看起来空空如也是正常的。
  4. 点击 Create new secret key 并复制。它以 sk- 开头。

根据 OpenWebUI 的 API key 文档,有几点值得留意:

  • 每个账号只有一个 key。 新建 key 会替换旧 key,旧 key 立即失效。如果别的工具已经在用你的 key,那么为 SurfMind 新建一个就会让那个工具罢工。给 SurfMind 单独建一个非管理员账号,就能避开这个问题。
  • key 代表的就是你本人。 它能看到的模型、拥有的权限,都和创建它的账号一模一样。
  • 不要用 JWT token,也就是同一面板里展示给管理员的那个。那是你浏览器会话的 token,会过期。

第 2 步:在 SurfMind 中添加 OpenWebUI

在 SurfMind 中,点击面板底部的模型名称,然后依次点 Show all → Custom → Add Custom Models。选择通用的 OpenAI-compatible 预设,并填写:

字段 OpenWebUI 该填什么
API Name 随便起,例如 OpenWebUI
API URL https://your-openwebui-host/api/chat/completions
Models URL https://your-openwebui-host/api/models
API Key Header Authorization
API Key 你的 sk-… key,前面不要加 Bearer(SurfMind 会自动加上)

如果 OpenWebUI 和你的浏览器在同一台电脑上,host 通常是 http://localhost:3000(Docker 常用的端口映射)或 http://localhost:8080(pip 安装或裸机安装):

  • API URL:http://localhost:3000/api/chat/completions
  • Models URL:http://localhost:3000/api/models

保存后,从列表里选一个你的 OpenWebUI 模型,随便打开一篇文章,让 SurfMind 帮你总结一下。

两个要避开的路径错误。 粘贴以 /api/chat/completions 结尾的完整端点,而不是只填主机地址或以 /api 结尾的地址。SurfMind 的 API URL 字段不会替你补全路径。另外,任何地方都不要加 /v1。/api/v1/chat/completions 和 /v1/chat/completions 都不是 OpenWebUI 的聊天端点。

故障排查:“模型能加载,聊天却失败”

这是 OpenWebUI 用户反馈最多的问题,所以单独拿出来讲。如果下拉菜单中能正常显示模型列表,说明你的 host、key 和网络路径都没问题,出错的是聊天请求本身的某个环节。按下面的顺序逐一排查。

首先,脱离 SurfMind 测试一下。 在终端里跑一条 curl,就能判断问题出在 OpenWebUI 还是你的 SurfMind 设置上。把 host、key 和模型 id 换成你自己的:

curl -X POST https://openwebui.example.com/api/chat/completions \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "llama3.2:latest", "messages": [{"role": "user", "content": "Say hi"}]}'

模型 id 要和 SurfMind 模型列表(或 GET /api/models)里显示的完全一致。如果这条命令能跑通,就回头检查 SurfMind 的各个字段。如果它也失败了,返回的报错会指向下面某一个原因。

1. 聊天路径不对。 Models URL 和 API URL 是两个独立的字段,所以可能一个对、一个错。检查 API URL 是否恰好以 /api/chat/completions 结尾:没有 /v1,没有结尾斜杠,也没有拼写错误。

2. 端点限制拦住了聊天。 管理员可以开启 API Key Endpoint Restrictions,也就是一份 API key 可调用路由的白名单。如果名单里有 /api/models 却没有 /api/chat/completions,就会出现一模一样的症状,通常表现为 403。请让管理员把 /api/chat/completions 加进去。

3. 某个模型设置强制了流式模式。 OpenWebUI 有一个 Stream Chat Response 设置,可以在每个模型的高级参数里单独设置,也可以由管理员在 Settings → Admin → Models 下设为默认值。根据 OpenWebUI 的文档,这个设置决定回复是否以流式返回,不管客户端请求的是什么。如果某个模型被强制成了客户端预料之外的模式,返回的回复格式就可能让客户端无法解析。如果只有某些模型聊天失败,检查一下它们的这个设置,把它改回 Default。

4. 反向代理吞掉了 Authorization 请求头。 如果 OpenWebUI 部署在一个自己也用 Authorization 做登录的网关后面(basic auth、SSO、API 网关),你的 key 根本到不了 OpenWebUI。OpenWebUI 也接受通过自定义请求头传递 key,默认是 x-api-key。这种情况下,在 SurfMind 的 API Key Header 里选择 x-api-key。如果管理员用 CUSTOM_API_KEY_HEADER 改过请求头的名字,代理就必须把那个请求头原样透传过去。

5. 模型 id 对不上。 从下拉菜单里选,别手动输入。OpenWebUI 里 Ollama 模型的 id 带有标签(llama3.2:latest),而工作区模型用的是你给它起的 id,不是它的显示名称。

6. OpenWebUI 背后的服务商出了问题。 当上游服务商拒绝请求时,OpenWebUI 会把它的状态码原样传回来。429 来自服务商的速率限制,而不是 OpenWebUI 或 SurfMind。在 OpenWebUI 自己的聊天界面里试一下同一个模型。如果那里也失败,问题就出在上游。

其他报错,速查一览

症状 可能原因 解决办法
401 Unauthorized key 错误或已被替换、在 key 字段里输入了 Bearer、多了空格 重新复制 key,确认之后没有再新建过 key
403 Forbidden API Keys 开关未开启、缺少功能权限,或被端点白名单拦截 请管理员把这三项都检查一遍
404,或返回 HTML 页面而不是 JSON 路径错误(/v1/...) 使用 /api/chat/completions 和 /api/models
用局域网 IP(http://192.168.x.x)连接失败 浏览器拦截了发往非 localhost 地址的纯 http 请求 为 OpenWebUI 配置 https 访问(Caddy、Tailscale、Cloudflare Tunnel 或反向代理)
返回奇怪的 {},或报 “not valid JSON” 错误 服务端的 CORS_ALLOW_ORIGIN 配置有误 OpenWebUI 的文档要求必须设置它。确认它没有拦截请求
在家能用,换个地方就不行 localhost 只代表“这台电脑” 使用服务器真实的主机名,并确保从你浏览器所在的位置能访问到

关于适用于所有自定义端点的通用规则(端口、http 与 https、基础 URL 与完整端点),请看我们的自定义 AI 连接指南。

该用 OpenWebUI、SurfMind,还是两个都用?

这不是一道单选题。

  • 只用 OpenWebUI:如果你用 AI 主要是在一个专门的标签页里长时间对话——和知识库里的文档聊天、跑 pipeline、为团队管理模型——它就非常合适。
  • 只用 SurfMind:如果你用 AI 大多是从屏幕上正在看的内容出发,而且乐意直接连接服务商或 Ollama 这类本地运行器,它就非常合适。
  • 两个都用:如果你已经在 OpenWebUI 的配置上下了功夫,又希望在每个页面上都能用到它,而不必把所有东西再配一遍,那就两者兼用。

分工很简单:OpenWebUI 负责管理你的模型,SurfMind 让你在浏览器里直接使用这些模型。

常见问题

OpenWebUI 有 API 吗? 有。OpenWebUI API 是一个使用 Bearer token 鉴权的 REST API。大多数工具需要的两个端点是:用于列出模型的 GET /api/models,以及用于聊天的 POST /api/chat/completions,后者接受 OpenAI 风格的请求。

OpenWebUI API 兼容 OpenAI 吗? 请求和响应格式是兼容的,但路径不是标准路径:OpenWebUI 用的是 /api/chat/completions,而不是 /v1/chat/completions。任何允许你填写完整端点 URL 的客户端(比如 SurfMind)都能用它。

我的 OpenWebUI API key 在哪里找? 进入 Settings → Account → API keys,点击 Show,再点 Create new secret key。如果找不到这个区域,需要管理员在 Settings → Admin → Authentication 下开启 API Keys,并给你的账号开通 API Keys 权限。

我能在 SurfMind 里使用 OpenWebUI 的工作区模型吗? 能。工作区模型和其他模型一样,会被 /api/models 列出来。调用它们时,OpenWebUI 会套用它们保存好的设置。

连接 OpenWebUI 会把我的数据发到 SurfMind 的服务器吗? 使用自定义端点时,SurfMind 会把请求发到你配置的 URL,在这里就是你的 OpenWebUI 服务器。然后由你的 OpenWebUI 服务器转发给你选中的模型。如果那个模型在本地运行,页面内容就始终留在你自己掌控的硬件上。

免费吗? 免费。SurfMind 的自定义端点不收任何费用,我们也不设使用上限。你只需支付自己的服务商收取的费用,本地模型则分文不花。

还是没搞定?

如果 curl 测试能通过,但 SurfMind 依然无法和你的 OpenWebUI 模型聊天,请发邮件到 wave@surfmind.ai。邮件里请附上你的 API URL(不要带 key)、HTTP 状态码,以及是部分模型还是所有模型都失败。自托管的配置千差万别,这些反馈能帮我们让 SurfMind 和它们配合得更顺畅。

获取 SurfMind →

相关文章

查看全部