1. 为什么要在 Windows 上折腾 MinerU 4.0 本地部署RAG 做久了你会发现一个很尴尬的事实模型换了一茬又一茬向量库从 FAISS 换到 Milvus 再换到 Qdrant检索策略从朴素向量召回一路升级到混合检索加重排序但整个链路里最拖后腿的往往不是这些高级环节而是最不起眼的 PDF 解析。我见过太多项目检索效果差、答非所问、表格数据全乱追根溯源最后都指向同一个问题——文档预处理阶段把内容喂坏了。MinerU 4.0 就是冲着这个痛点来的。它本质上是一个面向 RAG 场景优化的文档解析工具能把 PDF、图片、Office 文档转成结构清晰的 Markdown 和 JSON尤其是对公式、表格、多栏排版的处理比市面上大多数通用解析库要靠谱得多。而本地部署这四个字对很多团队来说是刚需合同、财报、内部技术文档这些东西你不可能往公有云 API 上扔。所以这篇就聊聊怎么在 Windows 上把 MinerU 4.0 跑起来并且真正用到 RAG 的文档预处理流程里。这篇文章适合三类人看一是正在搭 RAG 知识库、被 PDF 解析折磨过的工程师二是需要在离线环境处理敏感文档的团队三是想搞清楚 MinerU 到底值不值得从别的方案迁移过来的技术选型者。我会把环境准备、模型下载、参数调优、批量处理脚本、常见报错排查都讲透尽量让你照着做就能跑通而不是看完还得自己猜。先说结论Windows 上部署 MinerU 4.0 完全可行但坑比 Linux 多主要集中在 CUDA 环境、模型下载和路径处理这三块。下面按实操顺序展开。2. 部署前的整体思路与环境选型2.1 为什么选本地部署而不是调 API很多人第一反应是直接用 MinerU 的在线 API省事。但实际项目里本地部署有三个绕不开的理由。第一是数据合规。RAG 知识库处理的文档往往包含未公开的商业信息走外部接口意味着数据出了你的边界这在很多行业是直接一票否决的。第二是成本可控。API 按量计费文档量一大费用涨得比算力还快而本地部署是一次性投入后续边际成本几乎为零。第三是可定制。本地部署你能改解析参数、能接自己的后处理逻辑、能控制并发和缓存策略API 只能用它给你的那套。当然本地部署也有代价你得有块像样的显卡。MinerU 4.0 的模型推理对显存有要求后面会具体说。2.2 硬件与系统的最低门槛我把实测下来能跑和跑得舒服的配置列一下方便你对号入座。配置项最低可用推荐配置说明操作系统Windows 10 64位Windows 11 22H2需要支持 WSL2 或原生 CUDA显卡GTX 1660 6GBRTX 3060 12GB 及以上显存决定能跑哪些模型内存16GB32GB批量处理时内存吃紧硬盘20GB 空闲50GB SSD模型文件本身就有十几个 GPython3.103.10 或 3.113.12 部分依赖还没跟上这里要特别提醒一句显存是硬门槛。6GB 显存只能跑轻量模式表格和公式识别会降级12GB 才能比较舒服地跑完整流程。如果你只有核显或者显存不够也不是完全没戏可以用 CPU 模式但速度会慢到让你怀疑人生一篇几十页的 PDF 可能要跑好几分钟。2.3 部署路线的两种选择Windows 上部署 MinerU 有两条路一是原生 Windows 环境直接装二是走 WSL2。我的建议是如果你只是偶尔处理几篇文档原生装就行如果要批量处理、要长期跑服务强烈建议上 WSL2。原因很实际MinerU 底层依赖的一些库在 Windows 原生环境下编译经常出问题尤其是涉及 CUDA 扩展的部分。WSL2 里跑的是完整的 Linux 环境依赖安装顺畅得多而且性能损耗很小。不过 WSL2 也有它的麻烦比如文件系统跨系统访问慢、GPU 直通需要额外配置。下面我两条路都会讲你根据自己的情况选。3. 原生 Windows 环境搭建实操3.1 Python 环境与虚拟环境隔离第一步永远是环境隔离。我踩过太多次坑系统 Python 里装了一堆东西最后依赖冲突到没法排查。用 conda 或者 venv 都行我个人习惯 conda因为管理 CUDA 版本方便。conda create -n mineru python3.10 -y conda activate mineru创建完先别急着装 MinerU先把 pip 源换一下不然下载速度能让你等到睡着。国内的话用清华源或者阿里源都行。pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple这里有个细节MinerU 4.0 对 PyTorch 版本有要求不要自己先装 PyTorch让它作为依赖自动装否则版本对不上会报一堆莫名其妙的错。3.2 CUDA 与 PyTorch 的版本匹配这是 Windows 部署最容易翻车的地方。CUDA 版本、显卡驱动、PyTorch 版本三者必须匹配错一个就跑不起来。先确认你的显卡驱动支持的 CUDA 版本命令行执行nvidia-smi右上角会显示 CUDA Version。注意这个是你驱动支持的最高版本不是你必须装的版本。然后去 PyTorch 官网查对应关系比如 CUDA 11.8 对应cu118的安装包。# 以 CUDA 11.8 为例装完后 MinerU 会自动拉取匹配的 torch pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118装完验证一下 GPU 是否可用import torch print(torch.cuda.is_available()) print(torch.cuda.get_device_name(0))如果输出True和你的显卡型号说明环境没问题。如果输出False八成是 CUDA 版本和 PyTorch 不匹配或者驱动太旧回去检查。注意不要同时装 CPU 版和 GPU 版的 PyTorch会冲突。如果之前装过先pip uninstall torch torchvision卸干净再重装。3.3 安装 MinerU 4.0 本体环境对了装 MinerU 就简单了。官方推荐用 pip 装也可以从源码装。pip install mineru如果你要用最新的 4.0 特性建议从源码装git clone https://github.com/opendatalab/MinerU.git cd MinerU pip install -e .装完之后跑一下mineru --version确认安装成功。第一次运行会自动下载模型这一步是很多人卡住的地方因为模型文件有好几个 G网络不好会一直卡在获取中。3.4 模型文件的离线下载与放置模型下载慢或者下不动是 Windows 部署的高频问题。解决办法是手动下载模型文件然后放到指定目录。MinerU 的模型默认放在用户目录下的.cache/mineru或者配置指定的路径。你可以先跑一次让它创建目录结构然后去 HuggingFace 或者 ModelScope 手动下载对应的模型文件解压后放进去。模型主要分几块版面分析模型、公式识别模型、表格识别模型、OCR 模型。如果你只处理电子版 PDF文字可选中的那种OCR 模型可以不装能省不少空间。实操心得模型下载建议用 ModelScope 的镜像国内速度快很多。下载完记得校验文件完整性我遇到过一次模型文件下了一半结果解析出来全是乱码排查了半天才发现是模型损坏。4. 用 WSL2 部署的进阶方案4.1 WSL2 环境准备与 GPU 直通如果你决定走 WSL2先在 PowerShell 里装好 WSL2 和一个 Ubuntu 发行版。wsl --install -d Ubuntu-22.04装完进 Ubuntu更新一下系统然后装 CUDA Toolkit。WSL2 的 GPU 直通需要 Windows 侧的驱动支持只要你的显卡驱动是较新版本WSL2 里直接就能用nvidia-smi看到显卡。sudo apt update sudo apt upgrade -y sudo apt install -y build-essential python3-pip python3-venvWSL2 里装 CUDA 不用装完整驱动只装 toolkit 就行驱动是 Windows 侧提供的。4.2 WSL2 下的依赖安装与验证WSL2 里装 MinerU 和原生 Windows 差不多但依赖编译顺畅得多。python3 -m venv mineru-env source mineru-env/bin/activate pip install --upgrade pip pip install mineru验证 GPUpython -c import torch; print(torch.cuda.is_available())WSL2 的一个坑是文件系统性能。如果你把文档放在 Windows 的/mnt/c/下读写会非常慢。建议把待处理文档复制到 WSL2 的 Linux 文件系统里比如~/data/处理速度能快好几倍。4.3 两种方案怎么选简单给个决策建议单次处理、文档量小、不想折腾选原生 Windows批量处理、要跑服务、追求稳定选 WSL2。我自己的生产环境是 WSL2开发调试用原生两边都留着。5. 核心解析流程与参数调优5.1 单文件解析的最小可用命令MinerU 的命令行接口设计得挺直观最基础的用法就一行mineru -p input.pdf -o output_dir它会输出 Markdown 和 JSON 两种格式。Markdown 适合直接喂给 RAG 的文本切分环节JSON 保留了版面结构信息适合做更精细的处理。但默认参数不一定适合你的场景下面几个参数是必须调的。5.2 关键参数逐个拆解--method解析方法有auto、txt、ocr三个选项。电子版 PDF 用txt最快扫描件必须用ocrauto让它自己判断。我一般电子版直接指定txt省得它误判。--lang语言设置中文文档一定要指定ch不然 OCR 识别率会掉一大截。--device指定cuda或cpu。有显卡就cuda别犹豫。--batch-size批处理大小显存够就调大能提升吞吐。12GB 显存可以设到 8 或 166GB 就老实设 2 或 4。--formula和--table是否启用公式和表格识别。这两个功能吃显存如果文档里没有公式表格关掉能快不少。一个比较通用的命令长这样mineru -p input.pdf -o output_dir --method txt --lang ch --device cuda --batch-size 8 --formula --table5.3 输出结果的结构解读解析完的输出目录里你会看到几个文件。.md是转换后的 Markdown.json是结构化数据还有images/目录存的是从 PDF 里抽出来的图片。JSON 的结构值得研究一下它把每个元素都标了类型text、title、table、formula、image。做 RAG 的时候你可以根据类型做差异化处理——标题作为层级切分依据表格单独走结构化存储公式转成 LaTeX 保留。实操心得不要直接把 Markdown 整篇丢进向量库。MinerU 输出的 Markdown 里表格是 HTML 格式的直接切分会把表格切碎。正确做法是先按标题层级切分表格单独抽出来做结构化处理再决定是转成文本描述还是存成结构化数据。6. 接入 RAG 文档预处理流水线6.1 从解析到切分的完整链路MinerU 只是预处理的第一步后面还要接切分、向量化、入库。我一般这么设计流水线MinerU 解析 PDF输出 Markdown 和 JSON按 JSON 里的标题层级做语义切分而不是按固定字数硬切表格和公式单独处理表格转成自然语言描述或结构化存储切分后的 chunk 做向量化连同元数据一起入库这个链路里第 2 步是关键。固定字数切分是最偷懒也最伤效果的做法它会把一个完整的语义单元切碎。用 MinerU 给的标题层级做切分能保证每个 chunk 语义完整。6.2 批量处理的脚本实现单文件处理用命令行就够了批量处理得写脚本。下面这个脚本是我实际在用的做了并发控制和错误重试。import os import subprocess from concurrent.futures import ThreadPoolExecutor, as_completed from pathlib import Path def parse_pdf(pdf_path, output_root): pdf_path Path(pdf_path) out_dir Path(output_root) / pdf_path.stem out_dir.mkdir(parentsTrue, exist_okTrue) cmd [ mineru, -p, str(pdf_path), -o, str(out_dir), --method, txt, --lang, ch, --device, cuda, --batch-size, 8 ] try: subprocess.run(cmd, checkTrue, capture_outputTrue, timeout600) return pdf_path.name, True, except subprocess.TimeoutExpired: return pdf_path.name, False, timeout except subprocess.CalledProcessError as e: return pdf_path.name, False, e.stderr.decode()[:200] def batch_parse(input_dir, output_dir, max_workers2): pdfs list(Path(input_dir).glob(*.pdf)) results [] with ThreadPoolExecutor(max_workersmax_workers) as executor: futures {executor.submit(parse_pdf, p, output_dir): p for p in pdfs} for future in as_completed(futures): name, ok, msg future.result() results.append((name, ok, msg)) print(f{name}: {OK if ok else FAIL - msg}) return results if __name__ __main__: batch_parse(./pdfs, ./parsed, max_workers2)这里max_workers不要设太大因为每个进程都要占显存设成 2 比较稳。设太大反而会因为显存不足频繁失败。6.3 表格与公式的特殊处理RAG 里表格是最难处理的部分。MinerU 能把表格识别成 HTML但 HTML 直接进向量库效果很差。我的做法是把表格转成 Markdown 表格再给表格加一段自然语言摘要两者一起存。公式的话MinerU 输出的是 LaTeX直接保留就行。检索时如果用户问的是公式相关内容LaTeX 文本也能被匹配到。注意表格识别不是百分百准确尤其是跨页表格和复杂合并单元格。批量处理完一定要抽样检查别全信自动结果。7. 常见报错与排查速查7.1 模型下载卡住或失败最常见的报错就是一直显示获取中。原因基本是网络问题。解决办法是手动下载模型放到缓存目录或者配置镜像源。export HF_ENDPOINThttps://hf-mirror.comWindows 下用set代替export。设完再跑下载速度会正常。7.2 CUDA out of memory显存不够。解决办法按优先级调小--batch-size、关掉--formula和--table、换更小的模型、实在不行上 CPU。7.3 中文乱码或识别错误检查--lang是不是设成了ch。另外确认模型文件完整损坏的模型会导致输出乱码。7.4 路径含中文或空格导致失败Windows 下路径带中文或空格经常出问题。把待处理文件放到纯英文、无空格的路径下能避免一大类莫名其妙的错误。报错现象可能原因解决方向一直获取中网络问题配镜像或手动下模型CUDA OOM显存不足调小 batch、关功能输出乱码模型损坏或语言设错校验模型、设 lang路径报错中文/空格路径换纯英文路径依赖冲突环境不干净重建虚拟环境7.5 排查思路的通用原则遇到报错先看日志MinerU 的日志会告诉你卡在哪一步。是模型加载失败还是推理过程出错还是输出写入失败定位到具体环节再对症下药。别一上来就重装那样只会浪费 time。8. 性能优化与生产化建议8.1 提升吞吐的几个手段批处理大小、并发数、模型选择这三个是影响吞吐的主要因素。显存够的话把 batch-size 调大是最直接的。另外如果文档里大部分是纯文本关掉公式和表格识别能快一倍以上。还有一个容易被忽略的点把模型常驻内存。如果你要连续处理大量文档别每次都重新加载模型写个常驻服务模型加载一次反复用。8.2 缓存策略同一份文档可能被处理多次加个缓存能省很多算力。用文件哈希做 key处理过的直接读缓存结果。import hashlib def file_hash(path): h hashlib.md5() with open(path, rb) as f: for chunk in iter(lambda: f.read(8192), b): h.update(chunk) return h.hexdigest()8.3 与向量库的对接解析完的 chunk 要入库。我一般用 Milvus 或 Qdrant元数据里存上来源文件名、页码、元素类型方便检索时做过滤和溯源。这一步别偷懒元数据设计好了后面做引用回溯会轻松很多。9. 我踩过的坑和几条实在建议部署 MinerU 这一路坑是真不少。最开始我在原生 Windows 上装CUDA 版本和 PyTorch 对不上折腾了一下午。后来换 WSL2顺畅多了但文件系统跨系统访问慢的问题又冒出来把文档挪到 Linux 侧才解决。模型下载那块也吃过亏第一次下到一半断了没校验就用结果解析出来全是乱码还以为是参数问题查了半天才发现是模型文件损坏。从那以后我养成了下载完先校验的习惯。还有一点别迷信自动解析的结果。表格、公式、复杂排版自动识别总有出错的时候。生产环境一定要加人工抽检环节尤其是关键文档。RAG 的效果上限很大程度上取决于预处理的质量这一步偷懒后面检索再花哨也救不回来。如果你刚开始搞我的建议是先拿几篇有代表性的文档跑通全流程把参数调顺了再上批量。别一上来就几百篇一起跑出了问题你都不知道是哪篇、哪个环节的锅。稳扎稳打比什么都强。
1. 为什么要在 Windows 上折腾 MinerU 4.0 本地部署RAG 做久了你会发现一个很尴尬的事实模型换了一茬又一茬向量库从 FAISS 换到 Milvus 再换到 Qdrant检索策略从朴素向量召回一路升级到混合检索加重排序但整个链路里最拖后腿的往往不是这些高级环节而是最不起眼的 PDF 解析。我见过太多项目检索效果差、答非所问、表格数据全乱追根溯源最后都指向同一个问题——文档预处理阶段把内容喂坏了。MinerU 4.0 就是冲着这个痛点来的。它本质上是一个面向 RAG 场景优化的文档解析工具能把 PDF、图片、Office 文档转成结构清晰的 Markdown 和 JSON尤其是对公式、表格、多栏排版的处理比市面上大多数通用解析库要靠谱得多。而本地部署这四个字对很多团队来说是刚需合同、财报、内部技术文档这些东西你不可能往公有云 API 上扔。所以这篇就聊聊怎么在 Windows 上把 MinerU 4.0 跑起来并且真正用到 RAG 的文档预处理流程里。这篇文章适合三类人看一是正在搭 RAG 知识库、被 PDF 解析折磨过的工程师二是需要在离线环境处理敏感文档的团队三是想搞清楚 MinerU 到底值不值得从别的方案迁移过来的技术选型者。我会把环境准备、模型下载、参数调优、批量处理脚本、常见报错排查都讲透尽量让你照着做就能跑通而不是看完还得自己猜。先说结论Windows 上部署 MinerU 4.0 完全可行但坑比 Linux 多主要集中在 CUDA 环境、模型下载和路径处理这三块。下面按实操顺序展开。2. 部署前的整体思路与环境选型2.1 为什么选本地部署而不是调 API很多人第一反应是直接用 MinerU 的在线 API省事。但实际项目里本地部署有三个绕不开的理由。第一是数据合规。RAG 知识库处理的文档往往包含未公开的商业信息走外部接口意味着数据出了你的边界这在很多行业是直接一票否决的。第二是成本可控。API 按量计费文档量一大费用涨得比算力还快而本地部署是一次性投入后续边际成本几乎为零。第三是可定制。本地部署你能改解析参数、能接自己的后处理逻辑、能控制并发和缓存策略API 只能用它给你的那套。当然本地部署也有代价你得有块像样的显卡。MinerU 4.0 的模型推理对显存有要求后面会具体说。2.2 硬件与系统的最低门槛我把实测下来能跑和跑得舒服的配置列一下方便你对号入座。配置项最低可用推荐配置说明操作系统Windows 10 64位Windows 11 22H2需要支持 WSL2 或原生 CUDA显卡GTX 1660 6GBRTX 3060 12GB 及以上显存决定能跑哪些模型内存16GB32GB批量处理时内存吃紧硬盘20GB 空闲50GB SSD模型文件本身就有十几个 GPython3.103.10 或 3.113.12 部分依赖还没跟上这里要特别提醒一句显存是硬门槛。6GB 显存只能跑轻量模式表格和公式识别会降级12GB 才能比较舒服地跑完整流程。如果你只有核显或者显存不够也不是完全没戏可以用 CPU 模式但速度会慢到让你怀疑人生一篇几十页的 PDF 可能要跑好几分钟。2.3 部署路线的两种选择Windows 上部署 MinerU 有两条路一是原生 Windows 环境直接装二是走 WSL2。我的建议是如果你只是偶尔处理几篇文档原生装就行如果要批量处理、要长期跑服务强烈建议上 WSL2。原因很实际MinerU 底层依赖的一些库在 Windows 原生环境下编译经常出问题尤其是涉及 CUDA 扩展的部分。WSL2 里跑的是完整的 Linux 环境依赖安装顺畅得多而且性能损耗很小。不过 WSL2 也有它的麻烦比如文件系统跨系统访问慢、GPU 直通需要额外配置。下面我两条路都会讲你根据自己的情况选。3. 原生 Windows 环境搭建实操3.1 Python 环境与虚拟环境隔离第一步永远是环境隔离。我踩过太多次坑系统 Python 里装了一堆东西最后依赖冲突到没法排查。用 conda 或者 venv 都行我个人习惯 conda因为管理 CUDA 版本方便。conda create -n mineru python3.10 -y conda activate mineru创建完先别急着装 MinerU先把 pip 源换一下不然下载速度能让你等到睡着。国内的话用清华源或者阿里源都行。pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple这里有个细节MinerU 4.0 对 PyTorch 版本有要求不要自己先装 PyTorch让它作为依赖自动装否则版本对不上会报一堆莫名其妙的错。3.2 CUDA 与 PyTorch 的版本匹配这是 Windows 部署最容易翻车的地方。CUDA 版本、显卡驱动、PyTorch 版本三者必须匹配错一个就跑不起来。先确认你的显卡驱动支持的 CUDA 版本命令行执行nvidia-smi右上角会显示 CUDA Version。注意这个是你驱动支持的最高版本不是你必须装的版本。然后去 PyTorch 官网查对应关系比如 CUDA 11.8 对应cu118的安装包。# 以 CUDA 11.8 为例装完后 MinerU 会自动拉取匹配的 torch pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118装完验证一下 GPU 是否可用import torch print(torch.cuda.is_available()) print(torch.cuda.get_device_name(0))如果输出True和你的显卡型号说明环境没问题。如果输出False八成是 CUDA 版本和 PyTorch 不匹配或者驱动太旧回去检查。注意不要同时装 CPU 版和 GPU 版的 PyTorch会冲突。如果之前装过先pip uninstall torch torchvision卸干净再重装。3.3 安装 MinerU 4.0 本体环境对了装 MinerU 就简单了。官方推荐用 pip 装也可以从源码装。pip install mineru如果你要用最新的 4.0 特性建议从源码装git clone https://github.com/opendatalab/MinerU.git cd MinerU pip install -e .装完之后跑一下mineru --version确认安装成功。第一次运行会自动下载模型这一步是很多人卡住的地方因为模型文件有好几个 G网络不好会一直卡在获取中。3.4 模型文件的离线下载与放置模型下载慢或者下不动是 Windows 部署的高频问题。解决办法是手动下载模型文件然后放到指定目录。MinerU 的模型默认放在用户目录下的.cache/mineru或者配置指定的路径。你可以先跑一次让它创建目录结构然后去 HuggingFace 或者 ModelScope 手动下载对应的模型文件解压后放进去。模型主要分几块版面分析模型、公式识别模型、表格识别模型、OCR 模型。如果你只处理电子版 PDF文字可选中的那种OCR 模型可以不装能省不少空间。实操心得模型下载建议用 ModelScope 的镜像国内速度快很多。下载完记得校验文件完整性我遇到过一次模型文件下了一半结果解析出来全是乱码排查了半天才发现是模型损坏。4. 用 WSL2 部署的进阶方案4.1 WSL2 环境准备与 GPU 直通如果你决定走 WSL2先在 PowerShell 里装好 WSL2 和一个 Ubuntu 发行版。wsl --install -d Ubuntu-22.04装完进 Ubuntu更新一下系统然后装 CUDA Toolkit。WSL2 的 GPU 直通需要 Windows 侧的驱动支持只要你的显卡驱动是较新版本WSL2 里直接就能用nvidia-smi看到显卡。sudo apt update sudo apt upgrade -y sudo apt install -y build-essential python3-pip python3-venvWSL2 里装 CUDA 不用装完整驱动只装 toolkit 就行驱动是 Windows 侧提供的。4.2 WSL2 下的依赖安装与验证WSL2 里装 MinerU 和原生 Windows 差不多但依赖编译顺畅得多。python3 -m venv mineru-env source mineru-env/bin/activate pip install --upgrade pip pip install mineru验证 GPUpython -c import torch; print(torch.cuda.is_available())WSL2 的一个坑是文件系统性能。如果你把文档放在 Windows 的/mnt/c/下读写会非常慢。建议把待处理文档复制到 WSL2 的 Linux 文件系统里比如~/data/处理速度能快好几倍。4.3 两种方案怎么选简单给个决策建议单次处理、文档量小、不想折腾选原生 Windows批量处理、要跑服务、追求稳定选 WSL2。我自己的生产环境是 WSL2开发调试用原生两边都留着。5. 核心解析流程与参数调优5.1 单文件解析的最小可用命令MinerU 的命令行接口设计得挺直观最基础的用法就一行mineru -p input.pdf -o output_dir它会输出 Markdown 和 JSON 两种格式。Markdown 适合直接喂给 RAG 的文本切分环节JSON 保留了版面结构信息适合做更精细的处理。但默认参数不一定适合你的场景下面几个参数是必须调的。5.2 关键参数逐个拆解--method解析方法有auto、txt、ocr三个选项。电子版 PDF 用txt最快扫描件必须用ocrauto让它自己判断。我一般电子版直接指定txt省得它误判。--lang语言设置中文文档一定要指定ch不然 OCR 识别率会掉一大截。--device指定cuda或cpu。有显卡就cuda别犹豫。--batch-size批处理大小显存够就调大能提升吞吐。12GB 显存可以设到 8 或 166GB 就老实设 2 或 4。--formula和--table是否启用公式和表格识别。这两个功能吃显存如果文档里没有公式表格关掉能快不少。一个比较通用的命令长这样mineru -p input.pdf -o output_dir --method txt --lang ch --device cuda --batch-size 8 --formula --table5.3 输出结果的结构解读解析完的输出目录里你会看到几个文件。.md是转换后的 Markdown.json是结构化数据还有images/目录存的是从 PDF 里抽出来的图片。JSON 的结构值得研究一下它把每个元素都标了类型text、title、table、formula、image。做 RAG 的时候你可以根据类型做差异化处理——标题作为层级切分依据表格单独走结构化存储公式转成 LaTeX 保留。实操心得不要直接把 Markdown 整篇丢进向量库。MinerU 输出的 Markdown 里表格是 HTML 格式的直接切分会把表格切碎。正确做法是先按标题层级切分表格单独抽出来做结构化处理再决定是转成文本描述还是存成结构化数据。6. 接入 RAG 文档预处理流水线6.1 从解析到切分的完整链路MinerU 只是预处理的第一步后面还要接切分、向量化、入库。我一般这么设计流水线MinerU 解析 PDF输出 Markdown 和 JSON按 JSON 里的标题层级做语义切分而不是按固定字数硬切表格和公式单独处理表格转成自然语言描述或结构化存储切分后的 chunk 做向量化连同元数据一起入库这个链路里第 2 步是关键。固定字数切分是最偷懒也最伤效果的做法它会把一个完整的语义单元切碎。用 MinerU 给的标题层级做切分能保证每个 chunk 语义完整。6.2 批量处理的脚本实现单文件处理用命令行就够了批量处理得写脚本。下面这个脚本是我实际在用的做了并发控制和错误重试。import os import subprocess from concurrent.futures import ThreadPoolExecutor, as_completed from pathlib import Path def parse_pdf(pdf_path, output_root): pdf_path Path(pdf_path) out_dir Path(output_root) / pdf_path.stem out_dir.mkdir(parentsTrue, exist_okTrue) cmd [ mineru, -p, str(pdf_path), -o, str(out_dir), --method, txt, --lang, ch, --device, cuda, --batch-size, 8 ] try: subprocess.run(cmd, checkTrue, capture_outputTrue, timeout600) return pdf_path.name, True, except subprocess.TimeoutExpired: return pdf_path.name, False, timeout except subprocess.CalledProcessError as e: return pdf_path.name, False, e.stderr.decode()[:200] def batch_parse(input_dir, output_dir, max_workers2): pdfs list(Path(input_dir).glob(*.pdf)) results [] with ThreadPoolExecutor(max_workersmax_workers) as executor: futures {executor.submit(parse_pdf, p, output_dir): p for p in pdfs} for future in as_completed(futures): name, ok, msg future.result() results.append((name, ok, msg)) print(f{name}: {OK if ok else FAIL - msg}) return results if __name__ __main__: batch_parse(./pdfs, ./parsed, max_workers2)这里max_workers不要设太大因为每个进程都要占显存设成 2 比较稳。设太大反而会因为显存不足频繁失败。6.3 表格与公式的特殊处理RAG 里表格是最难处理的部分。MinerU 能把表格识别成 HTML但 HTML 直接进向量库效果很差。我的做法是把表格转成 Markdown 表格再给表格加一段自然语言摘要两者一起存。公式的话MinerU 输出的是 LaTeX直接保留就行。检索时如果用户问的是公式相关内容LaTeX 文本也能被匹配到。注意表格识别不是百分百准确尤其是跨页表格和复杂合并单元格。批量处理完一定要抽样检查别全信自动结果。7. 常见报错与排查速查7.1 模型下载卡住或失败最常见的报错就是一直显示获取中。原因基本是网络问题。解决办法是手动下载模型放到缓存目录或者配置镜像源。export HF_ENDPOINThttps://hf-mirror.comWindows 下用set代替export。设完再跑下载速度会正常。7.2 CUDA out of memory显存不够。解决办法按优先级调小--batch-size、关掉--formula和--table、换更小的模型、实在不行上 CPU。7.3 中文乱码或识别错误检查--lang是不是设成了ch。另外确认模型文件完整损坏的模型会导致输出乱码。7.4 路径含中文或空格导致失败Windows 下路径带中文或空格经常出问题。把待处理文件放到纯英文、无空格的路径下能避免一大类莫名其妙的错误。报错现象可能原因解决方向一直获取中网络问题配镜像或手动下模型CUDA OOM显存不足调小 batch、关功能输出乱码模型损坏或语言设错校验模型、设 lang路径报错中文/空格路径换纯英文路径依赖冲突环境不干净重建虚拟环境7.5 排查思路的通用原则遇到报错先看日志MinerU 的日志会告诉你卡在哪一步。是模型加载失败还是推理过程出错还是输出写入失败定位到具体环节再对症下药。别一上来就重装那样只会浪费 time。8. 性能优化与生产化建议8.1 提升吞吐的几个手段批处理大小、并发数、模型选择这三个是影响吞吐的主要因素。显存够的话把 batch-size 调大是最直接的。另外如果文档里大部分是纯文本关掉公式和表格识别能快一倍以上。还有一个容易被忽略的点把模型常驻内存。如果你要连续处理大量文档别每次都重新加载模型写个常驻服务模型加载一次反复用。8.2 缓存策略同一份文档可能被处理多次加个缓存能省很多算力。用文件哈希做 key处理过的直接读缓存结果。import hashlib def file_hash(path): h hashlib.md5() with open(path, rb) as f: for chunk in iter(lambda: f.read(8192), b): h.update(chunk) return h.hexdigest()8.3 与向量库的对接解析完的 chunk 要入库。我一般用 Milvus 或 Qdrant元数据里存上来源文件名、页码、元素类型方便检索时做过滤和溯源。这一步别偷懒元数据设计好了后面做引用回溯会轻松很多。9. 我踩过的坑和几条实在建议部署 MinerU 这一路坑是真不少。最开始我在原生 Windows 上装CUDA 版本和 PyTorch 对不上折腾了一下午。后来换 WSL2顺畅多了但文件系统跨系统访问慢的问题又冒出来把文档挪到 Linux 侧才解决。模型下载那块也吃过亏第一次下到一半断了没校验就用结果解析出来全是乱码还以为是参数问题查了半天才发现是模型文件损坏。从那以后我养成了下载完先校验的习惯。还有一点别迷信自动解析的结果。表格、公式、复杂排版自动识别总有出错的时候。生产环境一定要加人工抽检环节尤其是关键文档。RAG 的效果上限很大程度上取决于预处理的质量这一步偷懒后面检索再花哨也救不回来。如果你刚开始搞我的建议是先拿几篇有代表性的文档跑通全流程把参数调顺了再上批量。别一上来就几百篇一起跑出了问题你都不知道是哪篇、哪个环节的锅。稳扎稳打比什么都强。
