paperclip：开源文档解析利器，把PDF变成LLM友好的Markdown

项目标题叫paperclip，第一次看到这个名字，我脑子里飘过的画面是办公桌上那个能把一堆散纸页夹在一起的小回形针。等我把这个开源项目部署起来，拿一份双栏排版、带着表格和公式的中文PDF实测过后，才意识到这个名字确实起得妙：它的用途就是把一堆结构混乱的扫描件、PDF和图片，夹成一份规规矩矩、带着标题层级和表格语法的Markdown文档，让大模型能直接读、直接查、直接拿去用。这个开源项目来自Google，目标非常聚焦——做文档解析，输出LLM友好的结构化文本。

我为什么觉得这东西值得专门写一篇经验帖？因为最近两年做RAG、做Agent、做企业知识库的人，很多还在跟PDF死磕。直接把PDF扔给向量模型，文本提取不干净，版面全乱；自己调OCR，识别出文字却丢掉了结构，双栏论文左右两栏混成一团；买商业解析服务，效果好但数据要出域，不少场景合规上就过不去。paperclip给出的是一条本地化、开源、可自托管的路。它适合AI应用开发者、数据工程团队、文档中台负责人，以及任何一个每天被扫描件和报表PDF折磨的人。以下内容围绕我在真实部署和调参中踩过的坑、验证过的方案和测出来的效果展开，尽量讲得具体一些。

1. 项目背景：为什么文档处理中间要插一层转换

1.1 它不是又一个OCR，而是LLM时代的文档预处理车间

传统OCR解决的是“把图像里的文字变成字符串”，这个能力说实话已经成熟很多年了。但在大模型场景里，光有字符串远远不够。你给大模型喂一份合同扫描件，它需要知道哪句话是条款标题、哪段是正文、哪个区域是表格、表格里的行和列分别是什么含义。更麻烦的是PDF本身有不同类型的版面，双栏论文、产品手册、财务报告、发票，每一种的阅读顺序都不一样。如果只是粗暴地把识别出来的文字按坐标堆在一起，语言模型再强，读到的也是一堆逻辑错乱的碎片。

paperclip做的事情更像是一个“文档预处理车间”。它会先做版面分析，把页面划分成标题、段落、表格、图片、页眉页脚等不同区块，再把区块按正确的阅读顺序重新排列，最后输出成结构化的Markdown。打个比方，传统OCR相当于把会议录音转成一段单纯文字，paperclip相当于把录音整理成带议程、发言人、决议事项的会议纪要。前者解决“有没有”，后者解决“能不能直接拿去干活”。

我自己的体会是，在RAG场景里这层转换非常关键。很多人做知识库时喂了一堆PDF进去，结果检索效果一直上不去，问题往往出在上游：句子被版面打乱，表格被拆散，模型检索到的是物理位置相邻、逻辑上毫无关联的内容。paperclip这类工具的价值就在这些看不见的地方。

1.2 为什么选用Rust和ONNX Runtime做推理底座

看这个项目的技术选型，能明显感觉到它不是为了“跑通Demo”而设计的。后端用Rust实现，这一点我很认可。Rust没有运行时GC，内存管理可控，写出来的解析服务在长时间批量运行时不容易出现莫名其妙的内存膨胀；同时它的计算密集型代码性能接近C/C++，适合承载OCR和版面分析这类推理任务。

推理层用的是ONNX Runtime，好处是统一了模型运行环境。同一套pipeline里的OCR模型、版面分析模型、表格识别模型，都可以导出成ONNX格式，在CPU或GPU上跑。实际测试下来，纯CPU推理确实可以跑，速度比GPU慢不少，但对很多内部知识库场景来说，CPU部署意味着不需要申请GPU资源，可以直接压在现有服务器上。数据全程本地处理，不上传第三方API，这一点对处理合同、医疗记录、内部报表的团队来说几乎等于刚需。

我记得有朋友问过，为什么不用GPT-4V这类多模态大模型直接解析PDF？这就要看场景了。如果只是偶尔解析几份几页的文档，多模态模型确实方便，把图片丢进去让它总结就行。但如果是每晚定时跑几千份文件，用API的成本、限流和延迟会非常难受。本地小模型组成的解析管线虽然单页精度上不如顶尖多模态大模型，但胜在稳定、便宜、可控，而且通过参数调整可以在很多常见文档类型上逼近可用水平。

2. 核心功能拆解：一份PDF进去，Markdown出来，中间发生了什么

2.1 版面分析与阅读顺序重建

