MarkPDFdown 教程:用大模型视觉识别把 PDF 高质量转成 Markdown

把 PDF 转成 Markdown,听起来简单,真做过的人都知道有多坑。传统转换工具靠解析 PDF 内部的文字层和坐标硬抠内容,遇到双栏排版、跨页表格、数学公式、流程图就开始乱套:段落顺序错位、表格塌成一团、公式变乱码,扫描版 PDF(纯图片)更是直接无能为力。转完之后人工修复的时间,往往比自己重打一遍还长。

MarkPDFdown 换了一条路线:它不抠文字层,而是把文档交给多模态大模型做视觉识别——让 GPT-4o、Claude 这类能「看图」的模型先看懂整页的版面结构,再转写成 Markdown。标题层级、列表、表格这些格式元素由模型按语义还原,对复杂排版和扫描件的适应性远好于规则型工具。它是开源项目(Apache-2.0 协议),通过 LiteLLM 统一接入多家模型服务。本文把它的原理、安装、配置和使用完整走一遍。

一、原理与功能

MarkPDFdown 的核心链路很简单:读取 PDF(或图片)→ 调用多模态大模型进行视觉理解与转写 → 输出干净、可编辑的 Markdown 文本。模型调用层用的是 LiteLLM,所以它不绑死单一厂商,官方明确支持三家接入方式:

  • OpenAI:gpt-4o、gpt-4o-mini、gpt-4-vision-preview 等视觉模型
  • OpenRouter:可调用 Claude 3.5 Sonnet、Gemini Pro Vision、Llama 3.2 90B Vision 等
  • Requesty:同样可路由到 GPT-4o、Claude Sonnet 等模型

功能方面,官方列出的主要能力包括:

  • PDF 转 Markdown:保留标题、列表、表格等格式元素,处理包含表格、公式、图表的复杂文档结构
  • 图片转 Markdown:输入一张图片(如截图、扫描单页),同样转成 Markdown
  • 页码范围选择:用 --start / --end 只转指定页,不必每次处理整本
  • 两种运行模式:文件模式(--input/--output)和管道模式(stdin/stdout,后者对 Docker 和脚本编排友好)
  • 桌面应用:不想用命令行的话,官方另有 GUI 桌面版仓库,一条 npx 命令即可拉起(见下文)

项目本身是模块化结构:cli.py 管命令行接口,main.py 是核心转换逻辑,config.py 管配置,core/llm_client.py 封装 LiteLLM 调用。代码量不大,想二次开发或嵌进自己的文档处理流水线也方便。

二、安装

环境要求:Python 3.9 或以上,以及至少一家受支持模型服务(OpenAI / OpenRouter / Requesty)的 API Key。官方推荐用 uv 安装,conda 也可以。注意它目前是从源码安装的方式:克隆仓库后在本地安装,不是 pip 一键装包。

方式一:uv(官方推荐)

# 没装 uv 的先装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 克隆仓库
git clone https://github.com/MarkPDFdown/markpdfdown.git
cd markpdfdown

# 安装依赖并创建虚拟环境
uv sync

# 以开发模式安装本包
uv pip install -e .

方式二:conda

conda create -n markpdfdown python=3.9
conda activate markpdfdown

git clone https://github.com/MarkPDFdown/markpdfdown.git
cd markpdfdown

pip install -e .

方式三:桌面应用(GUI)

如果只是想点点鼠标转几个文件,不想碰命令行,官方提供了桌面应用(在单独的仓库维护),用 npx 直接运行:

npx -y markpdfdown

三、使用教程

使用前先完成第四节的 .env 配置(至少配好模型名和对应的 API Key),之后转换就是一条命令的事。

第 1 步:基本转换(文件模式,官方推荐)

# PDF 转 Markdown
markpdfdown --input document.pdf --output output.md

# 也可以用 Python 模块方式运行,效果相同
python -m markpdfdown --input document.pdf --output output.md

第 2 步:只转指定页码范围

大文档没必要整本转。用 --start 和 --end 圈定页码,既省时间也省 API 调用量:

# 只转第 1-10 页
markpdfdown --input document.pdf --output output.md --start 1 --end 10

# 转第 5-15 页,单独存成一章
markpdfdown --input large_document.pdf --output chapter.md --start 5 --end 15

第 3 步:图片转 Markdown

输入换成图片文件即可,截图、拍照的单页文档、扫描图都能这样处理:

markpdfdown --input image.png --output output.md

第 4 步:管道模式

不加 --input/--output 时,它从标准输入读、往标准输出写,天生适合拼进 shell 流水线,也是 Docker 里的标准用法:

# PDF 经管道转成 Markdown
markpdfdown < document.pdf > output.md

python -m markpdfdown < document.pdf > output.md

第 5 步:批量转换

官方给的批量示例就是一个 shell 循环,把当前目录的 PDF 逐个转成同名 .md:

for file in *.pdf; do
    markpdfdown --input "$file" --output "${file%.pdf}.md"
done

第 6 步:Docker 运行

不想在宿主机装 Python 环境的,可以用仓库自带的 Dockerfile 构建镜像,运行时通过环境变量传模型配置,走管道模式进出文件:

# 构建镜像
docker build -t markpdfdown .

# 用 OpenAI 运行
docker run -i \
  -e MODEL_NAME=gpt-4o \
  -e OPENAI_API_KEY=sk-your-api-key-here \
  markpdfdown < input.pdf > output.md

