搞知识库和 RAG 相关项目的人迟早会撞上一堵墙PDF 解析。用了各种工具提取文字结果表格变一团乱麻公式全部乱码双栏论文的阅读顺序错得离谱。这些垃圾输入进 RAG 里检索出来的内容根本没法用。我之前也折腾了小半年最后固定在 Windows 上本地部署 MinerU 4.0把 PDF 解析这步彻底做扎实了。这篇文章就围绕 MinerU 4.0 的本地部署完整讲清楚环境准备、模型权重、命令行和 Python SDK 两种用法再带上我把解析结果接进 RAG 预处理管线的实践经验。如果你是做本地知识库、RAG 问答、文档结构化入库这类工作的或者手里有一批 PDF 需要批量转成干净的 Markdown这篇文章可以直接照着抄作业。1. 为什么解析这一步会卡住 RAG 的脖子1.1 PDF 解析不是“把字抽出来”很多人在 RAG 项目里对 PDF 的处理方式还停留在用 PyMuPDF 或者 pdfplumber 把文字层直接抽出来。对纯文本论文这种简单场景确实够用但现实里的文档远比想象中复杂。双栏排版、跨页表格、嵌入式公式、扫描件、页眉页脚、图表混排每一样都能让简单的文本抽取结果彻底崩坏。我见过最典型的问题就是解析出来的表格数据顺序完全错乱。PDF 内部存储的其实是一堆“绘制指令”文字、图形、图片全都在一个流式结构里阅读顺序需要算法自己去推断。MinerU 这类工具之所以强是因为它把版面检测、阅读顺序还原、公式识别、表格重建这几个环节全部串起来了而不是简单地把字符捞出来拼在一起。1.2 解析质量就是 RAG 上限RAG 的质量大体上被三个环节卡着文档解析、切片策略、检索召回。其中文档解析是最容易被忽视的但它决定后续所有环节的上限。原始文本一团糟检索再强也救不回来。举个例子我要把一个年度的行业统计 PDF 做成问答知识库。如果解析出来的表格变成“2023 2024 2025 同比 增长 30 25 20”这样断成散片的文本向量检索根本配不上“2024 年增长率是多少”这种问题。但用 MinerU 把表格还原成真正的 Markdown 表结构文字、列头、行标签都完整保留检索命中率立刻就不一样了。所以我的结论很直接在 RAG 预处理流程里解析这一步值得花时间投入。MinerU 4.0 恰好就是针对这个痛点设计的本地部署之后还能做到文档不出内网数据安全这块也顺带解决了。2. MinerU 4.0 到底是干嘛的2.1 核心能力拆解MinerU 是一个开源的 PDF 文档解析引擎它的核心目标是把 PDF 转成结构完整的 Markdown 或 JSON。4.0 版本在架构上整合了几个关键能力版面检测与阅读顺序还原、公式检测与 LaTeX 转换、表格识别与 Markdown 重建、OCR 文字识别。换句话说输入是一份 PDF 文件输出是保留了层级结构、公式和表格的干净文本。内部工作流大致可以理解为先把每一页做版面分析识别出标题、段落、表格、公式、图片区域再用检测模型区分矢量文本和需要 OCR 的扫描文本最后通过后处理模块恢复阅读顺序并把公式转成 LaTeX把表格重建成 Markdown 语法。2.2 和“装个库跑 pip”的区别网上有很多号称能解析 PDF 的库但实测下来分水岭很清晰。普通 PDF 文本提取库只能处理“有文字层”的 PDF遇到扫描件直接抓瞎。商业云服务效果好但文档要上传到别人服务器知识库场景里很多客户根本接受不了。MinerU 本地跑的好处在于三点一是文档不出内网敏感资料放心处理二是一次部署终身免费批量解析也不心疼成本三是解析结果完全在自己手里Markdown 输出可以随意二次加工和接入下游。这三点恰好是 RAG 项目最看重的。我自己的使用感受是MinerU 对中文文档的支持格外友好中英混排、中文表格、中文公式场景的表现甚至比一些我尝试过的商业 API 还要稳。本地部署之后性能和速度都能自己控制。3. Windows 环境准备与依赖安装3.1 硬件底线与推荐配置先把硬件说清楚免得后面踩坑。MinerU 模型链路包含版面检测、公式识别、OCR 等多个模型推理时对内存有一定要求。我的建议配置如下使用场景CPU内存GPU硬盘最低可用小文件4 核 i3 以上8 GB无10 GB 可用空间推荐日常 RAG6 核 i5 以上16 GB8 GB 显存如 RTX 306020 GB 可用空间大批量处理8 核以上32 GB12 GB 显存以上50 GB 可用空间没有 N 卡也能跑纯 CPU 模式完全可以工作就是速度会慢不少。我实测一份 20 页的中文双栏论文在 i5-12400 纯 CPU 下解析耗时大概 2 到 4 分钟同样的活交给 RTX 3060 只要 30 到 60 秒。如果你的知识库文档量很大一张甜品级显卡能帮你省下大量时间。3.2 安装 Python 和创建干净环境MinerU 4.0 依赖 PyTorchPython 版本建议 3.10 到 3.12太老的版本容易在依赖上打架。我用的环境是 Windows 11 Python 3.11.9。第一步创建独立的虚拟环境。这步千万别省因为 MinerU 的依赖链很长直接装到系统 Python 里以后很容易和别的项目互相污染。在命令行里执行python -m venv mineru-env然后激活环境mineru-env\Scripts\activate紧接着安装 MinerU。这里有个小细节如果你用 GPU建议先装好 GPU 版的 PyTorch再装 MinerU避免 MinerU 依赖的 PyTorch 自动装成 CPU 版。我的安装顺序是这样pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121 pip install -U mineru最后再确认一下安装了哪些版本防止后续报一些莫名其妙的属性错误pip show mineru torch torchvision注意Windows 上如果 pip 安装过程中提示显卡驱动版本太低先更新 NVIDIA 驱动再做一次 pip install 即可。驱动版本和 CUDA 版本不匹配是 Windows 上最常见的安装失败原因。3.3 模型权重下载与目录管理MinerU 解析 PDF 是靠多个预训练模型协同工作这些模型权重不会包含在 pip 包内部。首次运行解析命令时MinerU 会自动从模型仓库拉取权重默认的位置在用户目录的缓存文件夹下一般是C:\Users\你的用户名\.cache\huggingface\hub但这里有坑。国内网络环境下Hugging Face 的自动下载经常走到一半就断。我的做法是提前手动把模型权重下载到本地再指定给 MinerU 使用。飞书文档里官方也给过模型下载指引基本思路是去 ModelScope 或 Hugging Face 找到对应的 MinerU 模型仓库用下载工具整体拉下来然后放到指定目录。我用 ModelScope 下载的命令大致是这样pip install modelscope modelscope download --model opendatalab/PDF-MinerU-4.0 --local_dir C:\\models\\mineru-models下载完成后在解析命令里显式指定模型路径或者把模型目录放进环境变量MINERU_MODEL_DIR里。这样 MinerU 就无法访问网络也能正常跑彻底实现离线解析。4. 命令行快速跑通4.1 单文件解析安装完成、模型就位之后最快验证效果的方式是用命令行跑一个单文件。MinerU 4.0 的 CLI 入口非常简单我平时最常用的命令是这个mineru -p ./docs/年报.pdf -o ./output -m auto这几个参数的含义拆开说-p输入的 PDF 文件或文件夹路径。-o输出目录MinerU 会在里面自动创建以 PDF 文件名命名的子目录。-m解析模式可选auto、ocr、txt。auto是自动判断带文字层就直接抽取检测到扫描页就切到 OCRtxt表示只处理纯文本型 PDFocr表示强制全部走 OCR 流程。跑完之后输出目录下会有一个*.md文件、一个存放图片的文件夹以及 JSON 格式的中间结果文件。这些产物都是 RAG 预处理可以直接用的。4.2 批量文件夹解析与关键参数单文件验证没问题之后接下来就是批量。MinerU 的 CLI 原生支持文件夹输入直接把-p指向一个包含大量 PDF 的目录就行mineru -p ./docs -o ./output -m auto --formula on --table on --workers 2参数说明--formula on开启公式识别扫描件和公式密集的文档建议开启。--table on开启表格重建会把表格还原成规范的 Markdown 表格语法。--workers 2并发解析的进程数。Windows 上不要开太大我实测 4 个 worker 时内存容易被占满反而比 2 个 worker 慢。批量处理时会遇到一个问题文件夹里混着各种类型的 PDF有的有文字层有的纯扫描。-m auto就是想对付这种情况的MinerU 会一页一页判断哪种方式合适就上哪种。我的经验是批量任务先挑一小批试跑确认输出目录结构和效果没问题再全量开跑。这样能避免跑完才发现参数不合适再重新返工。4.3 输出产物长什么样这是我最想让大家看清楚的部分。一份包含表格和公式的 PDF 解析出来后Markdown 产物大致是这样的## 3. 实验结果 表 1 列出了不同模型在测试集上的表现。 | 模型 | 准确率 | 召回率 | F1 | | --- | --- | --- | --- | | Base | 87.2 | 83.5 | 85.3 | | Proposed | 91.6 | 89.4 | 90.5 | 模型的优化目标可以表示为 $$ Loss -\sum_{t1}^{T} \log P(y_t | y_{t}, x) $$注意几个细节表格有完整的表头分隔线列和行都没有丢公式被转成了 LaTeX 格式标题层级保持住了。这种输出质量直接决定了后面做向量切块时候的语义完整性。5. 在 Python 里把 MinerU 当 SDK 用5.1 异步 API 的基本用法命令行适合快速验证和跑批但如果你要把 MinerU 集成到自己的知识库构建脚本里就要用 SDK 方式。MinerU 4.0 提供了异步 API简单到有点不像一个“重型解析引擎”该有的样子。import asyncio from mineru import MinerU async def parse_single_pdf(pdf_path: str, output_dir: str): data await MinerU.process( pdf_pathpdf_path, enable_formulaTrue, enable_tableTrue, exclude_bannerTrue, # 去掉页眉页脚 ) md_content data.md_content with open(f{output_dir}/output.md, w, encodingutf-8) as f: f.write(md_content) print(data)data对象里包含了解析产生的 Markdown 内容、JSON 结构和图片信息。整个过程你不需要关心模型加载、版面检测、OCR 调度的细节SDK 把这些全部封装好了。5.2 封装一个可复用的解析函数实际项目里我会把这个 API 再包一层加上失败重试和日志记录方便大规模跑文档库import asyncio import logging from pathlib import Path from mineru import MinerU logging.basicConfig(levellogging.INFO) async def parse_pdf_to_markdown(pdf_path: str, output_dir: str) - Path | None: pdf_name Path(pdf_path).stem target_dir Path(output_dir) / pdf_name target_dir.mkdir(parentsTrue, exist_okTrue) md_path target_dir / f{pdf_name}.md if md_path.exists(): logging.info(f跳过已处理文件: {pdf_name}) return md_path try: data await MinerU.process( pdf_pathpdf_path, enable_formulaTrue, enable_tableTrue, exclude_bannerTrue, ) md_path.write_text(data.md_content, encodingutf-8) logging.info(f解析完成: {pdf_name}) return md_path except Exception as e: logging.error(f解析失败 {pdf_name}: {e}) return None这里面做了一个“已处理文件跳过”的判断。这个习惯帮我省了不知道多少重复工时跑大批量文档的时候中途断了重新跑只有没完成的文件会再次执行。提示Windows 的路径里如果包含中文或空格尽量在调用前用pathlib.Path规范化一下。某些依赖库在后端处理路径时对特殊字符不感冒容易踩到莫名奇妙的编码错误。6. 把解析结果接入 RAG 预处理管线6.1 从 Markdown 到高质量分块拿到干净的 Markdown 之后RAG 预处理才刚开始。很多人直接按固定字符长度切块这其实浪费了 MinerU 辛辛苦苦还原出来的结构信息。我的策略是基于 Markdown 结构进行语义分块优先用标题层级、表格边界、列表边界作为切分点。Python 里可以用markdown-it-py先把 Markdown 解析成结构化 token再按层级组装成块。简化的做法是这样from markdown_it import MarkdownIt def split_markdown_by_structure(md_text: str, max_len: int 1200): tokens MarkdownIt().parse(md_text) blocks [] current: list[str] [] current_len 0 for token in tokens: line token.content if token.content else if token.tag in [h1, h2, h3, h4]: if current and current_len 50: blocks.append(\n.join(current)) current [] current_len 0 current.append(f{token.tag if token.tag else }{line}.strip()) current_len len(line) if current_len max_len: blocks.append(\n.join(current)) current [] current_len 0 if current: blocks.append(\n.join(current)) return blocks这个思路的核心在于不要让一句完整的话被硬生生切在两段里也不要让一个表格的列头和数据分到两个 chunk 里。基于结构的切块召回质量比纯字符切块高出一截。6.2 向量化和检索的完整示例切好块之后接向量化。我用的是本地方案embedding 模型用 BGE-M3向量数据库用 Chroma两个都可以在 Windows 本地跑。from sentence_transformers import SentenceTransformer import chromadb from chromadb.utils import embedding_functions # 加载本地 embedding 模型 model SentenceTransformer(BAAI/bge-m3) # 初始化 Chroma client chromadb.PersistentClient(path./chroma_db) collection client.get_or_create_collection( nameknowledge_base, embedding_functionembedding_functions.SentenceTransformerEmbeddingFunction( model_nameBAAI/bge-m3 ), ) def index_markdown(md_text: str, doc_id: str): chunks split_markdown_by_structure(md_text) texts [c for c in chunks if c.strip()] ids [f{doc_id}_{i} for i in range(len(texts))] collection.add(documentstexts, idsids) return len(texts)检索的时候直接查result collection.query(query_texts[2024年营收增长率是多少], n_results5) for i, doc in enumerate(result[documents][0]): print(fTop {i 1}:) print(doc) print(---)整条链路在 Windows 本地完全闭环PDF 进结构化向量出全程没有外部 API 调用。6.3 几个绕不开的实测心得第一MinerU 解析出来的表格不要丢进向量库之前再做一次“扁平化”。直接把 Markdown 表格原文作为 chunk 存储检索时命中率反而更高。因为表格的分隔符和表头结构本身带有语义提示扁平化成纯文本反而丢失了列结构之间的对应关系。第二解析结果里的公式$...$可以直接保留。BGE 这类向量模型对 LaTeX 语法的编码效果还不错检索“损失函数定义”这类问题时保留公式原文的 chunk 往往能召回到正确答案。第三我强烈建议在 RAG 索引阶段把文档元数据来源、页码、原始文件名一起存进向量库。这样检索结果可以追溯到原始 PDF 的具体位置调试知识库的时候会轻松很多。7. 踩坑实录与性能调优7.1 常见问题速查表症状原因解决方案运行时提示模块缺少属性MinerU 和 PyTorch 版本不匹配把 MinerU 升到最新版本并固定 torch 为 cu121 版本GPU 显存不足崩溃大批量并发时模型同时加载调低--workers或者用--batch_size 1强制单页处理扫描件解析出一堆乱码没有正确触发 OCR 模式用-m auto或对扫描 PDF 强制-m ocr模型下载卡住网络访问模型仓库不稳定提前用 ModelScope 下载权重指定本地路径解析结果丢失表格边框表格过于复杂跨页合并开启--table on然后尽量保证输入 PDF 是原始排版版本CPU 模式速度极慢模型全部跑在 CPU 上安装 CUDA 版 PyTorch确认torch.cuda.is_available()为 TrueWindows 杀毒软件误拦截模型目录被实时扫描拖慢把缓存目录加入排除项这里面最坑的是第一个。Windows 上如果之前装过其他深度学习框架PyTorch 版本被改动过MinerU 运行时就会报一些很底层的属性错误。排查办法就是重新创建一个干净的虚拟环境按前面的顺序重新装一遍。7.2 提升吞吐量的思路如果你有一个大几十 GB 的 PDF 文档库单进程解析的吞吐量肯定不够看。我实测过的有效提速方案有两个。思路一是在单机内做多进程并行。MinerU 本身支持--workers参数但 Windows 上受限于进程调度和内存带宽4 个 worker 基本到顶。我的经验值是在--workers 2和--workers 4之间做个平衡配合每个 PDF 文件独立目录输出基本不会互相干扰。思路二是批量文档按类型分流。把扫描版 PDF 和文本型 PDF 分开分别配置不同的参数。文本型 PDF 用-m txt不开 OCR速度能快好几倍扫描型 PDF 再开全量 OCR。这样能让算力花在真正需要它的地方。还有一个容易被忽略的点输出目录的磁盘类型。MinerU 解析过程中会生成大量临时图片和中间文件如果输出目录放在机械硬盘上写入瓶颈会明显拖慢整体速度。我建议把输出目录放在 SSD 上整个流程的吞吐量能提升不少。最后再分享一个小经验别急着在部署完的第一天就跑全部文档。先挑十几份覆盖不同排版的 PDF 试跑对照输出 Markdown 仔细看一遍表格、公式、标题层级这三个方向。确认没问题之后再把这个流程固定成你的标准 RAG 预处理管道。这一关把住了后面的知识库建设就顺了。 
长河君 · 2026/10/6 6:30:53 · 阅读 1.2k Windows本地部署MinerU 4.0：PDF解析与RAG预处理实战
搞知识库和 RAG 相关项目的人迟早会撞上一堵墙PDF 解析。用了各种工具提取文字结果表格变一团乱麻公式全部乱码双栏论文的阅读顺序错得离谱。这些垃圾输入进 RAG 里检索出来的内容根本没法用。我之前也折腾了小半年最后固定在 Windows 上本地部署 MinerU 4.0把 PDF 解析这步彻底做扎实了。这篇文章就围绕 MinerU 4.0 的本地部署完整讲清楚环境准备、模型权重、命令行和 Python SDK 两种用法再带上我把解析结果接进 RAG 预处理管线的实践经验。如果你是做本地知识库、RAG 问答、文档结构化入库这类工作的或者手里有一批 PDF 需要批量转成干净的 Markdown这篇文章可以直接照着抄作业。1. 为什么解析这一步会卡住 RAG 的脖子1.1 PDF 解析不是“把字抽出来”很多人在 RAG 项目里对 PDF 的处理方式还停留在用 PyMuPDF 或者 pdfplumber 把文字层直接抽出来。对纯文本论文这种简单场景确实够用但现实里的文档远比想象中复杂。双栏排版、跨页表格、嵌入式公式、扫描件、页眉页脚、图表混排每一样都能让简单的文本抽取结果彻底崩坏。我见过最典型的问题就是解析出来的表格数据顺序完全错乱。PDF 内部存储的其实是一堆“绘制指令”文字、图形、图片全都在一个流式结构里阅读顺序需要算法自己去推断。MinerU 这类工具之所以强是因为它把版面检测、阅读顺序还原、公式识别、表格重建这几个环节全部串起来了而不是简单地把字符捞出来拼在一起。1.2 解析质量就是 RAG 上限RAG 的质量大体上被三个环节卡着文档解析、切片策略、检索召回。其中文档解析是最容易被忽视的但它决定后续所有环节的上限。原始文本一团糟检索再强也救不回来。举个例子我要把一个年度的行业统计 PDF 做成问答知识库。如果解析出来的表格变成“2023 2024 2025 同比 增长 30 25 20”这样断成散片的文本向量检索根本配不上“2024 年增长率是多少”这种问题。但用 MinerU 把表格还原成真正的 Markdown 表结构文字、列头、行标签都完整保留检索命中率立刻就不一样了。所以我的结论很直接在 RAG 预处理流程里解析这一步值得花时间投入。MinerU 4.0 恰好就是针对这个痛点设计的本地部署之后还能做到文档不出内网数据安全这块也顺带解决了。2. MinerU 4.0 到底是干嘛的2.1 核心能力拆解MinerU 是一个开源的 PDF 文档解析引擎它的核心目标是把 PDF 转成结构完整的 Markdown 或 JSON。4.0 版本在架构上整合了几个关键能力版面检测与阅读顺序还原、公式检测与 LaTeX 转换、表格识别与 Markdown 重建、OCR 文字识别。换句话说输入是一份 PDF 文件输出是保留了层级结构、公式和表格的干净文本。内部工作流大致可以理解为先把每一页做版面分析识别出标题、段落、表格、公式、图片区域再用检测模型区分矢量文本和需要 OCR 的扫描文本最后通过后处理模块恢复阅读顺序并把公式转成 LaTeX把表格重建成 Markdown 语法。2.2 和“装个库跑 pip”的区别网上有很多号称能解析 PDF 的库但实测下来分水岭很清晰。普通 PDF 文本提取库只能处理“有文字层”的 PDF遇到扫描件直接抓瞎。商业云服务效果好但文档要上传到别人服务器知识库场景里很多客户根本接受不了。MinerU 本地跑的好处在于三点一是文档不出内网敏感资料放心处理二是一次部署终身免费批量解析也不心疼成本三是解析结果完全在自己手里Markdown 输出可以随意二次加工和接入下游。这三点恰好是 RAG 项目最看重的。我自己的使用感受是MinerU 对中文文档的支持格外友好中英混排、中文表格、中文公式场景的表现甚至比一些我尝试过的商业 API 还要稳。本地部署之后性能和速度都能自己控制。3. Windows 环境准备与依赖安装3.1 硬件底线与推荐配置先把硬件说清楚免得后面踩坑。MinerU 模型链路包含版面检测、公式识别、OCR 等多个模型推理时对内存有一定要求。我的建议配置如下使用场景CPU内存GPU硬盘最低可用小文件4 核 i3 以上8 GB无10 GB 可用空间推荐日常 RAG6 核 i5 以上16 GB8 GB 显存如 RTX 306020 GB 可用空间大批量处理8 核以上32 GB12 GB 显存以上50 GB 可用空间没有 N 卡也能跑纯 CPU 模式完全可以工作就是速度会慢不少。我实测一份 20 页的中文双栏论文在 i5-12400 纯 CPU 下解析耗时大概 2 到 4 分钟同样的活交给 RTX 3060 只要 30 到 60 秒。如果你的知识库文档量很大一张甜品级显卡能帮你省下大量时间。3.2 安装 Python 和创建干净环境MinerU 4.0 依赖 PyTorchPython 版本建议 3.10 到 3.12太老的版本容易在依赖上打架。我用的环境是 Windows 11 Python 3.11.9。第一步创建独立的虚拟环境。这步千万别省因为 MinerU 的依赖链很长直接装到系统 Python 里以后很容易和别的项目互相污染。在命令行里执行python -m venv mineru-env然后激活环境mineru-env\Scripts\activate紧接着安装 MinerU。这里有个小细节如果你用 GPU建议先装好 GPU 版的 PyTorch再装 MinerU避免 MinerU 依赖的 PyTorch 自动装成 CPU 版。我的安装顺序是这样pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121 pip install -U mineru最后再确认一下安装了哪些版本防止后续报一些莫名其妙的属性错误pip show mineru torch torchvision注意Windows 上如果 pip 安装过程中提示显卡驱动版本太低先更新 NVIDIA 驱动再做一次 pip install 即可。驱动版本和 CUDA 版本不匹配是 Windows 上最常见的安装失败原因。3.3 模型权重下载与目录管理MinerU 解析 PDF 是靠多个预训练模型协同工作这些模型权重不会包含在 pip 包内部。首次运行解析命令时MinerU 会自动从模型仓库拉取权重默认的位置在用户目录的缓存文件夹下一般是C:\Users\你的用户名\.cache\huggingface\hub但这里有坑。国内网络环境下Hugging Face 的自动下载经常走到一半就断。我的做法是提前手动把模型权重下载到本地再指定给 MinerU 使用。飞书文档里官方也给过模型下载指引基本思路是去 ModelScope 或 Hugging Face 找到对应的 MinerU 模型仓库用下载工具整体拉下来然后放到指定目录。我用 ModelScope 下载的命令大致是这样pip install modelscope modelscope download --model opendatalab/PDF-MinerU-4.0 --local_dir C:\\models\\mineru-models下载完成后在解析命令里显式指定模型路径或者把模型目录放进环境变量MINERU_MODEL_DIR里。这样 MinerU 就无法访问网络也能正常跑彻底实现离线解析。4. 命令行快速跑通4.1 单文件解析安装完成、模型就位之后最快验证效果的方式是用命令行跑一个单文件。MinerU 4.0 的 CLI 入口非常简单我平时最常用的命令是这个mineru -p ./docs/年报.pdf -o ./output -m auto这几个参数的含义拆开说-p输入的 PDF 文件或文件夹路径。-o输出目录MinerU 会在里面自动创建以 PDF 文件名命名的子目录。-m解析模式可选auto、ocr、txt。auto是自动判断带文字层就直接抽取检测到扫描页就切到 OCRtxt表示只处理纯文本型 PDFocr表示强制全部走 OCR 流程。跑完之后输出目录下会有一个*.md文件、一个存放图片的文件夹以及 JSON 格式的中间结果文件。这些产物都是 RAG 预处理可以直接用的。4.2 批量文件夹解析与关键参数单文件验证没问题之后接下来就是批量。MinerU 的 CLI 原生支持文件夹输入直接把-p指向一个包含大量 PDF 的目录就行mineru -p ./docs -o ./output -m auto --formula on --table on --workers 2参数说明--formula on开启公式识别扫描件和公式密集的文档建议开启。--table on开启表格重建会把表格还原成规范的 Markdown 表格语法。--workers 2并发解析的进程数。Windows 上不要开太大我实测 4 个 worker 时内存容易被占满反而比 2 个 worker 慢。批量处理时会遇到一个问题文件夹里混着各种类型的 PDF有的有文字层有的纯扫描。-m auto就是想对付这种情况的MinerU 会一页一页判断哪种方式合适就上哪种。我的经验是批量任务先挑一小批试跑确认输出目录结构和效果没问题再全量开跑。这样能避免跑完才发现参数不合适再重新返工。4.3 输出产物长什么样这是我最想让大家看清楚的部分。一份包含表格和公式的 PDF 解析出来后Markdown 产物大致是这样的## 3. 实验结果 表 1 列出了不同模型在测试集上的表现。 | 模型 | 准确率 | 召回率 | F1 | | --- | --- | --- | --- | | Base | 87.2 | 83.5 | 85.3 | | Proposed | 91.6 | 89.4 | 90.5 | 模型的优化目标可以表示为 $$ Loss -\sum_{t1}^{T} \log P(y_t | y_{t}, x) $$注意几个细节表格有完整的表头分隔线列和行都没有丢公式被转成了 LaTeX 格式标题层级保持住了。这种输出质量直接决定了后面做向量切块时候的语义完整性。5. 在 Python 里把 MinerU 当 SDK 用5.1 异步 API 的基本用法命令行适合快速验证和跑批但如果你要把 MinerU 集成到自己的知识库构建脚本里就要用 SDK 方式。MinerU 4.0 提供了异步 API简单到有点不像一个“重型解析引擎”该有的样子。import asyncio from mineru import MinerU async def parse_single_pdf(pdf_path: str, output_dir: str): data await MinerU.process( pdf_pathpdf_path, enable_formulaTrue, enable_tableTrue, exclude_bannerTrue, # 去掉页眉页脚 ) md_content data.md_content with open(f{output_dir}/output.md, w, encodingutf-8) as f: f.write(md_content) print(data)data对象里包含了解析产生的 Markdown 内容、JSON 结构和图片信息。整个过程你不需要关心模型加载、版面检测、OCR 调度的细节SDK 把这些全部封装好了。5.2 封装一个可复用的解析函数实际项目里我会把这个 API 再包一层加上失败重试和日志记录方便大规模跑文档库import asyncio import logging from pathlib import Path from mineru import MinerU logging.basicConfig(levellogging.INFO) async def parse_pdf_to_markdown(pdf_path: str, output_dir: str) - Path | None: pdf_name Path(pdf_path).stem target_dir Path(output_dir) / pdf_name target_dir.mkdir(parentsTrue, exist_okTrue) md_path target_dir / f{pdf_name}.md if md_path.exists(): logging.info(f跳过已处理文件: {pdf_name}) return md_path try: data await MinerU.process( pdf_pathpdf_path, enable_formulaTrue, enable_tableTrue, exclude_bannerTrue, ) md_path.write_text(data.md_content, encodingutf-8) logging.info(f解析完成: {pdf_name}) return md_path except Exception as e: logging.error(f解析失败 {pdf_name}: {e}) return None这里面做了一个“已处理文件跳过”的判断。这个习惯帮我省了不知道多少重复工时跑大批量文档的时候中途断了重新跑只有没完成的文件会再次执行。提示Windows 的路径里如果包含中文或空格尽量在调用前用pathlib.Path规范化一下。某些依赖库在后端处理路径时对特殊字符不感冒容易踩到莫名奇妙的编码错误。6. 把解析结果接入 RAG 预处理管线6.1 从 Markdown 到高质量分块拿到干净的 Markdown 之后RAG 预处理才刚开始。很多人直接按固定字符长度切块这其实浪费了 MinerU 辛辛苦苦还原出来的结构信息。我的策略是基于 Markdown 结构进行语义分块优先用标题层级、表格边界、列表边界作为切分点。Python 里可以用markdown-it-py先把 Markdown 解析成结构化 token再按层级组装成块。简化的做法是这样from markdown_it import MarkdownIt def split_markdown_by_structure(md_text: str, max_len: int 1200): tokens MarkdownIt().parse(md_text) blocks [] current: list[str] [] current_len 0 for token in tokens: line token.content if token.content else if token.tag in [h1, h2, h3, h4]: if current and current_len 50: blocks.append(\n.join(current)) current [] current_len 0 current.append(f{token.tag if token.tag else }{line}.strip()) current_len len(line) if current_len max_len: blocks.append(\n.join(current)) current [] current_len 0 if current: blocks.append(\n.join(current)) return blocks这个思路的核心在于不要让一句完整的话被硬生生切在两段里也不要让一个表格的列头和数据分到两个 chunk 里。基于结构的切块召回质量比纯字符切块高出一截。6.2 向量化和检索的完整示例切好块之后接向量化。我用的是本地方案embedding 模型用 BGE-M3向量数据库用 Chroma两个都可以在 Windows 本地跑。from sentence_transformers import SentenceTransformer import chromadb from chromadb.utils import embedding_functions # 加载本地 embedding 模型 model SentenceTransformer(BAAI/bge-m3) # 初始化 Chroma client chromadb.PersistentClient(path./chroma_db) collection client.get_or_create_collection( nameknowledge_base, embedding_functionembedding_functions.SentenceTransformerEmbeddingFunction( model_nameBAAI/bge-m3 ), ) def index_markdown(md_text: str, doc_id: str): chunks split_markdown_by_structure(md_text) texts [c for c in chunks if c.strip()] ids [f{doc_id}_{i} for i in range(len(texts))] collection.add(documentstexts, idsids) return len(texts)检索的时候直接查result collection.query(query_texts[2024年营收增长率是多少], n_results5) for i, doc in enumerate(result[documents][0]): print(fTop {i 1}:) print(doc) print(---)整条链路在 Windows 本地完全闭环PDF 进结构化向量出全程没有外部 API 调用。6.3 几个绕不开的实测心得第一MinerU 解析出来的表格不要丢进向量库之前再做一次“扁平化”。直接把 Markdown 表格原文作为 chunk 存储检索时命中率反而更高。因为表格的分隔符和表头结构本身带有语义提示扁平化成纯文本反而丢失了列结构之间的对应关系。第二解析结果里的公式$...$可以直接保留。BGE 这类向量模型对 LaTeX 语法的编码效果还不错检索“损失函数定义”这类问题时保留公式原文的 chunk 往往能召回到正确答案。第三我强烈建议在 RAG 索引阶段把文档元数据来源、页码、原始文件名一起存进向量库。这样检索结果可以追溯到原始 PDF 的具体位置调试知识库的时候会轻松很多。7. 踩坑实录与性能调优7.1 常见问题速查表症状原因解决方案运行时提示模块缺少属性MinerU 和 PyTorch 版本不匹配把 MinerU 升到最新版本并固定 torch 为 cu121 版本GPU 显存不足崩溃大批量并发时模型同时加载调低--workers或者用--batch_size 1强制单页处理扫描件解析出一堆乱码没有正确触发 OCR 模式用-m auto或对扫描 PDF 强制-m ocr模型下载卡住网络访问模型仓库不稳定提前用 ModelScope 下载权重指定本地路径解析结果丢失表格边框表格过于复杂跨页合并开启--table on然后尽量保证输入 PDF 是原始排版版本CPU 模式速度极慢模型全部跑在 CPU 上安装 CUDA 版 PyTorch确认torch.cuda.is_available()为 TrueWindows 杀毒软件误拦截模型目录被实时扫描拖慢把缓存目录加入排除项这里面最坑的是第一个。Windows 上如果之前装过其他深度学习框架PyTorch 版本被改动过MinerU 运行时就会报一些很底层的属性错误。排查办法就是重新创建一个干净的虚拟环境按前面的顺序重新装一遍。7.2 提升吞吐量的思路如果你有一个大几十 GB 的 PDF 文档库单进程解析的吞吐量肯定不够看。我实测过的有效提速方案有两个。思路一是在单机内做多进程并行。MinerU 本身支持--workers参数但 Windows 上受限于进程调度和内存带宽4 个 worker 基本到顶。我的经验值是在--workers 2和--workers 4之间做个平衡配合每个 PDF 文件独立目录输出基本不会互相干扰。思路二是批量文档按类型分流。把扫描版 PDF 和文本型 PDF 分开分别配置不同的参数。文本型 PDF 用-m txt不开 OCR速度能快好几倍扫描型 PDF 再开全量 OCR。这样能让算力花在真正需要它的地方。还有一个容易被忽略的点输出目录的磁盘类型。MinerU 解析过程中会生成大量临时图片和中间文件如果输出目录放在机械硬盘上写入瓶颈会明显拖慢整体速度。我建议把输出目录放在 SSD 上整个流程的吞吐量能提升不少。最后再分享一个小经验别急着在部署完的第一天就跑全部文档。先挑十几份覆盖不同排版的 PDF 试跑对照输出 Markdown 仔细看一遍表格、公式、标题层级这三个方向。确认没问题之后再把这个流程固定成你的标准 RAG 预处理管道。这一关把住了后面的知识库建设就顺了。