扫描包变文字:先 OCR,再压缩你仍要保留的 PDF
扫描包要分两步走:OCR 返回 Markdown 或可搜索的 PDF,压缩则通过重新编码 PDF 里的图像与流来缩小你仍要留存的那份文件。

所谓“扫描包”,通常是一叠页面图像钉成的一份 PDF:占磁盘,却搜不了、复制不了。人们爱把两个工具串起来用,但这两个工具干的是不同的活。OCR 返回文字,默认是 Markdown,也可以是可搜索的 PDF;压缩 重写你仍要保留的那份 PDF。
这个分工本身就是整条工作流。
这里的 OCR 实际给你什么
POST /api/v1/misc/ocr-pdf 跑识别,默认下载到的是一个 .md 文件(text/markdown),内容是原生 PDF 文本与图像页 OCR 结果的融合。传入 outputFormat=pdf 则改为返回可搜索 PDF:每一页按 300 dpi 渲染,由 Tesseract 识别,页面图像连同不可见的文本层一起返回,每次请求最多 50 页。Agent 或流水线要读文字时用 Markdown,需要在文件里选择和搜索时用 PDF。
Auto 与 Force 的区别(仅 Markdown 输出):
- 除
ocrType=force-ocr以外的任何值(包括门户上标着“Normal”的那个)都归 Auto:有现成文本的地方用它,对纯图像页做 OCR。 force-ocr则重读每一页,包括本来就有文本层的页。
门户表单只在选择可搜索 PDF 输出时显示语言选择器(12 种语言),该输出读取 languages(最多四个 Tesseract 语言代码,用 + 连接,默认 eng)。Markdown 输出没有语言设置,旧路径遗留的字段(deskew、clean 之类)两种输出都会忽略。Auto 与 Force 的取舍,以及坏扫描为什么识别不出来,见 OCR 是怎么读扫描 PDF 的。
OCR 不会把 PDF 变小。Markdown 下载是原扫描包旁边多出来的第二份产物,可搜索 PDF 则是按 300 dpi 页面图像重建的第二份 PDF,所以可能比原扫描件更大。
压缩放在哪一步
压缩(POST /api/v1/misc/compress-pdf)跑的是 qpdf 流压缩:--compress-streams=y、flate 重压缩,加上生成对象流。它还会把能解码的页面图像(JPEG,以及普通 RGB 或灰度)重新编码为质量 75 的 JPEG,把最长边超过 2000 px 的图像缩小,只有结果更小时才保留;给了 targetSizeMb 时,会以更低的质量和尺寸重试,最多七档,直到文件达标。它不造文本层,不子集化字体。已经很紧的文件收益可能很小。流与图像两种杠杆的背景见 压缩 PDF 时实际发生什么。
对要归档或邮件发送的那份 PDF 用压缩,需要文字时用 OCR 的 Markdown 输出。先压缩不会让 OCR 更准,还可能更差,因为压缩会缩小页面图像;先 OCR 也不会让 PDF 更小。
一条实用的顺序
- 查看器打不开这个包:先 修复 或 获取信息。
- 对扫描包做 OCR:要文字就出 Markdown,要一份能搜索的副本就出可搜索 PDF,并抽查几页文字。
- 如果体积仍是问题,另取 PDF 的副本(扫描包,或文本层在一次测试里仍可搜索的可搜索 PDF)做压缩。
- 规定要求时,保留未经处理的原件。
加密文件在任一步之前仍需授权的 解锁。敏感内容要用 清理 / 自动涂黑,不是 OCR。扫描件导出表格返回 204,说明没找到文本列:先 OCR 成可搜索 PDF,再决定电子表格工具是否用得上(空表格导出(204))。
该盯住的几份输出
跑完一轮,你手上可能有三份东西:原扫描包、一份 .md 的 OCR 下载或可搜索 PDF,以及可选的压缩后 PDF 副本。给它们贴上标签。只发 Markdown 会丢掉页面图像;只发原扫描包的压缩副本,依然没有可选可搜的文本层。既要文字又要更小 PDF 的流水线,可以先 OCR 成可搜索 PDF 再压缩这份文件,分两次请求或用一次 POST /api/v1/pipeline 调用都行,也可以把 Markdown 和压缩后的 PDF 当作两份输出存下来。
对文本层已损坏的原生数字包做 Force OCR 仍可能有用;对干净的原生数字包做 Auto,则可能完全跳过 OCR 运行。两种模式都不会把文字写回 PDF;可搜索 PDF 输出对两者都不理会,由 Tesseract 读取每一页。
这条工作流不是什么
扫描包之所以翻车,是因为团队假定一个按钮既能抽文字、又能像桌面 OCRmyPDF 流水线那样压小像素。在这里,文字默认以 Markdown 形式离开,PDF 仍是 PDF,除非你刻意去压缩它。没有哪一次 OCR 调用能返回“同一份 PDF,现在既可搜索又更小”:可搜索 PDF 是按 300 dpi 页面图像重建的新文件,一次测试里 69 KB 的单页扫描件变成了 253 KB 的可搜索 PDF,压缩后是 118 KB。
同一批 op 的 HTTP 自动化见 开发者。