• 云原生
• 后端
• 运维

在 Olares 1.12.6 中，Open WebUI 借助检索增强生成（Retrieval-Augmented Generation，RAG）能力，让本地 AI 模型可以直接基于你上传的 PDF、文本文件或精心整理的知识库回答问题。本文以 Olares 上的真实操作路径为主线，完整讲解从获取嵌入模型连接信息、在聊天中分析单个文档，到构建可复用持久知识库、配置 PaddleOCR 高级内容提取引擎的全过程，读完即可在本地私有环境跑通"文档问答"工作流。

背景：Open WebUI 的 RAG 与文档理解

Open WebUI 是一款自托管聊天界面，用于与 Olares 设备上的本地模型交互（安装与模型连接参见 Open WebUI 部署指南）。其文档理解能力建立在 RAG 之上：文档首先被切分为文本块并转换为向量，用户提问时系统检索最相关的片段，连同问题一起送入生成模型，使回复可以引用文档原文。

在这一流程中，嵌入模型（Embedding Model）是不可或缺的前置组件——它负责把文档文本映射为高维向量。在 Olares 上，Open WebUI 默认通过 OpenAI 兼容协议调用嵌入模型服务，文档要求安装EmbeddingGemma作为嵌入模型。

前提条件

开始前请确认以下条件已满足：

• 已安装并配置 Open WebUI，且至少连接了一个本地对话模型；
• 拥有 Open WebUI 实例的管理员权限（首次启动时创建的本地管理员账号）；
• 已从应用市场安装嵌入模型：

配置嵌入模型

文档理解要求嵌入模型把文本转换为向量数据。要完成配置，必须先获取嵌入模型的连接信息，再将其填入 Open WebUI。

第一步：获取嵌入模型连接信息

嵌入模型在 Olares 上以独立服务运行，客户端需要Model name（模型名称）和与其 API 格式匹配的Base URL才能连接。获取步骤如下：

1. 从启动台打开嵌入模型应用，其模型控制台会自动打开。
2. 等待模型显示就绪（Ready）、引擎显示运行中（Running）。
3. 在模型部分，按显示内容原样复制模型名称（不要缩写、不要删除仓库前缀或量化标签，否则可能触发 "Model not found" 错误）。
4. 在引擎部分：
   • 连接来源：选择Olares 内应用（Apps in Olares），因为 Open WebUI 与模型运行在同一集群内；
   • API 格式：选择OpenAI-Compatible；
   • 按显示内容原样复制Base URL地址。

说明：Olares 上独立模型应用作为与客户端分离的服务运行，连接双方需要准确的 Model name 与匹配的 Base URL，两者均可从模型控制台获取。更通用的连接方法论（连接来源、API 格式、Base URL、API key 的对应关系）参见 连接 AI 应用与模型服务。

如果希望换用其他嵌入模型：可从应用市场安装其他模型应用，或通过引擎基座应用创建模型实例；已安装 Olares CLI 与 Agent Skills 的 AI Agent 应用还可直接通过对话让 Agent 部署模型，例如输入使用 Ollama 引擎基座在我的 Olares 上部署 qwen3.5:9b。

第二步：在 Open WebUI 中应用嵌入设置

拿到模型名称与 Base URL 后，将其填入 Open WebUI：

1. 在 Open WebUI 中，点击头像图标，前往Admin Panel（管理面板）>Settings（设置）。
2. 在左侧边栏的Tools（工具）部分选择Documents（文档）。
3. 在Embedding（嵌入）区域指定以下设置：

4. 向下滚动到页面底部，点击右下角的Reindex（重建索引）以应用更改并重建向量索引。
5. 点击Save（保存）。

提示：嵌入模型的可用性直接影响整个 RAG 链路。如果之后发现 AI 无法把文档或网页搜索结果纳入上下文，应优先回到Admin Panel>Settings>Tools>Documents检查嵌入模型设置是否缺失或不可访问（详见文末排查章节）。

在聊天会话中分析单个文档

对于一次性分析或总结场景，可以直接把文档附加到聊天会话，无需创建知识库：

1. 开始一个新聊天。

2. 选择要使用的对话模型。

3. 点击聊天输入框下方的添加（add_2）图标，选择Upload Files（上传文件）。

4. 上传 PDF 或文本文件。

5. 输入提示词，要求模型分析文档，例如：

   Summarize the main points of this document.

6. 提交提示词。如果生成的回复中包含文件引用（file citations），说明 Open WebUI 已成功把该文档加入上下文——这是验证文档是否进入 RAG 链路的关键标志。

构建持久知识库

对于需要在多个聊天会话中重复使用的文档，应创建持久知识库（Knowledge Base），避免每次重复上传：