paperclip处理PDF和图片的第一步，不是急着识别文字，而是先理解版面。这里的核心模型是layoutlmv3路线，也就是用视觉和文本特征联合做版面理解。它能把一页文档划分成文本块、标题块、表格区域、图片区域、页眉页脚等类别。这一步做得好不好，直接决定后面所有输出的质量。

举个最常见的反面例子：双栏论文。很多人把扫描PDF放进普通OCR工具里，结果左右两栏的文字交替出现，一会儿上一行是左栏，一会儿下一行是右栏，读起来完全没法用。paperclip在版面分析之后，会重建阅读顺序，把左栏从上到下读到底，再切到右栏继续读。实测中英文混合的双栏论文，只要原稿扫描清晰，输出的Markdown段落顺序基本是符合人阅读习惯的。

页眉页脚的去除也是在这里完成的。我在测试一份十几页的行业报告时发现，如果不处理页眉页脚，后面做文本切块时每一块都会混入页码和公司名，检索噪声非常大。paperclip会把这类重复性区块识别出来，在输出正文时过滤掉。这一步对知识库场景的意义，比想象中大得多。

2.2 表格识别与结构化输出

表格是多模态解析里公认的大坑。普通OCR能识别出表格里的文字，但很难还原出“哪几个单元格是表头、哪几列属于同一个逻辑分组、跨行单元格的值应该归属哪一行”。如果表格还原不对，识别出来的内容就是一堆散装的短语，喂给大模型做大模型分析基本等于灾难。

paperclip在表格处理上用了专门的表格识别模型，把表格区域进一步解析成行列结构，并最终输出为Markdown表格语法。实际测试下来，对于没有合并单元格、边框清晰的常规表格，输出的Markdown表格可以直接粘贴使用；对于带合并单元格或者套表头的复杂报表，能识别出大部分结构，但会出现局部错位，需要人工校对。

这里必须提醒一句：表格识别的效果严重依赖扫描质量。如果原稿是照片拍的报表或者传真件，行线不清晰，模型定位列边界时会犹豫，输出结果就会串列。我在测试时把一张模糊的票据照片丢进去，输出表格只能用“勉强能用”来形容。解决办法是尽量把文件转成高分辨率扫描件，或者先用图像预处理把倾斜纠正、把底色去掉。

2.3 公式、图片与多语言支持

学术文档里除了文字和表格，还有公式和插图。公式如果被识别成普通文本，结构会完全失真，比如分式被压成一行，上下标全乱。paperclip在管线里对公式区域有专门处理，能识别常见公式并转成近似LaTeX风格的表示，这个能力对论文、教材、技术手册类文档挺实用。精度当然做不到像Mathpix那样对复杂公式完美还原，但够用于检索和摘要场景。

图片提取这块，官方方案里用视觉特征做图像区域的抽取，而不是单纯靠坐标方框截图。这样遇到图文混排的页面，能更准确地判断哪些区域是真正的插图（比如流程图、架构图、产品图），哪些只是带底色的文本块。抽取出来的图片会保留在Markdown输出中，并给出相对位置。

多语言支持是paperclip的一个突出优势。它的OCR管线针对英文、中文、日文、韩文、越南文、泰文等做过适配。我做中英文混排测试时，同一页里中英文切换频繁，模型没有出现常见的“中文吐英文乱码”情况，整体识别率可以接受。如果你的业务里以东亚语言为主，这个项目会比很多默认只做西文优化的开源工具更合适。

2.4 为什么最终输出格式选Markdown

很多人会问，输出成纯文本不也一样吗？答案是不一样的。Markdown是一种带轻量结构的格式，标题层级、表格、代码块、列表这些语义都能保留，但token开销比PDF原生提取要小得多。大模型对Markdown结构的理解能力很强，喂进去的文本里如果明确区分了“# 这是一个章节标题”和普通段落，模型在生成答案时就能更好地引用原文。

从检索角度看，Markdown也更好切块。传统做法是把文本按固定长度切块，切到一半会把句子的语义斩断。paperclip给出的文档天然带着标题层级，你可以按标题把文档切成长度不等的语义块，再交给向量化模型。这种结构化切块比固定长度切块在召回率上通常有实实在在的提升。另外，对Agent场景来说，模型需要判断“该看哪个章节”，Markdown的层级结构让这种定位变得更可靠。

3. 从零跑通paperclip：部署方法与API实测

3.1 环境准备与资源评估

