open-webui的部署和使用

本文最后更新于 2026年3月13日 上午

本文主要根据大模型集成交互界面open-webui的官方文档摘取了其配置和使用方法。

open-webui

概述

  • Open WebUI 是一个让您能够按照自己的方式运行 AI 的平台。您可以连接到任何模型——无论是本地模型还是云端模型。
  • 可连接 Ollama、OpenAI、Anthropic 或任何兼容平台。支持本地运行、云端运行或两者兼备。数据始终保留在它应该在的地方。
  • 语音、视觉、检索、生成、搜索。支持 Python 扩展。即刻可用。
  • Open WebUI 是一个可扩展、功能丰富且用户友好的自托管 AI 平台，旨在完全离线运行。 它基于通用标准构建，支持 Ollama 和 OpenAI 兼容协议 （特别是聊天补全）。这种协议优先的方法使其成为一个功能强大、与提供商无关的 AI 部署解决方案，适用于本地和云端模型。
  • 文档和功能完善，且扩展性（企业级多用户）高。

主要特性

  • 🚀 轻松安装 ：使用 Docker 或 Kubernetes（kubectl、kustomize 或 helm）无缝安装，享受轻松体验，同时支持 :ollama 和 :cuda 标签的镜像。
  • 🤝 Ollama/OpenAI API 集成 ：轻松集成兼容 OpenAI 的 API，实现与 Ollama 模型的多样化对话。自定义 OpenAI API URL，以连接 LMStudio、GroqCloud、Mistral、OpenRouter 等 。
  • 📱 响应式设计 ：在台式电脑、笔记本电脑和移动设备上享受无缝体验。
  • 📱 移动端渐进式 Web 应用 (PWA) ：使用我们的 PWA，在您的移动设备上享受类似原生应用的体验，提供本地主机上的离线访问和无缝的用户界面。
  • 📱 移动端渐进式 Web 应用 ：在您的移动设备上享受原生渐进式 Web 应用体验，支持在 localhost 或个人域名上离线访问，并拥有流畅的用户界面。为了确保我们的 PWA 能够安装在您的设备上，它必须在安全的环境中运行。这通常意味着它必须通过 HTTPS 提供服务。
  • ✒️🔢 完全支持 Markdown 和 LaTeX ：通过全面的 Markdown 和 LaTeX 功能提升您的 LLM 体验，实现更丰富的交互。
  • 🌐 网页浏览功能 ：使用 # 命令后跟网址，即可将网站无缝集成到聊天体验中。此功能允许您将网页内容直接融入对话，从而丰富和深入地促进互动。
  • 🎨 图像生成与编辑集成 ：使用多个引擎创建和编辑图像，包括 OpenAI 的 DALL-E、Gemini、ComfyUI（本地）和 AUTOMATIC1111（本地），支持生成和基于提示的编辑工作流程。
  • ⚙️ 多模型对话 ：轻松同时与多个模型互动，充分利用它们的独特优势，获得最佳反馈。并行使用多种模型，提升您的体验。
  • 🛠️ 引导式初始设置 ：清晰地完成设置过程，包括在首次设置期间明确指示创建管理员帐户。
  • 📂 集中式文件管理 ：统一的控制面板，方便您在一个地方搜索、查看和管理所有已上传的文档。删除文件时，会自动清理知识库关联和矢量嵌入。了解更多文件管理信息。
    • 通过上传文档（PDF、Word 文档、文本文件等），您可以将 AI 的响应建立在您自己的数据之上。
      • 聊天上传 ：只需将文件拖放到聊天中，或使用上传图标即可。
      • 知识库 ：将文件添加到结构化集合中，以便更永久、更有条理地检索。
  • 📄 使用多个引擎进行高级文档提取 ：使用您选择的提取引擎（Apache Tika、Docling、Azure Document Intelligence、Mistral OCR 或外部自定义（自建）内容提取引擎/文档加载器）从各种文档格式（包括 PDF、Word 文档、Excel 电子表格、PowerPoint 演示文稿等）中提取文本和数据。高级文档处理功能可与您的知识库无缝集成，在保留文档结构和格式的同时，支持对扫描文档和图像进行光学字符识别 (OCR)。了解更多关于文档提取的信息。
  • 🔍 网络搜索助力 RAG 和智能搜索研究 ：使用包括 SearXNG、Google PSE、Brave Search、Kagi、Mojeek、Bocha、Tavily、Perplexity 等在内的 15 多个搜索提供商执行网络搜索。使用原生函数调用时，模型可以按顺序执行多个搜索，并使用 fetch_url 工具读取完整页面内容以进行深度研究。了解智能搜索。
  • 🎨 图像生成与编辑集成 ：使用 DALL-E、Gemini、ComfyUI 和 AUTOMATIC1111 等引擎无缝创建和编辑图像。支持原生工具调用 ，允许模型在对话过程中独立生成和优化图像。了解更多关于图像生成的信息。
  • 🔍 文本选择快速操作 ：当 LLM 响应中的文本被突出显示时，会出现浮动按钮，提供“提问”或“解释”等更深入的交互，从而增强整体用户体验。
  • 🔄 便携式导入/导出 ：轻松导入和导出 Open WebUI 配置，简化跨多个系统复制设置的过程。
  • 💬 真正的异步聊天 ：享受不间断的多任务处理，支持真正的异步聊天，您可以创建聊天，离开聊天室，随时返回聊天室，回复内容已准备就绪。

部署

部署方式

  • Docker： 官方支持，并推荐给大多数用户使用
  • Python： 适合资源匮乏的环境或需要手动设置的用户
  • Kubernetes： 非常适合需要扩展和编排的企业级部署

我们提供多种安装方式，包括非 Docker 原生安装方法、Docker Compose、Kustomize 和 Helm。请访问我们的 Open WebUI 文档或加入我们的 Discord 社区获取更全面的指导。

Docker

为什么 Open WebUI 强调使用 Docker？

使用docker部署open-webui更方便使用官方支持的各种功能，比如文档提取。推荐使用此部署方式，一劳永逸。

安装指南

安装

使用 Docker 安装 Open WebUI 时，请务必在 Docker 命令中包含 -v open-webui:/app/backend/data 。这一步至关重要，它可以确保数据库正确挂载，防止数据丢失。

如果您希望使用包含 Ollama 或 CUDA 加速的 Open WebUI，我们建议您使用带有 :cuda 或 :ollama 标签的官方镜像。要启用 CUDA，您必须在 Linux/WSL 系统上安装 Nvidia CUDA 容器工具包 。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 如果您的电脑上安装了 Ollama ，请使用以下命令（一般情况）：
docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main

# 如果 Ollama 位于其他服务器上 ，请使用以下命令：
# 要连接到另一台服务器上的 Ollama，请将 `OLLAMA_BASE_URL` 更改为服务器的 URL：
docker run -d -p 3000:8080 -e OLLAMA_BASE_URL=https://example.com -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main

# 要运行支持 Nvidia GPU 的 Open WebUI ，请使用以下命令：
docker run -d -p 3000:8080 --gpus all --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:cuda

# 如果您仅使用 OpenAI API ，请使用以下命令：
docker run -d -p 3000:8080 -e OPENAI_API_KEY=your_secret_key -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main

# 安装带有捆绑 Ollama 支持的 Open WebUI
# 支持 GPU ：运行以下命令即可利用 GPU 资源：
docker run -d -p 3000:8080 --gpus=all -v ollama:/root/.ollama -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:ollama
# 仅使用 CPU ：如果您未使用 GPU，请改用以下命令：
docker run -d -p 3000:8080 -v ollama:/root/.ollama -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:ollama

## 等等，其它场景请见官方文档

安装完成后，您可以通过 http://localhost:3000 访问 Open WebUI。祝您使用愉快！😄

1
docker tag ghcr.io/open-webui/open-webui:main ghcr.io/open-webui/open-webui:v1.1.1  # （可选）备份当前image版本

可能的报错：

在生产环境中使用图像标签

如果您希望始终运行最新版本的 Open WebUI，可以根据您的配置使用 :main 、 :cuda 或 :ollama 镜像标签，如上例所示。对于稳定性和可复现性至关重要的 production environments ，建议锁定特定版本，而不是使用这些浮动标签。版本化镜像遵循以下格式：

1
ghcr.io/open-webui/open-webui:<RELEASE_VERSION>-<TYPE>

示例（图中所示版本仅用于说明目的）：

1
2
3
ghcr.io/open-webui/open-webui:v0.8.0
ghcr.io/open-webui/open-webui:v0.8.0-ollama
ghcr.io/open-webui/open-webui:v0.8.0-cuda

（可选）配置网络代理

v2rayN 必须允许来自 Docker 的连接

问题：v2rayN 默认可能只监听 127.0.0.1，而 Docker 容器通过 host.docker.internal 访问时，来源 IP 是 Docker 网关（如 172.17.0.1）。

检查方法：

1
2
# 检查 v2rayN 监听地址
netstat -ano | findstr "10808"

预期输出：

1
2
3
4
5
# ✅ 正确：监听所有接口
TCP    0.0.0.0:10808          0.0.0.0:0              LISTENING

# ⚠️ 可能有问题：只监听本地
TCP    127.0.0.1:10808        0.0.0.0:0              LISTENING

解决方案（如果需要）：

  1. v2rayN 设置 → 参数设置 → 允许来自局域网的连接 → 启用 → 确定。

完整的启动脚本

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
# =========================
# Open WebUI via docker run
# =========================

# ---- 可修改区：按需改成你的值 ----

# 安全配置（JWT 密钥）
# 重要：首次设置后不要随意更改，否则用户会话会失效
$WEBUI_SECRET_KEY = "your-secure-random-key-change-this"

# 数据目录（强烈建议用本机目录，而不是匿名 volume，方便备份/迁移）
$DataDir       = "C:\xxx\data"

# 容器基础配置
$ContainerName = "open-webui"
$Image         = "ghcr.io/open-webui/open-webui:main"

# WebUI 对外端口：浏览器访问 http://localhost:3000
$HostPort      = 3000
$ContainerPort = 8080

# 代理配置（v2rayN 默认端口 10808 或 10809）
# 如果你需要让容器内访问 HuggingFace / GitHub 等走代理
$PROXY_HOST = "host.docker.internal"
$PROXY_PORT = "10808"

