title: MinerU 新手完整配置教程Windows 下将 PDF 转为带图片的 Markdown作者: 肖恭伟tags:MinerUPDFMarkdownOCRWindows文献阅读MinerU 新手完整配置教程Windows 下将 PDF 转为带图片的 Markdown本文记录一次完整的 MinerU 配置、运行、排错和复盘过程面向第一次接触命令行工具的 Windows 用户。目标是把论文 PDF 转换为可在 Cursor、VS Code、Typora 或 Obsidian 中阅读的 Markdown并保留公式、表格和图片资源。一、先看正确步骤新手建议严格按下面的顺序操作安装 64 位 Python 3.103.13并确认python和pip可用。建立一个不含空格的工作目录例如D:\MinerU。创建并激活 Python 虚拟环境。安装 MinerU并确认版本。下载模型文件。准备输入 PDF首次测试尽量使用英文或简单中文 PDF。使用明确的后端和输出目录运行转换。检查输出目录中的 Markdown、images图片目录和 JSON 文件。用支持 Markdown 预览的编辑器打开 Markdown而不是直接双击纯文本文件。若图片缺失先检查相对路径和输出目录再判断是否需要重新转换。整个流程可以概括为安装 Python → 创建虚拟环境 → 安装 MinerU → 下载模型 → 转换 PDF → 检查 images → Markdown 预览二、MinerU 是什么MinerU 是一个文档解析工具可以将 PDF、图片、Word、PPT 和 Excel 等文件转换为结构化结果。对科研论文而言它通常可以输出Markdown 文本公式HTML 表格从 PDF 中提取的图片中间 JSON 或内容列表带版面识别信息的 PDF。需要注意Markdown 文件只是文本文件图片并不一定嵌入其中。Markdown 中的图片通常通过相对路径引用因此图片文件必须和 Markdown 一起保留。三、准备 Windows 环境3.1 安装 Python建议使用 64 位 Python 3.10、3.11、3.12 或 3.13。当前 MinerU 3.4.4 的 Python 要求为3.10,3.14。安装 Python 时建议勾选Add Python.exe to PATHpipvenv。安装完成后在 PowerShell 中执行python--version pip--version如果系统中有多个 Python也可以使用py--version py-0p3.2 建立工作目录建议把程序、输入文件和输出文件分开D:\MinerU\ ├─ .venv-mineru\ 虚拟环境 ├─ input\ 待转换 PDF └─ output\ 转换结果在 PowerShell 中执行New-Item-ItemType Directory-Force-PathD:\MinerU\input,D:\MinerU\output|Out-NullSet-LocationD:\MinerU路径包含中文或空格时必须使用引号。例如Set-LocationD:\我的论文\MinerU四、创建并激活虚拟环境在D:\MinerU目录中执行python-m venv.venv-mineru.\.venv-mineru\Scripts\Activate.ps1激活成功后命令行前面通常会出现(.venv-mineru)如果 PowerShell 提示禁止执行脚本可以只为当前用户放开本地脚本权限Set-ExecutionPolicy-Scope CurrentUser RemoteSigned然后重新激活.\.venv-mineru\Scripts\Activate.ps1验证当前 Python 是否来自虚拟环境python-cimport sys; print(sys.executable)输出路径应指向D:\MinerU\.venv-mineru\Scripts\python.exe五、安装 MinerU先升级基础安装工具python-m pip install--upgrade pip setuptools wheel安装 MinerUpython-m pip install-U mineru确认版本python-cimport importlib.metadata as m; print(m.version(mineru))也可以确认命令行入口是否存在python-m mineru.cli.client--help本文实际核验的版本是MinerU 3.4.4 Python 3.10.0六、下载模型文件MinerU 的部分后端需要本地模型。推荐使用模型下载命令python-m mineru.cli.models_download--help下载通用 Pipeline 模型python-m mineru.cli.models_download-s modelscope-m pipeline如果网络可以访问 Hugging Face也可以使用python-m mineru.cli.models_download-s huggingface-m pipeline如果计划使用 VLM 或混合高精度后端可以下载全部模型python-m mineru.cli.models_download-s modelscope-m all模型下载可能耗时较长且需要较大的磁盘空间。下载过程中不要关闭 PowerShell。首次运行前建议确认模型缓存已经生成。七、准备待转换 PDF将 PDF 放入输入目录。例如D:\MinerU\input\论文.pdf检查文件是否存在Test-Path-LiteralPathD:\MinerU\input\论文.pdfGet-Item-LiteralPathD:\MinerU\input\论文.pdf|Select-ObjectFullName,Length文件名包含中文时没有问题但在 PowerShell 中建议始终使用-LiteralPath和引号避免特殊字符被解释。八、执行 PDF 转 Markdown8.1 推荐的 Pipeline 后端Pipeline 后端适合先完成稳定的 PDF 文本、公式、表格和图片解析python-m mineru.cli.client -pD:\MinerU\input\论文.pdf-oD:\MinerU\output-b pipeline -m auto -l ch -f true -t truePowerShell 使用反引号换行。如果担心复制时丢失反引号也可以写成一行python-m mineru.cli.client-pD:\MinerU\input\论文.pdf-oD:\MinerU\output-b pipeline-m auto-l ch-f true-t true参数含义参数含义-p输入文件或目录-o输出目录-b pipeline使用 Pipeline 后端-m auto自动判断 PDF 使用文本解析还是 OCR-l ch中文文档-f true开启公式解析-t true开启表格解析8.2 高精度混合后端MinerU 3.4.4 还提供hybrid-engine。它更适合需要更高图表理解能力的场景但本地计算资源和模型要求更高python-m mineru.cli.client -pD:\MinerU\input\论文.pdf-oD:\MinerU\output-b hybrid-engine --effort high -l ch -f true -t true --image-analysis true--effort medium速度更快但混合后端在 medium 模式下可能关闭图像或图表分析需要图表分析时使用--effort high但耗时会增加。8.3 只转换指定页排查问题时不要一开始就转换几十页。可以先测试前 2 页python-m mineru.cli.client -pD:\MinerU\input\论文.pdf-oD:\MinerU\output-test-b pipeline -m auto -l ch -s 0 -e 1注意-s和-e使用从0开始的页码。九、检查输出结果转换结束后先不要急着打开 Markdown。先检查输出目录Get-ChildItem-LiteralPathD:\MinerU\output-Recurse-File|Select-ObjectFullName,Length,LastWriteTime正常情况下应当重点寻找*.md images\ *.json *_layout.pdf典型结构类似D:\MinerU\output\论文\ ├─ auto\ │ ├─ 论文.md │ ├─ images\ │ │ ├─ image-1.jpg │ │ └─ image-2.jpg │ ├─ *.json │ └─ *_layout.pdf检查图片数量$mdGet-ChildItem-LiteralPathD:\MinerU\output-Recurse-Filter*.md|Select-Object-First 1$md.FullName$imagesJoin-Path$md.DirectoryNameimagesWrite-Output(images exists: (Test-Path-LiteralPath$images))if(Test-Path-LiteralPath$images){(Get-ChildItem-LiteralPath$images-File).Count}检查 Markdown 中的图片引用Select-String-LiteralPath$md.FullName-Pattern!\[.*\]\(逐个验证图片引用是否存在$mdTextGet-Content-LiteralPath$md.FullName-Raw-Encoding UTF8[regex]::Matches($mdText,!\[[^]]*\]\(([^)])\))|ForEach-Object{$relative$_.Groups[1].Value$absoluteJoin-Path$md.DirectoryName$relative[pscustomobject]{Reference $relativeExists Test-Path-LiteralPath$absolutePath $absolute}}如果Exists为False说明 Markdown 里的图片引用失效不能仅靠更换阅读器解决。十、正确打开带图片的 Markdown10.1 Cursor 或 VS Code用 Cursor 或 VS Code 打开 Markdown 文件。按CtrlShiftV打开 Markdown 预览。或按CtrlK松开后再按V在右侧打开预览。Markdown 文件和images文件夹必须保持原有相对位置。10.2 Typora直接用 Typora 打开.md文件即可。图片文件夹不能移动或删除。10.3 Obsidian将 Markdown 文件和images文件夹放在同一个 Vault 内并保持 Markdown 中的相对路径有效。若图片是 Markdown 标准路径Obsidian 通常可以直接预览。10.4 浏览器浏览器直接打开 Markdown 文件通常只会显示源文本不会自动按 Markdown 渲染。应使用支持 Markdown 的编辑器或先通过 Markdown 插件/静态站点生成 HTML。十一、为什么图片有时显示不出来Markdown 中常见的图片引用是这表示图片位于当前 Markdown 文件所在目录下的images子目录中。下面的文件结构才是正确的论文.md images\ └─ 06b7e3b5753ec39beb4b89ccf8d6a1cbc2174adb8c9389bed6dc29dd7a843127.jpg以下情况都会导致图片不显示只有.md文件没有images文件夹图片文件名被修改Markdown 被移动到其他目录但images没有一起移动相对路径层级不正确图片实际生成在另一个输出目录使用了浏览器或纯文本编辑器而不是 Markdown 预览PDF 本身是扫描图片使用了不合适的解析模式转换过程没有正常结束。十二、图片缺失时的处理方法方法一重新确认输出目录Get-ChildItem-LiteralPathD:\MinerU\output-Recurse-Directory|Where-ObjectName-eqimages如果能找到images把整个结果目录一起移动不要只移动 Markdown。方法二重新转换并保留完整结果建议删除或改名旧的测试输出目录然后重新执行转换$inputD:\MinerU\input\论文.pdf$outputD:\MinerU\output\论文-newpython-m mineru.cli.client-p$input-o$output-b pipeline-m auto-l ch-f true-t true不要直接覆盖多个版本的输出否则容易把 Markdown 和图片目录混在一起。方法三使用版面 PDF 辅助检查如果输出中有*_layout.pdf可以打开它检查 MinerU 对页面、文本块、表格和图片的识别结果。版面 PDF 主要用于核验版面不等于 Markdown 图片资源本身。十三、常见问题13.1python不是命令重新安装 Python 并勾选 PATH或者使用 Python 安装器中的完整路径。也可以尝试py-3.10--version13.2 PowerShell 禁止运行激活脚本执行Set-ExecutionPolicy-Scope CurrentUser RemoteSigned然后重新激活虚拟环境。13.3 命令执行很久没有结束首次运行可能需要加载模型。先确认是否正在下载模型磁盘空间是否充足内存是否足够输入 PDF 是否过大是否误用了需要更高算力的hybrid-engine。新手排查时优先使用pipeline并用-s 0 -e 1只转换两页。13.4 PDF 是扫描件文字识别不完整使用 OCR 模式python-m mineru.cli.client-pD:\MinerU\input\扫描论文.pdf-oD:\MinerU\output\扫描论文-b pipeline-m ocr-l ch扫描件的公式、表格和图片识别效果取决于原始分辨率和版面复杂度转换后必须人工核对。13.5 公式或表格不准确可以尝试开启公式和表格解析-f true-t true但任何 OCR 或版面解析工具都不能保证科研论文公式 100% 正确。重要公式应回看原始 PDF。13.6 需要读取图表内容怎么办首先确认图片文件真实存在。若 Markdown 只有图片链接而没有图片资源不能依据 Markdown 文件本身读取图像内容。此时应找到原始 PDF打开对应页或从 PDF 渲染页面结合图注、正文上下文和图像本身进行总结不要把 OCR 提取的图注当成图像识别结果。十四、适合批量转换的 PowerShell 模板下面的模板可批量处理输入目录中的 PDF$pythonD:\MinerU\.venv-mineru\Scripts\python.exe$inputDirD:\MinerU\input$outputDirD:\MinerU\outputGet-ChildItem-LiteralPath$inputDir-Filter*.pdf-File|ForEach-Object{$pdf$_.FullNameWrite-Host正在转换$pdf$python-m mineru.cli.client -p$pdf-o$outputDir-b pipeline -m auto -l ch -f true -t true}批量处理时每次转换后都应检查输出目录尤其是 Markdown 和images是否一一对应。十五、推荐的科研文献工作流原始 PDF ↓ MinerU 转换 ↓ 检查 Markdown、公式、表格和 images ↓ 用 Obsidian/Cursor/Typora 阅读 ↓ 回看原始 PDF 核验关键公式和图表 ↓ 提炼摘要、方法、数据、结论和可复现实验信息对于论文图表建议同时保留原始 PDFMinerU Markdownimages图片目录JSON 或中间结果人工修订后的笔记。这样可以在 Markdown 解析不完整时回溯原始材料。十六、本次配置的实际环境记录本次环境中曾经使用过以下路径旧工作区D:\AIAgent\findMySelf 当前 MinerU 环境D:\AIAgent_obsidian\04-自动化系统\MinerU 虚拟环境D:\AIAgent_obsidian\04-自动化系统\MinerU\.venv-mineru 输入示例D:\MinerUInput 输出示例D:\MinerUOut 结果示例D:\MinerUResult由于 Windows 系统中的目录可能被迁移、重命名或同步教程中的路径只是示例。重新配置时应先用Test-Path验证路径再执行命令。十七、经验与教训17.1 正确认识 Markdown 与图片的关系Markdown 通常只保存图片链接不保存图片本体。看到并不代表example.jpg一定存在。必须同时确认Markdown 文件所在目录\images\example.jpg这也是本次打开论文 Markdown 时图片不显示的直接原因文档中的图片引用存在但对应的images资源目录没有出现在实际输出目录中。17.2 输出目录必须整体保留不要只复制.md文件。应复制整个论文结果目录。最少要一起保留 Markdown 和images需要后续排错时还应保留 JSON、版面 PDF 和原始 PDF。17.3 PDF 文本可读不代表图片可读MinerU 的 Markdown 可能成功提取正文和图注但图片资源可能缺失。读取文本、读取图像、理解图表是三个不同层次的问题不能用正文 OCR 结果替代图像读取。17.4 不能把 PDF 纯文本抽取当作页面渲染PDF 文本抽取适合查找图注和正文不适合观察曲线、坐标轴、图例和版面。需要总结图表时必须读取真实图片或把 PDF 对应页面渲染成图像后再分析。17.5 先查工具再写命令本次过程中曾尝试使用pdftoppm和fitz但当前 Windows 环境没有pdftoppm虚拟环境中也没有fitz。因此命令不能凭经验假设存在。排错时应先执行Get-Commandpdftoppm,magick,mutool,gswin64c-ErrorAction SilentlyContinue python-cimport importlib.util as u; print(bool(u.find_spec(fitz)))如果工具不存在应改用已安装的工具或明确安装依赖而不是继续重复失败命令。17.6 优先使用当前版本的真实帮助信息MinerU 不同版本的命令参数可能不同。应先执行python-m mineru.cli.client--help python-m mineru.cli.models_download--help再复制参数。本文命令依据 MinerU3.4.4的实际帮助信息整理。17.7 Windows 路径必须谨慎处理中文路径、空格、括号和特殊字符都可能导致命令解析问题。PowerShell 中优先使用-LiteralPath完整路径命令参数中的路径统一使用单引号。脚本中则使用变量保存路径减少重复输入和拼写错误。17.8 先做小样本测试不要一开始处理整本书或数百页论文。先转换前 12 页确认模型、后端、公式、表格和图片都正常再进行完整转换。这样可以快速区分“环境问题”和“文档本身的问题”。17.9 先使用稳定后端再追求高精度pipeline更适合作为入门和批量处理的起点。hybrid-engine的图表分析能力更强但需要更多模型和计算资源。新手遇到卡顿或失败时应先回到pipeline验证基本链路。17.10 解析结果必须人工核验对于科研论文以下内容都不应盲信OCR 识别出的数字和单位公式中的上下标表格中的列关系图注和图内文字页眉页脚和参考文献编号。MinerU 负责提高整理效率不能替代对原始论文的最终核验。十八、结语MinerU 的完整使用链路并不只是“安装一个 Python 包然后打开 Markdown”。真正可靠的流程是先确认 Python 和 MinerU 版本再下载模型使用稳定后端完成小样本测试最后检查 Markdown 与图片资源是否匹配。对于论文阅读最重要的判断标准不是“转换命令是否退出”而是正文、公式、表格、图片和相对路径是否都能在目标阅读器中正确呈现。发布前检查清单代码块中的路径已替换为自己的实际路径已说明 Python、MinerU 和操作系统版本已给出安装、模型下载和转换命令已解释images目录与 Markdown 的相对路径关系已给出常见报错和排查办法已提醒读者核验公式、表格和图表CSDN 发布时已删除个人隐私和不必要的本机路径 MinerU 新手完整配置教程：Windows 下将 PDF 转为带图片的 Markdown
title: MinerU 新手完整配置教程Windows 下将 PDF 转为带图片的 Markdown作者: 肖恭伟tags:MinerUPDFMarkdownOCRWindows文献阅读MinerU 新手完整配置教程Windows 下将 PDF 转为带图片的 Markdown本文记录一次完整的 MinerU 配置、运行、排错和复盘过程面向第一次接触命令行工具的 Windows 用户。目标是把论文 PDF 转换为可在 Cursor、VS Code、Typora 或 Obsidian 中阅读的 Markdown并保留公式、表格和图片资源。一、先看正确步骤新手建议严格按下面的顺序操作安装 64 位 Python 3.103.13并确认python和pip可用。建立一个不含空格的工作目录例如D:\MinerU。创建并激活 Python 虚拟环境。安装 MinerU并确认版本。下载模型文件。准备输入 PDF首次测试尽量使用英文或简单中文 PDF。使用明确的后端和输出目录运行转换。检查输出目录中的 Markdown、images图片目录和 JSON 文件。用支持 Markdown 预览的编辑器打开 Markdown而不是直接双击纯文本文件。若图片缺失先检查相对路径和输出目录再判断是否需要重新转换。整个流程可以概括为安装 Python → 创建虚拟环境 → 安装 MinerU → 下载模型 → 转换 PDF → 检查 images → Markdown 预览二、MinerU 是什么MinerU 是一个文档解析工具可以将 PDF、图片、Word、PPT 和 Excel 等文件转换为结构化结果。对科研论文而言它通常可以输出Markdown 文本公式HTML 表格从 PDF 中提取的图片中间 JSON 或内容列表带版面识别信息的 PDF。需要注意Markdown 文件只是文本文件图片并不一定嵌入其中。Markdown 中的图片通常通过相对路径引用因此图片文件必须和 Markdown 一起保留。三、准备 Windows 环境3.1 安装 Python建议使用 64 位 Python 3.10、3.11、3.12 或 3.13。当前 MinerU 3.4.4 的 Python 要求为3.10,3.14。安装 Python 时建议勾选Add Python.exe to PATHpipvenv。安装完成后在 PowerShell 中执行python--version pip--version如果系统中有多个 Python也可以使用py--version py-0p3.2 建立工作目录建议把程序、输入文件和输出文件分开D:\MinerU\ ├─ .venv-mineru\ 虚拟环境 ├─ input\ 待转换 PDF └─ output\ 转换结果在 PowerShell 中执行New-Item-ItemType Directory-Force-PathD:\MinerU\input,D:\MinerU\output|Out-NullSet-LocationD:\MinerU路径包含中文或空格时必须使用引号。例如Set-LocationD:\我的论文\MinerU四、创建并激活虚拟环境在D:\MinerU目录中执行python-m venv.venv-mineru.\.venv-mineru\Scripts\Activate.ps1激活成功后命令行前面通常会出现(.venv-mineru)如果 PowerShell 提示禁止执行脚本可以只为当前用户放开本地脚本权限Set-ExecutionPolicy-Scope CurrentUser RemoteSigned然后重新激活.\.venv-mineru\Scripts\Activate.ps1验证当前 Python 是否来自虚拟环境python-cimport sys; print(sys.executable)输出路径应指向D:\MinerU\.venv-mineru\Scripts\python.exe五、安装 MinerU先升级基础安装工具python-m pip install--upgrade pip setuptools wheel安装 MinerUpython-m pip install-U mineru确认版本python-cimport importlib.metadata as m; print(m.version(mineru))也可以确认命令行入口是否存在python-m mineru.cli.client--help本文实际核验的版本是MinerU 3.4.4 Python 3.10.0六、下载模型文件MinerU 的部分后端需要本地模型。推荐使用模型下载命令python-m mineru.cli.models_download--help下载通用 Pipeline 模型python-m mineru.cli.models_download-s modelscope-m pipeline如果网络可以访问 Hugging Face也可以使用python-m mineru.cli.models_download-s huggingface-m pipeline如果计划使用 VLM 或混合高精度后端可以下载全部模型python-m mineru.cli.models_download-s modelscope-m all模型下载可能耗时较长且需要较大的磁盘空间。下载过程中不要关闭 PowerShell。首次运行前建议确认模型缓存已经生成。七、准备待转换 PDF将 PDF 放入输入目录。例如D:\MinerU\input\论文.pdf检查文件是否存在Test-Path-LiteralPathD:\MinerU\input\论文.pdfGet-Item-LiteralPathD:\MinerU\input\论文.pdf|Select-ObjectFullName,Length文件名包含中文时没有问题但在 PowerShell 中建议始终使用-LiteralPath和引号避免特殊字符被解释。八、执行 PDF 转 Markdown8.1 推荐的 Pipeline 后端Pipeline 后端适合先完成稳定的 PDF 文本、公式、表格和图片解析python-m mineru.cli.client -pD:\MinerU\input\论文.pdf-oD:\MinerU\output-b pipeline -m auto -l ch -f true -t truePowerShell 使用反引号换行。如果担心复制时丢失反引号也可以写成一行python-m mineru.cli.client-pD:\MinerU\input\论文.pdf-oD:\MinerU\output-b pipeline-m auto-l ch-f true-t true参数含义参数含义-p输入文件或目录-o输出目录-b pipeline使用 Pipeline 后端-m auto自动判断 PDF 使用文本解析还是 OCR-l ch中文文档-f true开启公式解析-t true开启表格解析8.2 高精度混合后端MinerU 3.4.4 还提供hybrid-engine。它更适合需要更高图表理解能力的场景但本地计算资源和模型要求更高python-m mineru.cli.client -pD:\MinerU\input\论文.pdf-oD:\MinerU\output-b hybrid-engine --effort high -l ch -f true -t true --image-analysis true--effort medium速度更快但混合后端在 medium 模式下可能关闭图像或图表分析需要图表分析时使用--effort high但耗时会增加。8.3 只转换指定页排查问题时不要一开始就转换几十页。可以先测试前 2 页python-m mineru.cli.client -pD:\MinerU\input\论文.pdf-oD:\MinerU\output-test-b pipeline -m auto -l ch -s 0 -e 1注意-s和-e使用从0开始的页码。九、检查输出结果转换结束后先不要急着打开 Markdown。先检查输出目录Get-ChildItem-LiteralPathD:\MinerU\output-Recurse-File|Select-ObjectFullName,Length,LastWriteTime正常情况下应当重点寻找*.md images\ *.json *_layout.pdf典型结构类似D:\MinerU\output\论文\ ├─ auto\ │ ├─ 论文.md │ ├─ images\ │ │ ├─ image-1.jpg │ │ └─ image-2.jpg │ ├─ *.json │ └─ *_layout.pdf检查图片数量$mdGet-ChildItem-LiteralPathD:\MinerU\output-Recurse-Filter*.md|Select-Object-First 1$md.FullName$imagesJoin-Path$md.DirectoryNameimagesWrite-Output(images exists: (Test-Path-LiteralPath$images))if(Test-Path-LiteralPath$images){(Get-ChildItem-LiteralPath$images-File).Count}检查 Markdown 中的图片引用Select-String-LiteralPath$md.FullName-Pattern!\[.*\]\(逐个验证图片引用是否存在$mdTextGet-Content-LiteralPath$md.FullName-Raw-Encoding UTF8[regex]::Matches($mdText,!\[[^]]*\]\(([^)])\))|ForEach-Object{$relative$_.Groups[1].Value$absoluteJoin-Path$md.DirectoryName$relative[pscustomobject]{Reference $relativeExists Test-Path-LiteralPath$absolutePath $absolute}}如果Exists为False说明 Markdown 里的图片引用失效不能仅靠更换阅读器解决。十、正确打开带图片的 Markdown10.1 Cursor 或 VS Code用 Cursor 或 VS Code 打开 Markdown 文件。按CtrlShiftV打开 Markdown 预览。或按CtrlK松开后再按V在右侧打开预览。Markdown 文件和images文件夹必须保持原有相对位置。10.2 Typora直接用 Typora 打开.md文件即可。图片文件夹不能移动或删除。10.3 Obsidian将 Markdown 文件和images文件夹放在同一个 Vault 内并保持 Markdown 中的相对路径有效。若图片是 Markdown 标准路径Obsidian 通常可以直接预览。10.4 浏览器浏览器直接打开 Markdown 文件通常只会显示源文本不会自动按 Markdown 渲染。应使用支持 Markdown 的编辑器或先通过 Markdown 插件/静态站点生成 HTML。十一、为什么图片有时显示不出来Markdown 中常见的图片引用是这表示图片位于当前 Markdown 文件所在目录下的images子目录中。下面的文件结构才是正确的论文.md images\ └─ 06b7e3b5753ec39beb4b89ccf8d6a1cbc2174adb8c9389bed6dc29dd7a843127.jpg以下情况都会导致图片不显示只有.md文件没有images文件夹图片文件名被修改Markdown 被移动到其他目录但images没有一起移动相对路径层级不正确图片实际生成在另一个输出目录使用了浏览器或纯文本编辑器而不是 Markdown 预览PDF 本身是扫描图片使用了不合适的解析模式转换过程没有正常结束。十二、图片缺失时的处理方法方法一重新确认输出目录Get-ChildItem-LiteralPathD:\MinerU\output-Recurse-Directory|Where-ObjectName-eqimages如果能找到images把整个结果目录一起移动不要只移动 Markdown。方法二重新转换并保留完整结果建议删除或改名旧的测试输出目录然后重新执行转换$inputD:\MinerU\input\论文.pdf$outputD:\MinerU\output\论文-newpython-m mineru.cli.client-p$input-o$output-b pipeline-m auto-l ch-f true-t true不要直接覆盖多个版本的输出否则容易把 Markdown 和图片目录混在一起。方法三使用版面 PDF 辅助检查如果输出中有*_layout.pdf可以打开它检查 MinerU 对页面、文本块、表格和图片的识别结果。版面 PDF 主要用于核验版面不等于 Markdown 图片资源本身。十三、常见问题13.1python不是命令重新安装 Python 并勾选 PATH或者使用 Python 安装器中的完整路径。也可以尝试py-3.10--version13.2 PowerShell 禁止运行激活脚本执行Set-ExecutionPolicy-Scope CurrentUser RemoteSigned然后重新激活虚拟环境。13.3 命令执行很久没有结束首次运行可能需要加载模型。先确认是否正在下载模型磁盘空间是否充足内存是否足够输入 PDF 是否过大是否误用了需要更高算力的hybrid-engine。新手排查时优先使用pipeline并用-s 0 -e 1只转换两页。13.4 PDF 是扫描件文字识别不完整使用 OCR 模式python-m mineru.cli.client-pD:\MinerU\input\扫描论文.pdf-oD:\MinerU\output\扫描论文-b pipeline-m ocr-l ch扫描件的公式、表格和图片识别效果取决于原始分辨率和版面复杂度转换后必须人工核对。13.5 公式或表格不准确可以尝试开启公式和表格解析-f true-t true但任何 OCR 或版面解析工具都不能保证科研论文公式 100% 正确。重要公式应回看原始 PDF。13.6 需要读取图表内容怎么办首先确认图片文件真实存在。若 Markdown 只有图片链接而没有图片资源不能依据 Markdown 文件本身读取图像内容。此时应找到原始 PDF打开对应页或从 PDF 渲染页面结合图注、正文上下文和图像本身进行总结不要把 OCR 提取的图注当成图像识别结果。十四、适合批量转换的 PowerShell 模板下面的模板可批量处理输入目录中的 PDF$pythonD:\MinerU\.venv-mineru\Scripts\python.exe$inputDirD:\MinerU\input$outputDirD:\MinerU\outputGet-ChildItem-LiteralPath$inputDir-Filter*.pdf-File|ForEach-Object{$pdf$_.FullNameWrite-Host正在转换$pdf$python-m mineru.cli.client -p$pdf-o$outputDir-b pipeline -m auto -l ch -f true -t true}批量处理时每次转换后都应检查输出目录尤其是 Markdown 和images是否一一对应。十五、推荐的科研文献工作流原始 PDF ↓ MinerU 转换 ↓ 检查 Markdown、公式、表格和 images ↓ 用 Obsidian/Cursor/Typora 阅读 ↓ 回看原始 PDF 核验关键公式和图表 ↓ 提炼摘要、方法、数据、结论和可复现实验信息对于论文图表建议同时保留原始 PDFMinerU Markdownimages图片目录JSON 或中间结果人工修订后的笔记。这样可以在 Markdown 解析不完整时回溯原始材料。十六、本次配置的实际环境记录本次环境中曾经使用过以下路径旧工作区D:\AIAgent\findMySelf 当前 MinerU 环境D:\AIAgent_obsidian\04-自动化系统\MinerU 虚拟环境D:\AIAgent_obsidian\04-自动化系统\MinerU\.venv-mineru 输入示例D:\MinerUInput 输出示例D:\MinerUOut 结果示例D:\MinerUResult由于 Windows 系统中的目录可能被迁移、重命名或同步教程中的路径只是示例。重新配置时应先用Test-Path验证路径再执行命令。十七、经验与教训17.1 正确认识 Markdown 与图片的关系Markdown 通常只保存图片链接不保存图片本体。看到并不代表example.jpg一定存在。必须同时确认Markdown 文件所在目录\images\example.jpg这也是本次打开论文 Markdown 时图片不显示的直接原因文档中的图片引用存在但对应的images资源目录没有出现在实际输出目录中。17.2 输出目录必须整体保留不要只复制.md文件。应复制整个论文结果目录。最少要一起保留 Markdown 和images需要后续排错时还应保留 JSON、版面 PDF 和原始 PDF。17.3 PDF 文本可读不代表图片可读MinerU 的 Markdown 可能成功提取正文和图注但图片资源可能缺失。读取文本、读取图像、理解图表是三个不同层次的问题不能用正文 OCR 结果替代图像读取。17.4 不能把 PDF 纯文本抽取当作页面渲染PDF 文本抽取适合查找图注和正文不适合观察曲线、坐标轴、图例和版面。需要总结图表时必须读取真实图片或把 PDF 对应页面渲染成图像后再分析。17.5 先查工具再写命令本次过程中曾尝试使用pdftoppm和fitz但当前 Windows 环境没有pdftoppm虚拟环境中也没有fitz。因此命令不能凭经验假设存在。排错时应先执行Get-Commandpdftoppm,magick,mutool,gswin64c-ErrorAction SilentlyContinue python-cimport importlib.util as u; print(bool(u.find_spec(fitz)))如果工具不存在应改用已安装的工具或明确安装依赖而不是继续重复失败命令。17.6 优先使用当前版本的真实帮助信息MinerU 不同版本的命令参数可能不同。应先执行python-m mineru.cli.client--help python-m mineru.cli.models_download--help再复制参数。本文命令依据 MinerU3.4.4的实际帮助信息整理。17.7 Windows 路径必须谨慎处理中文路径、空格、括号和特殊字符都可能导致命令解析问题。PowerShell 中优先使用-LiteralPath完整路径命令参数中的路径统一使用单引号。脚本中则使用变量保存路径减少重复输入和拼写错误。17.8 先做小样本测试不要一开始处理整本书或数百页论文。先转换前 12 页确认模型、后端、公式、表格和图片都正常再进行完整转换。这样可以快速区分“环境问题”和“文档本身的问题”。17.9 先使用稳定后端再追求高精度pipeline更适合作为入门和批量处理的起点。hybrid-engine的图表分析能力更强但需要更多模型和计算资源。新手遇到卡顿或失败时应先回到pipeline验证基本链路。17.10 解析结果必须人工核验对于科研论文以下内容都不应盲信OCR 识别出的数字和单位公式中的上下标表格中的列关系图注和图内文字页眉页脚和参考文献编号。MinerU 负责提高整理效率不能替代对原始论文的最终核验。十八、结语MinerU 的完整使用链路并不只是“安装一个 Python 包然后打开 Markdown”。真正可靠的流程是先确认 Python 和 MinerU 版本再下载模型使用稳定后端完成小样本测试最后检查 Markdown 与图片资源是否匹配。对于论文阅读最重要的判断标准不是“转换命令是否退出”而是正文、公式、表格、图片和相对路径是否都能在目标阅读器中正确呈现。发布前检查清单代码块中的路径已替换为自己的实际路径已说明 Python、MinerU 和操作系统版本已给出安装、模型下载和转换命令已解释images目录与 Markdown 的相对路径关系已给出常见报错和排查办法已提醒读者核验公式、表格和图表CSDN 发布时已删除个人隐私和不必要的本机路径