Docling 文档提取

注意

本教程由社区贡献，不受 Open WebUI 团队支持。它仅作为如何针对特定用例自定义 Open WebUI 的演示。想要贡献？请查看贡献教程。

🐤 Docling 文档提取

本篇文档提供了将 Docling 与 Open WebUI 集成的逐步指南。Docling 是一个文档处理库，旨在将包括 PDF、Word 文档、电子表格、HTML 和图像在内的广泛文件格式转换为结构化数据（例如 JSON 或 Markdown）。凭借内置的版面检测、表格解析和语言感知处理支持，Docling 通过一个统一且可扩展的接口，简化了用于搜索、摘要和检索增强生成 (RAG) 等 AI 应用的文档准备工作。

前提条件

• Open WebUI 实例
• 系统中已安装 Docker
• 为 Open WebUI 设置了 Docker 网络

集成步骤

步骤 1：运行 Docling-Serve 容器

基础 CPU 部署：

docker run -p 5001:5001 \
  -e DOCLING_SERVE_ENABLE_UI=true \
  quay.io/docling-project/docling-serve

GPU 部署 (NVIDIA CUDA)：

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

推荐的生产环境 Docker Compose 部署：

version: "3.8"
services:
  docling-serve:
    image: quay.io/docling-project/docling-serve-cu128:latest
    container_name: docling-serve
    ports:
      - "5001:5001"
    environment:
      # 启用用于测试的 Web UI
      - DOCLING_SERVE_ENABLE_UI=true
      # 关键设置：在使用外部 LLM API 进行图像描述时需要
      - DOCLING_SERVE_ENABLE_REMOTE_SERVICES=true
      # 同步请求的最大等待时间（秒）—— 针对大文档请调大
      - DOCLING_SERVE_MAX_SYNC_WAIT=600
      # 本地引擎 worker 的数量
      - DOCLING_SERVE_ENG_LOC_NUM_WORKERS=2
      # CPU 线程配置
      - OMP_NUM_THREADS=4
      - MKL_NUM_THREADS=4
      # 重要提示：保持为 1 以避免出现 "Task Not Found" 错误
      - UVICORN_WORKERS=1
    restart: unless-stopped
    # 针对 NVIDIA 的 GPU 支持：
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

重要提示：UVICORN_WORKERS 设置

当将 UVICORN_WORKERS 设置为大于 1 且使用默认的 LocalOrchestrator 时，您将会遇到 “Task Not Found (404)”（找不到任务）错误。这是因为每个 worker 都在内存中维护着自己独立的任务存储，从而导致一个 worker 创建的任务无法被另一个 worker 访问。

请始终使用 UVICORN_WORKERS=1，除非您已经配置了类似于 Redis 这样的共享状态机制。

步骤 2：配置 Open WebUI

1. 登录您的 Open WebUI 实例。
2. 导航至 Admin Panel → Settings → Documents。
3. 将 Default 内容提取引擎下拉菜单更改为 Docling。
4. 将提取引擎 URL 设置为 http://host.docker.internal:5001（Docker 环境）或 http://localhost:5001（原生环境）。
5. 保存更改。

步骤 3：配置图像描述（可选）

要在文档中启用基于 AI 的图像描述：

1. 在 Documents 选项卡中，启用 Describe Pictures in Documents。
2. 选择描述模式：local（本地）或 API。
   • local：视觉模型在 Docling 容器内自身运行。
   • API：Docling 调用外部服务（例如 Ollama、兼容 OpenAI 的端点）。

API 模式必备设置

当使用 API 模式（调用类似于 Ollama 的外部服务）时，您必须在 docling-serve 上设置以下环境变量：

DOCLING_SERVE_ENABLE_REMOTE_SERVICES=true

如果不设置此项，Docling 将拒绝向外部服务发送的请求，并返回 OperationNotAllowed 错误。

JSON 配置示例

确保您的配置是有效的 JSON！

本地模型配置：

{
  "repo_id": "HuggingFaceTB/SmolVLM-256M-Instruct",
  "generation_config": {
    "max_new_tokens": 200,
    "do_sample": false
  },
  "prompt": "Describe this image in a few sentences."
}

API 配置 (Ollama)：

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

Docling-Serve 环境变量参考

