LlamaIndex 教程:如何程序化提取 PDF 数据,从判断文件实际内容入手
LlamaIndex 发布 PDF 数据提取教程,主张写代码前先用 pypdf 判断文件属于原生数字、扫描还是混合类型,再选库。教程对比 pypdf、pdfplumber、PyMuPDF 与 Camelot 的许可、速度与表格能力,其中 PyMuPDF 约比 pdfplumber 快十倍,但采用 AGPL-3.0 或商业双许可。
LlamaIndex:产品、工程与评测·2026-11-19 00:00· 42 分钟前AI 评分56
如何以编程方式从 PDF 中提取数据:先弄清文件里实际有什么
AI 导读
LlamaIndex 发布 PDF 数据提取教程,强调写代码前先判断文件是原生数字、扫描还是混合类型,并给出用 pypdf 分类文本层的示例。教程对比 pypdf、pdfplumber、PyMuPDF 和 Camelot 的许可、速度与表格能力,讲解双栏交错、缺 ToUnicode 映射和连字等常见坑,指出 Tesseract OCR 会丢失表格结构。
正文 · 原文
如果你打开一份银行对账单的原始字节,打印“Total”的那一行看起来会像 BT /F1 10 Tf 72 712 Td (Total) Tj ET。
这是一条指令:在字体 F1 中,于距左边缘 72 个单位的位置绘制五个字形。文件中的另一处,另一条指令在向右几百个单位处绘制“$4,210.00”。该格式从未说明这两个字符串属于同一组、位于同一表格行,甚至从未说明页面上有表格。
PDF 只是描述墨迹落在哪里。你的眼睛重建出段落、分栏和单元格。提取库也必须重建它们。

