快速将复杂PDF转Markdown：Marker五分钟上手指南-二趣网

快速将复杂PDF转Markdown：Marker五分钟上手指南

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

刚转完的一份47页报告乱成一团：表格单元格挤成一行、公式变成^和\的字符堆、图注跟图片分家。PDF转Markdown最常见的失败就是这样。Marker 是一个开源的 PDF 转换工具，能把 PDF、图片、PPTX 等文件转成 Markdown、JSON、HTML 与 Chunks，本地运行，支持 GPU/CPU。

不适合谁：三类文档先想清楚

先说边界，避免白花时间：

老旧扫描件：在第三方基准 olmocr-bench 里，"old scans" 一类 balanced 模式只有 43.2 分，是八类里最弱的。如果你的主力素材是带公式的老扫描页，README 建议改用整页 VLM 路线（surya / Chandra）。
嵌套表格 + 复杂表单：官方 Limitations 明确写了"very complex layouts, with nested tables and forms, may not work"，加--use_llm --force_ocr能解决大部分，但不保证全部。
追求绝对精度且愿意调 API：Gemini Flash 3.5 得 76.4、托管的 Chandra 2 得 85.8，都略高于本地 balanced 的 76.0。

反过来，数字原生（born-digital）的 PDF 正是它的主场：balanced 模式在数字类文档上得 83.5 分。

一图看懂 PDF 转换流水线

整个流程可以理解成一个包裹分拣中心：PDF 是进厂的一车包裹，逐站流转。

收货台（marker/providers/）：拆开原始文件，按阅读顺序取出页面图像与内嵌文本
传送带（marker/builders/）：做版面检测，把每页切成文本、表格、图片等一个个独立块
分拣工位（marker/processors/）：表格工位重排列行、公式工位输出 LaTeX、代码工位保留缩进
打包出货（marker/renderers/）：把块组装成 Markdown / JSON / HTML / Chunks 四种形态

关键设计在图中也有体现：所有工位（worker）都是瘦 CPU 进程，共享一个 surya VLM 推理服务器；VLM 只在必要时被调用（公式、乱码页、扫描页）。模块分工如下：

模块	在分拣中心的职责	对应哪类元素
marker/providers/	收货拆包	PDF、图片、PPTX、DOCX、XLSX、HTML、EPUB 七类输入
marker/builders/	传送带分块	页面级块：文本、图片位置、表格边界
marker/processors/	工位加工	表格、公式、代码、页眉页脚、列表项
marker/renderers/	打包出货	markdown / json / html / chunks 四种输出

三个真实文档实战

仓库自带三个真实样例的转换结果，下面的命令都可以原样复现。

案例一：双栏学术论文

材料：Multi-column CNN 论文，双栏排版加密集公式，是"学术论文转 Markdown"的典型难度。命令：marker_single multicolcnn.pdf --mode balanced

效果：两栏按正确阅读顺序输出，公式以$$LaTeX 形式写入，架构图单独存为图片。易错点：fast 模式在 arXiv math 类只有 23.4 分，公式密集论文别图省事，用 balanced。

案例二：带代码的教材

材料：《Think Python》，大量代码块与插图。命令：marker_single thinkpython.pdf --output_dir out

效果：代码输出为三重反引号代码块，图片存入与 md 同目录并自动引用。易错点：只搬 .md 不搬图片目录，引用就断了，两者一起移动。

案例三：只想要表格

材料：文档里表格多，但只关心表格本身，不要正文。

marker_single switch_trans.pdf --use_llm --force_layout_block Table \ --converter_cls marker.converters.table.TableConverter --output_format json

效果：只输出表格块，json 里带页码与边界框，表格内容默认是 HTML。易错点：--use_llm需要配 LLM 密钥（默认 Gemini，要GOOGLE_API_KEY），没配会直接失败。

数据说话：基准得分与吞吐

第三方基准 olmocr-bench（1,403 个 PDF、约 8,400 条断言）上的结果如下：

文档类型（8 类之一）	balanced 得分	一句话解读
Baseline 常规文本	99.7	普通文本近乎满分
Headers & footers	95.9	页眉页脚默认自动剥离
arXiv math	83.9	LaTeX 公式是强项
Multi column	76.6	双栏不乱序
Tables	73.4	数字表格由文本层重建，LLM 可再提升
Long tiny text	71.3	小字号偏弱
Old scans	43.2	老旧扫描件最弱
Overall	76.0	八类宏平均，digital-only 为 83.5

吞吐（单张 B200 实测，持续并发）：balanced 2.9 页/秒、fast 7.4 页/秒、fast 无 OCR 23.7 页/秒（折合每页 42 毫秒）；同场对比中 MinerU 为 0.54 页/秒，docling 为 2.1 页/秒。这个数字对你的意义：一块 GPU 上，balanced 模式转完 500 页约 3 分钟，日常批处理足够用。

五分钟上手步骤

安装（需 Python 3.10+，处理非 PDF 格式装完整版）：

pip install marker-pdf

装完即可用；pip install marker-pdf[full]才能处理 PPTX/DOCX 等其余格式。

单文件：

marker_single /path/to/file.pdf

产出 markdown、提取的图片与_meta.json。

批量：

marker /path/to/folder --workers 4 --output_dir out

--workers增加并行 worker（共享同一个推理服务器），--skip_existing支持断点续转。

避坑速查表

问题	典型症状	一行解决
文字乱码	中文、公式读成生僻字符	`marker_single doc.pdf --force_ocr`
精度不够	复杂版面、公式错乱	`marker_single doc.pdf --use_llm`（配 GOOGLE_API_KEY）
内存不足	进程 OOM 崩溃	调小`--workers`，或把长 PDF 拆成多个文件
只想转几页	整文档太慢	`--page_range "0,5-10,20"`
批量中断	不想重跑已转文件	`--skip_existing`
想看检测结果	不确定版面检出了什么	`--debug`保存每页标注图与 json

参数调优速查

参数	作用	什么时候用
`--mode balanced\\|fast`	balanced：VLM 版面检测 + 按需整页重 OCR；fast：轻量检测器 + 文本层	GPU 默认 balanced，CPU/MPS 默认 fast
`--disable_ocr`	永不启动 VLM，纯文本层提取	纯数字 PDF 求最快（23.7 页/秒）
`--force_ocr`	全页强制 OCR	乱码或扫描文档
`--use_llm`	LLM 复核表格、公式、表单	精度不够时；默认 Gemini，可换 Ollama/Claude 等
`--output_format`	markdown / json / html / chunks	chunks 适合 RAG 分块
`--converter_cls`	换成`marker.converters.table.TableConverter`	只抽表格时
`--processors`	用完整模块路径列表覆盖默认处理链	需要定制加工逻辑时
`VLLM_GPUS=0,1`/`--num_chunks`+`--chunk_idx`	多 GPU 或按节点分片	大规模文档集

接下来做三件事

今天装好pip install marker-pdf，转一份自己的 PDF，对照上面避坑表验证一次；
挑一份公式或表格密集的文档，分别跑 balanced 和--use_llm，看分数差多少；
想改行为就进源码：处理链在 marker/processors/，基准复现脚本说明见 benchmarks/README.md。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析