把一台 Mac 变成＂PDF 粉碎机＂:MinerU 本地部署实录(附我踩过的全部坑)

如果你也常年和 PDF 打交道——政策文件、研究报告、扫描版红头文件——又想把它们干净地喂给大模型或塞进知识库,这篇文章是写给你的。

先说结论

我用一个周末,在两台 Mac 上部署了开源 PDF 解析工具MinerU,目标很简单:把各种格式混乱的 PDF 批量转成干净的 Markdown,直接进 Obsidian 知识库,全程本地、文件不出本机。

结果是值的。但过程并不像官方文档写的那么"一行命令搞定"——我连续踩了好几个坑:虚拟环境建错了位置、系统代理拦截了本机请求、它偷偷开始下载一个我根本用不上的 2.3GB 模型、号称"本地"的桌面客户端其实会把文件偷偷上传云端、以及最后为了追求"快一倍"的加速差点把整个环境搞乱。

这篇文章把部署主线和这些坑一起写下来。教程部分你可以照着做,踩坑部分能帮你少走我走过的弯路。读完你会得到一套完全离线、专门处理敏感文档的 PDF 转换流水线。

一、MinerU 是什么,为什么值得装

MinerU 是上海人工智能实验室(OpenDataLab)开源的 PDF 解析工具,GitHub 上星标已经五万多。它的核心能力,是把 PDF 转换成机器可读的 Markdown 或 JSON。

听起来平平无奇,但它解决的是一个真实的痛点:PDF 是给人看的,不是给机器读的。你直接复制 PDF 里的文字,经常得到乱序的、夹着页眉页脚的、表格全散架的文本。喂给大模型做问答或者塞进 RAG 知识库,效果大打折扣。

MinerU 做的事情,是把这个"翻译"做对:

版面分析:自动识别标题、正文、图表、页眉页脚,按正确的阅读顺序输出。双栏排版的论文也不会串行。

OCR 识别:扫描件、盖章的红头文件这类没有文字层的 PDF,也能"读"出来,支持中英等上百种语言。

表格识别:表格转成 HTML 或 Markdown,处理带数据的报表、结算细则很实用。

公式识别:数学公式转 LaTeX。

自动去噪:把页眉、页脚、页码这些干扰内容剔掉,保证语义连贯。

最关键的两点:它完全免费(AGPL-3.0 开源协议),而且可以完全本地运行。后者对处理工作敏感文件的人来说,几乎是唯一正确的选择——文件不上传任何服务器,合规上不用提心吊胆。

只有安装和首次下载模型那一步需要联网,之后断网也能用。

二、部署主线:五步装好

我用的是 Apple Silicon 的 Mac(M 系列芯片),系统 macOS。下面这套流程在 Mac mini 和 MacBook Air 上都跑通了。Windows / Linux 思路一样,具体命令略有差异。

整个安装的逻辑其实就一句话:装工具 → 建专属文件夹 → 造一个隔离沙盒 → 进沙盒 → 在沙盒里装 MinerU 和模型。

第 1 步:装 uv(更快的 Python 包管理器)

pip3 install uv -i https://mirrors.aliyun.com/pypi/simple/

uv

是用 Rust 写的 Python 包管理器,装包速度比传统 pip 快一个数量级。

-i

参数指定从阿里云镜像下载,国内网络下不容易超时。后面所有安装命令都带这个镜像参数。

第 2 步:建文件夹和虚拟环境

mkdir -p ~/mineru && cd ~/mineruuv venv --python 3.12source .venv/bin/activate

第一行新建一个专属文件夹并进去,所有东西集中放这里,以后想卸载直接删整个文件夹。第二行用 uv 创建一个虚拟环境——你可以把它理解成一个隔离的沙盒,MinerU 那几十个依赖包都装在里面,不会污染系统 Python,也不会和你其他项目打架。第三行激活这个沙盒,激活后终端提示符前面会出现(mineru)字样。

⚠这里埋着我踩的第一个坑,后面专门讲。现在你只需要记住一件事:激活成功后,提示符前面必须是 (mineru)

第 3 步:装 MinerU 本体

uv pip install ”mineru[core]” -i https://mirrors.aliyun.com/pypi/simple/

[core]

表示安装核心功能集,排除掉 GPU 服务器专用的重型组件,Mac 上装这个就够。加引号是防止终端把方括号误解析。

第 4 步:下载模型

