hwdsl2/docling-server

Docker上的Docling文档解析

 

GitHub: https://github.com/hwdsl2/docker-docling

属于https://github.com/hwdsl2/self-hosted-ai-stack的一部分——通过单条命令部署完整的自托管AI栈。

本Docker镜像用于运行自托管文档解析服务器，基于https://github.com/docling-project/docling构建。支持将PDF、DOCX、PPTX、XLSX、HTML、Markdown、LaTeX等格式转换为结构化Markdown、JSON或HTML输出。设计目标是简单、私密、自托管。

📘 新书： 自托管AI构建者指南 — 学习如何将此服务部署为完整、默认安全的私有AI栈的一部分。

核心功能

• 文档转文本API：将PDF、DOCX、PPTX、HTML等转换为Markdown/JSON
• 基于IBM Docling：高精度布局分析、OCR和表格结构识别
• 支持同步/异步转换、文件上传和URL输入
• RAG应用的分块端点（分层和混合分块）
• 可选Web UI playground（DOCLING_ENABLE_UI）
• 通过辅助脚本管理模型（docling_manage）
• 文档数据保留在您的服务器上，无第三方数据传输
• NVIDIA GPU（CUDA）加速以提升推理速度（:cuda镜像标签）
• 离线/气隙模式：使用预缓存模型运行，无需互联网访问（DOCLING_LOCAL_ONLY）
• 通过GitHub Actions自动构建和发布
• 通过Docker卷实现持久化数据
• 支持平台：linux/amd64、linux/arm64

使用场景

• 本地文档结构化处理，保障数据隐私
• RAG（检索增强生成）应用的文档预处理
• 企业内部文档转换与管理
• 离线环境下的文档解析需求

快速开始

使用以下命令启动文档解析服务器：

bash
docker run \
    --name docling \
    --restart=always \
    -v docling-data:/var/lib/docling \
    -p 5001:5001 \
    -d docker.xuanyuan.run/hwdsl2/docling-server

注意： 对于面向互联网的部署，强烈建议使用反向代理添加HTTPS。此时，将-p 5001:5001替换为-p 127.0.0.1:5001:5001，以防止直接访问未加密端口。

带GPU（NVIDIA CUDA）的docker-compose部署

提供单独的docker-compose.cuda.yml用于GPU部署：

bash
cp docling.env.example docling.env
# 根据需要编辑docling.env，然后执行：
docker compose -f docker-compose.cuda.yml up -d
docker logs docling

示例docker-compose.cuda.yml（已包含）：

yaml
services:
  docling:
    image: docker.xuanyuan.run/hwdsl2/docling-server:cuda
    container_name: docling
    restart: always
    ports:
      - "5001:5001/tcp"  # 若使用主机反向代理，改为"127.0.0.1:5001:5001/tcp"
    volumes:
      - docling-data:/var/lib/docling
      - ./docling.env:/docling.env:ro
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

volumes:
  docling-data:
    name: docling-data

在环境文件中设置DOCLING_DEVICE=cuda（或auto）以使用GPU。

GPU快速启动（NVIDIA CUDA）

若您有NVIDIA GPU，使用:cuda镜像实现硬件加速推理：

bash
docker run \
    --name docling \
    --restart=always \
    --gpus=all \
    -v docling-data:/var/lib/docling \
    -p 5001:5001 \
    -d docker.xuanyuan.run/hwdsl2/docling-server:cuda

要求： NVIDIA GPU、主机安装https://www.nvidia.com/en-us/drivers/（Linux：575.57.08+，Windows：576.57+）和https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html。`:cuda`镜像仅支持`linux/amd64`。

模型已内置到镜像中，首次启动时加载到内存。查看日志确认服务器就绪：

bash
docker logs docling

看到“Docling document parsing server is ready”后，转换第一个文档：

bash
curl -X POST http://您的服务器IP:5001/v1/convert/source \
    -H "Content-Type: application/json" \
    -d '{"sources": [{"kind": "http", "url": "https://arxiv.org/pdf/2501.17887"}]}'

环境变量

所有变量均为可选。新安装并挂载/var/lib/docling卷时会自动生成API密钥。无密钥的现有安装保持开放以兼容旧版本。

本镜像使用以下变量，可在env文件中声明（见示例）：

注意： 在env文件中，值可使用单引号包裹（如VAR='value'），=两侧不要加空格。若修改DOCLING_PORT，需相应更新docker run命令中的-p参数。

使用env文件的示例：

