• 云原生
• 后端
• 运维

Open WebUI 是一款自托管的开源聊天界面。在 Olares 上安装它之后，你可以通过自己的本地模型（例如 Qwen3.6-27B，由 llama.cpp 推理引擎驱动）进行完全私密的 AI 对话——所有会话数据都保留在你的设备上，不经过任何第三方云端服务。本文以 Olares 1.12.6 为版本基线，完整讲解从应用市场安装 Open WebUI、创建管理员账号、从模型控制台获取连接信息、配置 OpenAI 兼容 Provider 到开始第一次聊天的全流程，并穿插模型控制台、引擎基座等 Olares 底层机制的原理说明，帮助你一次配置成功。

1. 为什么在 Olares 上使用 Open WebUI

Open WebUI 是一个自托管的聊天界面，让你在 Olares 设备上与本地模型进行私密对话。与直接调用云端大模型 API 不同，这种组合带来三个直接价值：

• 数据私密性：模型权重运行在 Olares 本地，对话内容不上传至任何第三方服务器，所有会话保留在自己的设备上。
• 本地算力利用：Olares 设备上的 GPU/CPU 算力可以被充分利用，对话响应延迟只取决于本地硬件。
• 统一聊天入口：Open WebUI 提供了类 ChatGPT 的聊天界面，可集中管理多个本地模型，无需为每个模型单独维护客户端。

在 Olares 的架构中，模型推理能力由独立的“模型应用”以服务形式提供，而 Open WebUI 扮演“客户端应用”角色。两者通过标准的 OpenAI 兼容 API 进行通信，这正是本指南配置流程的核心逻辑。

2. 学习目标与前置条件

本指南将带你完成四个关键步骤：

1. 在 Olares 上安装 Open WebUI。
2. 创建管理员账号。
3. 将 Open WebUI 连接到本地模型。
4. 使用配置好的模型开始聊天会话。

开始前，你需要准备：

• 一台具有足够磁盘空间和内存的 Olares 设备。
• 从应用市场安装以下聊天模型：

可选：使用其他模型。你也可以选择不同大小的模型，或改用其他模型提供商：

• 从应用市场安装其他模型应用。
• 通过引擎基座应用创建模型实例，使用自己的模型。

如果 AI Agent 应用已安装 Olares CLI 和 Agent Skills，可以让它部署模型并跳过手动设置。例如：

使用 Ollama 引擎基座在我的 Olares 上部署 qwen3.5:9b。

3. 安装 Open WebUI

在应用市场中完成 Open WebUI 的安装：

1. 打开应用市场，搜索 "Open WebUI"。

2. 点击获取，然后点击安装，等待安装完成。安装完成后，Open WebUI 会出现在启动台（Launchpad）中。

从源码看应用分发机制：Olares 中的应用以 Helm Chart 形式打包并分发，每个应用由manifest（应用元数据与入口定义）、chart（资源编排）等部分组成，相关解析逻辑位于 framework/oac 目录下（如 manifest.go、appconfig.go）。从应用市场点击“获取/安装”后，Olares 会根据这些配置拉取镜像、创建资源并暴露入口，等待状态变为就绪后即可在启动台启动。

4. 创建管理员账号

首次启动 Open WebUI 时，你需要创建一个本地管理员账号，用于管理模型和设置。

1. 从启动台打开 Open WebUI。
2. 在欢迎页面中，点击Get started。
3. 输入你的姓名、邮箱和密码，创建管理员账号。

这个管理员账号是 Open WebUI 自身的账号体系，与 Olares 账号相互独立。后续添加其他用户、共享模型、配置网页搜索等管理操作都需要先使用该账号登录Admin Panel。

5. 获取模型连接信息

要将 Open WebUI 连接到模型，你需要先从模型的**模型控制台（Model Console）**收集连接信息。Olares 上的独立模型作为与客户端应用分开的服务运行。要连接两者，客户端需要准确的Model name，以及与其所需 API 格式相匹配的Base URL。你可以从模型控制台获取这两个值。