export MINERU_MODEL_SOURCE=modelscopemineru-models-download -s modelscope -m pipeline

第一行设置环境变量,告诉 MinerU 从ModelScope(魔搭,阿里旗下的国内模型平台)下载模型,而不是默认的 HuggingFace——后者国内基本连不上。第二行执行下载,

-m pipeline

表示只下载 pipeline 模式的模型组(版面分析、OCR、表格、公式那一套),体积几个 GB,CPU 就能跑,是 Mac 上的最佳选择。

这一步最花时间。我这边几个 GB 下了大约一个小时,中间有个 1GB 多的公式识别模型尤其慢。下完之后会在用户主目录生成一个

mineru.json

配置文件,记录模型存放路径——这就是之后能完全离线运行的底气。

第 5 步:跑通第一个文件

mineru -p 测试文件.pdf -o ./output -b pipeline

-p是输入的 PDF,

-o是输出目录,

-b pipeline

显式指定用 pipeline 后端(这个参数很重要,后面讲坑的时候你就明白了)。

如果是扫描版的红头文件,加上

--method ocr

强制走 OCR:

mineru -p 扫描件.pdf -o ./output -b pipeline --method ocr

怎么判断该不该加 OCR?很简单:用"预览"打开 PDF,试着用鼠标选中一段文字——选得中是文字版,选不中、只能框选整页的就是扫描版,得加 OCR。

跑完检查 output 目录,有

.md

文件就说明成功了。到这里,MinerU 就能用了。

三、进阶:把它接进 Obsidian,一条命令批量转换

单文件能跑只是开始。我真正想要的是:把一整个文件夹的 PDF 一次性转换,结果直接归档进 Obsidian 知识库。于是写了个批处理脚本。

新建一个

pdf2obsidian.sh

#!/bin/bashsource ~/mineru/.venv/bin/activateexport MINERU_MODEL_SOURCE=localSRC=”$1”# PDF 来源目录(运行时传入)VAULT=”$HOME/Obsidian/你的Vault/PDF转换”# ← 改成你的 Vault 路径for pdf in ”$SRC”/*.pdf; do name=$(basename ”$pdf” .pdf) echo ”▶ 处理: $name” mineru -p ”$pdf” -o ”$VAULT/$name” -b pipelinedoneecho ”✅ 全部完成”

几个要点:脚本是新开的进程,不继承你终端里的激活状态,所以必须在脚本内部自己激活一次虚拟环境;

MINERU_MODEL_SOURCE=local

强制读本地模型,断网也能跑;

SRC="$1"

取运行时传入的第一个参数作为来源目录,这样想转哪个文件夹就传哪个,不用写死;遍历时给变量加双引号,是为了中文和带空格的文件名不出错——做政策文件的话文件名基本都是中文,这个引号必不可少。

然后授权、运行:

chmod +x pdf2obsidian.sh./pdf2obsidian.sh ~/Downloads/待转PDF

chmod +x

给脚本加可执行权限,只需做一次。

./

必须加,表示"当前目录下的"——这是 shell 的安全机制,不加会提示找不到命令。

之后日常使用就只重复最后一行,换不同目录参数即可。这条流水线让我把一堆散落的 PDF,变成了 Obsidian 里结构清晰、可全文搜索的笔记。

四、五个坑,我替你踩过了

主线很顺,但魔鬼在细节里。下面这几个坑,每一个都卡了我一段时间,网上的教程大多没提。

坑 1:虚拟环境建到了错误的位置

我最早是把命令一股脑粘贴进终端的,其中有一行是

mkdir ~/mineru && cd ~/mineru

问题在于,我之前试着建过一次

~/mineru

文件夹,于是这次

mkdir

报错"文件已存在"——而

&&

的规则是前一条命令失败,后一条就不执行,所以

cd ~/mineru

根本没跑。

结果就是:虚拟环境被建到了主目录,而不是

~/mineru

里。

怎么发现的?激活之后,提示符变成了

(hydtzyj)

(我的用户名),而不是预期的

(mineru)

。虚拟环境默认用所在目录名命名,这个细节暴露了位置不对。后果是,批处理脚本里写的路径

~/mineru/.venv

会找不到环境而报错。

解法:把

&& 换成 ;

(不管前一条成败都执行后一条),或者用

mkdir -p

（-p表示目录已存在也不报错)。我上面的主线教程里已经改成了

