有边框的表,pdfplumber 默认参数就够用,13 行 5 列 0.12 秒全对。没有边框的表,默认参数返回空列表,也不报错。PyMuPDF 的 table.extract() 会把小数点搬到格子末尾,1280.00 变成 128000,金额静默差 100 倍。这三句话就是本文的全部结论,下面是六份文件、六条路线的实测过程。
六份文件、六条路线,先看行数对不对
我按国内最常见的六种表格形态,用 reportlab 生成了六份 PDF,每份都留了逐格金标:有边框的订单表、同内容但去掉全部线条的无边框表、带跨行合并的区域表、单元格文字折三行的合同表、跨两页的 60 行物料表、带千分位与括号负数的财务表。
每条路线都跑这六份文件。三条路线来自三个库:pdfplumber 0.11.10、camelot 2.0.0、PyMuPDF 2.1。PyMuPDF 我拆成两条,直接用 table.extract() 和用单元格坐标重新取文本,因为这两者结果差得太远。camelot 拆成 lattice 与 stream 两个 flavor。
测试机是 M4 加 16GB 内存,Python 3.13.12,macOS 27.3。每份文件都很小,单页 13 行以内,所以下面的耗时是从进程启动到出结果的端到端时间,含库导入,不是纯解析耗时。
| 表格形态 | 金标行数 | pdfplumber 默认 | camelot lattice | camelot stream | PyMuPDF extract | PyMuPDF 取坐标 |
|---|---|---|---|---|---|---|
| 有边框订单表 | 12 | 12 | 12 | 13 | 12 | 12 |
| 无边框同内容 | 12 | 0 | 0 | 13 | 12 | 12 |
| 跨行合并区域表 | 6 | 7 | 7 | 8 | 7 | 7 |
| 单元格折三行 | 5 | 5 | 5 | 16 | 5 | 5 |
| 跨两页 60 行 | 60 | 60 | 60 | 61 | 60 | 60 |
| 财务表千分位 | 7 | 7 | 7 | 8 | 7 | 7 |
合并表那一行全部是 7,因为表格区域里有一行跨四列的标题「2026 年销售明细」,三个库都把它当成了一行数据。真实文档里这种情况到处都是,标题、注释、页码只要跟表格贴得够近,都会被吃进来。
camelot stream 每一行都多 1 行,多出来的就是表格上方那行标题文字。stream 不认线条,靠文字间距聚类,表外的文字与表内第一行间距一致时就被一起圈进来。这个行为不是 bug,但你得自己检查首行。
为什么先看行数,而不是单元格准确率
单元格准确率是个虚荣指标。把 12 行数据识别成 24 行,每行拆成两半,只要字没丢,单元格命中率仍然接近 100%,可你再也没法用它做求和与透视。所以本文的主指标是行准确率:整行五个格子逐格完全匹配才算命中一行。
第二个指标是数字保真率。金标里凡是含数字的单元格,必须在输出里逐字找到,一个字符都不能变。千分位、小数点、括号、货币符号都算字符。这一条专治各种静默篡改,也是本文最有用的一个指标。
评分脚本不长,核心就是两次集合比:
def norm(c):
return " ".join(str(c or "").split())
gt_rows = [tuple(norm(c) for c in r) for r in gold_rows]
got_rows = set(tuple(norm(c) for c in r) for r in out_rows)
row_acc = sum(1 for r in gt_rows if r in got_rows) / len(gt_rows)
数字保真则把金标里含数字的格子提出来,逐个看是否原样出现在输出的单元格集合里。凡是出现「数字对了但符号没了」的情况,这一项立刻掉下去,而行准确率可能还很好看。
有边框的表:默认参数直接过
六份文件里,59 分的那份反而最简单。有完整横竖线条的表,pdfplumber 默认的 lines 策略一次命中 12 行,行准确率与数字保真率都是 1.000,端到端 0.116 秒,峰值内存 45.6MB。代码只有五行:
import pdfplumber
with pdfplumber.open("t1_grid.pdf") as pdf:
for page in pdf.pages:
for table in page.extract_tables():
for row in table:
print(row)
camelot 的 lattice 用同一份文件也拿到 12 行全对,代价是 0.621 秒与 335MB 峰值内存。它的内部逻辑是把页面转成图像再做形态学检测,所以第一次调用会连带把 opencv 拉起来,内存与时间都花在这上面。如果你手上全是 Word 或 Excel 导出的带线表,这两个都能用,差别只在启动成本。
PyMuPDF 在这一档就已经出问题了。行数是 12,看起来对,但数字保真只有 0.250。订单号 SO-2026-1001 出来是 SO20261001 - -,1280.00 出来是 128000 .。问题不在识别,在拼接顺序,我放到最后一节单独讲。
没有边框:返回空列表,而且不报错
把同一张表的线条全部去掉,只留文字对齐,pdfplumber 的 extract_tables() 返回 []。camelot 的 lattice 返回 0 张表,也不抛异常。两条默认路线在这个场景下都是百分百静默失败,你只能靠「本以为有表却拿到空」来发现。
pdfplumber 的修法是换策略,把垂直与水平边界都改成按文字位置推断:
settings = {
"vertical_strategy": "text",
"horizontal_strategy": "text",
}
tables = page.extract_tables(table_settings=settings)
rows = [r for r in tables[0] if any(c and c.strip() for c in r)]
改完能拿到 12 行数据,五个格子全对,数字保真 1.000。但原始输出是 25 行,每行数据后面跟着一行全空的占位行。原因是 text 策略在相邻两行文字之间画了一条零高度的分隔线,于是每行被切成两半,下半是空的。这行过滤不能省,省略以后行准确率仍然是 0,因为行集合根本对不上。
我还试了容差。text_x_tolerance 从 1 调到 20,text_y_tolerance 从 1 调到 3,六种组合下输出行数一模一样,都是 25。这批文件的字号统一、行高一致,容差在 1 到 20 点之间没有改变任何一条边界。所以网上那种「把容差调到 5 就好了」的经验,只在行距忽宽忽窄的文档里成立,不能当通用解。
camelot 的 stream 在这个场景反而是最省事的,一次给出 13 行,其中 12 行数据全对,多出来的是表格上方那行标题。它靠空白间距聚类,天然不吃线条。代价是不认线条也就意味着它会连着表外的文字一起吃。
跨页表:两张表拼成一张,表头要自己去重
60 行物料表跨了两页,每页都重复表头。三条路线都给出两张独立的表,第一张 41 行(1 行表头加 40 行数据),第二张 21 行(1 行表头加 20 行数据)。没有任何一个库会把它们合成一张,也没有任何一个库告诉你第二张表是第一张的续页。
拼的时候只要多做一步判断,表头就能去掉:
header = None
all_rows = []
for page in pdf.pages:
for table in page.extract_tables():
if header is None:
header = table[0]
all_rows.extend(table[1:])
elif table[0] == header:
all_rows.extend(table[1:])
else:
all_rows.extend(table)
跳过表头这一步不能靠「第一行长得像表头」,要靠与首页表头逐格相等。有些报表第二页的表头会换一种写法,比如把「金额」写成「金额(元)」,逐格比较就会失败,这时你会得到一行假的表头夹在数据中间,做求和时会算进去。我的建议是拼完之后再抽查一次行数,60 行就是 60 行,多一行就说明表头没去掉。
这批表如果后面要进检索库,拼好的整表还要再按语义切分,字段名与数值必须落在同一个块里,否则查「华东区 Q2 数量」会命中一堆只有数字的块。切分粒度的实测数据在另一篇里,这里不展开。
单元格内换行:折成三行的文字会碎成两行数据
这一档最能体现路线差异。同样一份合同表,5 行数据,第二列是折了两三次行的长条款摘要。pdfplumber 默认路线给出 5 行,行准确率 0.600,三行对两行错。camelot lattice 一模一样。PyMuPDF 取坐标也是 0.600。
错的原因很细:折行处被拼回了一格,但插入了一个半角空格。三年维保 变成 三年维 保,不含硬件与实施服务 变成 不含硬 件与实施服务。数字保真掉到 0.900 也是这个原因,条款里的 HT-2026-0311 被空格切开了。
去掉中文之间的多余空格,五行立刻变全对:
import re
def join_cjk(s):
return re.sub(r"(?<=[一-鿿]) (?=[一-鿿])", "", s)
这个正则在中文与中文之间删一个空格,不会动到英文单词之间、数字与单位之间的空格。中文文档里折行拼接产生的假空格,绝大多数都是这种形态。
换成 text 策略与 stream,情况更糟。两者都把折行当真换行,一行数据被拆成两三行,输出 10 行与 16 行,行准确率直接归零。所以结论很直接:有边框、文字会折行的表,用默认的 lines 策略反而是最稳的那条,别急着上 text。
踩坑:PyMuPDF 的 extract() 把标点搬到格尾
这是本轮最值得写下来的一条。行数完全正确、格子位置完全正确的表,PyMuPDF 的 table.extract() 出来的数字仍然是错的,而且错得很有规律:标点全部被挪到单元格末尾。
订单号 SO-2026-1001 变成 SO20261001 - -,两个连字符跑到最后。1280.00 变成 128000 .,小数点跑到最后。¥1,284,560.00 变成 128456000 ¥ , , .,货币符号、两个千分位逗号、小数点全被追加在末尾。16.5% 变成 165% .。
| 文件 | 数字格数 | extract() 数字保真 | 改用坐标取文本 |
|---|---|---|---|
| 有边框订单表 | 48 | 0.250 | 1.000 |
| 无边框同内容 | 48 | 0.250 | 1.000 |
| 跨行合并区域表 | 12 | 1.000 | 1.000 |
| 单元格折三行 | 20 | 0.250 | 0.900 |
| 跨两页 60 行 | 300 | 0.400 | 1.000 |
| 财务表千分位 | 21 | 0.000 | 1.000 |
财务表那一行是 0.000,21 个数字格一个都没保住。原因是这张表的数值都由货币符号、千分位、小数点组成,标点占比越高,被搬走的越多。如果你的流水线只用 extract(),把这些字符串直接塞进 float(),结果要么是异常,要么是静默偏差 100 倍。1280.00 被拼成 128000 时,float 转换是成功的。
修法是不用 extract(),改成先拿到单元格的矩形,再按矩形取文本:
import pymupdf
doc = pymupdf.open("t6_finance.pdf")
page = doc[0]
table = page.find_tables().tables[0]
for row in table.rows:
cells = []
for rect in row.cells:
if rect is None:
cells.append("")
else:
cells.append(" ".join(page.get_text("text", clip=rect).split()))
print(cells)
同一个库、同一份文件,数字保真从 0.250 直接到 1.000,财务表从 0.000 到 1.000。代价几乎为零,端到端耗时从 0.293 秒变成 0.312 秒,多出来的 19 毫秒是逐格取文本的开销。合并单元格那一档会出现 None 的矩形,也就是被合并覆盖的格子,所以那句判空必须写。
这不是我造的文件才有。用公开论文做交叉验证,第 8 页的 BLEU 对照表有 13 个含数字的格子,extract() 有 10 个把小数点搬到了格尾或独立成行,占 76.9%;换成坐标取文本,13 个全部正常。同一页里上标仍然会丢,1.0·10^20 出来是 1.0 · 1020,这个靠坐标修不了,得回到原始字体信息去拼。
顺带记一个反直觉的地方:PyMuPDF 的单元格数量可以用来判断有没有合并。len(table.cells) 在规整表上等于行数乘列数,在合并表上是 25 而 8 乘 4 等于 32,差值 7 就是被合并吃掉的格子。这条比看 whitespace 更直接,但它不告诉你哪几格合并了,恢复结构仍然要自己填。
成本与选型
三个库装在一个干净虚拟环境里,实际体积差得比想象中大。装 pdfplumber 拉 9 个包、占 58MB;camelot 拉 15 个包、占 237MB,大头是 opencv;PyMuPDF 拉 13 个包、占 266MB。
| 路线 | 安装包数 | 占用体积 | 单页端到端耗时 | 峰值内存 | 内置质量自评 |
|---|---|---|---|---|---|
| pdfplumber 默认 | 9 | 58MB | 0.116 秒 | 45.6MB | 无 |
| pdfplumber text | 9 | 58MB | 0.113 秒 | 45.5MB | 无 |
| camelot lattice | 15 | 237MB | 0.621 秒 | 335.2MB | accuracy 100.0 |
| camelot stream | 15 | 237MB | 0.307 秒 | 109.1MB | accuracy 99.2 |
| PyMuPDF extract | 13 | 266MB | 0.293 秒 | 330.1MB | 无 |
| PyMuPDF 取坐标 | 13 | 266MB | 0.312 秒 | 331.9MB | 无 |
camelot 的 accuracy 请当作参考,别当质量证明。无边框那张表 stream 给 99.2,但它把表外标题吞进来了;合并单元格那张表 lattice 给 99.6,但六行数据里有四行的区域是空的。这两个数字衡量的是「检测到的框与文字的贴合程度」,完全不看结构对不对。看到 99 就放心入库,是这个库最容易踩的心态坑。
选型的顺序我是按这个逻辑走的。全页都是带线表格、要压内存、要快,用 pdfplumber 默认策略,45MB 的内存占用是其余路线的七分之一。表里没有线条,先试 pdfplumber 的 text 策略并过滤全空行,失败再换 camelot stream,换的时候一定检查首行有没有多出表外文字。
需要坐标、需要自己画框调试、或者要处理旋转与嵌套,用 PyMuPDF,但必须走 cells 加 clip 这条路,extract() 只能用来快速看一眼有没有表。合并单元格多、要做成能透视的宽表,三个库都得配合同一段前向填充代码,写一次就够。
三份文件里如果出现扫描件,上面所有路线全部失效,因为它们读的都是文本层。扫描件要走 OCR,中文识别选型与带表格图像的读法各有实测,整份 PDF 转 Markdown 的选型也另有一篇,链接放在下面。
- PDF 转 Markdown 选 docling 还是 MinerU:三份文件实测
- Qwen3-VL 读表格实测:900px 全对,手机拍的返回空
- 中文 OCR 怎么选:RapidOCR 与 Tesseract 十二图实测
- RAG 切分怎么设:200 到 1600 字实测召回差一倍
常见问题
pdfplumber 返回空列表,是不是文件坏了
绝大多数情况是这张表没有线条。默认策略靠线条定位,没有横竖线的表格一律返回空,而且不抛异常。先确认这份 PDF 能不能用鼠标选中文字,能选中就是有文本层,然后换成 text 策略再跑一次。
camelot 的 accuracy 显示 99,能不能直接入库
不能。这个数字只看单元格与检测框的贴合度,不看行数对不对,也不看合并单元格有没有展开。实测里 99.2 的那张表吞了表外标题行,99.6 的那张表四行区域是空的。入库前至少核一次行数,再抽查一列数字。
合并单元格哪个库能自动展开
一个都不能。PDF 里没有合并这个概念,只有没画的线,三个库看到的都是一格有字两格空白。统一做法是自己前向填充,填充条件里要带上「下一列有值」这个判断,否则空行会把上一组的值串到下一组。
延伸阅读
- 网页正文提取怎么选:trafilatura 与 readability 十页实测15 小时前
- 小米开源 Xiaomi-OCR-0:0.8B 参数 95.24 分文档解析登顶3 周前
- Cloudflare 文档提取 AI:19.3 秒 vs GLM-5.3 的 61.7 秒1 月前
- OXR 文档解析三榜登顶:1.3B 参数与 101 秒百页速度3 周前
继续读
往下这几篇值得接着看:
- 网页正文提取怎么选:trafilatura 与 readability 十页实测2026-11-21
- MCP 服务怎么开 HTTP 端口:六类报错实测与多进程 4042026-11-20
- uv 国内加速怎么配:装 Python 从 13.8 秒到 0.86 秒2026-11-11
