MinerU 新手完整配置教程：Windows 下将 PDF 转为带图片的 Markdown

---

title: MinerU 新手完整配置教程：Windows 下将 PDF 转为带图片的 Markdown

作者: 肖恭伟

tags:

• MinerU
• PDF
• Markdown
• OCR
• Windows
• 文献阅读

---

MinerU 新手完整配置教程：Windows 下将 PDF 转为带图片的 Markdown

本文记录一次完整的 MinerU 配置、运行、排错和复盘过程，面向第一次接触命令行工具的 Windows 用户。

目标是把论文 PDF 转换为可在 Cursor、VS Code、Typora 或 Obsidian 中阅读的 Markdown，并保留公式、表格和图片资源。

一、先看正确步骤

新手建议严格按下面的顺序操作：

1. 安装 64 位 Python 3.10～3.13，并确认 python 和 pip 可用。
2. 建立一个不含空格的工作目录，例如 D:\MinerU。
3. 创建并激活 Python 虚拟环境。
4. 安装 MinerU，并确认版本。
5. 下载模型文件。
6. 准备输入 PDF，首次测试尽量使用英文或简单中文 PDF。
7. 使用明确的后端和输出目录运行转换。
8. 检查输出目录中的 Markdown、images 图片目录和 JSON 文件。
9. 用支持 Markdown 预览的编辑器打开 Markdown，而不是直接双击纯文本文件。
10. 若图片缺失，先检查相对路径和输出目录，再判断是否需要重新转换。

整个流程可以概括为：

安装 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 PATH；
• pip；
• venv。

安装完成后，在 PowerShell 中执行：

python --version
pip --version

如果系统中有多个 Python，也可以使用：

py --version
py -0p

3.2 建立工作目录

建议把程序、输入文件和输出文件分开：

D:\MinerU\
├─ .venv-mineru\       虚拟环境
├─ input\              待转换 PDF
└─ output\             转换结果

在 PowerShell 中执行：

New-Item -ItemType Directory -Force -Path 'D:\MinerU\input','D:\MinerU\output' | Out-Null
Set-Location 'D:\MinerU'

路径包含中文或空格时，必须使用引号。例如：

Set-Location 'D:\我的论文\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 -c "import sys; print(sys.executable)"

输出路径应指向：

D:\MinerU\.venv-mineru\Scripts\python.exe

五、安装 MinerU

先升级基础安装工具：

python -m pip install --upgrade pip setuptools wheel

安装 MinerU：

python -m pip install -U mineru

确认版本：

python -c "import 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 -LiteralPath 'D:\MinerU\input\论文.pdf'
Get-Item -LiteralPath 'D:\MinerU\input\论文.pdf' | Select-Object FullName,Length

文件名包含中文时没有问题，但在 PowerShell 中建议始终使用 -LiteralPath 和引号，避免特殊字符被解释。

八、执行 PDF 转 Markdown

8.1 推荐的 Pipeline 后端

Pipeline 后端适合先完成稳定的 PDF 文本、公式、表格和图片解析：

python -m mineru.cli.client `
  -p 'D:\MinerU\input\论文.pdf' `
  -o 'D:\MinerU\output' `
  -b pipeline `
  -m auto `
  -l ch `
  -f true `
  -t true

PowerShell 使用反引号 ````` 换行。如果担心复制时丢失反引号，也可以写成一行：

python -m mineru.cli.client -p 'D:\MinerU\input\论文.pdf' -o 'D:\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 `
  -p 'D:\MinerU\input\论文.pdf' `
  -o 'D:\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 `
  -p 'D:\MinerU\input\论文.pdf' `
  -o 'D:\MinerU\output-test' `
  -b pipeline `
  -m auto `
  -l ch `
  -s 0 `
  -e 1

注意：-s 和 -e 使用从 0 开始的页码。

九、检查输出结果

转换结束后，先不要急着打开 Markdown。先检查输出目录：