mkdir -p

如果你已经建错了,

deactivate

退出,

cd

到正确目录重新

uv venv

再装一遍即可,模型缓存不受影响,uv 有缓存重装很快。

教训:粘贴多行命令时,留意每一行的执行结果,别被一行的失败带歪后面所有步骤。提示符里的环境名,是个免费的"我在哪"指示器。

坑 2:系统代理拦截了发往本机的请求

MinerU 自带一个网页版界面(Gradio WebUI),敲

mineru-gradio

就能启动,浏览器访问 localhost 即可。我满心欢喜地启动,结果它直接崩溃,报了一长串

RemoteProtocolError 和 Server disconnected

读堆栈信息,关键线索是其中一行出现了

http_proxy.py

原因找到了:我这台机器开着系统代理。Gradio 的启动流程是,先把服务跑起来,然后自己向本机发一个自检请求确认服务正常。问题在于,这个发往

127.0.0.1

的请求也被强制路由到了代理服务器,代理不认识本机端口,直接断开连接,自检失败,程序崩溃退出。

服务本身没问题,死在自检这一步。

解法:让本机地址绕过代理。启动前加两行:

export no_proxy=”localhost,127.0.0.1”export NO_PROXY=”localhost,127.0.0.1”

no_proxy

是各类网络库公认的"代理白名单",告诉程序访问这些地址时直连、不走代理。大小写都设是因为不同库读取的变量名不统一。想一劳永逸的话,把这两行写进

~/.zshrc

教训:凡是本地服务(不只是 MinerU,还有各种 FastAPI、Node 服务)在开了代理的机器上启动失败,先想想是不是本机回环请求被代理截胡了。这个

no_proxy

设置对所有本地服务都有保护作用,建议常备。

坑 3:它偷偷开始下一个我用不上的 2.3GB 模型

代理问题解决后,Gradio 终于启动了,但我发现它卡在下载一个新模型上——

model.safetensors,2.31GB,速度还慢。

日志里有一行说明了一切:

Using transformers as the inference engine for VLM

原来 MinerU 有两套解析后端:我下载并一直在用的pipeline(传统多模型流水线,轻量、Mac 友好),以及VLM(端到端的视觉大模型,精度更高但吃资源)。新版本的默认后端是融合两者的 hybrid 模式,一启动就会去拉那个 2.3GB 的 VLM 模型——而我之前只下了 pipeline 的模型,它就现下。

问题是:我的需求(政策文件、报表、结算细则)用 pipeline 完全够,VLM 那点精度优势我根本用不上。这 2.3GB 纯属浪费。

解法:

Ctrl+C

中止下载。命令行里显式指定

-b pipeline

,就不会触发 VLM 下载;Gradio 网页界面里,把后端下拉框选成 pipeline 即可。我上面所有命令都加了

-b pipeline

,就是这个原因。

一个意外收获:查资料时发现,MinerU 新增了专为 Apple Silicon 优化的MLX 加速后端,相比默认的 transformers 引擎能快一到两倍。但有个隐蔽的坑——命令行里不能直接写

-b vlm-mlx-engine

(会报错),正确做法是用

-b vlm-auto-engine

,它在 M 系列芯片上会自动检测并启用 MLX。不过这属于"想用高精度 VLM 时才需要"的进阶选项,日常用 pipeline 的话完全不用碰。

教训:工具的"默认配置"往往是给大多数人/最强硬件优化的,不一定适合你。搞清楚自己真正需要哪个模式,别被默认值牵着走下一堆用不上的东西。

坑 4:最隐蔽的一个——"本地"客户端其实在偷传云端

这个坑最值得警惕,因为它关乎数据安全。

MinerU 官网提供一个桌面客户端,界面精致,拖拽即用。我一度以为它是"本地解析的图形版",还差点推荐给同事。直到我多查了几篇实测教程才发现:桌面客户端和在线版默认会把文件上传到云端服务器解析。

更有迷惑性的是,客户端设置里"解析结果保存至"指向的是本地目录——但输出在本地,不代表解析过程在本地。文件很可能是先上传云端处理,再把结果存回本地。

对处理公开论文无所谓,但如果是公司内部的敏感文件,那就已经出本机了。

解法/原则:把三种使用方式按隐私分清楚——