部署paperclip不算重，但也不是随便一台小机器就能扛。我自己实测的体感是：4核CPU、8GB内存起步，纯CPU推理的情况下，一份10页左右的扫描PDF，解析时间大概在40秒到几分钟之间，具体取决于页面复杂度和dpi设置。如果机器内存只有4GB，解析大文档时容易把内存吃满。有GPU的话批量处理会舒服很多，但纯CPU也能稳定跑。

我一开始是在一台8核16GB、无GPU的服务器上部署的。跑完几份测试文档之后发现，主要瓶颈是CPU和内存，只要不同时塞太多并发请求，稳定性没什么问题。所以我的建议是：先用手头的普通服务器试跑，如果并发量上来了再考虑加GPU，不需要一上来就追求硬件。

3.2 启动服务与验证

部署方式官方推荐用Docker镜像，我用的也是Docker。整个流程很简单：安装Docker后，从GitHub Releases页面找到对应的容器镜像名称并拉取，然后启动服务。启动命令大致如下，镜像名记得以你拉取到的实际名为准：

sudo docker run -d \ --name paperclip \ -p 8080:8080 \ --restart=unless-stopped \ ghcr.io/google/paperclip:latest

启动后先用日志和服务状态确认容器正常，再检查API是否可用：

docker logs -f paperclip curl http://127.0.0.1:8080/api/v1/swagger

如果Swagger接口能返回JSON，说明服务已经起来了。这里提醒一句：第一次启动时系统会加载OCR、版面分析、表格识别等模型，模型文件合计几个GB，拉取和初始化可能要等一段时间，看起来像“卡住”了，其实是还在加载。要判断它是真卡住还是正常加载，看日志里是否有进展输出即可。

3.3 核心API调用与参数说明

paperclip的REST接口核心思路很简单：上传文件，返回Markdown。我用的是/api/v1/process这个处理接口，具体路径和参数名建议以你本机Swagger页面上展示的为准，因为不同版本可能有微调。

最朴素的调用方式是用curl：

curl -X POST "http://127.0.0.1:8080/api/v1/process" \ -H "accept: application/json" \ -F "file=@test.pdf"

返回结果是一个JSON结构，里面包含解析出的Markdown全文。第一次测试时，先别急着写业务代码，直接在Swagger页面里传一个样本文件，观察真实返回结构里字段叫什么名字，再落到代码里。

关于参数，最影响结果的两个方向是输入文件的清晰度和语言设置。如果处理中文扫描件，建议把语言相关的配置指到中文模型；如果原稿清晰度不够，调高dpi通常能提升表格和文字的识别率。但dpi也不是越高越好，纸张类的扫描件一般300dpi足够，太高了服务端耗时和内存占用会明显上升。

3.4 用Python写一个批处理脚本

为了把paperclip接进日常工作流，我写了一个最简单的Python批处理脚本：遍历某个目录下的所有PDF，调用本地服务解析，把返回的Markdown保存成文件。脚本很朴素，但足够作为扩展的起点。

import requests import sys import time from pathlib import Path API_ENDPOINT = "http://127.0.0.1:8080/api/v1/process" def parse_pdf(path: str) -> str: with open(path, "rb") as f: resp = requests.post(API_ENDPOINT, files={"file": f}, timeout=600) resp.raise_for_status() data = resp.json() # 字段名以你 Swagger 里看到的实际返回为准 return data["result"]["markdown"] def main(): input_dir = Path(sys.argv[1]) out_dir = Path("markdown_output") out_dir.mkdir(exist_ok=True) for pdf in sorted(input_dir.glob("*.pdf")): t0 = time.time() md = parse_pdf(str(pdf)) out = out_dir / (pdf.stem + ".md") out.write_text(md, encoding="utf-8") print(f"{pdf.name} -> {out} ({time.time() - t0:.1f}s)") if __name__ == "__main__": main()

脚本的用法是python batch_parse.py ./pdf_folder。实际跑批量任务时，我建议在这个基础上再加三样东西：失败重试、并发限制、结果日志。因为批量解析时总会碰到个别坏文件或者超时情况，把这些考虑进去能省很多手工检查的时间。

注意：我特意把timeout设成了600秒，因为复杂文档第一次解析时模型加载和版面分析都耗时较长，超时设太短容易被误杀。如果服务已经预热完，一般几十秒内就能返回。

4. 部署中常见问题与排查技巧实录

4.1 首次启动模型下载卡住或失败

第一次启动paperclip时，容器会自动下载模型。如果日志长时间停在模型下载环节，或者报下载失败，最常见的原因是网络问题和磁盘空间不足。先确认服务器能正常访问模型下载地址，再确认磁盘剩余空间够放几个GB的模型文件。

