PDF 文档转译器

为什么要把 PDF 变成 Markdown

PDF 一旦生成，内容就「锁」在版式里。开发者想把它接进 RAG 管道、喂给 LLM、或者存进版本库时，常见的几个坑：

• 用纯文本抽取工具拿到的数学公式变成 ∫0∞ 这类乱码，符号落在 Unicode 私用区（PUA），没法检索也没法复现。
• 扫描件没有文本层，PyMuPDF 抽取结果是空字符串，只能走 OCR。
• 幻灯片转出来的 PDF 分栏错位、图片和说明文字对不上，多栏排版更是把阅读顺序打乱。
• 逐页抠图再人工描述，100 页的论文要耗掉一整个下午。

核心机制：先抽取，再视觉转写

PDF-Scribe 是一个两阶段流水线，背后靠 Agnes-2.0-Flash 视觉模型做页面理解。

第一阶段 scripts/extract.py 干的是确定性工作：用 PyMuPDF 把每页渲染成 200 DPI 的 PNG，同时抽出原始文本层和内嵌图片，写入 meta.json。这一步不碰模型，快且可复现。

第二阶段 scripts/convert.py 把每页截图发给视觉 API，做真正的版面理解。它内置了工程上的几个关键细节：

• 并发与限流：5 个并发 worker，但 API 侧控制在 20 req/min，并预留 20% 安全余量。
• 失败重试：遇到 429 或 5xx 自动重试，最多 3 次。
• 崩溃续跑：每页结果单独落到 _transcribe_temp/，中断后重跑会跳过已完成页，不用从头再来。

输出端同时给两份产物：output.md 里公式是 $f(x) = \int_0^\infty e^{-t} dt$ 这样的 LaTeX，表格用标准 Markdown 语法，图片用文字描述加原文链接，页间用 --- 分隔；output.json 则给程序消费。

适用边界与注意点

需要配置 AGNES_API_KEY 和 FREEIMAGE_API_KEY 两个密钥，凭证保存在本地 config.json，记得别提交进仓库。

性能瓶颈在 API 限流而非并发。200 DPI 下实测：10 页约 30 秒，100 页约 6 分钟。想提 OCR 精度可以调高 DPI，代价是图片体积变大、请求变慢。

一个容易忽略的细节：用 markitdown 或 PyMuPDF 直接抽 PPT 生成的 PDF 时，数学符号会掉进 PUA 区。仓库里的 references/pua_map.py 提供了映射表，需要时调用 fix_pua_text() 做后处理。

图片描述由视觉模型生成，是文字转述而非原图嵌入，下游如果要做精确视觉匹配，这个环节要额外验证。