方式	文件是否出本机	适用
命令行 / 批处理脚本	✅ 完全本地	敏感文件的唯一正确选择
本地 Gradio WebUI	✅ 完全本地	想要图形界面、处理任意文件
桌面客户端 / 在线版	❌ 上传云端	仅限公开发布的文件

教训:"本地工具"这个标签不能想当然。涉及敏感数据时,务必搞清楚数据到底在哪里被处理。输出路径在本地,是个很容易让人放松警惕的假象。

坑 5(附赠):为了"快一倍",我真的把环境搞坏了

部署到这里其实已经够用了,但我看到一条诱人的信息:MinerU 新增了专为 Apple Silicon 优化的 MLX 加速,号称比默认引擎快一到两倍。我没忍住,折腾了一把。结果这是最深的一个坑。

装 MLX 依赖(mlx-vlm)时,它顺手把 transformers 从 4.x 升到了 5.x。当时没在意,直到我拿一本 583 页的书测试 pipeline,解析跑着跑着崩了,报了个

ImportError: cannot import name 'find_pruneable_heads_and_indices'

翻译成人话:MinerU 的公式识别模型要从 transformers 里调用一个函数,而这个函数在 5.x 版本里被删掉了。根因很明确——mlx-vlm 要 transformers 5.x,MinerU 的 pipeline 要 transformers 4.x,两者势不两立,装了一个就废了另一个。我为了一个用不上的加速,把天天要用的主力给搞瘫了。

更有迷惑性的是,崩之前它还正常打印了"开始处理 583 页、batch 1/10"的字样,让我一度以为成功了——其实那只是在下载模型文件,真正加载公式模型的那一刻才暴露冲突。"开始跑"不等于"能跑完",这个教训记一辈子。

修复倒是干脆:重装一遍 MinerU,它会自动把 transformers 降回 4.x 兼容版本。

uv pip install ”mineru[core]” -i https://mirrors.aliyun.com/pypi/simple/

降级后再跑那本 583 页的书,这次干净利落地跑完了全部 10 个批次,7 分钟出 Markdown。主力满血复活,而 mlx-vlm 自然也就失效了——但我一点不心疼,因为我压根没打算用它。

我的需求(把政策文件、研报转 Markdown)pipeline 几秒就干完,MLX 加速的是我根本用不上的 VLM 模式。这就像为了让一辆够用的家用车快一点,把发动机拆了换赛车引擎,结果车直接趴窝。

顺带几个小插曲也记一下,都是新手常见的:解析时报

Path does not exist

,是因为文件不在当前目录,用绝对路径并把整个路径用引号括起来就好(空格、括号都不用转义);还有一次我只粘贴了文件路径忘了加

mineru -p

,终端把 PDF 当程序执行,报

permission denied

——虚惊一场,不是真的权限问题。

教训:工具的"高级选项"很有诱惑力,但先问自己一句——我的实际需求,真的需要它吗?如果真要尝鲜,也该给它单独建一个隔离环境,别在跑得好好的主力环境里动手术。很多时候,够用的方案就是最好的方案。

五、写在最后

绕过这五个坑之后,我得到了一套相当顺手的工具:命令行批量转换处理日常的大宗文件,本地 Gradio 界面应付偶尔需要边调参数边看效果的单份文件,两者都完全本地、零泄密风险。一堆原本只能用眼睛看的 PDF,现在都变成了 Obsidian 里可搜索、可引用、可喂给大模型的结构化笔记。

性能也比我预期的好。就拿那本闯了祸的 583 页大部头来说,在一台 MacBook Air 上,从启动到生成 Markdown 总共约 7 分钟,其中模型加载占了一分多钟,真正解析每 64 页只要十几秒,全程跑在 Apple 的 GPU 上。对日常的政策文件、研究报告这种几十页的文档,基本是秒级出结果。

回头看,这些坑没有一个是 MinerU 本身的问题——它们分别来自 shell 的执行规则、系统代理配置、默认参数选择、以及对"本地"二字的想当然。这恰恰是自己动手部署工具的价值:你不只是学会了用一个软件,更是在每个卡壳的地方,理解了底层到底在发生什么。

如果你也准备装,希望这篇能帮你把那个周末省下来。

几个一句话备忘:

提示符前必须是

(mineru)

,不是就说明环境位置错了

本地服务启动失败,先查

no_proxy

是不是没绕过代理

日常一律

-b pipeline

,别让它下用不上的大模型

敏感文件只走命令行,绝不碰桌面客户端