diff --git a/docs.json b/docs.json index 77985ba6..6224e70c 100644 --- a/docs.json +++ b/docs.json @@ -74,7 +74,8 @@ "group": "生态集成", "icon": "puzzle-piece", "pages": [ - "zh-Hans/integrations/dify" + "zh-Hans/integrations/dify", + "zh-Hans/integrations/open-webui" ] }, { @@ -822,7 +823,8 @@ "group": "Integrations", "icon": "puzzle-piece", "pages": [ - "en/integrations/dify" + "en/integrations/dify", + "en/integrations/open-webui" ] }, { diff --git a/en/integrations/open-webui.mdx b/en/integrations/open-webui.mdx new file mode 100644 index 00000000..c56f3038 --- /dev/null +++ b/en/integrations/open-webui.mdx @@ -0,0 +1,31 @@ +--- +title: "Use Ace Data Cloud in Open WebUI" +description: "Add an OpenAI-compatible connection, grant model access, and check your first chat." +--- + +Open WebUI's built-in OpenAI-compatible **Chat Completions** connection can use Ace Data Cloud without a custom Pipe. This quickstart covers an existing instance; use the [full setup guide](/en/guides/platform/open_webui) for deployment, persistence, and troubleshooting. Its connection steps were checked in v0.11.4; v0.12.0 model discovery and ordinary-user Read permissions were also checked separately. + +## Before you start + +- Get an application API key from the [Ace Data Cloud console](https://platform.acedata.cloud/console/applications?utm_source=opensource&utm_medium=referral&utm_campaign=evergreen&utm_content=openwebui_docs_api_key). Check the selected model's access, current price, and balance. A restricted key needs both `/v1/models` and `/v1/chat/completions`. +- Use an Open WebUI administrator account to add the server-side connection and grant model access. Authorized users share this connection's key and can consume its Credits. Do not paste a key into chat messages or screenshots. + +## Add the connection + +1. Open Open WebUI. In the user menu, choose **Admin Panel → Settings → Connections**. +2. Under **OpenAI API → Manage OpenAI API Connections**, click **Add Connection** (`+`). +3. Leave **Connection Type** at **External**. Set **URL** to `https://api.acedata.cloud/v1` (no trailing slash), **Auth** to **Bearer**, and **API Key** to your application key. Leave **API Type** at **Chat Completions**. +4. Click **Verify Connection**. It checks the `/v1/models` endpoint; the button is optional when you save. Click **Save** in the connection dialog, then **Save** in the main Connections settings if prompted. +5. In **Admin Panel → Settings → Models**, grant the intended users or group **Read** access to each model. Then, as an authorized user, start a new chat and select a current Chat Completions model. Send `Reply with the single word OK.` Check the completed reply and the corresponding [usage record](https://platform.acedata.cloud/console/usages). + +Model IDs and availability change; use the returned list and the [current chat model catalog](https://platform.acedata.cloud/documents/openai-chat-completions). To show a smaller list, add exact IDs under **Advanced → Model IDs** using **Add** (`+`) and save. This allowlist controls discovery; it does not replace each model's Read permission. Seeing an ID does not prove support for images, tools, or other protocols. + +## Check the request and solve problems + +The URL already contains `/v1`; Open WebUI appends `/models` or `/chat/completions`. Do not enter the full chat endpoint or `/openai/v1` as the connection URL. **Verify Connection** checks discovery; only a completed chat proves the chat route. If an ordinary user sees no models, check Read grants separately from application access, key validity, and balance. + +Disable any unused default connection to avoid selecting or probing it. The Ace key stays in the server-side connection settings; restrict server and model access. A personal-key model Pipe or service Tool has its own user settings and permissions; the shared connection does not populate those keys. + +Each model request can consume Credits. Title, tag, and follow-up generation can send additional requests; disable these features for a controlled first check. Match charges in [usage history](https://platform.acedata.cloud/console/usages) by key and time window. An accepted media task is not a finished result; this text-chat quickstart does not validate media, files, Community tool publication, or every model. + +For connection rules, see Open WebUI's [official compatibility guide](https://docs.openwebui.com/getting-started/quick-start/connect-a-provider/starting-with-openai-compatible/). Continue with the [full setup guide](/en/guides/platform/open_webui) or [Chat Completions schema](/en/guides/openai/openai_chat_completions). diff --git a/zh-Hans/integrations/open-webui.mdx b/zh-Hans/integrations/open-webui.mdx new file mode 100644 index 00000000..7b2ee186 --- /dev/null +++ b/zh-Hans/integrations/open-webui.mdx @@ -0,0 +1,31 @@ +--- +title: "在 Open WebUI 中使用 Ace Data Cloud" +description: "添加 OpenAI 兼容连接、授权模型，并核对第一次聊天。" +--- + +Open WebUI 内置的 OpenAI 兼容 **Chat Completions** 连接可以直接使用 Ace Data Cloud，无需自定义 Pipe。本文面向已有实例；部署、持久化和详细排错见[完整配置指南](/zh-Hans/guides/platform/open_webui)。连接步骤曾在 v0.11.4 核对；v0.12.0 的模型发现和普通用户读取权限也已分别验证。 + +## 准备工作 + +- 在 [Ace Data Cloud 应用控制台](https://platform.acedata.cloud/console/applications?utm_source=opensource&utm_medium=referral&utm_campaign=evergreen&utm_content=openwebui_docs_api_key)获取应用 API Key，确认模型权限、当前价格和余额。受限 Key 须同时允许 `/v1/models` 和 `/v1/chat/completions`。 +- 用 Open WebUI 管理员账户添加服务端连接并授权模型。获准用户共享该连接的 Key，可以消耗它的 Credits。不要把 Key 填在聊天正文或截图中。 + +## 添加连接 + +1. 在 Open WebUI 用户菜单中打开 **Admin Panel → Settings → Connections**。 +2. 在 **OpenAI API → Manage OpenAI API Connections** 下点击 **Add Connection**（`+`）。 +3. **Connection Type** 保持 **External**；**URL** 填 `https://api.acedata.cloud/v1`（末尾不要加 `/`）；**Auth** 选择 **Bearer**；**API Key** 填应用 Key；**API Type** 保持 **Chat Completions**。 +4. 点击 **Verify Connection** 检查 `/v1/models`；保存连接时也可以跳过这一步。点击连接弹窗中的 **Save**，如页面仍提示，再点击 Connections 主设置页的 **Save**。 +5. 在 **Admin Panel → Settings → Models** 给目标用户或组授予各模型的 **Read** 权限。随后以获准用户新建聊天，选择当前支持 Chat Completions 的模型，发送 `Reply with the single word OK.`，核对完整回复和对应的[使用记录](https://platform.acedata.cloud/console/usages)。 + +模型 ID 与可用性会变化，请结合返回列表和[当前聊天模型目录](https://platform.acedata.cloud/documents/openai-chat-completions)选择。只需少量模型时，在 **Advanced → Model IDs** 中逐个输入准确 ID、点击 **Add**（`+`）并保存。该允许列表控制模型发现，不能代替各模型的 Read 权限。出现模型 ID 不证明它支持图片、工具或其他协议。 + +## 核对请求与排错 + +URL 已包含 `/v1`，Open WebUI 会追加 `/models` 或 `/chat/completions`。不要填写完整聊天地址或 `/openai/v1`。**Verify Connection** 只验证模型发现，完整聊天回复才证明聊天路由可用。普通用户看不到模型时，须独立检查 Read 授权，不能只检查应用权限、Key 和余额。 + +停用不需要的默认连接，避免误选或探测。Ace Key 存放在服务端连接设置中，应限制服务器和模型的访问权限。个人模型 Key 的 Pipe 或服务 Tool 各有自己的用户设置与权限，共享连接不会自动填入这些 Key。 + +每次模型请求都可能消耗 Credits。生成标题、标签和后续提问可能发起额外请求；需要控制首次验证次数时，先关闭这些功能。在[使用历史](https://platform.acedata.cloud/console/usages)按 Key 和时间窗口核对扣费。媒体任务被接受不代表已经完成；本文文字聊天流程不验证媒体、文件、Community 工具发布或所有模型。 + +连接规则见 Open WebUI [官方兼容指南](https://docs.openwebui.com/getting-started/quick-start/connect-a-provider/starting-with-openai-compatible/)。后续可阅读[完整配置指南](/zh-Hans/guides/platform/open_webui)或 [Chat Completions 请求格式](/zh-Hans/guides/openai/openai_chat_completions)。