这就是为什么学习如何以编程方式从 PDF 中提取数据时,大部分工作都在你写任何代码之前。你选择的库取决于你拥有什么类型的文件,而最常见的错误就是不做检查就直接跳到 pip install。
在本指南中,我们将按照决策实际出现的顺序展开:这是什么类型的文件,开源库能从中提取出什么,扫描件会怎样,以及字符串如何变成字段。然后我们会看看如何把这一切合并为一次调用。
在选择库之前,先弄清你的 PDF 是否有文本层
你将要处理的每份 PDF 文档都属于以下三类之一:
- 原生数字。从 Word、ERP 或报表工具导出。库可以直接读取。
- 扫描件。每一页都是纸张的照片。文本提取返回空,因此需要 OCR。
- 混合型。带有扫描签名页的数字合同,或带有纯图片附录的对账单。这类文档会破坏为另外两类构建的流水线。
比例完全取决于你的文件来自哪里。在一个基于 Enron 数据构建的 4,911 份文件的合成 测试语料库中,44% 是数字文件,40% 是已经应用了 OCR 层的扫描件,16% 是纯图片。FOIA 公开文件或旧法院档案库看起来会非常不同。唯一能知道你的分布的方法就是测量:
from pypdf import PdfReader
def classify(path, min_chars=50):
"""Label each page 'text', 'scan', or 'empty', then label the whole file."""
labels = []
for page in PdfReader(path).pages:
text = (page.extract_text() or "").strip()
if len(text) >= min_chars:
labels.append("text")
elif page.images:
labels.append("scan")
else:
labels.append("empty")
if all(label == "text" for label in labels):
return "born-digital", labels
if "text" not in labels:
return "scanned", labels
return "mixed", labels
在一个文件夹上运行它,你会得到一张路由表。不过,它不会捕捉所有失败模式。有人已经跑过 OCR 的扫描件会被当作“文本”通过,即使隐藏的文本层是垃圾。如果一份“可搜索”扫描件提取出的文本读起来像字母汤,就把该文件当作扫描件,从页面图像重新提取,而不是信任多年前某人跑过的 OCR 结果。
原生数字 PDF:提取文本只需一行,提取结构则不然
在干净的原生数字文件上,从 PDF 中提取 文本 确实很容易。如果你只需要提取文本用于搜索或快速摘要,一次库调用就能完成,你可以到此为止。当你需要知道哪些词属于同一组时,困难才开始。
在 pypdf、pdfplumber 和 PyMuPDF 之间选择
你在每个教程中都会看到的这些库承担不同的工作:
| 库 | 许可证 | 速度 | 词位置 | 表格 | 最适合 |
|---|---|---|---|---|---|
| pypdf | BSD-3 | 中等 | 否 | 否 | 纯文本,零依赖 |
| pdfplumber | MIT | 慢(约 3.4 秒/文档) | 是,按词和字符 | extract_tables() |
调试布局、带框线的表格 |
| PyMuPDF | AGPL-3.0 或商业许可 | 快速(约 0.34 秒/文档) | 是,单词和文本块 | find_tables() |
批量处理 |
| Camelot | MIT | 中等 | 否 | Lattice 和 stream 模式 | 基于文本的 PDF 中的表格 |
这些速度数据来自 对 200 个 Common Crawl PDF 的 pdftext 基准测试,在 Apple Silicon 笔记本电脑上按文档逐一测量,结果显示 PyMuPDF 比 pdfplumber 快约十倍。许可证一列也很重要。PyMuPDF 采用 AGPL 或商业许可的双重授权,因此 将其打包进 SaaS 产品或分发的二进制文件中,要么使你受到 copyleft 条款约束,要么意味着需要向 Artifex 购买许可证。
下面是同一首页的三种读取方式:
from pypdf import PdfReader
text = PdfReader("statement.pdf").pages[0].extract_text()
import pdfplumber
with pdfplumber.open("statement.pdf") as pdf:
words = pdf.pages[0].extract_words() # dicts with text, x0, top, x1, bottom
import pymupdf # older code imports this as fitz
doc = pymupdf.open("statement.pdf")
blocks = doc[0].get_text("blocks") # (x0, y0, x1, y1, text, block_no, type)pypdf 调用返回一个字符串。另外两个返回坐标,而本指南后续内容都依赖于坐标。
第一周就会遇到的三个 Bug
分栏内容被交错读取。在双栏页面上,文本提取会横跨页面整个宽度直接读取。我们构建了一个双栏测试文件,pdfplumber 返回的第一行是“Left column. The beneficial owner Right column. Officers and...”,这是两栏各半句话粘在一起。解决办法是在提取前裁剪每一栏:
with pdfplumber.open("filing.pdf") as pdf:
page = pdf.pages[0]
mid = page.width / 2
left = page.crop((0, 0, mid, page.height)).extract_text()
right = page.crop((mid, 0, page.width, page.height)).extract_text()这能奏效,直到下一份文档把栏间距放在别的位置。
(cid:42) 会代替字母出现。未嵌入 ToUnicode 映射的字体只会给提取器字形 ID,而无法将它们转回字符。pdfminer.six(pdfplumber 构建于其上)会打印 (cid:NN) 占位符,这是其 FAQ 中最常见的问题之一,而 其他库可能返回看似合理的乱码。有些工具可以从嵌入字体自身的表中重建映射,但文件中往往没有任何内容能将那些字形映射回字母。这些页面即使技术上带有文本层,也应归入 OCR 处理路径。
连字会破坏匹配。排版文档常将“fi”存储为单个字符 U+FB01,因此搜索“financial”会错过“financial”。对你提取的所有内容运行 unicodedata.normalize("NFKC", text)。
表格:原生数字文档不再轻松的地方
对于带框线的表格,pdfplumber 的 extract_tables() 和 Camelot 的 lattice 模式都表现良好。在我们的测试对账单上,两者都准确返回了四行:
import camelot
tables = camelot.read_pdf("statement.pdf", pages="1-end", flavor="lattice")
rows = tables[0].df # a pandas DataFrameCamelot 的文档 建议对有边框的表格使用 lattice,对仅由空白分隔的表格使用 stream。两种模式都不适用于扫描件,因为两者都读取文本层。而且两者都不知道第 4 页的交易表会延续到第 5 页。合并的表头单元格、表格中间重复的表头行,以及换行到下一页的滚动余额,都会变成你需要编写和维护的代码。在一份 30 页的经纪对账单上,这种拼接代码往往比脚本其余部分加起来还长。我们关于 如何从 PDF 中提取表格 的指南单独讨论了这个问题。
大多数快速教程展示的是在 PNG 上运行 Tesseract,这跳过了你真正需要的步骤:从扫描的 PDF 文件 转换为图像。这一步需要 poppler 进行渲染,还需要 Tesseract 二进制文件本身,两者都需在操作系统层面安装:
from pdf2image import convert_from_path
import pytesseract
pages = convert_from_path("scanned.pdf", dpi=300)
text = "\n".join(pytesseract.image_to_string(img) for img in pages)Tesseract 自身的指导是 以 300 DPI 或更高分辨率渲染,而纠偏和阈值处理在边缘情况下有帮助。如果你更愿意留在原生数字文档技术栈中,ocrmypdf scanned.pdf searchable.pdf 会为文件添加文本层,让 pdfplumber 或 Camelot 接手处理。
问题在于 Tesseract 返回给你的结果。image_to_string 返回的是一个扁平字符串。表格结构丢失了。扫描一份带有独立借方和贷方列的账单,每一行返回时都变成一行,末尾只有一个数字,因此一笔 $3,250.00 的存款和一笔 $1,450.00 的房租付款看起来一模一样。在一次测试运行中,房租付款被读成了 "1 450.00",逗号丢失了。
分隔线会显示为游离的 = 和 | 字符。印章和签名会变成游离字符,手写字段大多消失。Tesseract 确实通过 image_to_data 报告逐词置信度,但除非你也编写相应代码,否则这套技术栈中下游没有任何环节使用它。预处理能让字符更干净。它无法恢复 OCR 未能捕获的版面布局。如需了解在扫描件和图像上更进一步的工具,请参阅我们对 OCR 软件 和 图像转文本转换器 的对比。