获取步骤如下：

1. 从启动台打开模型应用，其模型控制台会自动打开。

2. 等待模型显示就绪，且引擎显示运行中。只有当这两个状态同时满足时，模型服务才能对外提供推理能力。

3. 在模型部分，按显示内容原样复制模型名称。不要缩写，也不要删除仓库前缀（如unsloth/）或量化标签（如UD-Q4_K_XL），否则客户端可能返回类似 "Model not found" 的错误。

4. 在引擎部分：

   • 连接来源：选择Olares 内应用。该选项适用于运行在同一个 Olares 集群中的客户端（Open WebUI 正是这种情况）。
   • API 格式：选择OpenAI-Compatible。Open WebUI 原生支持 OpenAI 兼容接口，这是两者对接的关键。
   • 按显示内容原样复制Base URL地址，包括/v1等路径后缀。

理解 Base URL：Base URL 是模型服务应用接收并处理请求的地址。请原样复制，不要手动拼接或去掉路径后缀。典型的 Base URL 形如https://e46e044d.laresprime.olares.com/v1——其中主机名是模型应用在 Olares 内部网络中的入口地址，/v1是 OpenAI 兼容 API 的标准路径前缀。

6. 在 Open WebUI 中配置连接

连接信息准备就绪后，在 Open WebUI 中将该模型添加为 OpenAI 兼容提供商。

1. 在 Open WebUI 中，点击你的头像图标，选择Admin Panel。

2. 选择Settings标签页，然后从左侧边栏选择Connections。

3. 在Manage OpenAI API Connections右侧，点击加号按钮添加新连接。

4. 在API Base URL字段中，输入你从模型控制台复制的Base URL。例如，https://e46e044d.laresprime.olares.com/v1。

5. 点击Save。Open WebUI 会自动验证连接。当看到 "OpenAI API settings updated" 消息时，表示连接已建立。

关于 API key 的说明：部署在 Olares 本地的 AI 服务应用信任来自同一集群中其他应用的请求，因此通常不需要真实的 API key。如果客户端应用仍要求该字段有值，可以输入任意占位文本，例如olares或local。

7. 开始聊天

模型连接完成后，你就可以使用聊天界面了。

1. 在聊天区域，选择你配置好的模型。

2. 在文本框中输入提示词，然后按Enter键开始对话。Open WebUI 会通过你配置的 Base URL 把请求发送给 Olares 上的模型服务，模型推理完成后将流式返回结果。

8. 配置原理：从引擎基座到模型控制台

要深入理解上面的连接流程，需要了解 Olares 1.12.6 的Model Console（模型控制台）机制。Olares 提供了四个引擎基座应用：Ollama 引擎基座、vLLM 引擎基座、llama.cpp 引擎基座和SGLang 引擎基座，每个基于不同的推理引擎构建，用于管理本地 LLM 的全生命周期（拉取模型、加载推理、暴露 API、监控性能）。

• 本指南使用的 Qwen3.6-27B (llama.cpp) 属于预构建模型应用——它打包了 Olares 验证推荐的模型与引擎组合，从应用市场安装后即可使用，无需手动配置引擎环境变量。
• 如果你需要其他模型，可以克隆引擎基座创建模型实例，再通过环境变量（如MODEL_SOURCE、MODEL_NAME、MODEL_MODE、ENGINE_ARGS、*_REQUIRED_GPU_MEMORY）控制模型来源、服务名称、能力标签和显存占用。详细的变量说明与推荐参数见使用 Ollama、vLLM、llama.cpp 和 SGLang 运行本地大模型。

在模型控制台中选择连接来源与API 格式后，系统会生成对应的Base URL，并列出该 API 格式暴露的每个端点（HTTP 方法、路径和用途）。客户端应用只需要拿到 Base URL + Model name 即可完成对接——这就是第 5 节操作背后的机制。

模型控制台中各字段的含义与选择依据：

