PDF → Markdown (MinerU)
使用 MinerU (opendatalab/MinerU) 将 PDF 转换为干净且保留结构的 Markdown，这是处理学术论文的最高保真度开源引擎。管道后端在 GPU（CUDA）上运行。输出保留标题层级、内联 LaTeX 数学公式（$...$）、图表和表格（以 HTML 形式呈现）。
使用时机
- 用户请求“将这份 PDF 转换/提取为 Markdown（或文本）”。
- 最佳适用场景：学术论文——多栏布局、LaTeX 数学公式、表格、参考文献。
- 也能处理图片、
.docx、.pptx、.xlsx文件（直接传入文件）。
如何运行
MinerU 位于一个专用的隔离环境中，通过附带的 convert.py 封装脚本驱动，该脚本在进程内调用 MinerU 的 Python API。
这里 不要 使用
mineruCLI —— 在 3.4.0 版本中，它会在本地启动一个 API 服务器，在 Windows 上返回502 Bad Gateway。封装脚本绕过了这个问题。
"$MINERU_PYTHON" \
"<SKILLS_DIR>/pdf-to-markdown/convert.py" \
"<input.pdf>" "<output_dir>" --lang en
- 参数 1 — 输入文件（pdf/图片/docx/pptx/xlsx）。
- 参数 2 — 输出目录。
--lang— OCR 语言提示：en表示英文，ch表示中文/混合（默认是ch，也能处理英文）。仅影响 OCR 处理的（扫描）页面。- 成功时脚本会打印
DONE -> <path to .md>。
输出布局
<output_dir>/<name>/auto/<name>.md # markdown 文件
<output_dir>/<name>/auto/images/ # 提取的图片（在 markdown 中引用）
<output_dir>/<name>/auto/<name>_*.json # 布局/内容元数据（可忽略）
转换完成后
- 读取打印的
DONE -> ...md路径并告知用户。 - 可选择显示简短预览（标题 + 前几个标题）。
- 说明提取图片的写入位置。
- 质量通常很高：标题显示为
#，内联数学公式显示为$...$，表格显示为<table>HTML（单元格内可包含 LaTeX）。如果扫描版 PDF 出现乱码，请使用--method ocr重新运行。
预备/设置（仅在缺少某些组件时执行）
- 包含 MinerU 的解释器（环境
MINERU_PYTHON，默认为python）。 - 验证 CUDA：
$MINERU_PYTHON -c "import torch; print(torch.cuda.is_available())"→True。 - 模型已预先下载到
~/.cache/huggingface/hub/（一次性操作）。
如果缺少环境，请重新创建（如有需要，先安装 uv）：
uv venv --python 3.12 "<your-env>"
uv pip install --python "<your-env>/Scripts/python.exe" torch torchvision --index-url https://download.pytorch.org/whl/cu124
uv pip install --python "<your-env>/Scripts/python.exe" -U "mineru[core]"
"<your-env>/Scripts/mineru-models-download.exe" -s huggingface -m pipeline
然后设置 MINERU_PYTHON 为 <your-env>/Scripts/python.exe（Windows）或 <your-env>/bin/python（macOS/Linux）。在 macOS/Linux 上，模型下载二进制文件是 mineru-models-download（不带 .exe 后缀）。
故障排除
cuda.is_available()返回 False → 从cu124索引重新安装 torch（参见设置）。如果必要，管道仍然可以在 CPU 上运行，只是速度较慢。- 模型下载失败/缓慢 → 使用
-s modelscope重新运行mineru-models-download。 - 扫描版 PDF 乱码 → 在调用
convert.py时添加--method ocr。 vlm-engine/hybrid-engine后端 → 这些需要 vLLM/SGLang（Linux）；它们在 Windows 上返回 502。请坚持使用封装脚本使用的默认pipeline后端。
轻量级备选方案（简单 / Office 文档）
对于不需要布局保真度的非论文文件，Microsoft 的 MarkItDown 更快更简单——但它会破坏学术类双栏 PDF 和表格，因此对于论文，请优先使用 MinerU：
"$MINERU_PYTHON" -m pip install markitdown
"$MINERU_PYTHON" -m markitdown "<input>" > out.md