Open WebUI
本页需要用 Docker 部署服务（Docker 是一种把软件打包运行的工具，需要一定动手能力）。只想聊天、不想部署的话，改用 Cherry Studio 或 Lobe Chat。
Open WebUI 是一款可自部署的 Web 聊天前端，支持通过 OpenAI-compatible API 连接外部模型服务。接入彼源 AI 后，用户可以在 Open WebUI 中选择彼源 AI 提供的模型进行聊天，并在彼源 AI 控制台「使用日志」中查看每一条请求与额度消耗。
安装 Open WebUI
如果已经有可用的 Open WebUI 实例，可以直接进入后续配置步骤。如尚未部署，可先参考官方 Quick Start：
官方推荐使用 Docker 快速启动：
docker run -d -p 3000:8080 \
-v open-webui:/app/backend/data \
--name open-webui \
ghcr.io/open-webui/open-webui:main
启动后，通常可以在浏览器中访问：
http://localhost:3000
适用场景
- 希望自部署一个 Web 聊天前端。
- 希望通过 OpenAI 兼容接口接入彼源 AI 模型。
- 希望让多个用户通过同一个 Web 界面使用模型。
- 希望在 Open WebUI 内统一管理会话、模型选择和用户访问。
前置条件
开始前，请先准备以下信息：
| 项目 | 说明 |
|---|---|
| Open WebUI | 已安装并可以进入管理设置 |
| API Base URL | https://api.biyuan.ai/v1 |
| API Key | 在「令牌管理」中创建的 sk- 开头令牌 |
| 模型名称 | 从模型广场复制模型 ID；令牌设置了模型限制时，以 GET /v1/models 返回为准 |
建议为 Open WebUI 单独创建令牌，不要复用生产服务、团队共享或其他客户端正在使用的高权限令牌。
接入流程
创建 Open WebUI 专用令牌
-> 打开 Admin Settings
-> 新增 OpenAI connection
-> 填写 API Base URL 和 API Key
-> 添加或限制模型列表
-> 保存并发送测试消息
如何接入
1. 创建 Open WebUI 专用令牌
进入彼源 AI 控制台：
令牌管理 -> 添加令牌
建议命名为 open-webui、openwebui-team、openwebui-prod 等便于识别的名称。后续查看 Open WebUI 消耗、停用令牌或排查请求时，可以直接定位到对应令牌。
2. 打开 OpenAI 连接设置
在 Open WebUI 中进入：
Admin Settings -> Connections -> OpenAI
点击 Add Connection 或加号按钮，新增一个 OpenAI-compatible 连接。
3. 填写彼源 AI 配置
在连接配置中填写：
| 字段 | 填写内容 |
|---|---|
| URL / Base URL | https://api.biyuan.ai/v1 |
| API Key | 彼源 AI 令牌，例如 sk-... |
| Model IDs (Filter) | 可选；用于限制只显示指定模型 |
Open WebUI 会使用标准 Bearer token 调用 provider 的 /models 接口进行连接校验。彼源 AI 支持模型列表查询，通常可以自动显示当前令牌可用模型。
4. 限制模型列表
如果模型列表过多，或只希望 Open WebUI 暴露少量模型，可以在 Model IDs (Filter) 中添加模型 ID。该字段相当于模型白名单，只会让用户看到已添加的模型。
示例：
gpt-5.4
模型名称必须与彼源 AI 控制台显示一致。首次验证建议只添加一个模型，确认链路正常后再逐步扩展。
5. 保存并测试
保存连接后，回到 Open WebUI 聊天界面，选择刚刚添加的模型，发送一条简单消息：
请用一句话介绍你自己。
回到彼源 AI 控制台，打开「使用日志」，能看到刚才这条请求（模型、时间、消耗），说明接入成功。
环境变量方式
如果希望在部署时固定彼源 AI 配置，也可以使用环境变量：
OPENAI_API_BASE_URL="https://api.biyuan.ai/v1"
OPENAI_API_KEY="<你的彼源 AI 令牌>"
其中：
| 变量 | 说明 |
|---|---|
OPENAI_API_BASE_URL | 彼源 AI API Base URL，需要包含 /v1 |
OPENAI_API_KEY | 彼源 AI 令牌，例如 sk-... |
修改环境变量后，需要重启 Open WebUI。请勿把真实令牌写入公开文档、截图、代码仓库或聊天记录中。
界面示意
以下界面示意来自 Open WebUI 官方文档的 OpenAI-compatible 接入页，用于说明 provider connection 的配置入口与验证逻辑。
重点关注以下字段：
URL：填写https://api.biyuan.ai/v1。API Key：填写彼源 AI 令牌。Model IDs (Filter)：按需填写模型白名单。- 保存后在模型选择器中选择目标模型进行测试。
验证方法
推荐按以下顺序验证：
- 在彼源 AI 控制台确认令牌处于启用状态。
- 在 Open WebUI 中进入
Admin Settings -> Connections -> OpenAI。 - 填写
https://api.biyuan.ai/v1和彼源 AI 令牌。 - 如需限制模型，在
Model IDs (Filter)中添加一个模型名称。 - 保存连接。
- 在聊天界面选择目标模型并发送测试消息。
- 回到彼源 AI 控制台，打开「使用日志」，能看到刚才这条请求（模型、时间、消耗），说明接入成功。
注意事项
- 本页只覆盖聊天主链路接入；知识库、Embedding、图像、音频等扩展能力建议在聊天可用后再单独验证。
URL或OPENAI_API_BASE_URL需要包含/v1。- 不建议把管理密钥、生产服务密钥或团队共享高权限令牌直接用于 Open WebUI。
- 如果连接多个 provider，建议使用清晰的模型白名单或前缀，避免用户选错模型。
- 修改环境变量后通常需要重启服务；管理后台保存配置后也需要确认连接处于启用状态。
常见问题
Base URL 应该填写什么
填写：
https://api.biyuan.ai/v1
Open WebUI 按 OpenAI-compatible API 调用彼源 AI，因此这里需要包含 /v1。
连接校验失败
请依次检查：
- API Key 是否完整复制，且以
sk-开头。 - URL 是否填写为
https://api.biyuan.ai/v1。 - 当前令牌是否启用，且仍有可用额度。
- 当前令牌是否有至少一个聊天模型权限。
- 网络环境是否可以访问彼源 AI API。
模型列表中没有目标模型
请检查：
- 当前令牌是否有目标模型权限。
Model IDs (Filter)是否隐藏了目标模型。- 模型名称是否与彼源 AI 控制台显示一致。
- 连接配置是否已经保存并启用。
如果自动发现失败，可以在 Model IDs (Filter) 中手动添加模型 ID 后保存。
页面可以打开，但聊天失败
常见原因包括：
- 聊天界面选中的不是彼源 AI 连接下的模型。
- 当前模型不可用或令牌无权限。
- Open WebUI 仍在使用旧配置。
- 部署环境中的环境变量尚未重启生效。
建议先使用一个已确认可调用的模型完成最小验证，再继续排查目标模型或扩展能力。
知识库、图像或音频可以一起配置吗
不建议在首次接入时一起配置。先完成聊天主链路验证，再根据彼源 AI 当前开放能力分别配置知识库、图像或音频相关参数。这样更容易定位问题来源。
如何确认请求是否经过彼源 AI
最直接的方式是回到彼源 AI 控制台，打开「使用日志」，看有没有刚才这条请求（模型、时间、消耗）。若 Open WebUI 返回成功，但「使用日志」里没有这条请求，通常说明当前请求没有使用彼源 AI endpoint，或正在使用其他 provider 配置。
官方参考
- Open WebUI: Quick Start
- Open WebUI: Connect a Provider
- Open WebUI: OpenAI-Compatible
- Open WebUI: Environment Variable Configuration