关于模型与引擎未就绪时的排查思路，可参考模型或引擎未就绪；关于连接 AI 应用的通用方法论，可参考连接 AI 应用与模型服务。

9. 常见问题排查

9.1 模型应用卡在 "Waiting for Ollama" 或 "Needs attention"

如果模型应用在这些状态停留超过几分钟：

1. 前往设置>AI 算力（英文文档中为Accelerator）。
2. 检查你的 GPU 模式：
   • 如果你正在使用容量切分（Memory slicing），需确保模型应用已关联到 GPU，并分配了足够的 VRAM。
   • 如果你正在使用独占（Exclusive），需确保独占应用设置为你的模型应用。
3. 从启动台重启模型应用，然后再次检查状态。

9.2 麦克风出现 "Permission denied" 错误

尝试使用听写按钮或 Voice Mode 时，你可能收到以下错误：

• Permission denied when accessing microphone: NotAllowedError: Permission denied
• Permission denied when accessing media devices

原因：Olares 桌面会在嵌入式框架（iframe）中显示应用。出于严格的安全和隐私考量，现代浏览器会阻止嵌入式框架访问麦克风等敏感硬件，即使你已经在系统设置中授予浏览器相应权限。

解决办法：

1. 在 Olares 桌面的 Open WebUI 窗口右上角，选择“在新标签页打开”图标，在新的浏览器标签页中打开。
2. 在新的浏览器标签页中，点击聊天界面的麦克风图标。
3. 当浏览器提示时，允许麦克风访问。

9.3 Open WebUI 无法搜索网页

如果 AI 回复中没有包含网页搜索结果，请按以下顺序排查：

1. 对话中已启用搜索功能：在聊天区域，点击Integrations图标，并确保Web Search已启用。
2. 嵌入模型已配置且可访问：前往Admin Panel>Settings>Tools>Documents，验证嵌入模型设置。如果嵌入模型缺失或无法访问，Open WebUI 将无法处理网页搜索结果。
3. SearXNG 能返回你的查询结果：从启动台打开 SearXNG，运行相同的搜索。如果 SearXNG 没有返回结果，请检查Preferences>ENGINES中是否已启用可用的搜索引擎。
4. 网页加载器被拦截：如果你需要完整网页内容，而默认网页加载器因反爬取机制失败，请前往Admin Panel>Settings>Tools>Web Search，启用Bypass Web Loader。这将使用搜索结果摘要，而不是获取完整页面。

提示：如需稳定地检索完整网页，可以安装并配置 Firecrawl 作为网页加载器，具体步骤见将 Firecrawl 用作网页加载器。

10. 进阶扩展

在完成基础的本地对话后，你可以继续扩展 Open WebUI 的能力：

• 设置多用户访问：将入口认证级别改为公开，为其他用户创建账号，并通过 Public/Private 访问控制列表共享本地模型。注意：公开入口会将 Open WebUI 直接暴露到互联网，请确保所有账号使用强密码。
• 配置音频：启用语音转文字（STT）和文字转语音（TTS）能力。
• 启用网页搜索：配置嵌入模型（如 EmbeddingGemma）和 SearXNG，为聊天增加联网检索能力；如需完整网页内容，可搭配 Firecrawl 作为网页加载器。
• 使用知识库：上传文档并创建用于 RAG 检索增强生成的知识库。
• Open WebUI 常见问题：集中排查使用中遇到的常见故障。

11. 总结

在 Olares 上运行 Open WebUI 的核心链路可以概括为：应用市场安装 → 创建管理员账号 → 从模型控制台复制 Model name 与 Base URL → 在 Open WebUI Connections 中配置 OpenAI 兼容 Provider → 选择模型开始对话。整个过程不依赖任何外部云端，模型推理、会话数据全部保留在本地设备上。掌握这套流程后，你可以举一反三，用同样的方式将 LobeHub、Dify 等其他 AI 客户端连接到 Olares 上的本地模型服务。

• 云原生
• 后端
• 运维