Get-ChildItem -LiteralPath 'D:\MinerU\output' -Recurse -File |
  Select-Object FullName,Length,LastWriteTime

正常情况下，应当重点寻找：

*.md
images\
*.json
*_layout.pdf

典型结构类似：

D:\MinerU\output\论文\
├─ auto\
│  ├─ 论文.md
│  ├─ images\
│  │  ├─ image-1.jpg
│  │  └─ image-2.jpg
│  ├─ *.json
│  └─ *_layout.pdf

检查图片数量：

$md = Get-ChildItem -LiteralPath 'D:\MinerU\output' -Recurse -Filter '*.md' | Select-Object -First 1
$md.FullName
$images = Join-Path $md.DirectoryName 'images'
Write-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 '!\[.*\]\('

逐个验证图片引用是否存在：

$mdText = Get-Content -LiteralPath $md.FullName -Raw -Encoding UTF8
[regex]::Matches($mdText, '!\[[^]]*\]\(([^)]+)\)') | ForEach-Object {
  $relative = $_.Groups[1].Value
  $absolute = Join-Path $md.DirectoryName $relative
  [pscustomobject]@{
    Reference = $relative
    Exists = Test-Path -LiteralPath $absolute
    Path = $absolute
  }
}

如果 Exists 为 False，说明 Markdown 里的图片引用失效，不能仅靠更换阅读器解决。

十、正确打开带图片的 Markdown

10.1 Cursor 或 VS Code

1. 用 Cursor 或 VS Code 打开 Markdown 文件。
2. 按 Ctrl+Shift+V 打开 Markdown 预览。
3. 或按 Ctrl+K，松开后再按 V，在右侧打开预览。
4. Markdown 文件和 images 文件夹必须保持原有相对位置。

10.2 Typora

直接用 Typora 打开 .md 文件即可。图片文件夹不能移动或删除。

10.3 Obsidian

将 Markdown 文件和 images 文件夹放在同一个 Vault 内，并保持 Markdown 中的相对路径有效。若图片是 Markdown 标准路径，Obsidian 通常可以直接预览。

10.4 浏览器

浏览器直接打开 Markdown 文件通常只会显示源文本，不会自动按 Markdown 渲染。应使用支持 Markdown 的编辑器，或先通过 Markdown 插件/静态站点生成 HTML。

十一、为什么图片有时显示不出来

Markdown 中常见的图片引用是：

![](images/06b7e3b5753ec39beb4b89ccf8d6a1cbc2174adb8c9389bed6dc29dd7a843127.jpg)

这表示图片位于当前 Markdown 文件所在目录下的 images 子目录中。下面的文件结构才是正确的：

论文.md
images\
└─ 06b7e3b5753ec39beb4b89ccf8d6a1cbc2174adb8c9389bed6dc29dd7a843127.jpg

以下情况都会导致图片不显示：

• 只有 .md 文件，没有 images 文件夹；
• 图片文件名被修改；
• Markdown 被移动到其他目录，但 images 没有一起移动；
• 相对路径层级不正确；
• 图片实际生成在另一个输出目录；
• 使用了浏览器或纯文本编辑器，而不是 Markdown 预览；
• PDF 本身是扫描图片，使用了不合适的解析模式；
• 转换过程没有正常结束。

十二、图片缺失时的处理方法

方法一：重新确认输出目录

Get-ChildItem -LiteralPath 'D:\MinerU\output' -Recurse -Directory | Where-Object Name -eq 'images'

如果能找到 images，把整个结果目录一起移动，不要只移动 Markdown。

方法二：重新转换并保留完整结果

建议删除或改名旧的测试输出目录，然后重新执行转换：

$input = 'D:\MinerU\input\论文.pdf'
$output = 'D:\MinerU\output\论文-new'
python -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.1 python 不是命令

重新安装 Python 并勾选 PATH，或者使用 Python 安装器中的完整路径。也可以尝试：

