黄泓毅我最近被一个很实际的需求折腾了一下：要把一批扫描版PDF里的公式、表格、版式完整地抽成可编辑的Markdown。手写当然不现实，人工校对又费时间，所以就盯上了开源文档解析引擎 MinerU。这东西对论文、合同、扫描件的版面识别确实强，但它要真正跑起来是有门槛的——一堆深度学习模型、Python依赖、版本匹配问题，直接按老套路去装，很容易先耗费一两个小时搭环境。
后来我换了思路，用 Docker Compose 来做 MinerU 本地部署，把镜像、模型缓存、待处理文件全部通过一份 compose 文件管理起来。正是这个决定让整个过程压缩到了10分钟左右，而且换机器换目录都能复用。这篇文章就把完整的部署过程、版本自查方法、Compose 文件设计思路，以及我在实际跑通后遇到的几个高频坑一起写出来。无论你是不是第一次接触 Docker，只要跟着下面的步骤走，应该都能把这套解析环境搭起来。
1. 为什么用 Docker Compose 部署 MinerU，而不是先 pip install 一堆依赖
先聊一个可能劝退很多人的问题：MinerU 到底是个什么东西，为什么不能像普通 Python 包那样“pip install 完直接用”？
MinerU 本质上是一个文档解析引擎，底层依赖了多种用于版面检测、公式识别、表格结构还原、文字 OCR 的深度学习模型。它的工作方式不是单纯把 PDF 里的文字读出来，而是先做版面分析，识别出标题、正文、图片、表格、公式这些区域，再分别调用对应的识别模型，最后组合成结构化的 Markdown 或 JSON。
这就带来了一个直接问题：它依赖的 Python 版本、PyTorch 版本、CUDA 版本、模型权重文件，如果全部靠本机环境去管理，非常容易冲突。我记得早期我为了跑类似工具，曾在 conda 里折腾过半天，最后被一个 torch 版本不兼容问题卡住。而且模型权重往往上百 MB 甚至几个 GB，下载一次、缓存一次，路径还不统一，时间久了机器上会散落一堆不知道能不能复用的模型文件。
Docker 的意义在于把这些复杂依赖一次性打进镜像里。你拿到的是一个已经校准过运行环境的容器，里面有配好的 Python、依赖库和推理框架，不需要操心本机装了什么版本。而 Docker Compose 的加入，解决的则是第二个问题：你要怎么管理运行参数。
单独用 docker run 也能启动 MinerU，但如果你不希望每次敲一长串参数，还希望把输入目录、输出目录、模型缓存目录固定下来，Compose 这种声明式配置就是更好的选择。写一份 docker-compose.yml 放到项目里，以后不管换机器还是换部署环境，只要文件还在，执行同一条命令就能把环境拉起来。
这也解释了为什么标题里敢写“10分钟部署”。真正的时间消耗不在配置本身，而是环境固化和模型缓存准备。Compose 文件一次写好，后续就是重复使用的事。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 部署前的环境基线：Docker 20.10+ 与 Compose 2.0+ 意味着什么
很多人在部署 MinerU 时遇到的第一个问题不是 MinerU 本身，而是本机的 Docker 环境太老。项目官方在安装文档里通常会明确要求 Docker 20.10+ 和 Docker Compose 2.0+，这两个数字不是随便定的，它们背后有实际的技术原因。
先看 Docker 20.10 这个门槛。如果你只是在 CPU 上跑 MinerU，老版本 Docker 未必不能用，但一旦想用 GPU 加速，20.10 对 NVIDIA 容器运行时的集成才比较完善。MinerU 这类深度学习工具的镜像通常比较大，里面包含的推理框架也依赖新版 Docker 对资源和设备的管理能力。从降低排错成本的角度讲，直接跨过旧版本门槛是值得的。
再看 Compose 2.0+。如果你以前用过 Docker，大概率知道老的 docker-compose 命令（带横杠），它和现在主推的 docker compose（带空格）是两代东西。Compose v2 已经用 Go 语言重写，并作为 Docker CLI 的官方插件发布，安装和升级路径比原来干净得多。
检查本机环境，执行这两条命令就够了：
bash复制docker --version
docker compose version
如果第一条能正常显示版本号，说明 Docker 已经装了；第二条能显示类似 Docker Compose version v2.x.x，说明 compose 插件也在。
不