invoice-ocr（发票 OCR）

增值税发票识别技能 (VAT Invoice OCR Skill)

概述

本技能支持 PDF（单页/多页） 和 常见图片格式 的发票识别，底层强依赖百度云增值税发票 OCR 接口，将非结构化文档转化为结构化数据，并输出为 Excel 报告。核心处理包含三个模块：

1. 发票检测 — 过滤非发票图像、初判发票类型。
2. 内容识别 — 调用百度云专用 API 提取核心字段（失败时自动降级通用 OCR）。
3. 质量评估 — 基于字段完整度和引擎置信度进行自动化打分。

工作流程

步骤 1：环境与凭证检查

在执行任务前，必须确认以下条件：

• 输入文件有效性：文件格式须为 .pdf / .png / .jpg / .jpeg 等支持的格式。
• 环境变量配置 (.env)：工作目录下必须存在 .env 文件，且包含 BAIDU_API_KEY 和 BAIDU_SECRET_KEY。

* 若未检测到配置，必须主动询问用户。若用户无凭证，引导其前往 百度智能云控制台 免费申请。

• 输出路径：确认最终生成的 Excel 文件存放位置（默认：result.xlsx）。

步骤 2：安装依赖并执行

# 1. 安装核心依赖
pip install pymupdf openpyxl requests Pillow python-dotenv --break-system-packages -q

# 2. 运行极简命令行
python invoice_ocr_main.py \
  --input <文件路径> \
  --output ./outputs/发票识别结果.xlsx

步骤 3：结果交付

向用户交付生成的 Excel 文件，并简明扼要地总结处理情况（例如："已成功处理包含 3 页的 PDF，成功识别 2 张增值税专用发票，1 页因非发票内容已跳过，请查看 Excel 汇总。"）。

核心架构与模块说明

脚本 invoice_ocr_main.py 的核心架构如下：

1. 输入处理 (InputHandler)

• 统一将不同类型的输入转化为标准的 JPEG 字节流列表。
• 对大尺寸图片（>3MB）或高分辨率图像自动执行比例裁剪和质量压缩，规避 API 负荷限制。

2. 发票检测 (InvoiceDetector)

• 基于图像尺寸进行初步过滤（剔除极小图片）。
• 结合 OCR 提取的文本内容，通过正则和关键词（如"增值税专用发票"、"价税合计"等）确切判定发票类型并输出置信度。

3. 内容提取 (ContentExtractor)

• 严格通过 python-dotenv 读取鉴权信息，获取并缓存 Access Token。
• 优先请求 vat_invoice 增值税专用接口。
• 若接口返回错误码（如非标准发票类型），无缝降级调用 general_basic 通用文字识别接口，并通过正则尽力挽救关键数据。
• 内置自动重试机制（最高 3 次，间隔递增），增强网络抗抖动能力。

4. 质量评估 (QualityAssessor)

系统对成功识别的发票进行满分 100 分的量化评估，权重分配如下：

评级标准：

• 🟢 优秀 (90-100)：无需人工干预
• 🟡 良好 (70-89)：建议抽查核心金额
• 🔴 较差 (<70)：必须人工核验或重新扫描

Excel 报告输出结构

数据导出为单 Sheet（"发票汇总"），主打高度概括和直观，包含以下核心列头：

• 页码
• 发票类型
• 发票号码
• 开票日期
• 销售方
• 购买方
• 价税合计
• 质量评估（直接展示红黄绿指示灯及评级，如 "🟢 优秀"）

边缘 Case 容错处理