PDF-Scribe

两阶段处理流程，可将任意 PDF 转换为可搜索、结构良好的 Markdown（内嵌 LaTeX 公式）和 JSON。底层由 Agnes-2.0-Flash 视觉模型驱动。

适用场景

在任何 PDF 转换请求触发时启用。尤其适用于以下场景：

• 含数学公式的学术 PDF → 公式自动转换为 $...$ 或 $$...$$ 格式的 LaTeX
• 幻灯片类 PDF（如 PowerPoint 导出的 PDF）→ 幻灯片内容被准确提取
• 图像密集型 PDF → 每张图像均配有文字描述
• 扫描版文档 → 利用视觉模型进行 OCR 识别
• 复杂排版、多栏布局、表格、图表等

首次配置

python scripts/setup.py

脚本将提示您输入 Agnes AI API Key 和 freeimage.host API Key。 密钥将保存至 config.json（该文件已被 .gitignore 忽略，绝不会提交至 Git）。

或者，您也可通过环境变量设置：

• AGNES_API_KEY — 您的 Agnes AI API Key
• FREEIMAGE_API_KEY — 您的 freeimage.host API Key

工作流

第一阶段：提取（scripts/extract.py）

python scripts/extract.py  [--out-dir ] [--dpi 200]

输出内容包括：

• pages/ — 各页面的 200 DPI 截图（PNG 格式）
• text/ — 各页面原始文本（通过 PyMuPDF 提取）
• images/ — PDF 中嵌入的图像
• meta.json — 页面总数、各文件路径等元信息

第二阶段：转录（scripts/convert.py）

python scripts/convert.py  [--format both]

将每张页面截图并发发送至 Agnes-2.0-Flash 视觉 API（5 个并发 worker，限速 20 请求/分钟），并在收到 429 或 5xx 错误时自动重试。中间结果按页暂存于 _transcribe_temp/ 目录以保障崩溃恢复能力，最终合并生成输出。

输出文件：output.md + output.json

断点续传支持

若转换过程被中断，重新运行 convert.py 即可 —— 系统会自动跳过已成功转录的页面。

输出格式

Markdown（output.md）

• 公式：使用 $f(x) = int_0^infty e^{-t} dt$ 或 $$frac{partial u}{partial t}$$ 等标准 LaTeX 语法
• 表格：采用标准 Markdown 表格语法
• 图像：以文字描述形式置于方括号中，并链接至原始提取出的图像文件
• 页面分隔：使用 --- 分隔符，并以 ## Page N 作为每页标题

JSON（output.json）

{
  "total_pages": 72,
  "successful": 70,
  "pages": [
    {"page": 1, "ok": true, "content": "..."}
  ]
}

配置项

关键常量定义于 scripts/convert.py 中：

• MAX_CONCURRENT = 5 — 并发 API 请求 worker 数量
• RATE_LIMIT_RPM = 20 — Agnes API 的速率限制（预留 20% 安全余量）
• MAX_RETRIES = 3 — 失败时最大重试次数
• DPI（位于 extract.py 中，默认值为 200；提高 DPI 可提升 OCR 质量，但会导致图像体积增大）

参考：PUA 字符映射表

当对 PowerPoint 导出的 PDF 使用原始文本提取工具（如 markitdown、PyMuPDF）时，部分数学符号会落入 Unicode 私有使用区（PUA）。文件 references/pua_map.py 提供了对应的映射表用于修复此类字符。如有需要，可在后处理阶段调用 fix_pua_text() 函数。

性能表现

性能瓶颈在于 Agnes API 的速率限制（20 请求/分钟），而非并发能力。