文本在被映射到字段之前仍然不是数据
到目前为止,一切产出的都是字符串。下游系统想要的是记录:invoice_number、due_date、total,以及一个行项目列表。通常的下一步是基于标签锚定的正则表达式:
import re
match = re.search(r"Invoice\s*(?:#|No\.?|Number)[:\s]*([A-Z0-9-]+)", text)来自五十个供应商的发票
该模式对你编写时所针对的供应商有效。第二个供应商打印的是 "Inv. Ref",第三个把编号放在标签上方,第四个因为列太窄而把它拆成两行。每个正则表达式都是一个自定义模板,而一个接收来自五十个供应商发票的应付账款团队最终要维护五十个这样的模板。这正是 发票数据提取 工具存在的意义所在,我们关于 自动化发票处理 的文章详细说明了为什么行项目是难点。
银行和券商对账单
对账单有一个发票不具备的特性:它们能自我校验。期初余额加上每笔交易应等于期末余额,因此分页处漏掉一行会表现为不匹配:
assert abs(opening + sum(t["amount"] for t in transactions) - closing) < 0.01无论使用哪种提取工具,都要把这类校验写进代码。总额应当能加总,日期应当能解析,必填字段绝不应返回 null。银行对账单 OCR 的成败取决于这种完整性。
看看这个自己动手的技术栈已经变成了什么样子。有一个文本层检查、在三个库之间做选择、用 Camelot 处理表格、用 Tesseract 处理扫描件、列裁剪启发式规则,以及一层正则表达式胶水。每个分支都以自己的方式失败。工程成本在于每当出现新的文档类型时都要维护这种分支。
一条流水线应对所有分支:使用 LlamaParse 进行解析和提取
LlamaParse 用智能体式 OCR 取代了这种分支。在读取任何内容之前,一次具备版面感知能力的视觉处理会标记页面:这个块是正文文本,那个区域是带框线的表格,这个角落是扫描的签名,那个方框是条形图。随后智能体式编排会为每个区域选择一个读取器(干净印刷体用传统 OCR 引擎,表格或图表用视觉语言模型),并按阅读顺序将结果拼接回去。
你不必运行扫描检查、添加 Tesseract 作为回退方案,也不必为跨分页的表格编写拼接代码。以编程方式从 PDF 中提取数据的四分支方式变成了一次调用:
from llama_cloud import LlamaCloud
client = LlamaCloud() # reads LLAMA_CLOUD_API_KEY from the environment
file = client.files.create(file="statement.pdf", purpose="parse")
result = client.parsing.parse(
file_id=file.id,
tier="agentic",
version="latest",
output_options={"markdown": {"tables": {"output_tables_as_markdown": True}}},
expand=["markdown"],
)
for page in result.markdown.pages:
print(page.markdown) # tables come back as Markdown tables, scans included当你需要字段而不是 Markdown 时,LlamaParse 接受一个 schema 并返回符合该 schema 的 JSON,于是正则表达式层也消失了。下面的 schema 就是同一个对账单记录,包含交易列表:
import time
from pydantic import BaseModel, Field
from llama_cloud import LlamaCloud
class Transaction(BaseModel):
date: str = Field(description="Posting date as printed")
description: str
amount: float = Field(description="Negative for debits")
class Statement(BaseModel):
account_number: str
opening_balance: float
closing_balance: float
transactions: list[Transaction]
client = LlamaCloud()
uploaded = client.files.create(file="statement.pdf", purpose="extract")
job = client.extract.create(
file_input=uploaded.id,
configuration={
"data_schema": Statement.model_json_schema(),
"extraction_target": "per_doc",
"tier": "agentic",
},
)
while job.status not in ("COMPLETED", "FAILED", "CANCELLED"):
time.sleep(2)
job = client.extract.get(job.id)
statement = job.extract_result # a dict shaped like Statement拿它去跑一份单页报表,该报表把借方和贷方分列在两栏中打印,返回结果如下(已截取十笔交易中的前三笔):
{
"account_number": "4417-0092-3381",
"opening_balance": 2104.87,
"closing_balance": 7166.42,
"transactions": [
{"date": "09/02/2026", "description": "Payroll Deposit ACME CORP", "amount": 3250.0},
{"date": "09/03/2026", "description": "Rent Payment - Oakview Apts", "amount": -1450.0},
{"date": "09/05/2026", "description": "Whole Foods Market #1021", "amount": -87.42}
]
}PDF 里没有任何负号。amount 字段上的 "Negative for debits" 描述把两栏合并成了一个带符号的数字,正因如此,我们为 DIY 代码写的余额校验无需改动就能对 statement 运行并通过。对于包含数百个重复行的文档,我们关于提取重复实体的文章介绍了行级提取目标,而解析与提取一文则解释了何时该用哪一种。关于页面定位和图表解析选项,请参阅我们的LlamaParse PDF 解析操作指南。
成本足够具体,可以与工程时间相权衡。解析按层级按页计价:Fast 为 1 个 credit,Cost Effective 为 3 个,Agentic 为 10 个,Agentic Plus 为 25 个;Pro 计划下每千个 credit 为 1.25 美元,按需付费为 1.50 美元。

