PDF 转 Markdown 用于 RAG:哪些内容能留下,哪些会丢
PDF 转 Markdown 能保留标题、列表、表格和加粗斜体;代码块的围栏、链接地址和图片会丢,扫描页返回空文件。
PDF 转 Markdown能把有文字层的 PDF 里的标题、项目符号列表和编号列表、表格、加粗和斜体保留下来,但会丢掉代码块的围栏、链接背后的网址和所有图片。只有一张图片的页面不会报错,而是返回 HTTP 200 加一个空文件,所以做 RAG 的流水线在建索引之前,必须先检查结果是不是空的。
把 PDF 转成 Markdown 用于 RAG,哪些内容能留下?
在有文字的页面上,结构和文字都能留下。测试用了 4 份一页的文档:先写成 Markdown,用 Markdown 转 PDF渲染成 PDF,再转回 Markdown。同一个函数分别统计源文件和返回结果里的标题、列表项、表格、围栏代码块、加粗、斜体、链接和图片的数量。测量日期 2026-10-23,在本地服务器上进行。文章文档的结果如下:
| 元素 | 源文件 | 转换后的输出 |
|---|---|---|
| 标题 | 1 个一级、3 个二级、2 个三级 | 1、3、2 个,级别不变 |
| 项目符号列表项 | 4 | 4 |
| 编号列表项 | 3 | 3 |
| 表格 | 1 个,4 行 3 列 | 1 个,4 行 3 列 |
| 加粗和斜体 | 各 2 处 | 各 2 处 |
| 单词 | 98 个 | 98 个全部找到 |
| 围栏代码块 | 1 个,4 行 | 0 个;4 行挤成了一行 |
| 链接 | 1 个 | 0 个;文字保留,外面包着 <u>…</u>,网址没了 |
| 图片 | 1 张(在另一份文档里) | 0;不返回图片文件 |
第二份文档是一份报告,有编号标题、4 列 5 行的表格,以及编号和项目符号列表,结果的各项数量都与源文件相同,119 个单词全部找到。数量是按个数比较的,没有逐行比对;单词比较是去掉标记、转成小写、不看顺序之后进行的。
这些 PDF 是服务自己生成的干净的文字 PDF。数字描述的是结构规整的文字 PDF,不代表任意文件的转换效果;扫描件、多栏页面、重复出现的页眉页脚和公式都没有测。反方向的转换见从 Markdown 到 PDF 再回来。
对 RAG 索引来说,标题和表格行会变成可以按行切分的纯文本,转换成功的三份文档里一个单词也没丢。另一方面,答案藏在代码清单的换行、链接地址或图里的问题,光凭转换后的文本是回答不了的。
哪些内容留不下:代码围栏、链接网址和图片
代码块会丢掉围栏和换行,所以 Markdown 里不再标明它是代码。链接保留可见文字,输出里外面包着 <u> 标签,网址则被丢掉;如果标签会成为噪声,嵌入之前先去掉。图片根本不会写回,画在图片里的文字也不会被读出来。
只有图片的页面会返回空文件,而不是报错
把文章的一页按 300 dpi 渲染成 PNG,再包回一个 PDF,对服务来说就是一份扫描件。PDF 转 Markdown 返回 200,内容类型是 text/markdown,正文 0 字节。PDF 转文本在同一个文件里找到的字符数是 0。
不必是纯扫描页才会返回空。同一张图旁边只有 31 个单词时,也是 200 加空正文;而同一张图旁边有 98 个单词,就能正常转换。分界线在哪里没有测,所以大半是图片的页面都应当视为有风险。
要检查拿回来的文件大小。下面两条命令分别通过 API 和命令行取得同一个结果,最后一行用来发现空文件。对扫描件,pdfx 0.1.0 的退出码是 0,并写出一个 0 字节的文件,curl 也一样,所以光看退出码是看不出来的。
curl -X POST "https://pdf123.xyz/api/v1/convert/pdf/markdown" -F "[email protected]" -o report.md
pdfx pdf-to-markdown report.pdf -o report.md
test -s report.md || echo "empty: no text layer"
从扫描件里取出文字
扫描件要先过 OCR。它默认输出 Markdown 文本,可以直接喂给 RAG 流水线;因为读的是像素,识别可能出错,见OCR 如何读扫描 PDF。另一种输出是可搜索的 PDF,保留 PDF 并加上一层不可见的文字层。
不要把两者串起来。两次运行里,把扫描页做成可搜索的 PDF 之后,再交给 PDF 转 Markdown,结果仍是 200 加空正文,尽管文字层确实存在:两次 pdftotext 都能读出来,第一次 PDF 转文本也读出来了。OCR 的 Markdown 输出没有在这里测量,所以上表说明不了它保留结构的程度。
常见问题
PDF 转 Markdown 会保留表格吗?
会,以竖线分隔的表格形式。两份测试里的表格,行数和列数都与源文件相同,表头行也算在内。合并单元格和多栏版式没有测。
代码块和链接能保留吗?
只能保留一部分。两者的文字都在,但代码块会丢掉围栏和换行,链接会丢掉网址。
转换出来的文件为什么是空的?
请求成功了,但服务没有返回任何 Markdown。扫描页是这样,大半是图片、只有几行文字的页面也是这样。状态码是 200,不是错误。对这个文件运行 OCR。
转 Markdown 之前一定要先 OCR 吗?
页面以文字为主、并且有文字层的 PDF 不需要;在阅读器里能选中文字,就说明文字层存在。如果 PDF 转 Markdown 返回空文件,就用 OCR,取它的 Markdown 输出。