如果自动下载一直不成功，可以手动把模型文件下载好，放到容器指定的模型目录下，再重启容器。具体模型存放路径以项目文档为准。这样处理后启动会明显变快。我在一台内网服务器上部署时就是先手动放模型再启服务，绕开了下载超时的问题。

4.2 解析速度慢到无法接受

解析慢要先看是不是第一次启动、模型是否已经加载到内存。模型预热后，速度通常会快很多。如果预热后仍慢，检查dpi设置。很多人图省事直接设600dpi，结果一份10页文档跑五分多钟。我的经验是300dpi够用的别设太高。还有就是不要一次性塞太多并发请求，CPU资源被争抢后单页耗时反而飙升。

4.3 表格输出结构错乱

我在测试中发现的典型问题是：原稿本身表格线不清晰，或者表格跨页，输出时列对不齐。遇到这种情况，先看原稿是不是扫描角度歪了，歪了的话先做倾斜纠正；然后考虑提高扫描dpi；如果表格带多级表头和复杂合并单元格，paperclip只能做一个大致还原，需要人工校对后入库。

4.4 常见问题速查表

这些坑我基本都踩过一遍，尤其是表格识别和内存问题，在批量场景里最容易暴露。建议正式上线前，先拿20份不同版式的真实文档做一轮摸底测试，明确哪些文档类型可以直接自动入库，哪些需要人工介入。

5. 从“能跑”到“好用”：paperclip在实际业务里的三个玩法

5.1 给RAG知识库做高质量数据清洗

现在做RAG的人最大的痛点之一是“收进来的都是垃圾，检索出来的自然也是垃圾”。直接用PyPDF这类库提取PDF文本，遇到扫描件基本歇菜；用开源OCR工具，结构又丢了。paperclip的定位正好卡在中间：它输出的Markdown带着标题层级、表格和段落边界，这些信息对后续切片极其有用。

我建议把知识库处理流程改成：paperclip解析成Markdown后，按标题层级做切块，每一块再向量化。标题本身可以作为这块文本的元信息保存，检索时能给出更精确的上下文。对合同这类文档，一节标题往往就是一个法律条款，这种切块方式比按字符数硬切要科学得多。

5.2 给Agent提供文档阅读工具

如果你在做Agent或者工具调用，paperclip可以直接作为“读文档”的底层能力暴露给模型。Agent拿到一份PDF路径后，调用解析服务得到Markdown，再让模型基于这个Markdown回答用户问题。比起直接给Agent塞原始PDF或图片，这种做法的优势在于：模型收到的输入已经是结构清晰的文本，token消耗更少，信息密度更高。

我测试过一个场景：让Agent从一份几十页的行业报告里找出某个指标的定义和出处。把PDF先解析成Markdown后，Agent能通过标题快速定位到相关章节，回答时还能引用原文段落。如果直接给Agent塞多页图片，先不说视觉模型的成本，光是长上下文带来的注意力分散就够头疼了。

5.3 搭建批量文档转Markdown的流水线

把paperclip放进生产流水线时，我建议不要直接把它暴露到业务请求里，而是做成异步任务。目录监听或者消息队列收到新文件后，调用解析服务，解析结果写入存储，失败任务自动重试，处理完的文档进入人工抽检池。这种“自动化为主、人工兜底”的模式在文档中台场景下用得最稳。

批量流水线要注意两个细节：一是建立文档指纹去重，同一个文件重复上传会浪费算力；二是记录每个文件的解析耗时和异常日志，这样几百份文件跑下来，你能快速找出那只“坏苹果”。我跑过三百多份混合文档的批量任务，整体成功率很高，出问题的基本集中在模糊扫描件和超大表格文件上。

结尾

我自己跑完paperclip最大的体会是：这个项目并不追求把每个字符都识别得完美，它更在意把文档的骨架完整拆出来。回形针的妙处不是把纸张变得多好看，而是把一堆散乱的东西变成一份能直接拿走、能继续加工的材料。如果你准备把它用进数据处理管线，别把它当黑盒先跑一次，拿一批不同版式的真实文档做几分钟摸底，摸清强项和边界，再写进生产流程。最后分享一个我实际用的技巧：先拿低dpi快速扫一遍整本PDF，定位哪些页面的表格或公式有问题，再对少数重点页面单独调高dpi重跑。这样省时间，也不会让个别差页拖垮整批任务的进度。