在准确性方面,我们用保险申报文件、财务报告和政府文件构建了 ParseBench,总计约 2,000 页,每一页都经过人工核验。LlamaParse Agentic 以总体 84.9%、表格 90.7% 的成绩位居榜首,每页成本约 1.2 至 1.5 美分。测试是我们写的,产品也是我们卖的,所以请带着这一点来看待我们的第一名成绩。
排行榜位于 parsebench.ai,数据集和评测代码均已公开,其表格评分方法值得用于你自己的评测。如果你想看外部视角,我们会持续进行 AI PDF 解析器、AI 数据提取工具、文档解析 API 和 自动化文档提取软件 的对比。
一点提醒:对于干净的原生数字文件,如果你只需要文本,pypdf 免费、本地运行且够用。如果你想要一个本地方案,同时还能处理偶尔的扫描件,我们的开源项目 LiteParse 可在你的机器上运行,并内置 OCR。当文档必须留在你自己的环境中时,LlamaParse 也可以通过 Enterprise 计划部署在你自己的云账户或数据中心,并且 Cost Effective 和 Agentic 层级的解析可以运行在你托管的模型上。一旦出现扫描件、表格或供应商格式的多样性,LlamaParse 就值回其成本。
最难的那十分之一 PDF 决定了技术栈
任何库在演示 PDF 上看起来都不错。你实际选择的是:谁来维护针对扫描件、混合文件和表格密集文件的分支逻辑,而这些文件正是第一节中的分类器所分拣出来的。在我们看到的流水线中,这些文件通常按数量是少数,却占用了大部分工程时间,因为每新增一种供应商或报表格式,就要多一个裁剪框、多一条正则表达式、多一条页面拼接规则。
所以从测量开始。对一文件夹你实际收到的文档运行 classify(),看看“扫描”和“混合”两个桶的大小。如果它们是空的,就保留你的 pypdf 脚本。如果不是,就把那个桶交给 LlamaParse,并将它的表格与你的 DIY 分支产出的结果逐行对比,以余额校验作为裁判。这是在你自己的文件上公平测试如何以编程方式从 PDF 中提取数据的方法,而且你可以用注册时获得的 10,000 个免费 credit 来运行。
来源:LlamaIndex:产品、工程与评测 · llamaindex.ai
来源:RadarAI · aihot.news