Open WebUI 必备功能
您已经安装了 Open WebUI，连接了一个提供程序，并进行了第一次对话。本页面涵盖将基本聊天 UI 转变为日常使用的六件事。虽然这些都不是必需的，但大多数用户在第一周内会使用所有这些功能。
按顺序进行，或跳转到您需要的部分：
如果您正在为多个用户设置 Open WebUI，也请阅读扩展 Open WebUI指南。它涵盖与本页面上功能级别必需品分开的基础设施决策（PostgreSQL、Redis、外部向量数据库、共享存储）。这两个指南是相辅相成的 — 此处完成日常使用必需品，使用扩展指南进行多用户基础设施。
工具调用
没有工具，LLM 只能生成文本。有了工具，它可以查找、运行代码并代表您采取行动。您将工具连接到聊天（或连接到模型），模型在其响应期间决定何时调用它以及使用什么参数。Open WebUI 执行调用，将结果反馈回来，模型继续使用该新信息。
工具调用将聊天模型转变为代理。设置此功能可以解锁本页面其余部分介绍的大多数高级功能。
值得早期理解两件事。
理解工具调用模式
Open WebUI 有两种方式将模型连接到其工具，一个常见的混淆来源是标记为"默认"的方式不是大多数人应该使用的方式。一旦理解了历史和 Open WebUI 的设计理念，命名就更有意义了。
默认模式是旧版方法，用于广泛兼容性。如果您的模型支持函数调用（大多数现代模型都支持），原生模式是更好的选择。请查看下面如何切换。
Open WebUI 的一个核心目标是支持尽可能广泛的模型范围，从最先进的前沿 API 到在树莓派上运行的小型量化模型。当 Open WebUI 首次引入工具调用时，大多数模型没有内置函数 调用 API。给模型提供工具的唯一方法是在系统提示中将它们描述为纯文本，然后解析模型的响应以确定它试图调用哪个工具。这种基于提示的方法是 Open WebUI 所称的默认模式。它是原始的（当时是唯一的）实现，现在被认为是旧版处理。它保持为系统默认值，因为它是最低公分母：任何可以遵循系统提示中的指令的模型都可以使用它，不需要特殊的 API 支持。
从那以后，大多数模型提供程序都添加了原生函数调用支持。Open WebUI 称这个为原生模式。模型在其 API 请求的结构化部分中接收工具定义，并在其响应中返回结构化的工具调用。它更快、更可靠、保留 KV 缓存，对于 Open WebUI 的所有内置系统工具（内存、笔记、知识、网络搜索、图像生成、代码解释器）是必需的。所有新的工具调用功能都是为原生模式构建的。但它仅适用于实际公开函数调用 API 的模型，这就是为什么它不能成为通用默认值。
实际上，大多数用户应该启用原生模式。每个主要的当前模型都支持它（OpenAI、Anthropic、Gemini、Llama 3.1+、Qwen 2.5+、DeepSeek、GLM 等）。您可以为整个实例一次性设置它：
管理面板 > 设置 > 模型 → 单击模型列表右上角的设置按钮 → 设置函数调用 = 原生 → 保存。每个当前和未来的模型都继承该设置。
- 按模型： 管理面板 > 设置 > 模型 > [您的模型] > 模型参数 > 函数调用 = 原生
- 按聊天： 在聊天的聊天控制（右侧边栏）中
如果您运行的是不公开函数调用 API 的旧版本地模型或微调，请将该特定模型保留在默认模式。对于其他所有东西，原生模式是更好的选择。
选择要启用的工具
人们寻找的许多工具已经内置在 Open WebUI 中，只需打开即可：网络搜索、代码执行、图像生成、内存和知识库检索都无需安装任何插件即可使用。启用后，这些在使用原生模式时会自动显示为系统工具。
其中大多数需要少量设置（选择提供程序、添加 API 密钥或启用切换）。最受欢迎的几个设置指南：
- 网络搜索 — 连接搜索提供程序（Google、Brave、DuckDuckGo、SearXNG 等），以便模型可以查找内容
- 图像生成 — 连接图像提供程序（OpenAI DALL-E、ComfyUI、Automatic1111 等）用于聊天内图像创建
- 代码执行 — 直接在聊天中运行代码块（Pyodide 默认在浏览器中运行，或连接 Jupyter 进行服务器端执行）
- 内存 — 让模型在对话中记住有关您的事实
对于任何未内置的东西，Open WebUI 社区网站值得浏览。给出一些可用功能的几个类别：
- 可观测性/成本跟踪：Langfuse、OpenLit、Portkey。将每个聊天轮次、令牌使用情况和延迟记录到您自己的堆栈。
- 智能家居/自动化：Home Assistant 工具，让模型可以控制设备、例程和场景。
- 研究：arXiv、PubMed、Semantic Scholar、Wolfram Alpha。带有真实引文的结构化结果。
- 问题跟踪/消息：Jira、Linear、GitHub Issues、Slack、Discord、电子邮件。
- 数据库/API：针对您自己的数据库的只读 SQL，或对您的内部 API 的调用。
- 特定领域：天气、股票、加密货币、航运跟踪、食谱等。
工具出现在聊天输入的 + 菜单中。模型仅看到为该对话启用的工具。
Open WebUI 社区托管数千个社区构建的插件。在自己编写任何东西之前，浏览已经存在的内容：按受欢迎程度排序、按类别筛选，并浏览几页。大多数时候，有人已经构建了您需要的内容（或足够接近以进行分叉）。
更多详情：
插件
Open WebUI 开箱即用地附带了很多功能，但其真正的力量在于它被设计为可扩展的。许多人们在演示中展示的高级功能（自动翻译、令牌/成本跟踪、自定义后处理、利基提供程序集成）是插件，构建在平台之上。理解插件景观是对新用户来说最大的一个解锁。
有两个插件系列：工具和函数。
工具给模型提供在响应期间可以调用的能力：
| 来源 | 它做什么 | 示例 |
|---|---|---|
| 内置 | 随 Open WebUI 附带的系统工具。在管理面板中启用，无需安装。 | 网络搜索、代码解释器、图像生成、内存、笔记、知识检索 |
| 自定义 | ||
| ↳ 工具 | 您自己编写或从社区网站安装的代码。在工作区 > 工具中管理。 | Langfuse / OpenLit 可观测性、Home Assistant、arXiv / PubMed 查询、Wolfram Alpha、Jira / Linear、SQL 查询 |
| ↳ 工具服务器 | 通过 MCP 或 OpenAPI 连接的外部服务。在管理面板 > 设置 > 工具中配置。 | 您自己的微服务、第三方 API、现有的 MCP 服务器 |
函数在平台级别运行并修改 Open WebUI 本身的行为方式。有三种类型：
| 类型 | 它做什么 | 示例 |
|---|---|---|
| 管道 | 向模型选择器添加新"模型"，由自定义代码支持 | 模型路由（基于提示的便宜与昂贵）、多步代理循环、自定义 LLM 后端 |
| 过滤器 | 在通过时修改每个请求和/或响应，在每个聊天轮次自动进行 | 上下文修剪、PII 洗涤、令牌/成本计数、Langfuse 追踪、响应重新格式化 |
| 操作 | 在每条消息下添加一个按钮，用户点击它时运行自定义代码 | "重新生成后续"、"翻译回复"、"固定消息"、"保存到知识" |
工具和函数都可以从Open WebUI 社区网站浏览和安装，该网站托管数千个社区构建的插件。您也可以在管理面板中从头开始编写自己的。
安装插件
Open WebUI 社区网站托管工具和函数的一键目录。选择一个，单击"获取"，将其粘贴到管理面板中，启用它，并配置其辅助设置（插件的设置）。
每当您认为"如果 Open WebUI 做 X 就很好"时 ，它几乎肯定已经通过插件实现了。已经编写了数千个插件，您需要的那个通常已经存在。即使没有完全匹配，最接近的也通常只需约 20 行从您想要的内容进行调整，您可以从管理面板进行分叉。
参考阅读：
任务模型
默认情况下，后台任务（标题、标签、自动完成）使用您的主聊天模型。设置专用的任务模型是改进速度和减少不必要 API 成本的最简单方法。
每次 Open WebUI 需要为 UI 功能进行一小段"思考"（为侧边栏写聊天标题、生成标签、建议后续问题、为提示框中的自动完成供电）时，它会调用一个任务模型。默认情况下，该任务模型是您当前聊天的任何主要模型，这意味着：
- 您昂贵的旗舰模型每次您 打开新聊天时都会被调用，只是为了写"购物清单"。
- 在慢速本地模型上，每次按键都会感到滞后，因为自动完成正在等待 30B 参数模型。
- 推理模型（o1、r1、Claude with extended thinking）在生成三个字的标题之前花费五秒思考。
这些在后台运行，所以很容易被忽视。专用任务模型是一个小改变，会产生明显的差异。
解决方案： 在管理面板 > 设置 > 界面中，设置专用的任务模型。有两个字段，因为正确的选择取决于您的主聊天模型是什么：
- 任务模型（外部）：设置为快速、便宜的非推理云模型，如
gpt-5-nano、gemini-2.5-flash-lite或llama-3.1-8b-instant。 - 任务模型（本地）：设置为小型本地模型，如
qwen3:1b、gemma3:1b或llama3.2:3b。
主聊天体验不会改变。后台工作只是停止拖累。
当您在界面设置中时，如果您使用的是低规格机器或根本不想要它们，也可以完全禁用这些工作。每个都有一个管理员切换在同一页面和一个环境变量：
| 工作 | 管理员切换（设置 > 界面） | 环境变量 |
|---|---|---|
| 自动完成 （在每次按键时触发） | 自动完成生成 | ENABLE_AUTOCOMPLETE_GENERATION=False |
| 后续建议 | 后续生成 | ENABLE_FOLLOW_UP_GENERATION=False |
| 聊天标题生成 | 标题生成 | ENABLE_TITLE_GENERATION=False |
| 标签生成 | 标签生成 | ENABLE_TAGS_GENERATION=False |
自动完成是弱硬件上最大的"让其快速"切换。它在每次按键时触发，所以缓慢的任务模型会将整个提示框变成糨糊。如果 UI 感到缓慢，首先禁用它。
更多详情：性能和 RAM：专用任务模型。
上下文管理
经过足够的来回后，您最终会看到：
提示太长：207601，模型最大上下文长度：202751
此错误来自您的模型提供程序，而不是来自 Open WebUI。每次您发送消息时，整个对话（系统提示、所有之前的轮次、附加文件、工具调用结果和您的新消息）都会作为"提示"发送。当总和超过模型的上下文窗口时，提供程序会拒绝请求。
Open WebUI 故意不附带内置的修剪器，因为：
- 每个模型使用不同的分词器（GPT、Claude、Gemini、GLM、Llama 都不同）。
- 每个模型有不同 的上下文窗口（8k 到 1M+）。
- 每个部署想要不同的策略（按令牌修剪、按轮修剪、按消息计数修剪、首先删除附件、总结旧消息等）。
没有单一正确答案。支持的方法是安装一个过滤器函数，按您的条件修剪对话。
许多常见策略的社区过滤器已经存在，可以一键安装。如果没有适合的，代码足够短可以复制和调整。请参阅完整指南，包括最小的"最新 N 轮"过滤器：故障排除：上下文窗口/提示太长。
基础 RAG
RAG（检索增强生成）是允许您说"这是一个 400 页的 PDF，回答我关于它的问题"的功能，而无需模型每次都读取整个内容。Open WebUI 将您的文档分割成块，将其嵌入为向量，将其存储在向量数据库中，并在聊天时仅检索相关部分以传递给模型。
两种使用方式，按简单性顺序 ：
- 一次性附件。 将文件拖到任何聊天输入中并提出问题。文件被分割和嵌入仅用于该聊天。
- 知识库。 对于您想跨许多聊天重用的文档（公司手册、代码库、研究库、用户手册），去工作区 > 知识并创建知识库。然后您可以将整个知识库附加到聊天（通过输入中的
#快捷方式），或在工作区 > 模型中将其绑定到模型，以便该模型始终可用。
默认值对于入门是合理的。当您超过它们时，有三个最重要的旋钮：
- 嵌入引擎。 默认值（SentenceTransformers
all-MiniLM-L6-v2）在 CPU 上本地运行，每个工作进程消耗约 500 MB 的 RAM。对于任何多用户部署，通过RAG_EMBEDDING_ENGINE指向外部嵌入 API（OpenAI 或 Ollama withnomic-embed-text）。 - 内容提取引擎。 默认值使用
pypdf，在重型摄取期间会泄漏内存。对于任何超出偶然使用的内容，通过CONTENT_EXTRACTION_ENGINE切换到 Tika 或 Docling。 - 向量数据库。 默认 ChromaDB（本地 SQLite 支持）不容忍多工作进程部署。在规模上，切换到 PGVector — 它是 Open WebUI 团队正式支持和维护的唯一向量数据库。Milvus、Qdrant 和 MariaDB Vector 也可用，但由社区维护：它们可能在升级时中断，修复取决于社区贡献。请参阅环境配置参考了解设置和每个提供程序的社区免责声明。
对于"一个有少数 PDF 的单一用户"，这些都不重要。一旦您有 100 个文档或 10 个并发用户，所有这些都开始重要。
推荐的起始配置
如果您只想 RAG 开箱即用，这些设置是坚实的通用起点。它们不是针对每个用例进行精细调整，但对大多数文档类型会比默认值产生明显更好的结果。
在管理面板 > 设置 > 文档中设置这些：
| 设置 | 默认值 | 推荐值 | 原因 |
|---|---|---|---|
| 文本分割器 | character | token | 基于令牌的分割在不同文档类型中产生更一致的块大小 |
| Markdown 标题分割 | 开 | 开 | 通过在标题处分割来尊重文档结构，保持部分连贯 |
| 块大小 | 1000 | 2000 | 较大的块保留每次检索命中周围更多的上下文 |
| 块重叠 | 100 | 200 | 更多重叠意味着更低的风险会切断关键句子一半 |
| 顶部 K | 3 | 15 | 检索更多候选块，给模型更广泛的相关上下文池。如果您使用具有受约束上下文大小的本地模型，将其降低到 5 以避免用检索块填充上下文窗口 |
| 嵌入模型 | all-MiniLM-L6-v2（本地 CPU） | 外部（OpenAI 或 Ollama） | 默认值对单一用户有效，但每个工作进程消耗约 500 MB RAM。对于任何多用户设置，改用外部嵌入 API |
默认 SentenceTransformers 模型在 CPU 上本地运行，对单一用户入门是可以的。对于超出那个的任何东西，指向外部嵌入 API：使用 OpenAI API 密钥设置 RAG_EMBEDDING_ENGINE=openai，或使用任何 Ollama 嵌入模型设置 RAG_EMBEDDING_ENGINE=ollama（例如，nomic-embed-text）。这将卸载工作并释放重要的 RAM。
更多详情：
- RAG 概览
- 知识工作区
- RAG 性能调优
- 扩展：外部向量数据库 — 多工作进程和多副本部署所需
- 扩展：内容提取和嵌入 — 在规模上修复内存泄漏
开放终端
如果"运行 Python"太受限制，您想让模型实际在您的机器上工作（克隆仓库、安装包、运行测试套件、启动网站的本地预览、根据真实 CSV 迭代数据报告），这就是开放终端的用途。它连接真实的 shell（默认在 Docker 容器中沙箱化，或裸机如果您想要）作为工具模型可以调用，就像它调用任何其他工具一样。包含聊天内文件浏览器、实时网络预览和技能定义。
这是超过基本聊天后最大的"恍然大悟"功能。它将 Open WebUI 从聊天 UI 转变为模型实际为您构建事物的地方。如果原生模式开启，您已给模型一个有能力的终端，要求它为您构建一个小应用程序或对文件夹进行分析，看着它进行。
更多详情：
cptr（Open WebUI Computer）由 Open WebUI 团队开发，把你的整台电脑放进一个浏览器标签页：文件、终端、git、编辑器与 AI，从任何设备都能访问。它通过网关 API 接入 Open WebUI。
接下来做什么
您不需要上面的所有内容在第一天。新安装的合理顺序：
- 第一天： 选择一个好的默认模型，进行一些对话，熟悉 UI。
- 之后第一件事： 设置一个任务模型并决定您实际上想启用的后台工作。这是您可以进行的最大"感觉更好"的改变，它直接解决隐藏的每次聊天成本。
- 在第一周内： 全局启用原生模式并安装一个或两个与您的工作匹配的工具。
- 当您遇到它时： 第一次看到"提示太长"时安装上下文过滤器。
- 当您需要它时： 第一次想要跨多个文档提出问题时设置知识库。
- 当您准备好做大事时： 将模型指向开放终端，让它实际为您构建事物。
- 当您扩展时： 如果超过单一用户，重新访问 RAG 基础设施部分。
所有其他东西（企业 SSO、多副本 HA、Redis 扩展、可观测性）在高级主题和故障排除中，当且仅当您需要时。
故障排除
当出现问题时，从这里开始：
| 有问题... | 阅读这个 |
|---|---|
| 连接被拒绝、401 错误、CORS 失败、WebSocket 断开连接 | 连接错误 |
| "提示太长"或超过上下文窗口 | 上下文窗口/提示太长 |
| RAG 不返回相关结果、上传失败、知识库问题 | RAG 故障排除 |
| 网络搜索不工作或返回结果差 | 网络搜索故障排除 |
| 图像生成错误或提供程序设置 | 图像生成故障排除 |
| 语音转文本、文本转语音或音频播放 | 音频故障排除 |
| SSO、OAuth 或 LDAP 登录问题 | SSO 和 OAuth 故障排除 |
| 高内存使用、缓慢响应或工作进程崩溃 | 性能和 RAM · 扩展指南 |
| 登录循环、配置偏差或多副本设置中的数据库锁 | 扩展和 HA 故障排除 · 扩展指南 |
| 锁定管理员账户 | 重置管理员密码 |
| 具有自定义/内部 CA 的 TLS 证书错误 | 自定义 CA 存储 |
| Alembic 迁移错误或手动架构修复 | 数据库迁移 |
有问题？
本页是简化版本。完整文档深入了解更多。如果您没有找到您需要的：
- 搜索文档：使用任何页面顶部的搜索框。这里面有比本概览涵盖的要多得多。
- 在 GitHub Discussions 中提问：最好用于开放式问题、功能讨论和"我如何做 X？"线程。可搜索且对将来遇到相同问题的用户可见。
- 在 Discord 中提问：最活跃的社区。尝试
#questions频道；那里也有一个实验性机器人，具有完整文档和问题上下文，可以在几秒内回答大多数问题。 - 在 Reddit 中提问：用于更广泛的讨论、部署故事和社区展示。
- 报告错误：仅在您确认它是错误之后（可重现、最新版本、模板已填写）。"它不工作"问题会关闭；"这是确切的重现、这些是日志"问题会得到修复。