# HuggingFace 镜像
# 解决报错：huggingface_hub.utils._errors.LocalEntryNotFoundError
$HfEndpoint    = "https://hf-mirror.com"

# CORS：允许哪些前端 Origin 访问后端（通常你只在本机用 3000 就够了）
# 注意：Open WebUI 默认前端就是同源，只有在“前后端分离/反向代理/端口不同”时更需要配置
# https://docs.openwebui.com/reference/env-configuration/#cors_allow_origin
# 解决警告：WARNING: CORS_ALLOW_ORIGIN IS SET TO '*' - NOT RECOMMENDED FOR PRODUCTION DEPLOYMENTS.
$CorsAllowOrigin = "http://localhost:$HostPort;http://127.0.0.1:$HostPort"

# 解决警告：WARNI [langchain_community.utils.user_agent] USER_AGENT environment variable not set, consider setting it to identify your requests.
$UserAgent = "open-webui/0.8.3 (https://github.com/open-webui/open-webui)"

# 启用[KV 缓存优化](https://docs.openwebui.com/features/chat-conversations/rag/#kv-cache-optimization-performance-tip-)
$RagSystemContext = "True"

# ---- 准备工作：测试网络 ----
Test-NetConnection 127.0.0.1 -Port $PROXY_PORT
python C:\xxx\test_proxy.py

# ---- 准备工作：检查数据目录必须已存在，否则报错退出 ----
if (!(Test-Path -LiteralPath $DataDir)) {
  Write-Error "DATA_DIR does not exist: $DataDir. Please create it first (e.g. New-Item -ItemType Directory -Path '$DataDir')."
  exit 1
}

# 防止 $DataDir 指向的是文件而不是目录
if (-not (Test-Path -LiteralPath $DataDir -PathType Container)) {
  Write-Error "DATA_DIR exists but is not a directory: $DataDir"
  exit 1
}

# ---- 如果已存在同名容器，先停掉并删除，避免冲突 ----
$existing = docker ps -a --format "{{.Names}}" | Where-Object { $_ -eq $ContainerName }
if ($existing) {
  Write-Host "Stopping existing container: $ContainerName"
  docker stop $ContainerName | Out-Null
  Write-Host "Removing existing container: $ContainerName"
  docker rm $ContainerName   | Out-Null
}

# ---- 在默认浏览器中打开网址 ----
Start-Process "http://localhost:$HostPort"

