PDF 转 Markdown：质量优先指南

先判断手上的 PDF 属于哪一类

转换质量在你点「转换」之前就已经决定了。一份 PDF 要么带有坐标信息的文本层，要么只是文字的图片，要么两者混在一起——每种情况该走的路径都不一样。判断错的典型后果是：Markdown 看着挺正常，其实悄悄丢了半页内容。

十秒钟自测

• 试着选中一句话。 如果光标能连续选中一串文字，说明有可提取的文本层。
• 搜索一个你眼睛能看到的词。 明明看得见却搜不到，说明这页是图片，或者字体的字符映射坏了——两种都需要 OCR。
• 翻中间几页，别只看封面。 年报和手册经常在数字文件里夹着扫描件附件。
• 留意双栏、侧边栏和横向表格。 文字是有的，但它在文件里的存储顺序，通常不是人的阅读顺序。

成熟的生产流程应按页决定路径，不能因为四页扫描件就把 200 页全部送进模型。当前转换器只在检查到整份 PDF 都是图像页时切换到 Moondream；混合 PDF 仍走 Cloudflare 文本路径，需要检查扫描附件是否为空。

还有一条捷径值得先确认：如果这份 PDF 本来就是 Word 导出的，而原始 .docx 还能找到，就直接转 .docx。标题样式、自动编号、表格单元格这些在 PDF 里要靠反推的结构，Word 文件里原本就有——word转markdown 工具会直接读它们，并把丢掉的部分列出来。

PDF 转 Markdown 到底会在哪里出错

下面这些是最值得核查的失效模式，按浪费时间的程度排序。每一项都能在首页的样例里看到。

• 阅读顺序。 双栏论文常常是一段左栏、一段右栏交替存储的。粗糙的提取器会把两栏交织在一起，于是左栏的句子直接接上了右栏。arXiv 论文样例就是这类问题的标准测试用例。
• 重复的页面装饰。 页眉、页脚、页码、水印、版权声明，在提取器眼里都是普通文字，会直接插进正文中间——中文技术报告每页都重复一个页码标记，arXiv 论文的标题上方还压着一段转载声明。
• 表格。 PDF 里的表格不是数据，只是放在特定坐标上的文字，旁边画了几条线。合并单元格会被压平，多行单元格会被拆成多行，跨页的表格会变成两张互不相关的表。财务报表样例这三种情况都有。
• 公式。 行内公式通常会变成一堆错位字符：上下标被压平、希腊字母丢失、间距消失。如果公式重要，你需要的是能输出 LaTeX 的解析器，而不是文本提取器。
• 脚注与图注。 它们不在正文流里，所以要么整段消失，要么被插进某个段落中间。
• 中日韩文本。 中文 PDF 还要多处理全角标点、没有词边界、以及竖排版面。按英文调参的提取器会在每个字之间插空格，或者干脆吞掉标点。

不要「看一眼觉得没问题」，要真的核验

最大的陷阱是「看起来很合理」的 Markdown。读起来通顺的输出，仍然可能少了一条脚注、一行表格，甚至一整栏文字。五分钟走一遍下面的流程，能抓住绝大部分问题：

1. 把每页的第一个和最后一个区块和原文对一下。阅读顺序的问题最先在页边界和栏边界露出来。
2. 在 Markdown 里搜三个你在图、图注、脚注里看到的词。搜不到，就知道是哪一类内容被丢掉了。
3. 看标题大纲。一份 30 页的手册只产出两个标题，说明标题识别失败，你的 Markdown 没有可导航的结构。
4. 每份文档至少抽查一张表格——优先挑有合并单元格的，或者跨页的那张。
5. 粗略比较每页的字数。某页明显比邻页少很多，通常是扫描页、图片密集页，或者编码失败。

核验能成立的前提是把证据与推测分开。本实现保留处理方法和 Markdown 偏移；Cloudflare 返回页标记时保留页码，Moondream OCR 区块保留置信度。提供方没有给坐标时，坐标会明确留空。

表格：转换之前先决定策略

PDF 表格没有唯一正确的 Markdown 表示方式，所以先想清楚这张表要用来做什么。GFM 表格好读但表达不了合并单元格；HTML 能保住版面但难编辑；JSON 保住了数据但它不是文档。

{
  "type": "table",
  "page": 9,
  "bbox": null,
  "readingOrder": 14,
  "method": "cloudflare-markdown",
  "confidence": null,
  "notes": "Cloudflare toMarkdown 未提供"
}

JSON 的价值不在格式本身，而在证据字段保持明确：能归页时写页码，坐标或置信度没返回时写 null，并保留稳定的 Markdown 偏移供后续检查。

OCR：按页付费，而不是按文档付费

OCR 是任何转换流程里最贵的一环——既费时间也费钱，而大部分文档并不需要处处都上。以下情况才该用：

• 整页提取不出任何文字，或者产出的文字明显比邻页少很多。
• 提取出来是乱码字符，通常意味着内嵌字体没有可用的字符映射。
• 这页是照片、签署过的附件，或者一张你确实需要其中标注的示意图。
• 表格的结构比文字更重要，而它的线条是画上去的、不是编码出来的。

普通文本 PDF 会在本地分析后交给 Cloudflare 文档转换。它不用视觉 OCR，但 PDF 仍然会上传。纯扫描 PDF 则在本地渲染后发送给 Moondream 3.1，详见整体设计和当前计价状态。

只以照片形态存在的页面——白板、笔记本、纸质讲义——不必先装订成 PDF 再进流程。Markdown 相机可以把手写笔记直接拍照转 Markdown：一次最多三张照片，返回同样的分块结果，拍下来的内容不用绕路就能接上面的流程。

按 Markdown 的去处选择输出格式

解析一次，再按去处渲染。干净的阅读版 Markdown、Obsidian 笔记、文档站页面、检索分块，是同一次解析的不同产物。

这五种都在转换工具的输出格式区域，且都基于同一份分流转换结果。

一套可复用的流程

1. 先让浏览器检查文档，建立预览并判断是否存在可用文本层。
2. 文本 PDF 交给 Cloudflare 文档转换；纯扫描 PDF 渲染成图像后交给 Moondream 3.1 OCR。
3. 先核对被标记的页面：扫描件、表格和公式是最需要人工复核的地方。
4. 按上面的五分钟流程核验，任何看着不对的地方都用页码和原页预览回去查。
5. 导出与去处匹配的格式；如果这份文档重要，把来源映射一并留下。

这样的结果更容易审计：不是因为某个工具声称准确率 99%，而是服务返回的页级归属会被保留，缺失的证据也会明确留空。在处理重要文档前，先拿一份真实样例试一次。

PDF 转 Markdown 的常见疑问