变量	默认值	描述
DOCLING_SERVE_ENABLE_UI	false	在 /ui 端点启用 Web UI
DOCLING_SERVE_ENABLE_REMOTE_SERVICES	false	必需设置，用于基于 API 的图像描述
DOCLING_SERVE_MAX_SYNC_WAIT	120	等待同步请求的最大秒数
DOCLING_SERVE_ENG_LOC_NUM_WORKERS	1	本地引擎 worker 数量
DOCLING_SERVE_ARTIFACTS_PATH	/app/data	存储模型构件的路径
UVICORN_WORKERS	1	Uvicorn worker 数量（保持为 1 ！）
OMP_NUM_THREADS	4	用于 CPU 处理的 OpenMP 线程数
MKL_NUM_THREADS	4	Intel MKL 线程数

Docling 参数参考 (Open WebUI)

通过 Admin Settings > Documents 中的 DOCLING_PARAMS JSON 或通过环境变量进行配置。

参数	类型	描述	允许的值
pdf_backend	string	PDF 解析引擎	dlparse_v1, dlparse_v2, dlparse_v4, pypdfium2
table_mode	string	表格提取质量	fast, accurate
ocr_engine	string	OCR 库	tesseract, easyocr, ocrmac, rapidocr
do_ocr	bool	启用 OCR	true, false
force_ocr	bool	对数字版 PDF 强制执行 OCR	true, false
pipeline	string	处理复杂度	standard, fast
ocr_lang	list[string]	OCR 语言	见下方说明

语言代码

• Tesseract：3 字母的 ISO 639-2（例如 eng、deu、fra）
• EasyOCR：2 字母的 ISO 639-1（例如 en、de、fr）

示例配置：

{
  "do_ocr": true,
  "pdf_backend": "dlparse_v4",
  "table_mode": "accurate",
  "ocr_engine": "tesseract",
  "ocr_lang": ["eng"]
}

验证集成

1. 访问位于 http://127.0.0.1:5001/ui 的 Docling UI。
2. 上传一个测试文档，并验证它返回了 Markdown 输出。
3. 在 Open WebUI 中，将文件上传到知识库，并确认处理完成。

故障排查

"Task result not found. Please wait for a completion status."

原因：多个 Uvicorn worker 与内存任务存储并存。

解决方案：在您的 docling-serve 配置中设置 UVICORN_WORKERS=1。

"Connections to remote services is only allowed when set explicitly"

原因：图像描述 API 模式需要显式启用。

解决方案：在您的 docling-serve 环境中添加 DOCLING_SERVE_ENABLE_REMOTE_SERVICES=true。

/v1alpha/convert/file 出现 404 Not Found 错误

原因：使用了过时的 docling-serve 版本或 Open WebUI 版本。

解决方案：

• 将 Open WebUI 更新到最新版本（使用 /v1/convert/file）。
• 将 docling-serve 更新到 v1.0+（使用 /v1 API）。

大型文档出现超时错误

原因：DOCLING_SERVE_MAX_SYNC_WAIT 相对文档处理所需时间设置得过低。

解决方案：增大 DOCLING_SERVE_MAX_SYNC_WAIT（例如设为 600，表示 10 分钟）。

OCR 无法工作或语言检测不正确

原因：所选 OCR 引擎的 ocr_lang 格式有误。

解决方案：

• Tesseract 使用 3 字母代码：["eng", "deu"]
• EasyOCR 使用 2 字母代码：["en", "de"]

"Error calling Docling"（无具体错误详情）

诊断步骤：

1. 检查 docling-serve 日志：docker logs docling-serve。
2. 直接通过位于 http://localhost:5001/ui 的 UI 测试 Docling。
3. 验证 Open WebUI 和 docling-serve 容器之间的网络连接。

结论

将 Docling 与 Open WebUI 集成能显著提升您的文档处理能力。请务必记住以下关键要点：

• 始终将 UVICORN_WORKERS=1 以避免任务路由问题。
• 当使用基于 API 的图像描述时，启用 DOCLING_SERVE_ENABLE_REMOTE_SERVICES=true。
• 针对大型文档，增大 DOCLING_SERVE_MAX_SYNC_WAIT。
• 验证所有配置字段中的 JSON 语法。