py -3.10 --version

13.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 -p 'D:\MinerU\input\扫描论文.pdf' -o 'D:\MinerU\output\扫描论文' -b pipeline -m ocr -l ch

扫描件的公式、表格和图片识别效果取决于原始分辨率和版面复杂度，转换后必须人工核对。

13.5 公式或表格不准确

可以尝试开启公式和表格解析：

-f true -t true

但任何 OCR 或版面解析工具都不能保证科研论文公式 100% 正确。重要公式应回看原始 PDF。

13.6 需要读取图表内容怎么办

首先确认图片文件真实存在。若 Markdown 只有图片链接而没有图片资源，不能依据 Markdown 文件本身读取图像内容。此时应：

1. 找到原始 PDF；
2. 打开对应页或从 PDF 渲染页面；
3. 结合图注、正文上下文和图像本身进行总结；
4. 不要把 OCR 提取的图注当成图像识别结果。

十四、适合批量转换的 PowerShell 模板

下面的模板可批量处理输入目录中的 PDF：

$python = 'D:\MinerU\.venv-mineru\Scripts\python.exe'
$inputDir = 'D:\MinerU\input'
$outputDir = 'D:\MinerU\output'

Get-ChildItem -LiteralPath $inputDir -Filter '*.pdf' -File | ForEach-Object {
  $pdf = $_.FullName
  Write-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 核验关键公式和图表
  ↓
提炼摘要、方法、数据、结论和可复现实验信息

对于论文图表，建议同时保留：

• 原始 PDF；
• MinerU Markdown；
• images 图片目录；
• 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 通常只保存图片链接，不保存图片本体。看到：

![](images/example.jpg)

并不代表 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-Command pdftoppm,magick,mutool,gswin64c -ErrorAction SilentlyContinue
python -c "import 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

再复制参数。本文命令依据 MinerU 3.4.4 的实际帮助信息整理。

17.7 Windows 路径必须谨慎处理

中文路径、空格、括号和特殊字符都可能导致命令解析问题。PowerShell 中优先使用：

-LiteralPath '完整路径'

命令参数中的路径统一使用单引号。脚本中则使用变量保存路径，减少重复输入和拼写错误。

17.8 先做小样本测试

不要一开始处理整本书或数百页论文。先转换前 1～2 页，确认模型、后端、公式、表格和图片都正常，再进行完整转换。这样可以快速区分"环境问题"和"文档本身的问题"。

17.9 先使用稳定后端，再追求高精度

pipeline 更适合作为入门和批量处理的起点。hybrid-engine 的图表分析能力更强，但需要更多模型和计算资源。新手遇到卡顿或失败时，应先回到 pipeline 验证基本链路。

17.10 解析结果必须人工核验

对于科研论文，以下内容都不应盲信：

• OCR 识别出的数字和单位；
• 公式中的上下标；
• 表格中的列关系；
• 图注和图内文字；
• 页眉页脚和参考文献编号。

MinerU 负责提高整理效率，不能替代对原始论文的最终核验。

十八、结语

MinerU 的完整使用链路并不只是"安装一个 Python 包，然后打开 Markdown"。真正可靠的流程是：先确认 Python 和 MinerU 版本，再下载模型，使用稳定后端完成小样本测试，最后检查 Markdown 与图片资源是否匹配。

对于论文阅读，最重要的判断标准不是"转换命令是否退出"，而是：正文、公式、表格、图片和相对路径是否都能在目标阅读器中正确呈现。

---

发布前检查清单

• 代码块中的路径已替换为自己的实际路径
• 已说明 Python、MinerU 和操作系统版本
• 已给出安装、模型下载和转换命令
• 已解释 images 目录与 Markdown 的相对路径关系
• 已给出常见报错和排查办法
• 已提醒读者核验公式、表格和图表
• CSDN 发布时已删除个人隐私和不必要的本机路径