# ---- 创建并运行容器 ----
docker run -d `
  --name $ContainerName `
  --restart no `
  -p ${HostPort}:${ContainerPort} `
  --add-host=host.docker.internal:host-gateway `
  -v "${DataDir}:/app/backend/data" `
  -e HTTP_PROXY=http://${PROXY_HOST}:${PROXY_PORT} `
  -e HTTPS_PROXY=http://${PROXY_HOST}:${PROXY_PORT} `
  -e NO_PROXY="localhost,127.0.0.1,::1,0.0.0.0,.local,.lan,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,host.docker.internal" `
  -e HF_ENDPOINT=$HfEndpoint `
  -e DATA_DIR="/app/backend/data" `
  -e CORS_ALLOW_ORIGIN=$CorsAllowOrigin `
  -e USER_AGENT=$UserAgent `
  -e RAG_SYSTEM_CONTEXT=$RagSystemContext `
  -e WEBUI_SECRET_KEY=$WEBUI_SECRET_KEY `
  $Image

Write-Host ""
Write-Host "Open WebUI is starting..."
Write-Host "URL: http://localhost:$HostPort"
Write-Host ""
Write-Host "Logs: docker logs -f $ContainerName"
Write-Host ""

(docker exec open-webui env | Select-String "PROXY").Line
Write-Host ""

docker logs -f $ContainerName
1
2
3
4
5
6
7
8
9
# 停止容器（两种策略都可以）
docker stop open-webui

# （可选）备份当前image版本
docker tag ghcr.io/open-webui/open-webui:main ghcr.io/open-webui/open-webui:v1.1.1

# 验证状态
docker ps --filter name=open-webui
# 输出：无（容器已停止）

更新

原版 containrrr/watchtower 已停止维护 ，可能无法兼容较新的 Docker 版本。我们建议使用 nickfedor/watchtower 分支。

如果容器名称不同，请将 open-webui 替换为您的容器名称。

使用 Watchtower 手动更新 Docker 容器：

1
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock nickfedor/watchtower --run-once open-webui

或，每 5 分钟自动更新一次容器：

1
docker run -d --name watchtower --restart unless-stopped -v /var/run/docker.sock:/var/run/docker.sock nickfedor/watchtower --interval 300 open-webui

或，

1
2
3
4
5
6
7
8
9
10
11
12
13
docker images  # 查看镜像

docker tag ghcr.io/open-webui/open-webui:main ghcr.io/open-webui/open-webui:v1.1.1  # （可选）备份当前image版本

docker pull ghcr.io/open-webui/open-webui:main  # 拉取最新版本

docker tag ghcr.io/open-webui/open-webui:main ghcr.io/open-webui/open-webui:v1.1.2  # （可选）标记更新后的image版本

# 停止并移除当前容器
docker stop open-webui
docker rm open-webui

docker run --name open-webui ghcr.io/open-webui/open-webui:main  # 重新启动容器（请对照实际运行命令）

卸载

1
2
3
docker rm -f open-webui  # 停止并移除容器
docker rmi ghcr.io/open-webui/open-webui:main  # 移除Image（可选）
docker volume rm open-webui  # 删除卷（可选，警告：删除所有数据）： 如果您想彻底删除您的数据（聊天记录、设置等）

conda

安装

  1. 创建环境与安装open-webui：
1
2
3
4
5
6
7
8
9
10
11
12
13
# Linux
conda create --name open-webui python=3.11  

# Windows
conda create --copy --name open-webui python=3.11  
# 打开新建环境下的Lib文件夹的site.py文件(C:\Users\username\.conda\envs\conda_env\Lib\site.py), 找到USER_SITE、USER_BASE那两行, 默认是None, 修改后如下:
USER_SITE = r"C:\Users\username\.conda\envs\conda_env\Lib\site-packages"
USER_BASE = r"C:\Users\username\.conda\envs\conda_env\Scripts"
# 记得加上r抑制转义, 否则有可能因为非法转义报错, 导致进入不了虚拟环境。

conda activate open-webui

pip install open-webui -i https://pypi.tuna.tsinghua.edu.cn/simple  # 临时换源（清华源）
  1. 配置环境变量：
1
2
3
4
5
6
7
$env:DATA_DIR="C:\xxx\open-webui\data"  # 设置 DATA_DIR 环境变量设置指定文件夹
$env:DATA_DIR  # 查看环境变量的值（的方法）
Write-Host "DATA_DIR: $env:DATA_DIR" -ForegroundColor Green  # 使用 Write-Host 打印消息（带颜色）
# https://docs.openwebui.com/reference/env-configuration/#cors_allow_origin
$env:CORS_ALLOW_ORIGIN="http://localhost:8080;http://127.0.0.1:8080"  # 解决警告：WARNING: CORS_ALLOW_ORIGIN IS SET TO '*' - NOT RECOMMENDED FOR PRODUCTION DEPLOYMENTS.
$env:USER_AGENT="open-webui/0.8.3 (https://github.com/open-webui/open-webui)"  # 解决警告：WARNI [langchain_community.utils.user_agent] USER_AGENT environment variable not set, consider setting it to identify your requests.
$env:HF_ENDPOINT="https://hf-mirror.com"  # 解决报错：huggingface_hub.utils._errors.LocalEntryNotFoundError

如果您想将数据存储在特定位置，请使用（Linux/Mac）： DATA_DIR=./data open-webui serve 或（Windows）： $env:DATA_DIR=".\data"; open-webui serve

  1. 启动open-webui：
1
open-webui serve  # 使用该命令启动服务器

此方法会安装所有必要的依赖项并启动 Open WebUI，从而实现简单高效的设置。安装完成后，您可以通过 http://localhost:8080 访问 Open WebUI（或可尝试 http://localhost:3000）。祝您使用愉快！😄

“OPEN-WEBUI：未找到命令”？

如果终端显示命令不存在：

  1. 确保您的 conda 环境已激活 （ conda activate open-webui ）。
  2. 如果仍然出现错误，请尝试直接通过 Python 运行： python -m open_webui serve

（可选）配置网络代理

指定open-webui走使用v2rayN配置的网络代理

1
2
3
4
5
# 如果您的 v2rayN 监听在 10808 端口
$env:HTTP_PROXY="http://127.0.0.1:10808"
$env:HTTPS_PROXY="http://127.0.0.1:10808"
# 建议把本机与常见内网段排除，避免访问本地/局域网服务也走代理导致异常
$env:NO_PROXY = "localhost,127.0.0.1,::1,0.0.0.0,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16"
  • HTTP_PROXY：指定 HTTP 请求的代理服务器。
  • HTTPS_PROXY：指定 HTTPS 请求的代理服务器。重要：值仍然是 http:// 开头！ 原因：客户端与代理服务器之间的通信是 HTTP 协议，代理服务器再与目标网站建立 HTTPS 连接（CONNECT 方法）。
  • NO_PROXY：指定不走代理的地址列表。

验证 open-webui 是否使用 v2rayN 代理？

  • 测试网络端口是否存在：

    1
    Test-NetConnection 127.0.0.1 -Port 10808
    • TcpTestSucceeded : True → 情况 1（代理端口在）
    • False → 情况 2（代理端口不在/不可达）

  • 运行以下测试脚本：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    # test_proxy.py
    import requests
    import os

    # 检查环境变量
    print("=== 环境变量检查 ===")
    print(f"HTTP_PROXY: {os.environ.get('HTTP_PROXY', '未设置')}")
    print(f"HTTPS_PROXY: {os.environ.get('HTTPS_PROXY', '未设置')}")
    print(f"NO_PROXY: {os.environ.get('NO_PROXY', '未设置')}")

    # 测试需要代理的网站
    print("\n=== 代理连接测试 ===")
    test_urls = [
        ("Google", "https://www.google.com"),
        ("OpenAI", "https://api.openai.com"),
        ("GitHub", "https://api.github.com"),
    ]

    for name, url in test_urls:
        try:
            response = requests.get(url, timeout=5)
            print(f"✅ {name}: 成功 (状态码: {response.status_code})")
        except Exception as e:
            print(f"❌ {name}: 失败 ({str(e)})")

  • 查看 v2rayN 连接日志是否有新的连接记录，如果看到类似以下日志，说明代理生效：

    1
    2
    2026-02-17 16:30:15 [INFO] 127.0.0.1:xxxxx → api.anthropic.com:443
    2026-02-17 16:30:15 [INFO] 127.0.0.1:xxxxx → api.openai.com:443

  • 在 open-webui 中测试需要代理的 API。在Admin Settings-Connections-OpenAI- Manage-Add New Connection，点开窗口输入URL和API Key后有一个”测试连接“按钮。

  • 使用网络监控工具TCPView

    1. 下载 TCPView（微软官方工具）
    2. 运行 TCPView，筛选（搜索） python 或 open-webui 进程。
    3. 在 open-webui 中触发 API 请求。
    4. 观察连接目标
      • 如果看到连接到 127.0.0.1:10808（v2rayN 端口），说明代理生效。
      • 如果直接连接到外部 IP（如 104.18.x.x），说明未走代理。

  • 等等。

完整的启动脚本

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
# start-open-webui.ps1

# 激活conda环境
conda activate open-webui

# ===== 网络代理配置（控制后端外网请求）=====
# 如果您的 v2rayN 监听在 10808 端口
$env:HTTP_PROXY="http://127.0.0.1:10808"
$env:HTTPS_PROXY="http://127.0.0.1:10808"
# 建议把本机与常见内网段排除，避免访问本地/局域网服务也走代理导致异常
$env:NO_PROXY = "localhost,127.0.0.1,::1,0.0.0.0,.local,.lan,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16"
# 使用 Write-Host 打印消息（带颜色）
Write-Host "HTTP_PROXY: $env:HTTP_PROXY" -ForegroundColor Green
Write-Host "HTTPS_PROXY: $env:HTTPS_PROXY" -ForegroundColor Green
Write-Host "NO_PROXY: $env:NO_PROXY" -ForegroundColor Green

# 从 HTTP_PROXY 中提取主机和端口
if ($env:HTTP_PROXY -match 'https?://([^:/]+):(\d+)') {
    $proxyHost = $matches[1]
    $proxyPort = $matches[2]
    
    # 测试网络端口是否存在
    Test-NetConnection $proxyHost -Port $proxyPort
} else {
    Write-Host "无法解析 HTTP_PROXY 格式"
}

python C:\xxx\test_proxy.py

Write-Host

# 解决报错：huggingface_hub.utils._errors.LocalEntryNotFoundError
$env:HF_ENDPOINT="https://hf-mirror.com"
Write-Host "HF_ENDPOINT: $env:HF_ENDPOINT" -ForegroundColor Green

# 设置 DATA_DIR 环境变量设置指定文件夹
$env:DATA_DIR="C:\xxx\open-webui\data"
Write-Host "DATA_DIR: $env:DATA_DIR" -ForegroundColor Green

# https://docs.openwebui.com/reference/env-configuration/#cors_allow_origin
# 解决警告：WARNING: CORS_ALLOW_ORIGIN IS SET TO '*' - NOT RECOMMENDED FOR PRODUCTION DEPLOYMENTS.
$env:CORS_ALLOW_ORIGIN="http://localhost:8080;http://127.0.0.1:8080"
Write-Host "CORS_ALLOW_ORIGIN: $env:CORS_ALLOW_ORIGIN" -ForegroundColor Green

# 解决警告：WARNI [langchain_community.utils.user_agent] USER_AGENT environment variable not set, consider setting it to identify your requests.
$env:USER_AGENT="open-webui/0.8.3 (https://github.com/open-webui/open-webui)"
Write-Host "USER_AGENT: $env:USER_AGENT" -ForegroundColor Green

# 启用[KV 缓存优化](https://docs.openwebui.com/features/chat-conversations/rag/#kv-cache-optimization-performance-tip-)
$env:RAG_SYSTEM_CONTEXT="True"
Write-Host "RAG_SYSTEM_CONTEXT: $env:RAG_SYSTEM_CONTEXT" -ForegroundColor Green

Write-Host

# 在默认浏览器中打开网址
Start-Process "http://localhost:8080"

# 启动服务器
open-webui serve

在Windows Powershell终端执行该脚本即可：

1
C:\xxx\start-open-webui.ps1

更新

1
2
3
conda activate open-webui
pip index versions open-webui  # 查看可用版本
pip install --upgrade open-webui -i https://pypi.tuna.tsinghua.edu.cn/simple # 更新

卸载

1
2
conda remove --name open-webui --all
rm -rf ~/.open-webui  # 删除数据（警告：将删除所有数据），删除您的数据目录（通常为 ~/.open-webui ，除非另有配置）

uv

小知识

  • open-webui 的 Docker 部署 和 conda 部署使用相同的数据格式，可以直接复用 DATA_DIR 文件夹。
    • ✅ 先备份数据目录（以防万一）
    • ✅ 完全停止 conda 实例后再启动 Docker
    • ✅ 使用 -v 挂载现有目录到容器
    • ✅ 启动后验证数据完整性
  • 等等。

快速入门

其它

  • 创建管理员：在 Open WebUI 上创建的第一个帐户将获得管理员权限 ，可以控制系统用户管理和系统设置。
  • **用户注册：**后续注册均处于 “待审核” 状态，需要管理员批准才能访问。
  • 浏览器缓存： 有时，即使启用了热刷新，浏览器缓存也会阻止您看到最新更改。请尝试强制刷新浏览器：
    • Windows/Linux： Ctrl+Shift+R
    • macOS： Cmd+Shift+R
    • 或者，您可以尝试清除浏览器缓存或在隐私/隐身浏览器窗口中打开前端。
  • Open WebUI 的更新频率如何？（发布计划）
    • 我们的目标是每周发布主要版本 ，并根据需要发布错误修复和小幅更新 。但这并非绝对的计划——有些周可能会发布多个版本，而有些周可能一个版本都没有。
    • 为了随时了解最新信息，您可以关注我们 GitHub Releases 页面上的发行说明和公告。
  • 请查看 https://github.com/open-webui/open-webui/releases 上的发行说明 ，了解重大变更。
  • 在进行重大版本更新之前， 请备份数据。
  • 更新后请清除浏览器缓存 ，以确保加载最新的网页界面。

API

常用的兼容服务器和提供商

有很多服务器和工具提供与 OpenAI 兼容的 API。选择最适合您工作流程的即可：

必需的 API 端点

为确保与 Open WebUI 完全兼容，您的服务器应实现以下 OpenAI 标准端点：

Endpoint Method Required? Purpose
/v1/models GET Yes Used for model discovery and selecting models in the UI.
/v1/chat/completions POST Yes The core endpoint for chat, supporting streaming and parameters like temperature.
/v1/embeddings POST No Required if you want to use this provider for RAG (Retrieval Augmented Generation).
/v1/audio/speech POST No Required for Text-to-Speech (TTS) functionality.
/v1/audio/transcriptions POST No Required for Speech-to-Text (STT/Whisper) functionality.
/v1/images/generations POST No Required for Image Generation (DALL-E) functionality.

Open WebUI 会传递标准的 OpenAI 参数，例如 temperature 、 top_p 、 max_tokens （或 max_completion_tokens ）、 stop 、 seed 和 logit_bias 。如果您的模型和服务器支持 tools 和 tool_choice 参数，它还支持工具使用 （函数调用）。

配置

Open WebUI 不仅适用于 OpenAI/Ollama/Llama.cpp，它还可以连接任何实现了 OpenAI 兼容 API 的服务器 ，无论服务器是本地运行还是远程运行。如果您想运行不同的语言模型，或者您已经有了自己喜欢的后端或生态系统，那么 Open WebUI 就是您的理想之选。

  • 我们支持的协议 ：任何遵循广泛采用的 API 标准（例如 Groq、OpenRouter、OpenAI、Mistral、Perplexity 等）的提供商都受到原生支持。我们也对 OpenResponse 提供实验性支持。
  • 我们避免使用专有 API ：为了维护通用且易于维护的代码库，我们不会在核心代码中实现特定于提供商的非标准 API。对于不受支持的提供商，请使用管道或中间件代理。
  • 如果您使用的提供商需要专有 API，我们建议使用**管道 **（浏览社区管道 ）或像 LiteLLM 或 OpenRouter 这样的中间件代理，将它们桥接到受支持的协议。

Open WebUI 对 Open Responses 提供实验性支持，Open Responses 是一种用于多提供商、可互操作 LLM 接口的开放规范。

为避免每次更新后都被注销，您必须设置一个持久的 WEBUI_SECRET_KEY 。在 Docker Compose 或环境配置中将 WEBUI_SECRET_KEY 设置为一个固定的安全字符串。长期登录会话

使用conda部署后第一次启动时，会提示：

1
2
3
Loading WEBUI_SECRET_KEY from file, not provided as an environment variable.
Generating a new secret key and saving it to C:\Users\xxx\.webui_secret_key
Loading WEBUI_SECRET_KEY from C:\Users\xxx\.webui_secret_key

Open WebUI 让您轻松连接和使用 OpenAI 及其他兼容 OpenAI 的 API。本指南将引导您完成添加 API 密钥、设置正确的端点以及选择模型等步骤，让您可以立即开始交互。

Open WebUI 是一个以协议为中心的平台。虽然我们为 OpenAI 模型提供一流的支持，但我们主要通过 OpenAI Chat Completions API 协议来实现这一点。

我们专注于数十家供应商共享的通用标准，并对诸如 Open Responses 等新兴标准提供实验性支持。有关详细说明，请参阅我们的**协议支持常见问题解答 **。

在 Open WebUI 中添加 API 链接：

  1. Open WebUI 运行后，前往⚙️ Admin Settings 。

  2. 导航至 Connections > OpenAI > Manage （查找扳手图标）。

  3. 点击➕ Add New Connection 。

    • 连接类型 ：External

    • URL ： https://api.openai.com/v1 （或您的服务提供商的端点）

    • API Key ：您的私钥（通常以 sk-... 开头）

    • Model IDs (Filter) ：默认值（空） ：自动检测提供商提供的所有可用型号。设置 ：用作Allowlist 。只有您在此处输入的特定型号 ID 才会对用户可见。使用此功能可以隐藏较旧或价格较高的型号。

      使用 OpenRouter 时，我们强烈建议 ：

      1. **使用allowlist ** （添加特定的模型 ID）。OpenRouter 会公开数千个模型，如果不进行过滤，这些模型会使模型选择器变得杂乱无章，并降低管理面板的运行速度。
      2. 启用模型缓存 （ Settings > Connections > Cache Base Model List 或 ENABLE_BASE_MODELS_CACHE=True ）。如果没有缓存，由于需要查询大量模型，页面首次加载可能需要 10-15 秒甚至更久。更多详情请参阅性能指南。

      某些提供商（例如 MiniMax ）不通过 /models 端点公开其模型。对于这些提供商，您必须手动将模型 ID（例如 MiniMax-M2.5 ）添加到模型 ID（筛选器） 列表中，才能使其显示在用户界面中。

    • Prefix ID：如果您连接了多个提供同名模型的供应商（例如，两个供应商都提供 llama3 ），请在此处添加前缀（例如， groq/ ）以区分它们。模型将显示为 groq/llama3 。

    • Click Save ✅。

    • 等等。

    适用于 Microsoft Azure OpenAI 部署。

  4. 完成。

如果您的 API 提供商响应缓慢或遇到超时问题，您可以调整模型列表获取超时时间：

1
2
# Increase timeout for slow networks (default is 10 seconds)
AIOHTTP_CLIENT_TIMEOUT_MODEL_LIST=15

如果您保存了一个无法访问的 URL，并且用户界面变得无响应，请参阅 “模型列表加载问题故障排除指南”以获取恢复选项。

自动补全

Open WebUI 提供了一项基于人工智能的自动完成功能，可在您输入提示时实时提供文本补全建议。它就像您聊天输入的“副驾驶”，帮助您使用已配置的任务模型更快地创建提示。

启用后，Open WebUI 会监控您在聊天框中的输入。当您停止输入时，它会将您当前的文本发送到一个轻量级任务模型 。该模型会预测接下来可能出现的单词或句子，这些预测会以“幽灵文本”的形式叠加在您的输入之上。

  • 接受建议 ：按 Tab （或 Right Arrow 键）接受建议。
  • 拒绝/忽略 ：只需继续输入即可覆盖建议。

自动完成功能很大程度上依赖于任务模型的响应速度。我们建议使用小型、快速、非推理模型，以确保建议能够即时显示。

推荐型号：

任务模型:

  • TASK_MODEL：在使用 Ollama 模型时，用于生成标题和网络搜索查询等任务的默认模型。
  • TASK_MODEL_EXTERNAL：在使用 OpenAI 兼容端点时，用于标题和网络搜索查询生成等任务的默认模型。

配置方法：

  1. Admin Panel Settings: Go to Admin Settings > Interface > Task Model and toggle Autocomplete Generation.

    Go to Admin Settings > Interface and verify a Task Model is selected. 如果未选择模型，则该功能无法生成预测。

    推理模型 ：请确保您未使用“推理”模型（如 o1 或 o3），因为它们的内部思维过程会产生过大的延迟，从而破坏实时自动完成功能。

    自动完成功能会在你每次暂停输入时向你的 LLM 发送请求。

    API 提供商 ：这将产生大量的 API 调用（尽管通常令牌数量很短）。请注意提供商的 Rate Limits (Requests Per Minute/RPM and Tokens Per Minute/TPM) ，以避免服务中断。

  2. 账户-设置-界面-输入-勾选“自动补全提示词”。

  3. 完成。

工具和功能

  • https://docs.openwebui.com/features/extensibility/plugin/

  • 社区资源获取

  • 工具扩展了 LLM 的功能，使其能够收集真实世界的实时数据，例如天气、股票价格等。

    • 工具是指允许 LLM 执行超出其默认能力范围的更多操作 （例如检索实时信息或根据外部数据执行自定义任务）的事物。

  • 函数扩展了 Open WebUI 本身的功能，使您能够添加新的 AI 模型支持（如 Anthropic 或 Vertex AI）或改进可用性（如创建自定义按钮或过滤器）。使用文档

    • 函数可以帮助 WebUI 本身执行更多操作 ，例如添加新的 AI 模型或创建更智能的数据筛选方式。
    • Auto Memory：自动记忆功能会监听你的对话，并检测事实、偏好、关键时刻或任何对助手有用的信息，以便它记住你。它将这些信息存储为单独的记忆，因此未来的 AI 交互将保持个性化和情境感知—— 无需您进行微观管理 。
    • Advanced Context Manager：这个OpenWebUI插件通过递归总结技术智能管理长对话上下文，避免传统截断方法导致的信息丢失。

  • Pipelines 更适合希望将 Open WebUI 功能转换为 API 兼容的工作流的高级用户——主要用于卸载繁重的处理任务。

  • 使用 Tools and Functions 非常简单，因为所有功能都已内置于核心系统中！您只需点击一个按钮 ，即可直接从社区导入这些功能 ，无需任何编码或复杂的技术工作。

文档长期记忆

怎样确保它能记住？

为了保险起见，建议你采取以下操作：

  1. 查看设置：检查你使用的平台是否有“开启记忆”、“保存到知识库”或“创建智能体”的选项，并确保它是打开的。
  2. 主动“投喂”：如果不确定它是否记得，最简单的方法是重新上传文档，或者在对话开始时提醒它：“请参考我之前上传的那份关于XX的文档”。
  3. 使用“文件上传”功能而非复制粘贴：很多平台现在支持“上传文件”并将其固定在侧边栏。这种上传方式通常比单纯复制粘贴文本更容易被系统识别为“长期知识”，因为它作为一个独立文件被存储了。

如何让你的开源界面也能“记住”？

如果你想让你的开源项目也具备“过几天还能记得文档”的能力，你需要做额外的开发工作（这正是商业平台的核心价值之一）：

  1. 建立外部数据库（你的“硬盘”）：
    • 当你第一次上传文档并聊天时，不仅要调用 API，还要把文档的关键信息（或向量化后的摘要）和对话历史存到数据库（如 SQLite, MongoDB, 或向量数据库）里。
  2. 实现“会话 ID”机制：
    • 给每个用户或每个对话窗口分配一个唯一的 ID。当你过几天再次在这个窗口聊天时，你的开源界面需要通过这个 ID 去数据库里检索“上次我们聊了什么”。
  3. 自动拼接上下文（RAG）：
    • 在你按下发送键的那一刻，你的开源界面需要先去数据库把“旧文档内容”找回来，把它插入到你当前的问题前面，组成一个新的、包含历史信息的 Prompt，然后再调用 API。

用户如何缓解大模型的“上下文窗口”长度限制？

对于非技术用户（普通用户）来说，虽然无法像开发者那样去修改模型代码或搭建向量数据库，但依然可以通过**“巧用工具”和“改变提问策略”**来有效缓解上下文窗口的限制。

结合当前主流大模型（如 GPT-4o, Claude-3, 通义千问等）的功能，我为你总结了以下 4 个实操性极强的方法：

1. 善用“文件分析”模式（最省心的方法）

不要把长文档内容直接复制粘贴到对话框里，而是利用平台原生的文件上传功能。

  • 为什么有效：像 ChatGPT Plus、Claude 或 Kimi 这样的成熟平台，当你上传 PDF、Word 或 TXT 文件时，它们在后台并不是简单地把全文塞进上下文窗口。它们通常会先对文件进行预处理（切片和向量化），当你提问时，系统只把与问题最相关的片段提取出来给模型看。
  • 怎么做：点击输入框旁边的“回形针”或“上传”图标，把文件传上去，然后直接问：“请根据我上传的文档，总结核心观点”。

2. 主动进行“人工摘要”（给模型减负）

当你进行多轮长对话时，上下文会越来越臃肿。你需要像导演一样，手动清理黑板。

  • 为什么有效：模型的“短期记忆”有限，太早的信息会被挤出窗口。你需要把早期的关键信息“压缩”成摘要，确保它始终在视野内。
  • 怎么做：
    1. 当一段讨论告一段落时，主动让模型生成一个摘要。例如，输入指令：“请用 300 字总结我们刚才讨论的方案要点。”
    2. 复制这个摘要。
    3. 开启一个新对话（或者在当前对话靠前的位置），先把摘要发给模型，再继续讨论新问题。这相当于手动给模型续上了“长期记忆”。

3. 改变提问话术：明确“关注重点”

当上下文很长时，模型可能会“注意力分散”。你需要通过指令（Prompt）明确告诉它该看哪里。

  • 为什么有效：通过指令强制模型去“检索”和“聚焦”，可以绕过部分上下文长度的限制。
  • 怎么做：
    • 加粗关键信息：在输入框里，把你最不想让它忘记的信息用 ** 标记（如果界面支持 Markdown）。
    • 使用明确指令：在问题末尾加上类似的话：“请务必参考上文中的‘需求规格’章节来回答，不要遗漏细节。”
    • 分段处理：如果要分析一篇超长文章，不要问“全文讲了什么”，而是分段让它处理：“请分析第 1-3 段的逻辑，然后我们再看后面的。”

4. 选择“长文本”专用模型（选对工具）

不同的模型，上下文窗口大小天差地别。

  • 为什么有效：与其在小池塘里挤，不如去大海里游。
  • 怎么做：
    • 如果你需要处理几万字的报告，优先选择宣称支持“长上下文”的模型，如 Claude-3 (支持 200K)、GPT-4o (支持 128K) 或国内的 Kimi (支持 200K+)。
    • 避免使用那些主要针对代码或短对话优化的轻量级模型（通常只有 4K-8K 窗口）。

💡 总结

作为普通用户，你不需要懂技术原理，只需要记住这三点：

  1. 上传文件优于复制粘贴。
  2. 聊久了就手动总结一下，开启新对话。
  3. 问问题时指令要明确，帮模型“划重点”。

Open WebUI 的记忆机制

简单来说，Open WebUI 就像一个带笔记本（数据库）的助手。虽然它不像某些商业 APP 那样拥有“黑科技”般的全自动长期记忆，但它通过技术手段实现了非常实用的持久化记忆。

具体表现如下：

1. 对话历史记忆：✅ 能记住（靠数据库）

表现： 如果你过几天再打开同一个对话窗口（Conversation），Open WebUI 会自动加载之前的聊天记录，并把它们作为上下文发送给大模型。

  • 原理：Open WebUI 默认会将你的所有聊天记录加密存储在本地的数据库中（如 SQLite）。当你点击那个旧的对话窗口时，它会自动从数据库里把历史消息（messages）读出来，拼接到新的请求里发送给 Ollama 或 API。
  • 限制：这依赖于“上下文窗口”的长度。如果你们之前的聊天内容太长（比如几万字），超出了模型的处理范围，最前面的内容会被“挤”出窗口，导致模型“忘记”开头的部分。

2. 文档/文件内容记忆：❌ 不能自动记住（需手动处理）

表现： 这是你最关心的一点。如果你上次上传了一个 PDF 或 TXT 文件，聊完就关了。过几天回来，模型不会自动“记得”那个文件的内容。

  • 原因：Open WebUI 默认的“记忆”是基于文本对话历史的。它存储了你们聊了什么，但通常不会自动把上次上传的文件内容“注入”到这次的对话中。
  • 除非：你使用了它的 RAG（检索增强生成） 功能或向量数据库插件（如 ChromaDB）。如果你在管理员设置里配置了知识库，并将文件存入了知识库，那么过几天回来，你可以通过提问触发检索，从而“唤醒”对文档的记忆。

3. 个性化记忆：✅ 可以手动设置

Open WebUI 还有一个**“记忆（实验性）”**功能（通常在设置 -> 个性化里）。

  • 表现：你可以手动添加一些关于你自己的信息（例如：“我是张三，我是一名程序员，我喜欢喝咖啡”）。
  • 原理：这些信息会被作为**系统提示词（System Prompt）**的一部分，永远跟随你的每一次对话。所以，哪怕隔一年，它依然记得你的名字和职业。

使用Open WebUI实现长期记忆

要在 Open WebUI 中实现长期记忆（特别是针对上传文档的记忆），核心方法就是利用 RAG（检索增强生成） 技术来创建和管理知识库。

简单来说，你需要把文档“喂”给知识库，这样即使过了几天，在新的对话中，模型也能实时从这个“硬盘”里检索信息，而不是依赖容易溢出的“短期记忆”（上下文窗口）。

以下是具体的操作步骤：

📚 第一步：创建并上传知识库

这是最关键的一步，相当于给你的 AI 建立一个可以随时查阅的“图书馆”。

  1. 进入知识库管理页面：
    • 登录 Open WebUI 后，在左侧菜单栏找到并点击 工作空间 (Workspace)，然后选择 知识库 (Knowledge)。
  2. 新建知识库：
    • 点击 + 新建知识库 (New Knowledge Base)。
    • 为你的知识库输入一个名称（建议使用英文或数字，避免特殊字符），例如 CompanyDocs 或 StudyNotes。
    • 点击确认创建。
  3. 上传文档：
    • 进入你刚创建的知识库页面，点击 上传文件 (Upload Files)。
    • 选择你想要长期记忆的文档。Open WebUI 支持多种格式，如 PDF、Word (.docx)、TXT、Markdown (.md) 等。
    • 上传成功后，系统会自动对文档进行索引处理（分块和向量化），你可以在状态栏看到处理进度。

💬 第二步：在对话中调用知识库

完成了知识库的建立，你就有两种方式在对话中使用它：

方式一：使用标签 # 调用（推荐）

这是最直接的方法，可以确保模型引用你指定的知识库内容。

  • 操作：在输入框中提问时，在问题末尾加上 # 符号和你创建的知识库名称。
  • 示例：假设你创建了一个名为 ProductManual 的知识库，你可以这样问：

    “请总结一下我们产品的核心功能 #ProductManual”

  • 效果：模型会自动检索 ProductManual 知识库中的相关内容，并基于这些内容来回答你，从而实现了跨越时间的“长期记忆”。

方式二：启用插件自动检索

你可以开启 RAG 插件，让它在后台自动判断是否需要检索知识库。

  • 操作：在聊天界面的插件中心（通常在输入框上方或侧边栏），找到名为 Retrieval Augmentation (检索增强) 或类似的插件并启用它。
  • 效果：开启后，当你提问涉及已上传知识的内容时，系统会自动尝试从知识库中检索相关信息片段，辅助模型生成更准确的答案。

🧠 补充：设置个性化记忆（针对个人信息）

如果你希望模型长期记住关于你自己的信息（例如你的名字、职业、喜好），可以使用“个性化记忆”功能。这相当于给模型设置一个永久的“备注”。

  • 路径：点击左下角你的头像 -> 设置 (Settings) -> 个性化 (Personalization)。
  • 操作：在“记忆（实验性）”区域，点击 管理，然后添加关于你自己的详细信息（例如：“我是张三，我是一名软件工程师，我正在研究大模型应用”）。
  • 效果：这些信息会被作为系统提示词的一部分，跟随每一次对话，确保模型始终“记得你是谁”。

通过以上步骤，你就可以充分利用 Open WebUI 的知识库功能，彻底解决文档记忆的问题。

创建知识库并使用

知识

摘自Knowledge。

知识库是 Open WebUI 中的一个部分，您可以在其中存储结构化信息，以便系统在您与系统交互时可以参考这些信息。

想象一下，你正在进行一个长期项目，希望系统能够记住某些参数、设置，甚至是项目的关键信息，而无需每次都手动提醒。或者，你可能希望它记住你在聊天和回复方面的特定个人偏好。

知识库部分用于存储此类持久信息 ，以便 Open WebUI 可以在未来的对话中引用它，从而创造更连贯、更个性化的体验 。

以下是一些您可以将内容存储在知识库中的示例：

  • 重要的项目参数或您将经常参考的具体数据点。
  • 您想要应用的自定义命令、工作流程或设置。
  • Open WebUI 在每次聊天中可以遵循的个人偏好、准则或规则。

Open WebUI 的知识库（Knowledge Base / RAG）适合的场景可以概括为一句话：当你希望模型回答“以你提供的资料为准”，并且这些资料量大、分散、经常要查证时。

在聊天中访问已存储的知识非常简单！只需引用已保存的内容（在名称前使用“#”），Open WebUI 即可提取数据或遵循您在知识部分设置的特定准则。

管理员可以将整个知识库导出为可下载的 zip 文件。这对于备份知识库、在不同实例之间迁移数据或与他人共享精心整理的知识库非常有用。

内容提取引擎

  • 文档提取：文档提取对于将非结构化文档内容转换为语言模型可以有效使用的结构化数据至关重要。Open WebUI 提供强大的文档提取功能，使您能够在 RAG（检索增强生成）工作流程中处理和分析各种类型的文档。

内容提取引擎用于知识库、聊天中的单个文件上传和网络搜索结果。

引擎选择逻辑

Open WebUI 通过 get_loader 函数实现智能引擎选择，源码位于：

1
backend/open_webui/retrieval/loaders/main.py

Navigate to Admin Panel → Settings → Documents → 通用 → 内容提取引擎。支持的提取引擎有：

  • 默认
  • 外部
  • Apache Tika（综合排名2）
  • Docling（综合排名1）
  • Datalab Marker API
  • Document Intelligence（综合排名3）
  • Mistral OCR
  • MinerU（综合排名3）
  • ...

引擎选择逻辑：

  • open-webui 的设计是：先由配置项 CONTENT_EXTRACTION_ENGINE 选一个大引擎（external/tika/docling/...），然后在这个引擎分支内部，再根据文件是否是“纯文本/代码类”决定走 TextLoader （main.py 顶部直接从 langchain_community.document_loaders 导入了 TextLoader）还是走该引擎的二进制解析/OCR能力；若不满足该引擎的启用条件，再 fallback 到默认的本地 loader（PDF/Office/unstructured 等）。

  • “纯文本/代码类”快速通道：_is_text_file(...)：它维护了一个 known_source_ext（包含大量源码/配置/日志/JSON 等扩展名），或 MIME 是 text/*（但排除 html）就认为是 text file，然后在很多引擎里会直接用 TextLoader，避免把源码/文本丢进 OCR/复杂解析。

    • 使用“默认”选项时，*.tex文件和*.md文件保持原内容。
    • 实测启用docling后，*.tex文件被docling转成了markdown格式（且自动去掉了原文中的注释），而没有被TextLoader处理。*.md文件同样。
    • pandoc latex转markdown表现出的效果（排版，图表、标题链接转换，等）要好于docling。
    • （双栏）pdf转markdown推荐使用docling、MinerU。
    • word文档转markdown推荐使用pandoc、docling。
    • 对于个人使用而言，为了更好的内容提取效果，在可行范围内，可以在本地使用更好的转换器把文档转成markdown格式后，在使用“默认”内容提取引擎上传到知识库？
    • def _is_text_file(self, file_ext: str, file_content_type: str) -> bool:
    return file_ext in known_source_ext or (
        file_content_type
        and file_content_type.find("text/") >= 0
        # Avoid text/html files being detected as text
        and not file_content_type.find("html") >= 0
    )

      1
      2
      3

      * ```python
        known_source_ext = ["go","py","java","sh","bat","ps1","cmd","js","ts","css","cpp","hpp","h","c","cs","sql","log","ini","pl","pm","r","dart","dockerfile","env","php","hs","hsc","lua","nginxconf","conf","m","mm","plsql","perl","rb","rs","db2","scala","bash","swift","vue","svelte","ex","exs","erl","tsx","jsx","hs","lhs","json",]

    • ...

  • tika：Apache Tika Server：

    • 触发条件：engine == "tika" 且 TIKA_SERVER_URL 存在

    • 策略：如果 _is_text_file(...) → TextLoader，否则 → TikaLoader（HTTP 调 Tika）

    • open-webui 实际“交给 Tika”的文件类型范围：

      open-webui 并没有显式列出 Tika 支持的扩展名白名单。
      它的策略是：

      • 只要不是 _is_text_file 判定的文本文件，就全部交给 Tika。

      因此在 open-webui 视角下：

      • 会交给 Tika 的：几乎所有“二进制/富文档”类型（PDF、Office、图片、EPUB 等），以及任何 MIME 不是 text/* 的文件（并且扩展名不在 known_source_ext）
      • 不会交给 Tika 的：源码/配置/日志/JSON 等在 known_source_ext 的文件；以及普通 text/plain 等（但 text/html 例外：HTML 不会被当成 text file，会交给 Tika）

      至于 Tika 自身到底能不能解析某个文件（例如某些图片/特殊格式），失败与否要看你的 Tika Server 组件/版本与解析器支持。

  • docling：Docling 服务（/v1/convert/file）：

    • 触发条件：engine == "docling" 且 DOCLING_SERVER_URL 存在

    • 策略：text file → TextLoader；否则 → DoclingLoader（HTTP POST + 可选 params）

    • open-webui 实际“交给 Docling”的文件类型范围：

      和 Tika 一样，open-webui 没有给 Docling 单独做扩展名白名单，规则就是：

      • 非 _is_text_file 的文件 → 都交给 Docling
      • _is_text_file 的文件 → TextLoader 本地读，不交给 Docling

      所以在 open-webui 视角下，Docling 会接到的类型范围也非常宽（PDF、Office、图片、HTML/EPUB 等）。

      Docling 服务端是否支持、是否能成功转换，取决于 Docling 本身的能力与部署配置；

  • 其它引擎......

  • 如果以上 engine 分支都不触发，代码会走一个“基于文件扩展名/Content-Type 的本地解析器映射”，你可以理解为默认策略：

    • pdf → PyPDFLoader（可选 extract_images、mode）
    • csv → CSVLoader
    • rst/xml/html/md/epub/docx/xls/xlsx/ppt/pptx/msg/odt → 各类 Unstructured / BSHTML / Docx2txt 等
    • _is_text_file(...) → TextLoader
    • 兜底仍然 TextLoader（即使不是 text file 也会强行当文本读）

docling本地部署

  • 在 Windows 上，Docker Desktop 对 GPU (CUDA) 的支持需要 WSL2 后端且配置较复杂。目前 Docling 官方镜像主要优化 CPU 运行。

  1. docker部署：

    1. Basic CPU deployment:

      下载模型：

      1
      2
      3
      4
      5
      6
      7
      8
      9
      # (命令行界面 (CLI))[https://hugging-face.cn/docs/huggingface_hub/guides/cli]
      powershell -ExecutionPolicy ByPass -c "irm https://hugging-face.cn/cli/install.ps1 | iex"  # Windows 
      curl -LsSf https://hugging-face.cn/cli/install.sh | bash  # macOS and Linux 
      hf --help  # 安装完成后，您可以检查 CLI 是否已正确设置

      $env:HF_ENDPOINT="https://hf-mirror.com"

      hf download HuggingFaceTB/SmolVLM-256M-Instruct --local-dir "C:\xxx\docling\models\HuggingFaceTB--SmolVLM-256M-Instruct"
      hf download docling-project/CodeFormulaV2 --local-dir "C:\xxx\docling\models\docling-project--CodeFormulaV2"
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      26
      27
      28
      29
      # ---- 如果已存在同名容器，先停掉并删除，避免冲突 ----
      $existing = docker ps -a --format "{{.Names}}" | Where-Object { $_ -eq "docling-serve" }
      if ($existing) {
        Write-Host "Stopping existing container: docling-serve"
        docker stop docling-serve | Out-Null
        Write-Host "Removing existing container: docling-serve"
        docker rm docling-serve   | Out-Null
      }

      # ---- 创建并运行容器 ----
      docker run -d --name docling-serve -p 5001:5001 `
        --restart no `
        -e DOCLING_SERVE_ENABLE_UI=true `
        -e DOCLING_SERVE_ENABLE_REMOTE_SERVICES=true `
        -e DOCLING_SERVE_MAX_SYNC_WAIT=600 `
        -e UVICORN_WORKERS=1 `
        -e HF_ENDPOINT=https://hf-mirror.com `
        -v "C:\xxx\docling\models\HuggingFaceTB--SmolVLM-256M-Instruct:/opt/app-root/src/.cache/docling/models/HuggingFaceTB--SmolVLM-256M-Instruct" `
        -v "C:\xxx\docling\models\docling-project--CodeFormulaV2:/opt/app-root/src/.cache/docling/models/docling-project--CodeFormulaV2" `
        quay.io/docling-project/docling-serve:latest
        
      Write-Host ""
      Write-Host "Docling is starting..."
      Write-Host "URL: http://127.0.0.1:5001/ui/"
      Write-Host ""
      Write-Host "Logs: docker logs -f docling-serve"
      Write-Host ""

      docker logs -f docling-serve
      1
      docker tag quay.io/docling-project/docling-serve:latest quay.io/docling-project/docling-serve:v1.1.1  # （可选）备份当前image版本

      （可选）通过docker network可以实现容器通过专用 Docker 网络直接通信，而非通过宿主机中转。

      1
      2
      3
      4
      5
      6
      7
      8
      9
      docker network create openwebui-net
      docker run -d `
        --name docling-serve `
        --network openwebui-net `
        ...
      docker run -d `
        --name open-webui `
        --network openwebui-net `
        ...

    2. GPU deployment (NVIDIA CUDA):

      1
      2
      3
      docker run --gpus all -p 5001:5001 `
        -e DOCLING_SERVE_ENABLE_UI=true `
        quay.io/docling-project/docling-serve-cu128

  2. open-webui配置：

    1. 登录到您的 Open WebUI 界面。
    2. Navigate to Admin Panel → Settings → Documents
    3. Change the Default content extraction engine dropdown to Docling
    4. Set the extraction engine URL to http://host.docker.internal:5001 (Docker) or http://localhost:5001 (native)
    5. Save the changes

  3. （可选）配置图片描述：

    1. In the Documents tab, activate Describe Pictures in Documents

    2. Choose a description mode: local or API

      • 本地 ：Vision 模型在 Docling 容器内运行。JSON 配置示例：

        1
        2
        3
        4
        5
        6
        7
        8
        {
          "repo_id": "HuggingFaceTB/SmolVLM-256M-Instruct",
          "generation_config": {
            "max_new_tokens": 200,
            "do_sample": false
          },
          "prompt": "Describe this image in a few sentences."
        }

      • API ：Docling 调用外部服务（例如，Ollama、OpenAI 兼容的端点）。API 配置（Ollama）：

        1
        2
        3
        4
        5
        6
        7
        8
        {
          "url": "http://host.docker.internal:11434/v1/chat/completions",
          "params": {
            "model": "llava:7b"
          },
          "timeout": 60,
          "prompt": "Describe this image in great detail."
        }

        使用 API 模式（调用 Ollama 等外部服务）时， 必须在 docling-serve 上设置以下环境变量：DOCLING_SERVE_ENABLE_REMOTE_SERVICES=true。如果没有这个，Docling 将拒绝向外部服务的请求，并返回 OperationNotAllowed 错误。

  4. Configure via DOCLING_PARAMS JSON in Admin Settings > Documents or via environment variable. 示例：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    {
      "pdf_backend": "dlparse_v4",
      "table_mode": "accurate",
      "ocr_engine": "tesseract",
      "do_ocr": true,
      "force_ocr": false,
      "pipeline": "standard",
      "ocr_lang": ["eng", "chi_sim"]
    }

  5. 验证集成：故障排除

    1. powershell终端验证：

      1
      2
      curl.exe http://127.0.0.1:5001/health
      docker exec -it open-webui sh -c "curl http://host.docker.internal:5001/health"

    2. 访问 Docling 用户界面，地址为 http://127.0.0.1:5001/ui

    3. 上传测试文档并验证它是否返回 Markdown 输出

    4. 在 Open WebUI 中，上传文件到知识库并确认处理完成。

  6. 更新：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    docker images  # 查看镜像

    docker tag quay.io/docling-project/docling-serve:latest quay.io/docling-project/docling-serve:v1.1.1  # （可选）备份当前image版本

    docker pull quay.io/docling-project/docling-serve:latest  # 拉取最新版本

    docker tag quay.io/docling-project/docling-serve:latest quay.io/docling-project/docling-serve:v1.1.2  # （可选）标记更新后的image版本

    # 停止并移除当前容器
    docker stop docling-serve
    docker rm docling-serve

    docker run --name docling-serve quay.io/docling-project/docling-serve:latest  # 重新启动容器（请对照实际运行命令）

  7. 完成。

KV 缓存优化

  • https://docs.openwebui.com/features/chat-conversations/rag/#kv-cache-optimization-performance-tip-
  • 对于专业和高性能的使用场景（尤其是在处理长文档或频繁的后续问题时），启用 KV 缓存优化可以显著提高响应时间。
  • 如果您正在使用 Ollama 、 llama.cpp 、 OpenAI 或 Vertex AI ，并且经常“与文档进行对话”，请在您的环境中设置环境变量 RAG_SYSTEM_CONTEXT=True ，以体验更快的后续响应！
  • $env:RAG_SYSTEM_CONTEXT="True"

RAG原则

RAG（检索增强生成）想“稳定好用”，通常要遵循一些工程化原则。下面按实用性把常见原则整理出来（偏 Open WebUI 这类知识库形态也适用）。

1) 语料治理（Corpus hygiene）

  1. 把“你自己的材料/必须对齐口径的材料”与“外部参考材料”分开，避免检索时互相污染。

  2. 权威源优先、同类材料分层

    • 最权威、最终定稿、对外口径一致的文档放在“权威层”（比如最终论文、最终制度）。
    • 草稿/阶段性文档放在“非权威层”，避免与权威层冲突。

  3. 版本与时间戳明确

    • 文档名/元数据写清楚版本、日期、适用范围（例如 V1/V2、2025-10、适用于某系统版本）。
    • 否则检索可能把旧规则当新规则引用。

  4. 减少噪声：先清洗再入库

    • 去掉页眉页脚、目录重复、参考文献堆叠、无意义的版权页等。
    • PDF 双栏/扫描件尤其要注意，必要时转 Markdown/纯文本再入库。

  5. 避免“重复与近重复”泛滥

    • 同一内容的多份拷贝会让检索 Top-K 里充满重复片段，挤掉真正有用的上下文。
    • 解决：去重、只保留最终版、或在元数据标注“主版本”。

2) 切分（Chunking）原则

  1. 以“可被引用的最小完整语义单元”为 chunk

    • chunk 目标不是越小越好，而是能独立解释清楚一个点（定义、步骤、条款、结论+条件）。

  2. 保留结构信息

    • 把标题层级、章节路径（如“3.2 方法 / 3.2.1 模块A”）带进 chunk 元数据或正文前缀。
    • 这样模型引用时更像“在读文档”，也更利于定位。

  3. 合理 overlap（重叠）

    • 适度重叠能避免句子/步骤被切断造成语义缺失；重叠太大则会引入重复、增加上下文成本。

3) 检索（Retrieval）原则

  1. 召回要“宁缺毋滥”还是“宁滥毋缺”要按任务选

    • 写专利/制度问答：更适合“宁缺毋滥”（高精度，没证据就说不知道）。
    • 头脑风暴/综述初稿：可以“宁滥毋缺”（高召回，再让模型归纳）。

  2. 混合检索对专有名词更友好（如果可用）

    • 纯向量检索对“错误码/公式编号/特定术语”可能不如“向量 + 关键词(BM25)”的混合策略稳定。

  3. 设置阈值与失败策略

  • 有相似度阈值时，用它避免把不相关片段硬塞给模型。
  • 更进一步：检索不足就触发澄清提问或拒答（而不是编）。

4) 生成（Generation）与可控性原则

  1. 明确“证据优先”规则
  • 在 system prompt 里要求：结论必须能被检索片段支持；无法支持就标注不确定/需要补充资料。
  1. 要求引用与可追溯
  • 让模型输出“引用片段/来源标题/章节”，并区分：
    • 来自知识库的事实
    • 来自模型常识的解释/推断
  1. 把“任务指令”和“资料上下文”分开管理
  • 任务指令（写作风格、输出格式、限制条件）放 prompt；
  • 事实依据放检索上下文；
  • 避免把大量规则写进资料库或把资料当指令。

5) 评估与迭代原则（最容易被忽略）

  1. 建立一组固定问题做回归测试
  • 每次改 chunk/embedding/Top-K，就用同一组问题对比命中率、引用质量、回答一致性。
  1. 用“失败案例”反向驱动改库
  • 典型失败：检索命中但回答仍错、引用不相关、把旧版本当新版本。
  • 对应措施：清洗/去重/拆库/加版本标签/调阈值/改提示词。

RAG教程

摘自RAG Tutorial。

其它参考链接：

  • 检索增强生成（RAG）：检索增强生成（RAG）是一种尖端技术，它通过整合来自各种来源的上下文来增强聊天机器人的对话能力。它的工作原理是从各种来源（例如本地和远程文档、网络内容，甚至是 YouTube 视频等多媒体资源）中检索相关信息。然后，将检索到的文本与预定义的 RAG 模板结合，并添加到用户的提示中，从而提供更明智、更符合上下文的回复。

在本教程中，您将学习如何使用检索增强生成 (RAG) 和 Open WebUI 将真实世界的文档加载为知识库。我们将以最新的 Open WebUI 文档为例，逐步演示如何进行此设置。

检索增强生成（RAG）将逻辑逻辑模型（ LLM ）与从外部来源检索到的知识相结合。该系统从上传的文档或知识库中检索相关数据，从而提高响应的质量和准确性。

  1. 下载文档并解压。

  2. 创建知识库：

    1. Navigate to Workspace > Knowledge > + Create a Knowledge Base.
    2. What are you working on?: Open WebUI Documentation
    3. What are you trying to achieve?: Assistance
    4. Visibility: Private
    5. Groups: Select a group if needed.
    6. Click Create Knowledge.
    7. 上传文件：点击open-webui右上角“+”（添加内容）-上传目录（上传相关文件时推荐创建一个knowledge_bases\文件夹来统一管理，还有“同步目录”功能可选），选择解压文档后的目录。可能遇到的问题及解决：
    8. 等待文件上传和知识库创建完成即可。

  3. 使用知识库创建自定义模型（点击链接以查看详细的配置教程）：

    1. Go to Workspace > Models > + Add New Model.

    2. Configure the Model:

      1. Name: Open WebUI

      2. Base Model: (Select the appropriate Llama or other available model)

        基础模型 ：代理程序底层运行的实际模型。您可以选择任何连接到 Open WebUI 的模型。您可以像创建 llama3 一样轻松地为 gpt-4o 创建自定义预设。

        • 回退行为 ：如果配置的基础模型不可用，且 ENABLE_CUSTOM_MODEL_FALLBACK 环境变量设置为 True ，系统将自动回退到第一个配置的默认模型（在管理面板 > 设置 > 模型 > 默认模型 中设置）。这确保了即使特定基础模型被移除或暂时不可用，关键任务自定义模型仍能保持功能正常。

      3. Knowledge Source: Select Open WebUI Documentation from the dropdown.

        知识库 ：您无需为每次聊天手动选择文档，而是可以将特定的知识库集合或文件绑定到此模型。选择此模型后，RAG（检索增强生成）功能将自动针对这些特定文件启用。**点击附加的项目（知识库/文件）**即可在 “聚焦检索” （RAG 数据块）和 “使用整个文档” （完整内容注入）之间切换。有关详细信息，请参阅 “完整上下文与聚焦检索” 。

        我们 RAG 嵌入功能的可切换混合搜索（hybrid search）子功能，通过 BM25 增强了 RAG 的功能，并利用 CrossEncoder 进行重新排序，同时还提供可配置的相关性评分阈值。这能为您的特定用例提供更精准、更个性化的 RAG 体验。

        管理员面板-设置-文档-检索-混合搜索

      4. Save the Model.

  4. 示例和用法：

    1. Navigate to New Chat and select the Open WebUI model.

    2. Example Queries:

      1
      2
      User: "How do I configure environment variables?"
      System: "Refer to Section 3.2: Use the `.env` file to manage configurations."
      1
      2
      User: "How do I update Open WebUI using Docker?"
      System: "Refer to `docker/updating.md`: Use `docker pull` and restart the container."

    3. 启用 RAG 模型后，系统会从文档中检索最相关的部分来回答您的问题。

  5. 后续步骤：添加更多知识，通过添加更多文档来不断扩展您的知识库。

通过这种设置，您可以有效地利用 Open WebUI 文档， 通过检索与用户查询相关的信息来帮助用户。尽情构建和查询您的自定义知识增强模型吧！

文件夹功能

摘自Folders & Projects。

Open WebUI 提供强大的基于文件夹的组织功能，可以将简单的聊天容器转变为功能齐全的项目工作区 。文件夹不仅允许您对相关对话进行分组，还可以定义适用于其中所有聊天的特定上下文、系统提示和知识库。

特性

  • 将对话移至文件夹
    • 拖放 ：点击并将侧边栏中的任何对话拖到文件夹中。
    • 右键菜单 ：右键单击对话，然后选择“移动到文件夹”。
  • 文件夹可以嵌套在其他文件夹内，从而创建层级结构。
  • 点击侧边栏中的文件夹，它就会成为你的活动工作区，您发起的任何新聊天记录都会自动创建在此文件夹中。新聊天将继承文件夹的设置 （系统提示和知识）。
  • 为文件夹分配一个专用的系统提示符，该提示符将自动应用于文件夹中的所有对话：
    • 系统提示信息会添加到文件夹中创建的每个新对话的前面 。
    • 这样可以针对特定任务或角色调整人工智能的行为。
    • 系统提示是可选的——即使没有系统提示，您也可以纯粹使用文件夹进行组织。
  • 将知识库和文件链接到您的文件夹：
    • 文件夹中所有附件和知识库都会自动作为上下文包含在每次聊天中。
    • 这样就可以对所有文件夹对话启用 RAG（检索增强生成）。
    • 知识是可选的——文件夹无需附加任何文件即可用于组织文件。

示例

假设你正在进行一个 Python 开发项目：

  1. 创建一个名为“Python 专家”的文件夹 。

  2. 编辑文件夹并设置系统提示词：

    1
    You are an expert Python developer. You provide clean, efficient, and well-documented code. When asked for code, prioritize clarity and adherence to PEP 8 standards.

  3. 通过链接项目的技术规范 PDF 或库文档来附加知识。

  4. 点击文件夹将其选为当前工作区。

  5. 开始聊天 ——每一次新的对话都将包含：

    • 精通 Python 的角色
    • 访问您的项目文档
    • 文件夹中的自动整理

引用对话

在 open-webui 中，“引用其他对话”（通常称为 Context Awareness、Memory 或 Chat History Reference）是一个强大的功能，它允许大模型在回答当前问题时，参考您之前的聊天记录或其他特定对话的内容。

这意味着您可以打破“每次对话都是孤岛”的限制，实现跨话题的知识关联和长期记忆。

默认情况下，大模型只记得当前对话窗口内的历史。开启“引用其他对话”后，系统会：

  1. 检索您指定的（或所有的）历史对话记录。
  2. 提取与当前问题相关的片段。
  3. 注入到当前的 Prompt 中发送给大模型。

这个功能本质上也是 RAG（检索增强生成）：

  1. 索引：系统把您所有的历史对话也当作“文档”，进行分段和向量化存储。
  2. 检索：当您提问时，系统不仅在“知识库文档”里搜，也在“历史对话库”里搜。
  3. 生成：将搜到的相关历史对话片段 + 当前问题 + 知识库文档片段 一起发给大模型。

当您引用一个对话时，open-webui 只会发送该对话中的“文本历史记录”（即您和模型说过的话），而不会自动重新提取或发送该对话中曾经上传过的原始文档文件或附加的知识库内容。

技巧

小知识

  • Open WebUI 的“知识库”（Knowledge / KB）功能，本质上是把 **RAG（Retrieval-Augmented Generation，检索增强生成）**做进聊天界面：你把资料放进去（文档、网页内容、笔记等），系统先把资料切分并向量化建立索引；对话时先检索最相关片段，再把片段连同问题一起发给模型，从而让回答“基于你的资料”，并降低模型胡编的概率。
  • 更新与重建索引：新增资料后重新向量化，或对切分/嵌入策略变更后重建。
  • 在 Open WebUI 里“附加知识库”后，模型通常不会自动变成只依据知识库来回答；更准确的说法是：Open WebUI 把“检索到的知识库片段”作为额外上下文拼进提示词里交给模型，而模型依然会结合：
    • 你当前对话内容（问题、上下文）
    • 知识库检索出来的片段（RAG 上下文）
    • 模型自身参数里学到的通用知识与推理能力
    • 至于 联网搜索：这不是“模型天然会做”的事，而取决于你的 Open WebUI 是否启用了相应的工具/函数（如 Web Search）、工作流或插件，并且该能力是否对当前会话可用。没启用就不会“自己上网找资料”。

经验

  • open-webui网页长时间打开后操作卡顿？尝试刷新一下页面。

  • 在与大模型的对话中上传文档后，每次对话时，open-webui 会重新检索相关文档片段，并将这些片段（全文）发送给大模型 API。因此，除非是文档内容需要大模型每次都参考，否则，使用对话而不是上传文档更好（节省token）。

  • 直接上传文档 VS 先创建知识库再附加到与大模型的对话中：

    • 一次性/临时任务：更推荐 对话里直接上传文档
    • 反复使用/多人共享/长期维护：更推荐 先建知识库（KB）再在对话中附加

  • 对于阅读论文等内容，应该使用的是“完整上下文”。否则可能出现论文中连贯的信息读取不全的问题。

    使用 “使用整个文档” 开关，将单个文件和知识库设置为完全绕过 RAG（红绿灯）机制。这样，无论原生函数调用设置如何，都会将完整的文件内容注入到每条消息中。有关详细信息，请参阅“ 完整上下文与聚焦检索” 。

    • 设置方法：账户-管理员页面-设置-文档-通用：
      • PDF加载模式：单文档模式
      • 勾选“绕过嵌入和检索”。

  • 对于使用conda部署的open-webui，账户-管理员页面-设置-文档-通用-内容提取引擎：默认：

    在知识库中把文件上传完成后，可以点击文件查看提取的效果。

    • 对双栏、文字可选择的PDF文档的内容提取效果（包括公式）还可以。
    • 对于word文档，看起来默认的“内容提取引擎”采取了转文本的方式，这会导致公式出现缺失或显示不全。

  • 等等。

推荐上传的文档类型（按优先级/效果大致排序）

  1. Markdown（.md）/ 纯文本（.txt）
  • 优点：文本抽取几乎零损耗；标题层级、列表结构清晰（尤其是 md）；最利于切分与引用。
  • 适合：技术文档、规范、FAQ、知识手册。
  1. HTML（.html/.htm）或“网页内容导出为 HTML/Markdown”
  • 优点：结构化强（标题、段落、链接）；通常比 PDF 更容易抽取。
  • 注意：可能带导航、页脚等噪声，最好先清洗。
  1. Word（.docx）
  • 优点：相对 PDF 更容易拿到“连续的正文文本”和段落结构；表格也往往更可解析。
  • 注意：如果文档里图片很多、或用了复杂文本框/分栏/浮动对象，抽取效果会变差。
  1. PDF（.pdf）（不作为首选，但常见）
  • 优点：通用、易获取。
  • 缺点：对“文本抽取”来说不稳定：换行/分页/双栏/页眉页脚/脚注/表格/扫描件 OCR 都可能让抽取文本变碎、顺序错乱或夹杂噪声，影响检索命中率。

（如果你的 Open WebUI 部署支持更多类型，如 PPTX、XLSX 等，一般也能用，但“可检索知识库”的效果常常不如把内容先转成 Markdown/纯文本再上传。）

如果你能控制资料形态，实践里常见做法是：把 Word/PDF 先转换为 Markdown（并简单清洗）再入库。

知识库的具体应用方式

  • 个人/少量资料、项目化使用：优先用 Folders & Projects + 附加知识库
    理由：既能复用，又不会像“基于知识库创建模型”那样把知识绑定得过死；而且对话组织更清晰。
  • 临时/一次性对话：用 对话里直接附加知识库
  • 要做“固定知识域助手/发布给别人用/强一致口径”：用 基于知识库创建模型
    • 对于基于知识库的模型，即使对于个人项目来说可能并非绝对必要，而创建一个文件夹来添加额外的提示和整理聊天记录仍然很有用。

在open-webui中其它“在对话中引入文档/资料”的方式：

  • 对话中直接上传文件

  • 通过“网页/URL 导入”把在线文档变成可检索上下文

  • 通过“联网搜索 / Web Search 工具”把外部资料带入对话

  • 通过“工具/函数调用（Tool / Function）”从外部系统拉取文档内容

    Open WebUI 的工具机制可以把第三方内容“读出来”当上下文，例如：

    • 从内部 HTTP 接口拉取某份文档
    • 从对象存储/文件服务器取文件并抽取文本
    • 从 Confluence/Notion/Google Drive/SharePoint 等（若你们有相应 connector 或自建工具）

    适用：企业内部文档系统已经很成熟，不想把文档再搬一份进 KB；或希望“实时取最新版本”。

  • 通过“粘贴/引用文本片段”作为对话上下文（手动但很常用）

  • 通过“从历史对话/项目资料复用”间接引入文档内容

系统提示词

概述

在大模型API的消息结构中，通常有三种角色：

角色 英文 作用 示例
系统提示词 system 设定模型行为准则和角色 "你是一个专业的技术助手，回答要简洁准确"
用户消息 user 用户的具体问题或指令 "请解释什么是REST API"
助手消息 assistant 模型的历史回复 "REST API是一种..."

系统提示词是大模型API中的"高级指令"，地位高于普通用户消息。

open-webui

优先级依次提升：

  • 系统提示词可以设置在多个位置，不是只能设置在一个位置。
  • 随着优先级的提升，建议系统提示词的具体约束程度逐渐放缓。
  • 工作区-提示词。
    • Open WebUI Workspace 区的 Prompts 部分允许用户创建、管理和共享自定义提示。此功能允许用户保存常用提示，并通过斜杠命令轻松访问这些提示，从而简化与 AI 模型的交互。
  • 对话-对话高级设置-系统提示词。
    • **说明：**单次聊天设置是指为特定聊天实例配置的系统提示和高级参数。这些设置仅适用于当前对话，不会影响后续聊天。
    • 权限覆盖 ：用户无法覆盖系统提示或管理员已针对特定型号设置的特定高级参数 （ #2 ）。这确保了设置的一致性和对特定型号设置的遵循。
    • 适合：用于“本次对话的具体目标/约束”
  • 分组-文件夹-系统提示词。
    • 为文件夹分配一个专用的系统提示符，该提示符将自动应用于文件夹中的所有对话。
    • 适合：该文件夹内对话遵守的同一规范，不会遗漏。
  • 设置-通用-系统提示词。
    • 在 “通用设置”的 **“系统提示符词 ”**字段中，指定您要使用的主要系统提示符（ 即，为 LLM 赋予一个定义性字符 ）。这样，该提示符将在每个帐户级别生效，并可在所有 LLM 中作为系统提示符使用，而无需在 “工作区” 部分对模型进行任何调整。
    • 对于您的辅助系统提示（ 例如，给 LLM 分配任务 ），您可以选择将其放置在聊天控制侧边栏的 “系统提示” 字段中（按聊天设置），还是放置在工作区 “模型” 部分的“模型”部分（按模型设置），以便管理员可以直接进行设置。这样，您的帐户级系统提示就可以与聊天控制提供的按聊天设置的系统提示或模型提供的按模型设置的系统提示协同工作。
    • 覆盖功能 ：用户可以在自己的帐户上设置自己的系统提示，但他们必须意识到，如果管理员已经针对正在使用的特定型号，按型号设置了系统提示或特定的高级参数， 则这些参数仍然可以被覆盖。
    • 适合：建议仅放很轻的个人偏好（如“默认用中文回答”“需要时给出要点列表”），不要放专用的长规则。
  • 工作区-模型-系统提示词。
    • 系统提示定义了模型的行为和角色。
    • **说明：**基于型号的设置是指为特定型号配置的默认系统提示和高级参数。这些设置适用于使用该型号的所有聊天实例。
    • 模型优先级： 如果管理员已在工作区部分预设了某个模型的系统提示或特定高级参数值， 则用户帐户在常规设置或聊天控制部分所做的任何上下文长度更改都将被忽略，该模型将保持预配置值不变。请注意， 管理员帐户未修改的参数仍可由用户帐户手动调整，且调整范围可以是每个帐户或每个聊天。
    • 对于基于知识库的模型，即使对于个人项目来说可能并非绝对必要，而创建一个文件夹来添加额外的提示和整理聊天记录仍然很有用。

为了避免不同层级互相打架，推荐你把提示词拆成：

  • 身份/原则（长期稳定）：放在 模型级 或 文件夹/项目级（或账号级默认）
  • 任务指令（一次性/短期）：放在 单对话 system prompt 或直接用 Workspace Prompts 模板插入

这样既稳定又灵活，也更符合你提到的“协同工作”的思路。

示例

1
Serve me as a writing and programming assistant. Please ask me any clarifying questions you have about my question before every answer so that I can provide you with more information. Please be extremely comprehensive.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
You are a professional writing assistant. Please follow these guidelines:

1. **Language**: Always respond in Chinese (简体中文).

2. **Clarification Process**: Before providing each answer, ask me clarifying questions to gather more context and details. This ensures your responses are accurate and comprehensive.

3. **Technical Documentation**: When writing technical content (such as academic papers, patents, technical reports, etc.):
   - Use mathematical formulas to explain concepts whenever applicable.
   - **Proactive Formulation**: You are authorized and encouraged to derive or construct new mathematical formulas if existing descriptions are insufficient to clarify a concept. Do not limit yourself to only restating provided formulas.
   - All formulas must be written in LaTeX format (inline: `$...$`, display: `$$...$$`)
   - Ensure formulas are properly formatted and renderable

4. **Incremental Generation**: When writing lengthy documents or chapters:
   - Generate content incrementally (one section at a time)
   - Wait for user confirmation before proceeding to the next section
   - This ensures accuracy and allows for course correction

5. **Response Quality**: 
   - Be thorough and comprehensive in your explanations
   - Use Markdown format for structured output (headings, lists, code blocks)
   - Prioritize clarity and precision over brevity

其它资料

  • 日志功能：日志记录对于调试、监控和了解 Open WebUI 的运行状况至关重要。本指南解释了浏览器客户端 （前端）和应用服务器/后端中的日志记录工作原理。
  • 环境变量介绍：Open WebUI 提供了丰富的环境变量，允许您自定义和配置应用程序的各个方面。本页面全面介绍了所有可用的环境变量，包括它们的类型、默认值和描述。
  • Notes：Open WebUI 中的 “笔记” 功能提供了一个专门用于内容创建和知识管理的工作空间。Open WebUI 中的普通聊天会保留您的线性对话，而 “笔记”功能允许您整理特定内容，例如长篇草稿或代码速查表，这些内容独立于任何单个对话。您可以使用 LLM（逻辑逻辑模块）编写和完善这些笔记，并将其无缝地作为上下文插入到新的聊天中。
软件工具库
open-webui的部署和使用
http://zeyulong.com/posts/719343c9/
作者
龙泽雨
发布于
2026年2月17日
许可协议