安装

以 Docker 运行 Docling（docling-serve）

以容器运行官方 docling-serve HTTP API，无需 Python 环境。选对镜像（CPU 与 CUDA）、发布 5001 端口、启用 UI、curl 测试。高级部署见官方 docling-serve 项目。

Step 1

Docker 何时是（不是）答案

用 Docker：应用、流水线或团队需要经 HTTP 的 Docling（/v1/convert/source）、可复现部署或与主机 Python 隔离时。
不用 Docker：偶发本地转换。pip install docling 加 docling convert file.pdf --to md 更快（见总览）。
镜像很大（4–11 GB）：base/CPU 约 4.4 GB，CUDA 12.8 约 11.4 GB。拉取一次，到处复用。

Step 2

拉哪个镜像：CPU 与 CUDA

全部镜像发布于 quay.io/docling-project/… 与 ghcr.io/docling-project/…，面向 linux/amd64（base/CPU 另有 arm64）。若用 podman，请替换 docker。Tag 规则：base/CPU 镜像用 latest 与 main；CUDA 镜像故意没有 latest（CUDA 随 PyTorch 过时）。CUDA 镜像一律显式锁定，如 quay.io/docling-project/docling-serve-cu130:v1.18.0。ROCm 镜像存在但不发布（本地构建）；无预置权重的 slim 镜像在计划中。

docker pull quay.io/docling-project/docling-serve-cpu

docker pull quay.io/docling-project/docling-serve-cu130:v1.18.0

镜像	适用	架构 / 体积
`docling-serve` / `docling-serve-cpu`	纯 CPU 服务器、笔记本、CI	amd64 + arm64，约 4.4 GB
`docling-serve-cu128`	CUDA 12.8 的 NVIDIA GPU	amd64，约 11.4 GB
`docling-serve-cu130`	CUDA 13.0 的 NVIDIA GPU	amd64（+arm64），体积 TBD

Step 3

启动服务器（Docker / Podman）

CPU（最常见）。首次启动下载模型权重到镜像缓存，请预留时间与磁盘。compose 部署见 docs/deployment.md。CUDA GPU（需 nvidia-container-toolkit / --gpus）。

podman run -p 5001:5001 -e DOCLING_SERVE_ENABLE_UI=1 quay.io/docling-project/docling-serve

docker run --gpus all -p 5001:5001 -e DOCLING_SERVE_ENABLE_UI=1 quay.io/docling-project/docling-serve-cu130:v1.18.0

Step 4

备选：pip 安装 docling-serve

无容器的同一服务器，适合虚拟机或调试：

pip install "docling-serve[ui]"

docling-serve run --enable-ui

Step 5

端口、文档、UI 与健康检查

/docs 能渲染即健康。端口被占则以 -p 5002:5001 重映射，URL 改用 :5002。

API 基址：http://127.0.0.1:5001
交互式 API 文档（Swagger）：http://127.0.0.1:5001/docs
试用 UI：http://127.0.0.1:5001/ui（仅设 DOCLING_SERVE_ENABLE_UI=1 / --enable-ui 时）
稳定转换端点：POST /v1/convert/source（v1 API；旧代码请看v1 迁移说明）。

Step 6

经 API 转换首个文档

响应按请求选项返回 Markdown / JSON / HTML。全部运行时选项见 docs/usage.md 与 docling-serve 文档的 REST 说明。

curl -X POST http://localhost:5001/v1/convert/source -H 'Content-Type: application/json' -d '{"sources": [{"kind": "http", "url": "https://arxiv.org/pdf/2501.17887"}]}'

curl -X 'POST' \
  'http://localhost:5001/v1/convert/source' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "sources": [{"kind": "http", "url": "https://arxiv.org/pdf/2501.17887"}]
  }'

Step 7

配置与部署说明

经环境变量配置（见 .env.example 与 docs/configuration.md），如 DOCLING_SERVE_ENABLE_UI=1。
挂载缓存卷使模型权重在重启后保留；大 PDF 设置内存上限（见内存不足）。
生产环境的鉴权 / TLS / 限流放在反向代理；docs/deployment.md 的 compose 示例是起点。
生产锁定 tag（:v1.18.0 而非 :latest），CUDA tag 尤其如此。

Step 8

常见容器问题

服务器起不来——见docling-serve 无法启动：端口冲突、缺 [ui] extra 或入口点错误。
/ui 404——忘了 DOCLING_SERVE_ENABLE_UI=1 / --enable-ui。
GPU 镜像跑在 CPU 上——主机需 NVIDIA 驱动 + 容器 toolkit 并加 --gpus all；容器内以 nvidia-smi 确认。
拉取 CUDA 的 :latest 失败——符合预期：CUDA 镜像仅带显式版本 tag。
首次请求慢——正在下载权重，后续复用缓存。

Step 9

Docker FAQ

Docker 还是 pip 安装？

本地 CLI 转换选 pip（pip install docling）。应用或团队需要语言无关 HTTP API 时选 Docker（docling-serve）。

quay.io 还是 ghcr.io？

两者镜像相同，用更快或环境允许的那个。

为何没有 CUDA 的 :latest tag？

CUDA 版本随 PyTorch 推进而过时，:latest 可能悄悄切换 CUDA。请锁定显式版本如 -cu130:v1.18.0。

API 文档在哪？

自家服务器的 /docs 实时提供，另见上游用法、配置与部署指南。

高级部署见官方 docling-serve 项目。已按 Docling v2.129.0 验证 · 最近检查 2026-09-22 · 官方来源