在 Open WebUI 里遇到“上传 PDF 后解析失败”,大多数情况不是同一个原因:有的 PDF 是扫描件,本身没有文本层,Open WebUI 默认的纯文本抽取拿不到内容;有的是本机缺少 OCR 引擎或语言包,提取动作直接报错;还有的是连续上传多个文件时触发了资源或并发限制,解析超时被中断。建议先区分“没提取到内容”和“处理过程报错”,再决定改配置还是换文件。
先确认 Open WebUI 侧的日志与报错现场
解析失败通常会在后端日志留下痕迹,而不是只在页面提示。先用 Docker Compose 启动的,看一下 open-webui 容器输出:
docker compose logs -f open-webui上传单个 PDF 后固定观察关键词:RAG、OCR、pdf、timeout、tesseract。如果日志里出现 failed to extract text 或 OCR 相关报错,优先怀疑 OCR 依赖;如果日志只显示请求被切断或超时,再往并发和资源限制方向查。若容器日志里完全没有 PDF 相关记录,需要先确认上传的文件是否真的到达后端,而不是被浏览器端或反向代理拦截。
检查 OCR 依赖:扫描版 PDF 是重灾区
Open WebUI 对扫描版 PDF 的处理通常依赖 Tesseract 等 OCR 引擎。只装了主程序、没装语言包,或者容器里根本没安装 OCR 工具,都会让解析结果为空或直接失败。先在本机或容器内验证:
docker exec -it open-webui sh
which tesseract
tesseract `--list-langs`如果 tesseract 不存在,或者语言列表里没有 chi_sim(简体中文),说明 OCR 依赖不完整。结合运行方式,可以在启动命令或环境变量中加入对应配置。下面是一个 docker-compose 环境变量的示例骨架:
services:
open-webui:
environment:
- ENABLE_RAG_LOCAL_WEB_FETCH=true
- RAG_OCR_ENGINE=tesseract
- OCR_LANGUAGE=chi_sim+eng注意:RAG_OCR_ENGINE 这类变量名在不同版本里可能不同,需要结合当前版本的配置文档确认。确认方向是对的即可:先让系统能对扫描 PDF 做 OCR,再谈解析质量。对于中文扫描件,语言包缺失是非常常见的失败点,安装 tesseract-ocr-chi-sim 或对应语言包后,重新上传同一个 PDF 验证。
另外要检查 PDF 是否真的需要 OCR。如果文件是文字版 PDF,问题可能出在 Open WebUI 的解析器本身。可以用系统命令快速验证 PDF 是否含文本层:
pdftotext input.pdf - | head -50这条命令能输出文本说明 PDF 本身没问题;如果输出为空,基本可以认定是扫描件,必须走 OCR 链路。
并发上传与资源限制:表现为解析中断或排队
Open WebUI 的解析过程会占用 CPU 和内存,OCR 任务尤其吃资源。连续上传多个大 PDF,或者多个用户同时触发解析时,可能触发容器内存限制或任务超时。此时日志里通常会出现类似 context deadline exceeded、worker timeout 或内存相关的报错。
处理方式建议按“止血 -> 调整 -> 确认”的顺序:先停掉其他解析任务,单独上传同一个 PDF,确认单文件是否能成功;如果单文件成功,说明并发触发了资源瓶颈。可以调整 Open WebUI 的 RAG 重试次数,减少失败的偶然性:
environment:
- RAG_RETRY_COUNT=3但这只是让任务更有机会重试,不是性能优化。真正的风险边界在于:OCR 是 CPU 密集操作,增加并发并不会提升吞吐,反而可能拖垮整个容器。建议结合宿主机的可用内存和 CPU 核数决定,先把单文件解析稳定性确认好,再逐步放量。
最小复现:用一个文字版 PDF 和扫描版 PDF 对比
为了进一步定位问题,做一个最小复现实验。准备两个 PDF:一个是文字版(Word 或浏览器打印生成),一个是扫描版(拍照或扫描仪输出)。分别上传到 Open WebUI,观察两种文件的解析结果:
- 文字版成功、扫描版失败:方向锁定在 OCR 链路,检查 Tesseract 语言包和引擎配置。
- 两者都失败:问题可能在 Open WebUI 的 RAG 解析组件本身,或 PDF 文件格式不兼容(如特殊加密、超大文件)。
- 两者都成功但内容为空:检查上传后的文档内容是否被正确索引,可以尝试清空知识库后重新上传。
这个实验也可以直接用 API 验证。Open WebUI 的 API 不完全等同于页面行为,但通过 API 上传可以看到更直接的响应状态:
curl -X POST "http://localhost:3000/api/v1/files/" \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "file=@test.pdf"如果 API 返回成功但页面仍解析失败,优先排查前端与后端之间的代理或大小限制。
验证清单
完成以上步骤后,按下面顺序确认问题是否解决:
- 重新上传同一个 PDF,上传后等待解析完成,不要立刻提问。
- 在知识库或文档列表里打开该 PDF,确认能看到文本预览。
- 针对 PDF 内容提问,确认答案不是基于文件名猜出来的空回答。
- 连续上传 2-3 个不同的 PDF,确认没有触发并发超时。
- 如果换了 OCR 语言包,重启 Open WebUI 容器后再试一次。
如果以上检查点都通过,说明解析链路已经恢复。若仍然失败,就需要检查运行 Open WebUI 的宿主机资源是否足够,并在社区里附上日志片段请求帮助,而不是继续盲目调整参数。