Marker PDF 转换实战：3 条命令把真实 PDF 变成 Markdown

【免费下载链接】markerConvert PDF to markdown + JSON quickly with high accuracy项目地址: https://gitcode.com/GitHub_Trending/ma/marker

Marker 是 Datalab 开源的文档解析工具，核心是 Marker PDF 转换——把 PDF 转成 Markdown、JSON、HTML，表格、公式、代码块都按块结构解析，支持 GPU、CPU、MPS 三种运行方式。本文带你完成安装、确认依赖装齐，并用一份真实 PDF 拿到完整的 Markdown 输出。

三步拿到第一个转换结果

✅ 第 1 步，克隆仓库并建独立环境：

git clone https://gitcode.com/GitHub_Trending/ma/marker cd marker python -m venv .venv && source .venv/bin/activate

单独建 venv 是因为 marker-pdf 的依赖链里有 torch、transformers、surya-ocr 等重型包，直接装进系统 Python 容易污染其他项目。激活后python -V显示的版本应与系统 Python 一致，否则下一步的安装可能落进别的解释器。

✅ 第 2 步，可编辑模式安装：

pip install -e .

这条命令会装齐 pyproject.toml 里声明的全部依赖（torch≥2.7、transformers≥5.12、surya-ocr≥0.22.1 等），包含完整深度学习栈，下载量不小，是整个流程最耗时的一步。终端无红色报错、回到提示符即算完成。

✅ 第 3 步，验证入口并跑第一次转换：

marker_single --help marker_single /path/to/file.pdf

--help会列出全部可用参数，能打印出来就说明命令入口装好了。第二条命令默认把结果写到conversion_results目录（默认值定义在 marker/settings.py），里面出现同名 .md 文件和抽取出的 .jpeg 图，即判定跑通。首次运行还要下载 surya 模型权重，等待时间比后续明显长，属正常现象。

装之前核对：Python 版本、依赖与两种安装方式

⚠️ 版本边界以 pyproject.toml 为准，网上流传的旧教程若说更老的 Python 也能装，请忽略：

注意 PyPI 上的包名是marker-pdf而不是marker，这一点直接决定你下一节会不会踩第一个坑。

4 个高频失败：现象、原因与解法

现象：运行提示No module named 'marker'。原因：虚拟环境没激活，或包装进了另一个 Python。先用which python确认解释器路径；Windows 上改用.venv\Scripts\activate激活。

现象：pip install marker装出一个不相干的工具。原因：PyPI 上marker这个名字被别的项目占用，本项目正确的包名是marker-pdf。解法：pip uninstall marker -y之后重新pip install marker-pdf。

现象：安装报Requires-Python >=3.10。原因：本机 Python 低于 3.10。解法：升级 Python 后重建虚拟环境，旧环境直接复用没有意义。

现象：第一次转换极慢，像卡死。并非卡死——首次运行在下载 surya 模型权重，等进度条走完即可，之后只做推理，会明显变快。

怎么判断转换结果是对的：看输出目录，读基准分数

转换成功后，打开conversion_results目录：应有与 PDF 同名的 Markdown 文件、_meta.json和抽取出的图片。抽查表格行列、公式是否与原文对应；若出现乱码，通常是 PDF 自带文本层损坏，加--force_ocr对该页重新 OCR 即可。

整体精度可参考 olmOCR-bench（1,403 份 PDF、约 8,400 个 pass/fail 测试的第三方基准）：Marker 的 balanced 模式总分 76.0%，纯数字 PDF 83.5%，在单台 B200 上吞吐 2.9 页/秒，分数与速度都高于 MinerU（72.7% / 0.54 页/秒）和 docling（50.3% / 2.1 页/秒）。

模式选择看取舍：

一句话：公式多、质量优先选 balanced；纯数字文本、速度优先选 fast 或 no-OCR。

批量任务、LLM 混合模式与多卡：常用参数速查

• 批量：marker /path/to/folder转换整个目录；--workers 8提高并发；--skip_existing让中断的任务从断点续跑；--max_files 100限制数量。
• LLM 混合模式：加--use_llm可跨页合并表格、修复行内公式、抽取表单值，默认走 Gemini（gemini-3.5-flash），--llm_service可切到 Claude/OpenAI 等；API 密钥写入local.env文件，变量名见 marker/settings.py。
• 硬件与环境：多卡用VLLM_GPUS=0,1 marker /folder让推理服务跨卡分担；纯 CPU 机器加--mode fast或--disable_ocr，走纯文本层抽取，完全不启动 VLM。

下一步：对照示例输出，深入内部

• 评估转换质量，先看 data/examples/ 里现成的 Markdown 输出：thinkpython是教科书、multicolcnn是双栏论文，再拿自己的同类文档跑一遍对比。
• 想改输出逻辑，从marker/schema/下的 block 定义和 processors 层入手；marker_single --debug会保存每页检测到的布局图，便于定位问题。
• 想复现上面的基准数字，按benchmarks/README.md里的步骤跑benchmarks/inference.py，它输出的就是持续页/秒吞吐。

【免费下载链接】markerConvert PDF to markdown + JSON quickly with high accuracy项目地址: https://gitcode.com/GitHub_Trending/ma/marker