PDF 表格 OCR 识别转 Excel
功能
将 PDF 文件（尤其是扫描件）中的表格通过腾讯云 OCR 识别，智能映射到指定 Excel 模板列，输出结构化 Excel 文件。
支持两种 OCR 引擎自动对比：
- RecognizeTableAccurateOCR（表格识别 V3）：通用表格识别，支持 PDF 直传，返回单元格坐标 + base64 Excel，适合多行交易明细
- BankSlipOCR（银行回单识别）：银行回单专用，返回键值对，适合单张回单/凭证
触发条件
- 用户提供 PDF 文件并要求识别其中的表格
- 用户有银行流水/对账单 PDF 需要转为 Excel
- 用户提到"PDF 转表格""OCR 识别""银行流水提取"等
前置条件
1. 腾讯云 API 密钥（AK/SK）—— 必须
脚本通过环境变量 TENCENTCLOUD_SECRET_ID / TENCENTCLOUD_SECRET_KEY 读取凭证。
如何获取 AK/SK
- 登录腾讯云控制台：https://console.cloud.tencent.com/
- 进入访问管理 → API密钥管理：https://console.cloud.tencent.com/cam/capi
- 点击「新建密钥」，获取：
-SecretId— 标识用户身份的长字符串（约36字符）
-SecretKey— 用于加密签名的密钥（约32字符）
- ⚠️ SecretKey 只在创建时显示一次，请立即保存！ - 开通 OCR 服务（均有免费额度，无需付费即可使用）：
- 表格识别V3：https://console.cloud.tencent.com/ocr/recognizetableaccurateocr
- 银行回单识别：https://console.cloud.tencent.com/ocr/bankslipocr
设置环境变量
# macOS / Linux（临时生效）
export TENCENTCLOUD_SECRET_ID="你的SecretId"
export TENCENTCLOUD_SECRET_KEY="你的SecretKey"
# 可选：地域（默认 ap-guangzhou）
export TENCENTCLOUD_REGION="ap-guangzhou"
# macOS 永久生效（写入 ~/.zshrc）
echo 'export TENCENTCLOUD_SECRET_ID="你的SecretId"' >> ~/.zshrc
echo 'export TENCENTCLOUD_SECRET_KEY="你的SecretKey"' >> ~/.zshrc
source ~/.zshrc
# Windows PowerShell
$env:TENCENTCLOUD_SECRET_ID="你的SecretId"
$env:TENCENTCLOUD_SECRET_KEY="你的SecretKey"
> 脚本启动时会自动检查环境变量是否设置，未设置时打印完整获取指引并退出。
2. Python 依赖
pip install tencentcloud-sdk-python PyMuPDF XlsxWriter openpyxl
> 脚本启动时会自动检查依赖是否安装，未安装时提示安装命令。
3. 腾讯云 OCR 服务
需要在腾讯云控制台开通以下服务（均有免费额度）：
- 表格识别 V3（RecognizeTableAccurateOCR）
- 银行回单识别（BankSlipOCR）
使用方法
基本用法
python scripts/pdf_table_ocr.py <PDF路径> [更多PDF...] [选项]
参数说明
| 参数 | 说明 | 默认值 |
|---|---|---|
pdfs |
PDF 文件路径（可多个） | 必填 |
--template, -t |
Excel 模板路径（读取表头） | 无（使用内置默认表头） |
--output, -o |
输出 Excel 路径 | <PDF名>_OCR结果.xlsx |
--engine, -e |
OCR 引擎：auto/v3/bankslip |
auto |
--region, -r |
腾讯云地域 | ap-guangzhou |
示例
# 单个 PDF
python scripts/pdf_table_ocr.py 银行流水.pdf --template 模板.xlsx -o 结果.xlsx
# 多个 PDF（每个 PDF 一个 Sheet）
python scripts/pdf_table_ocr.py 工行.pdf 建行.pdf --template 模板.xlsx -o 合并结果.xlsx
# 仅用 V3 表格识别
python scripts/pdf_table_ocr.py 流水.pdf --engine v3
输出说明
每个 PDF 生成两个 Sheet：
1. 主数据 Sheet（PDF 文件名）：按模板 13 列结构输出，V3 识别的表格数据
2. BankSlip Sheet（{文件名}_BankSlip）：BankSlipOCR 识别的键值对，供对比参考
模板列映射
脚本自动将 OCR 识别的表头映射到模板列：
| 模板列 | OCR 表头关键词 |
|---|---|
| 业务日期 | 业务日期、账日期、交易日期、记账日期、日期 |
| 结算方式 | 结算方式、凭证种类、交易方式 |
| 支票号 | 支票号、凭证号、凭证号码 |
| 摘要 | 摘要、备注、说明 |
| 借方金额 | 借方金额、借方发生额、借方发生金额 |
| 贷方金额 | 贷方金额、贷方发生额、贷方发生金额 |
| 对方单位 | 对方户名、对方单位、对方名称 |
| 类/款/项/支付令/财政项目号 | 精确匹配（短关键词不子串匹配） |
| 来源名称 | 自动填入 PDF 文件名 |
> 未匹配到的模板列留空。
核心处理逻辑
- PDF 读取：PyMuPDF 获取页数，base64 编码传给 OCR API
- V3 表格识别：逐页调用 RecognizeTableAccurateOCR，PdfPageNumber 指定页码
- 表格重建：
- 过滤单格文本块（标题/元数据误识别为表格）
- 去重合并表头（合并单元格导致相邻列重复）
- 合并交替行（日期行+摘要行 → 单行，金融数据相同时自动合并）
- 过滤表头重复行
- 跨页表头智能检测（不只是精确匹配，还检测表头关键词模式，如"入账日期"≠"账日期"但都是表头） - BankSlip 识别：同时调用 BankSlipOCR 获取银行回单键值对
- 列名映射：关键词匹配（短关键词精确匹配，长关键词子串匹配）
- 数据清洗（OCR 识别后、入表前的数据加工，非直接入表）：
- 日期标准化：检测文档中已有的 4 位年份（如"2026"）作为参考年份，自动修正 OCR 误读的 2 位年份日期（如"16-05-06" → "2026-05-06"，而非错误的"2016-05-06"）
- 跨页重复表头过滤：扩展表头关键词集合（含"入账日期"等变体），检测并过滤混入数据的表头行
- 残留文本行过滤：过滤只有第一列有内容、其余列全空的 OCR 误识别行（如标题文字"工资#5.2934批量发放"被识别为单行表格）
- 单元格清理：None → ""，摘要列中泄露的表头文字（"摘要"/"备注"/"说明"）→ 清空
- 全空行跳过：跳过清洗后所有列均为空的行 - Excel 输出：xlsxwriter 按模板结构写表头 + 数据，金额列自动转数字
注意事项
- OCR 误读自动修正：V3 OCR 常把"2026"误读为"16"，脚本通过检测文档中正确的 4 位年份自动修正（同一份银行流水不会跨 3 年以上，差距过大视为 OCR 误读）
- PDF 大小限制：base64 编码后不超过 10MB
- API 频率限制：V3 为 2次/秒，BankSlip 为 10次/秒，脚本自动逐页处理
- 多页 PDF：跨页表格自动拼接，跨页重复表头自动跳过（含表头关键词变体检测）
- 凭证种类=0：银行流水中凭证种类/凭证号常为 "0"，这是原始数据如此
- 交替行模式：工商银行明细账中，日期和摘要在同一单元格内换行显示，OCR 会拆成两行，脚本自动检测并合并
文件结构
pdf-table-ocr/
├── SKILL.md ← 本文件
├── scripts/
│ ├── pdf_table_ocr.py ← 核心脚本
│ └── requirements.txt ← Python 依赖
└── references/
└── api_reference.md ← 腾讯云 OCR API 参考