1. 在 Open WebUI 中，点击头像图标，前往Workspace（工作区）>Knowledge（知识库）。

2. 点击Create（创建）。

3. 在What are you working on（你正在做什么）字段中输入知识库名称，例如Product FAQs。

4. 在What are you trying to achieve（你想达成什么目标）字段中输入描述，例如Frequently asked questions and support guides for Olares products。

5. 点击Create Knowledge保存集合。

6. 点击添加（add）图标 >Upload files（上传文件），上传文件来填充知识库内容。

创建完成后，该集合作为可复用的知识资产存在，后续任意新聊天均可引用，文件无需重复上传。

将知识库附加到聊天

创建知识库后，在聊天中将其附加，模型即可检索并引用其内容：

1. 开始一个新聊天。

2. 选择模型。

3. 点击聊天输入框下方的添加（add_2）图标，选择Attach Knowledge（附加知识库）。

4. 选择要使用的知识集合。

5. 提出与知识库内容相关的问题。模型会检索相关段落，并在回复中引用它们（引用来源即文档片段）。

建议：把"分析单个文档"（临时、一次性）与"构建知识库"（持久、可复用）两种模式区分使用——前者适合快速审阅，后者适合沉淀 FAQ、产品手册、团队资料等需要长期引用的内容。

（可选）配置 PaddleOCR 高级内容提取引擎

默认情况下，Open WebUI 使用简单的文本提取引擎。对于包含表格或复杂版式的文档，建议切换到 PaddleOCR 以获得更高的内容提取准确性。

:::warning 性能影响 PaddleOCR 需要更多 GPU 显存（VRAM），处理文档也比默认引擎更慢。仅在文档版式质量非常关键时才使用该引擎。 :::

配置步骤如下：

1. 从应用市场安装PaddleOCR应用。

2. 获取 PaddleOCR 端点 URL：

   • 打开 Olares 设置，前往应用（Applications）>PaddleOCR>入口（Entrances）；
   • 点击PaddleOCR，复制端点 URL，例如https://17b4c78a.laresprime.olares.com。

   说明：PaddleOCR 属于非 LLM 服务，不使用 OpenAI-Compatible 或 Ollama 等通用 provider 格式，而是通过自己的工具专属协议通信，因此无需配置 API 格式。端点 URL 从 Olares 设置的应用入口获取即可；确保入口认证级别为Internal，以便集群内其他应用无需登录即可访问（参见 连接 AI 应用与模型服务）。

3. 在 Open WebUI 中，前往Admin Panel>Settings。

4. 在左侧边栏的Tools部分选择Documents。

5. 在Content Extraction（内容提取）区域按如下方式配置：

   设置项	填写内容
   Content Extraction Engine（内容提取引擎）	在下拉列表中选择PaddleOCR-vl
   API Base URL	输入 PaddleOCR 端点 URL
   API Token	输入任意文本（例如local），不要留空

6. 点击Save（保存）。

关于 API Token 的说明：Olares 本地的 AI 服务信任来自同一集群内其他应用的请求，通常不需要真实密钥；但当客户端字段不允许留空时，填入占位文本即可（olares、local等）。

常见问题排查

围绕本文涉及的 RAG 链路，结合 Open WebUI 常见问题 给出以下排查要点：

• 回复中没有文件引用/知识库内容：优先确认嵌入模型是否已配置且可访问。前往Admin Panel>Settings>Tools>Documents，验证嵌入模型设置；嵌入模型缺失或不可访问时，Open WebUI 将无法处理文档与检索结果。
• "Model not found" 错误：嵌入模型名称被缩写或缺少前缀。回到模型控制台复制完整的模型名称（保留仓库前缀与量化标签）。
• 连接检查失败或 Base URL 无法访问：连接来源与客户端运行位置不匹配。重新打开模型控制台，选择Olares 内应用后再次复制 Base URL。
• 浏览器出现跨域（CORS）错误或 Olares 身份认证页面：客户端可能从浏览器前端直接发起了请求，请确认请求模式与服务入口符合客户端教程。

相关资源

• Open WebUI 部署与模型连接：在 Olares 上安装 Open WebUI 并连接本地对话模型
• 在 Open WebUI 中启用网页搜索：配置文档嵌入与 SearXNG 网页搜索（其中"设置文档嵌入"与本文共享同一配置面板）
• 连接 AI 应用与模型服务：连接来源、API 格式、Base URL 与 API key 的通用方法论
• Open WebUI 常见问题：模型状态、麦克风权限、网页搜索与嵌入模型等问题的排查
• 英文原文：Chat with documents and knowledge bases in Open WebUI

• 云原生
• 后端
• 运维