Docling 文档提取

警告

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

🐤 Docling 文档提取

本文档提供了一个将 Docling 集成到 Open WebUI 的分步指南。Docling 是一个文档 processing 库，旨在将各种文件格式（包括 PDF、Word 文档、电子表格、HTML 和图像）转换为结构化数据（如 JSON 或 Markdown）。Docling 内置支持布局检测、表格解析和语言感知处理，通过统一且可扩展的接口简化了 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
      # 本地引擎工作线程数
      - 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 设置

在默认使用 LocalOrchestrator 时，如果将 UVICORN_WORKERS 设置为大于 1，您将会遇到 "Task Not Found (404)" 错误。这是因为每个工作进程都维护自己的内存任务存储，使得一个工作进程创建的任务无法被另一个访问。

除非您配置了 Redis 等共享状态机制，否则请始终使用 UVICORN_WORKERS=1。

第 2 步：配置 Open WebUI

登录您的 Open WebUI 实例
导航至 管理员面板 → 设置 → 文档
将默认内容提取引擎下拉菜单更改为 Docling
将提取引擎 URL 设置为 http://host.docker.internal:5001 (Docker) 或 http://localhost:5001 (原生)
保存更改

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

要在文档中启用 AI 驱动的图像描述：

在文档选项卡中，激活描述文档中的图片
选择描述模式：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": "用几句话描述这张图片。"
}

API 配置 (Ollama)：

{
  "url": "http://host.docker.internal:11434/v1/chat/completions",
  "params": {
    "model": "llava:7b"
  },
  "timeout": 60,
  "prompt": "非常详细地描述这张图片。"
}

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`	本地引擎工作线程数
`DOCLING_SERVE_ARTIFACTS_PATH`	`/app/data`	存储模型产物的路径
`UVICORN_WORKERS`	`1`	Uvicorn 工作进程数（保持为 1！）
`OMP_NUM_THREADS`	`4`	CPU 处理的 OpenMP 线程数
`MKL_NUM_THREADS`	`4`	Intel MKL 线程数

Docling 参数参考 (Open WebUI)

在管理员设置 > 文档中通过 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"]
}

验证集成

访问 Docling UI：http://127.0.0.1:5001/ui
上传一个测试文档并验证它是否返回 Markdown 输出
在 Open WebUI 中，上传一个文件到知识库并确认处理完成

故障排除

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

原因：使用了多个具有内存任务存储的 Uvicorn 工作进程。

解决方案：在您的 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" 且没有具体细节

诊断步骤：

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

结论

将 Docling 与 Open WebUI 集成显著增强了文档处理能力。需要记住的关键点：

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

🐤 Docling 文档提取​

前提条件​

集成步骤​

第 1 步：运行 Docling-Serve 容器​

第 2 步：配置 Open WebUI​

第 3 步：配置图片描述（可选）​

JSON 配置示例​

Docling-Serve 环境变量参考​

Docling 参数参考 (Open WebUI)​

验证集成​

故障排除​

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

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

/v1alpha/convert/file 返回 404 Not Found​

大型文档超时错误​

OCR 不工作或语言检测不正确​

"Error calling Docling" 且没有具体细节​

结论​