# 用 OpenRouter 运行
docker run -i \
  -e MODEL_NAME=openrouter/anthropic/claude-3.5-sonnet \
  -e OPENROUTER_API_KEY=sk-or-your-api-key-here \
  markpdfdown < input.pdf > output.md

四、配置说明

MarkPDFdown 全部配置走环境变量:在项目目录把示例配置复制为 .env 再改即可,LiteLLM 会自动识别各家的 Key 变量名。

cp .env.sample .env

.env 的核心内容如下(按自己用的服务商保留对应的一组即可):

# 模型配置:填哪个模型,就用哪个
MODEL_NAME=gpt-4o

# API Key(三选一,与模型对应)
OPENAI_API_KEY=sk-your-api-key-here
# OPENROUTER_API_KEY=sk-or-your-api-key-here
# REQUESTY_API_KEY=sk-your-api-key-here

# 可选参数
TEMPERATURE=0.3
MAX_TOKENS=8192
RETRY_TIMES=3
  • MODEL_NAME:模型标识。OpenAI 直接写模型名(gpt-4o、gpt-4o-mini、gpt-4-vision-preview);走 OpenRouter 要带前缀,如 openrouter/anthropic/claude-3.5-sonnet、openrouter/google/gemini-pro-vision、openrouter/meta-llama/llama-3.2-90b-vision;走 Requesty 则是 requesty/openai/gpt-4o、requesty/anthropic/claude-sonnet-4-5 这样的写法。前缀写错是最常见的报错原因
  • TEMPERATURE:采样温度,示例默认 0.3。文档转写是「照着抄」的任务,低温更稳,别调高
  • MAX_TOKENS:单次输出上限,示例默认 8192。页面内容 dense、表格大时适当调大,避免转写被截断
  • RETRY_TIMES:调用失败重试次数,示例默认 3

模型怎么选:质量优先用 gpt-4o 或 Claude 3.5 Sonnet 这一档;量大、版面简单时用 gpt-4o-mini 这类便宜模型压成本;已经在用 OpenRouter/Requesty 聚合额度的,顺着现有通道走最省事。

五、效果与局限

它擅长的场景:版面复杂的文档——双栏论文、带合并单元格的表格、含公式的技术资料、图表混排的报告,以及传统工具直接投降的扫描版 PDF。因为是模型「看懂」页面再转写,阅读顺序、标题层级、表格结构都按语义还原,产出的 Markdown 拿来喂知识库、做 RAG 切分、放进笔记或博客都基本不用大修。这正是这类工具近两年最大的价值场景:把存量 PDF 批量变成 LLM 友好的文本。

它的局限也要说清:

  • 质量上限取决于模型:它本身不做识别,识别全靠所配的多模态模型。模型档次、页面清晰度直接决定成稿质量,官方没有也不可能给出统一的准确率承诺
  • 成本和速度随页数线性增长:每一页都要调用一次云端模型 API,几百页的书转下来,API 费用和耗时都不低。先用 --start/--end 小范围试转、确认效果和单页成本后再批量跑,是更稳妥的顺序
  • 结果是「转写」不是「提取」:模型生成的内容绝大多数时候忠实原文,但本质上是生成式输出,数字、人名、公式细节存在个别出错的可能。用于合同、财务、论文引用等严肃场景时,关键数据必须回原 PDF 核对,不能无脑信任
  • 没有本地离线模式:官方支持的接入都是云端服务(OpenAI / OpenRouter / Requesty),断网或无 Key 时用不了

六、注意事项

  • 隐私先行:转换时文档内容会发送到你所配置的模型服务商。涉及内部资料、未公开文档、个人敏感信息的 PDF,先确认公司合规要求和服务商的数据政策,再决定要不要用、走哪家
  • .env 别提交进 Git:API Key 写在 .env 里,仓库的 .gitignore 默认会忽略它,自己改配置时别手滑把真实 Key 提交或截图外发
  • 先试转再批量:新文档类型先转 3-5 页看效果,顺带观察单页耗时,心里有数后再跑批量循环,避免跑一半发现模型选错、整批返工
  • 报错先查三件事:MODEL_NAME 的厂商前缀是否与 Key 对应(OpenRouter 的 Key 配了不带前缀的模型名是最典型的一种)、Key 是否有效且有额度、网络能否直达对应 API。多数「跑不起来」都是这三类问题
  • 输出记得留底核对:批量任务建议保留「原 PDF + 输出 .md」的对应关系,抽查时按页对照最方便

七、适用人群与小结

MarkPDFdown 适合这几类人:正在搭知识库/RAG、需要把大量 PDF 语料转成干净 Markdown 的开发者;经常处理论文、报告、扫描件,被传统转换工具的烂排版折磨过的研究与办公用户;以及想把文档转换嵌进自动化流水线的人——它的管道模式和 Docker 用法就是为这个场景准备的。反过来,如果你转的都是文字层干净的简单文档,传统免费工具就够用,不必为每页付一次模型调用费;如果文档涉密且不允许出内网,这类云端视觉方案也不合适。

总结一句:MarkPDFdown 把「PDF 转 Markdown」从规则工程问题变成了模型能力问题——版面理解交给当下最强的多模态模型,自己只做一层薄而稳的封装(LiteLLM 接入 + 文件/管道双模式 + 页码控制)。思路取巧,但效果实打实。仓库在 GitHub 上以 Apache-2.0 协议开源,装好之后先拿一份你手头最难搞的 PDF 试转几页,成稿质量会替它自己说话。

发表回复

后才能评论