Docling 文档抽取

注意

本教程为社区贡献内容，不属于 OPL 数据空间团队的官方支持范围。它主要演示如何按你的具体场景定制 OPL 数据空间。若想参与贡献，请查看贡献指南。

🐤 Docling 文档抽取

本文介绍如何把 Docling 集成到 OPL 数据空间。Docling 是一套文档处理库，能够把 PDF、Word、表格、HTML、图像等多种文件格式转换为 JSON 或 Markdown 等结构化数据。它内建布局识别、表格解析和语言感知处理能力，很适合搜索、摘要和 RAG 等 AI 场景。

前置条件

• OPL 数据空间实例
• 已安装 Docker
• 已为 OPL 数据空间准备好 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:
      - DOCLING_SERVE_ENABLE_UI=true
      - DOCLING_SERVE_ENABLE_REMOTE_SERVICES=true
      - DOCLING_SERVE_MAX_SYNC_WAIT=600
      - DOCLING_SERVE_ENG_LOC_NUM_WORKERS=2
      - OMP_NUM_THREADS=4
      - MKL_NUM_THREADS=4
      - UVICORN_WORKERS=1
    restart: unless-stopped
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

重要：UVICORN_WORKERS

当你使用默认 LocalOrchestrator，且把 UVICORN_WORKERS 设置为大于 1 时，很容易遇到 "Task Not Found (404)"。原因是每个 worker 维护自己的内存任务存储，一个 worker 创建的任务无法被另一个 worker 访问。

除非你已经引入 Redis 这类共享状态机制，否则务必保持 UVICORN_WORKERS=1。

第 2 步：配置 OPL 数据空间

1. 登录 OPL 数据空间
2. 进入 管理员面板 → 设置 → Documents
3. 将 Default content extraction engine 改为 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 模式调用外部服务，必须在 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 界面
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 线程数

OPL 数据空间中的 Docling 参数说明

可在 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
2. 上传一个测试文档，确认能返回 Markdown 输出
3. 在 OPL 数据空间中把文件上传到知识库，确认处理成功完成

故障排查

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

原因：多个 Uvicorn worker 使用了内存态任务存储。

解决方法：把 UVICORN_WORKERS=1 写进 docling-serve 配置。

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

原因：图片描述的 API 模式需要显式允许远程服务。

解决方法：在 docling-serve 环境变量中加入 DOCLING_SERVE_ENABLE_REMOTE_SERVICES=true。

/v1alpha/convert/file 返回 404

原因：使用了过旧的 docling-serve 或 OPL 数据空间版本。

解决方法：

• 更新 OPL 数据空间到最新版本（它使用 /v1/convert/file）
• 更新 docling-serve 到 v1.0+（使用 /v1 API）

大文档超时

原因：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 测试 Docling
3. 确认 OPL 数据空间与 docling-serve 容器之间网络互通

总结

将 Docling 集成进 OPL 数据空间后，文档处理能力会明显提升。最关键的几点是：

• 始终保持 UVICORN_WORKERS=1
• 使用 API 图片描述时必须启用 DOCLING_SERVE_ENABLE_REMOTE_SERVICES=true
• 处理大文档时要适当增大 DOCLING_SERVE_MAX_SYNC_WAIT
• 所有 JSON 配置项都要先校验语法