bash
cp docling.env.example docling.env
# 编辑docling.env后执行：
docker run \
    --name docling \
    --restart=always \
    -v docling-data:/var/lib/docling \
    -v ./docling.env:/docling.env:ro \
    -p 5001:5001 \
    -d docker.xuanyuan.run/hwdsl2/docling-server

环境文件绑定挂载到容器中，重启时无需重建容器即可应用更改。

API参考

从URL转换文档

POST /v1/convert/source
Content-Type: application/json

参数：

示例：

bash
curl -X POST http://您的服务器IP:5001/v1/convert/source \
    -H "Content-Type: application/json" \
    -d '{"sources": [{"kind": "http", "url": "https://arxiv.org/pdf/2501.17887"}]}'

带API密钥认证：

bash
curl -X POST http://您的服务器IP:5001/v1/convert/source \
    -H "X-Api-Key: 您的API密钥" \
    -H "Content-Type: application/json" \
    -d '{"sources": [{"kind": "http", "url": "https://arxiv.org/pdf/2501.17887"}]}'

转换上传文件

POST /v1/convert/file
Content-Type: multipart/form-data

示例：

bash
curl -X POST http://您的服务器IP:5001/v1/convert/file \
    -F "files=@document.pdf"

异步转换

对于大型文档，使用异步端点避免超时：

POST /v1/convert/source/async → 返回task_id
GET /v1/status/poll/{task_id} → 轮询任务状态
GET /v1/result/{task_id} → 获取结果

健康检查

GET /health → 存活检查（始终返回200）
GET /ready → 就绪检查（模型加载前返回503）

版本信息

GET /version

返回docling、docling-serve和docling-core版本。

交互式API文档

完整的交互式Swagger UI可在以下地址访问：

http://您的服务器IP:5001/docs

注意： API密钥认证使用X-Api-Key头（非Authorization: Bearer）。健康、版本和文档端点（/health、/ready、/version、/docs）无需API密钥。

持久化数据

所有运行时数据存储在Docker卷（容器内/var/lib/docling）：

/var/lib/docling/
├── .port               # 活跃端口（供docling_manage使用）
├── .server_addr        # 缓存的服务器IP（供docling_manage使用）
└── hub/                # HuggingFace Hub缓存（用于运行时下载的模型）

注意： 文档转换模型（布局、表格结构、OCR）已内置到镜像中，无需单独下载。Docker卷仅存储运行时数据。

服务器管理

使用容器内的docling_manage脚本检查和管理服务器：

• 显示服务器信息：docker exec docling docling_manage --showinfo
• 列出支持格式：docker exec docling docling_manage --showformats
• 下载/更新模型：docker exec docling docling_manage --downloadmodels
• 显示版本信息：docker exec docling docling_manage --version

支持格式

输入格式

输出格式

输出格式通过API请求控制，详见/docs的交互式文档。

安全建议

使用反向代理

面向互联网的部署需在Docling服务器前放置反向代理处理HTTPS终止。本地或可信网络可无需HTTPS，但暴露到互联网时强烈建议使用HTTPS。

从反向代理访问Docling容器的地址：

• docling:5001：若反向代理与Docling在同一Docker网络（如同一docker-compose.yml中）
• 127.0.0.1:5001：若反向代理运行在主机且端口5001已发布（默认docker-compose.yml已发布）

Caddy示例（自动TLS，同一Docker网络）： Caddyfile：

docling.example.com {
  reverse_proxy docling:5001
}

nginx示例（主机反向代理）：

nginx
server {
    listen 443 ssl;
    server_name docling.example.com;

    ssl_certificate     /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass         http://127.0.0.1:5001;
        proxy_set_header   Host $host;
        proxy_set_header   X-Real-IP $remote_addr;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
        proxy_read_timeout 300s;
    }
}

新的持久化安装会自动生成DOCLING_API_KEY，使用docker exec docling docling_manage --showkey查看，或在脚本中使用docker exec docling docling_manage --getkey。无密钥的现有安装可在env文件中设置DOCLING_API_KEY启用认证。

更新镜像

更新镜像和容器：

1. 拉取最新版本：docker pull docker.xuanyuan.run/hwdsl2/docling-server
2. 移除旧容器：docker rm -f docling
3. 使用相同卷和端口重新运行docker run命令（数据保存在docling-data卷中）

与其他AI服务集成

Docling可作为自托管AI栈中的文档转换服务。详见https://github.com/hwdsl2/self-hosted-ai-stack获取完整/