跳到主要内容

Open WebUI

Open WebUI 是一个 Web 界面，可用于与模型聊天、管理对话、附加知识和使用工具。它通过基于协议的连接访问模型服务，包括兼容 OpenAI 的 API。

Open WebUI 管理员可以将 AISIX 添加为兼容 OpenAI 的连接。随后，Open WebUI 会发现 AISIX 调用方密钥可用的模型别名，并通过网关发送聊天请求。AISIX 治理模型请求路径，Open WebUI 则继续管理用户、聊天、知识、工具和界面行为。

前置条件​

开始之前，请准备以下内容：

  • 具有管理员权限的 Open WebUI 账户。
  • Open WebUI 部署环境可访问的 AISIX 代理 URL。
  • 专用于 Open WebUI 的 AISIX 调用方 API Key。
  • 支持聊天的模型别名，且调用方密钥可通过兼容 OpenAI 的 API 访问该别名。

如果 Open WebUI 在容器中运行，则无法通过 localhost 访问容器宿主机上的 AISIX 网关。请使用可在 Open WebUI 容器内解析的主机名，例如共享容器网络中的网关服务名。

添加 AISIX 连接​

将 AISIX 配置为标准的兼容 OpenAI 的连接：

  1. 在 Open WebUI 中打开 Settings → Admin → Connections。
  2. 在 Manage OpenAI API Connections 下选择 Add Connection。
  3. 将 URL 设置为包含 /v1 的 AISIX 代理 API 根路径，例如 https://gateway.example.com/v1。
  4. 保持 Auth 为 Bearer，将 API Key 设置为 AISIX 调用方 API Key。
  5. 保持 API Type 为 Chat Completions，使 Open WebUI 向 /v1/chat/completions 发送请求。
  6. 在 Advanced 下保持 Provider 为 Default。
  7. 将 Model IDs 留空，让 Open WebUI 发现调用方密钥可访问的别名。
  8. 选择 Save。

Open WebUI 使用调用方密钥请求 GET /v1/models。AISIX 只返回该密钥可用的模型别名，因此 Open WebUI 的模型选择器遵循网关的访问策略。

如果只想展示返回列表中的部分模型，请在 Model IDs 下添加选定的 AISIX 别名。此筛选仅缩小 Open WebUI 的展示范围，不会授予 AISIX 调用方密钥原本没有的访问权限。

验证聊天和流式响应​

开始新聊天，选择支持聊天的 AISIX 模型别名，并发送简短提示词，例如“用一句话介绍 AI 网关”。

确认以下结果：

  • Open WebUI 显示流式响应。
  • AISIX 记录一条成功的 POST /v1/chat/completions 请求。
  • 记录中的调用方密钥和模型与 Open WebUI 连接及所选别名一致。

除了可见的聊天，Open WebUI 还可能使用模型执行后台任务。如果为任务、嵌入、图像生成、语音或重排配置了单独的模型或端点，请分别验证这些路径，再判断 Open WebUI 的所有模型流量是否均由 AISIX 治理。

单独验证工具​

Open WebUI 的原生工具调用路径要求使用兼容 OpenAI 的流式工具调用片段。每个片段都必须保留工具调用的 index，以便 Open WebUI 在执行工具之前组装函数名称和参数。

AISIX 在 Chat Completions 路径上保留带索引的工具调用流。上游模型也必须支持请求的工具，且 Open WebUI 必须启用并授权该工具。请运行一个实际使用工具的对话轮次，并确认以下结果：

  • Open WebUI 执行预期工具。
  • AISIX 记录生成工具调用的模型请求，以及包含工具结果的后续请求。
  • 聊天界面显示最终回答。

纯文本聊天成功并不能证明这个多请求工具调用循环正常工作。

连接故障排查​

现象检查项
未显示模型确认 URL 以 /v1 结尾、调用方密钥有效，且 GET /v1/models 返回预期别名。确认请求路径后，再向 Model IDs 添加别名。
连接返回 401确认 API Key 填写的是 AISIX 调用方密钥，而非上游服务提供方密钥。
聊天返回 403确认调用方密钥可访问所选 AISIX 模型别名。
聊天返回 404从 URL 中移除 /chat/completions。Open WebUI 会将该路径追加到 /v1 API 根路径。
容器部署无法连接使用 Open WebUI 容器可访问的网关主机名，而非 localhost。
工具调用轮次返回空回复验证所选模型会输出带索引的兼容 OpenAI 的工具调用流片段，再检查 AISIX 和 Open WebUI 中该工具请求的日志。

下一步​