【技术干货】大模型文档结构化提取实战：Python解析PDF发票并批量生成CSV

摘要： 本文实现一套PDF发票结构化处理流程，涵盖文本解析、字段约束、大模型抽取、JSON校验与CSV导出，帮助开发者快速构建适用于财务、保险及合同审查场景的文档自动化能力。

文章目录

• • 一、背景介绍
  • 二、核心原理
  • • [2.1 统一文档处理流水线](#2.1 统一文档处理流水线)
    • [2.2 Schema约束与确定性输出](#2.2 Schema约束与确定性输出)
    • [2.3 MCP与API的适用边界](#2.3 MCP与API的适用边界)
  • 三、实战演示
  • • [3.1 环境准备](#3.1 环境准备)
    • [3.2 完整批量提取代码](#3.2 完整批量提取代码)
  • 四、工具/技术资源选型
  • 五、注意事项
  • • [5.1 扫描件与复杂表格](#5.1 扫描件与复杂表格)
    • [5.2 数据可靠性与安全](#5.2 数据可靠性与安全)
    • [5.3 性能优化](#5.3 性能优化)
  • 六、全文总结

一、背景介绍

企业文档通常以PDF、扫描件或复杂表格存在。传统方案需要串联OCR、文档分类器、版面分析模型与字段提取器，不仅链路较长，而且任一组件输出变化都可能导致后续流程失败。

大模型能够理解非固定模板，但直接让模型"总结发票"并不能保证结果可供程序使用。实际开发的核心问题是：如何将非结构化文档稳定转换为字段明确、类型统一、可验证的JSON数据。

本文采用"PDF解析 + Schema约束 + 大模型抽取 + 程序校验"的处理架构，并默认调用claude-opus-4-8。该模型性能强悍，擅长复杂逻辑推理、长文本处理、代码生成与纠错，适合复杂票据、合同及合规材料的结构化分析。

典型应用场景包括：

• 批量提取发票号码、金额、税额与供应商信息；
• 将合同条款转换为合规审查清单；
• 对保险单据、财务凭证进行分类和归档；
• 为RAG知识库生成带来源信息的结构化元数据。

二、核心原理

2.1 统一文档处理流水线

可靠的文档抽取不应由单次提示词完成，而应拆分为四个阶段：
#mermaid-svg-x25ThhXdaIqZXHNM{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-x25ThhXdaIqZXHNM .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-x25ThhXdaIqZXHNM .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-x25ThhXdaIqZXHNM .error-icon{fill:#552222;}#mermaid-svg-x25ThhXdaIqZXHNM .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-x25ThhXdaIqZXHNM .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-x25ThhXdaIqZXHNM .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-x25ThhXdaIqZXHNM .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-x25ThhXdaIqZXHNM .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-x25ThhXdaIqZXHNM .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-x25ThhXdaIqZXHNM .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-x25ThhXdaIqZXHNM .marker{fill:#333333;stroke:#333333;}#mermaid-svg-x25ThhXdaIqZXHNM .marker.cross{stroke:#333333;}#mermaid-svg-x25ThhXdaIqZXHNM svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-x25ThhXdaIqZXHNM p{margin:0;}#mermaid-svg-x25ThhXdaIqZXHNM .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-x25ThhXdaIqZXHNM .cluster-label text{fill:#333;}#mermaid-svg-x25ThhXdaIqZXHNM .cluster-label span{color:#333;}#mermaid-svg-x25ThhXdaIqZXHNM .cluster-label span p{background-color:transparent;}#mermaid-svg-x25ThhXdaIqZXHNM .label text,#mermaid-svg-x25ThhXdaIqZXHNM span{fill:#333;color:#333;}#mermaid-svg-x25ThhXdaIqZXHNM .node rect,#mermaid-svg-x25ThhXdaIqZXHNM .node circle,#mermaid-svg-x25ThhXdaIqZXHNM .node ellipse,#mermaid-svg-x25ThhXdaIqZXHNM .node polygon,#mermaid-svg-x25ThhXdaIqZXHNM .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-x25ThhXdaIqZXHNM .rough-node .label text,#mermaid-svg-x25ThhXdaIqZXHNM .node .label text,#mermaid-svg-x25ThhXdaIqZXHNM .image-shape .label,#mermaid-svg-x25ThhXdaIqZXHNM .icon-shape .label{text-anchor:middle;}#mermaid-svg-x25ThhXdaIqZXHNM .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-x25ThhXdaIqZXHNM .rough-node .label,#mermaid-svg-x25ThhXdaIqZXHNM .node .label,#mermaid-svg-x25ThhXdaIqZXHNM .image-shape .label,#mermaid-svg-x25ThhXdaIqZXHNM .icon-shape .label{text-align:center;}#mermaid-svg-x25ThhXdaIqZXHNM .node.clickable{cursor:pointer;}#mermaid-svg-x25ThhXdaIqZXHNM .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-x25ThhXdaIqZXHNM .arrowheadPath{fill:#333333;}#mermaid-svg-x25ThhXdaIqZXHNM .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-x25ThhXdaIqZXHNM .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-x25ThhXdaIqZXHNM .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-x25ThhXdaIqZXHNM .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-x25ThhXdaIqZXHNM .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-x25ThhXdaIqZXHNM .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-x25ThhXdaIqZXHNM .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-x25ThhXdaIqZXHNM .cluster text{fill:#333;}#mermaid-svg-x25ThhXdaIqZXHNM .cluster span{color:#333;}#mermaid-svg-x25ThhXdaIqZXHNM div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-x25ThhXdaIqZXHNM .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-x25ThhXdaIqZXHNM rect.text{fill:none;stroke-width:0;}#mermaid-svg-x25ThhXdaIqZXHNM .icon-shape,#mermaid-svg-x25ThhXdaIqZXHNM .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-x25ThhXdaIqZXHNM .icon-shape p,#mermaid-svg-x25ThhXdaIqZXHNM .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-x25ThhXdaIqZXHNM .icon-shape .label rect,#mermaid-svg-x25ThhXdaIqZXHNM .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-x25ThhXdaIqZXHNM .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-x25ThhXdaIqZXHNM .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-x25ThhXdaIqZXHNM :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} PDF文档
文本或OCR解析
大模型字段抽取
JSON校验与标准化
CSV或业务数据库

图1：PDF结构化提取流水线

文本型PDF可以直接读取字符层；扫描型PDF必须先经过OCR。解析结果进入大模型前，应保留页码、表格标题等上下文，避免同名字段发生错误关联。

2.2 Schema约束与确定性输出

大模型输出具有概率性，因此需要在提示词中明确字段名称、数据类型、缺失值规则和输出格式。例如金额统一为数值类型，日期统一为YYYY-MM-DD，无法确认的字段返回null，禁止模型根据常识补全。

API层将temperature设置为0，可以降低同一文档多次执行时的结果波动。模型返回后还需要执行JSON反序列化和字段白名单过滤，不能直接写入生产数据库。

2.3 MCP与API的适用边界

MCP适合在Claude、Cursor等编码代理中交互式调用文档工具，便于开发者快速分析单份材料。API更适合批处理、定时任务和业务系统集成。二者可以复用同一套解析、分类、提取逻辑，但生产环境仍应通过代码完成权限、重试与审计控制。

三、实战演示

3.1 环境准备

本示例要求Python 3.10及以上版本。安装PDF解析和HTTP请求依赖：

pip install pymupdf requests

将待处理文件放入invoices目录，并通过环境变量配置API密钥：

export XUEDINGMAO_API_KEY="替换为实际API密钥"

Windows PowerShell可使用：

$env:XUEDINGMAO_API_KEY="替换为实际API密钥"

3.2 完整批量提取代码

# 导入csv模块，用于将结构化结果写入通用表格文件
import csv
# 导入json模块，用于解析大模型返回的JSON字符串
import json
# 导入os模块，用于安全读取环境变量中的API密钥
import os
# 从pathlib导入Path，用于跨平台管理文件和目录路径
from pathlib import Path
# 导入fitz，即PyMuPDF的入口模块，用于读取文本型PDF
import fitz
# 导入requests模块，用于调用大模型Messages API
import requests

# 设置薛定猫AI服务地址，切换环境时可修改此常量
BASE_URL = "https://xuedingmao.com"
# 按要求拼接Anthropic兼容的Messages API端点
API_URL = f"{BASE_URL}/v1/messages"
# 指定用于复杂文档理解和结构化抽取的大模型
MODEL = "claude-opus-4-8"
# 定义待批量处理的PDF目录，可修改为实际业务目录
INPUT_DIR = Path("invoices")
# 定义最终CSV文件路径，可替换为绝对路径
OUTPUT_FILE = Path("invoice_result.csv")
# 从环境变量读取密钥，避免将敏感信息写入源码
API_KEY = os.getenv("XUEDINGMAO_API_KEY")

# 判断密钥是否存在，缺失时立即终止并给出明确提示
if not API_KEY:
    # 抛出异常，防止使用空密钥发送无效请求
    raise RuntimeError("请先配置环境变量 XUEDINGMAO_API_KEY")

# 创建输入目录；目录已存在时不会触发异常
INPUT_DIR.mkdir(parents=True, exist_ok=True)

# 定义PDF文本读取函数，适用于包含字符层的PDF文件
def read_pdf(pdf_path: Path) -> str:
    # 以只读方式打开指定PDF文档
    document = fitz.open(pdf_path)
    # 创建列表，用于按页保存文本并保留页码信息
    pages = []
    # 遍历文档中的每一页
    for page_number, page in enumerate(document, start=1):
        # 提取当前页文本，并在开头加入页码标记
        pages.append(f"【第{page_number}页】\n{page.get_text('text')}")
    # 关闭文档句柄，及时释放文件资源
    document.close()
    # 合并全部页面，形成发送给模型的完整上下文
    text = "\n".join(pages).strip()
    # 检查是否成功提取文本，扫描件通常会在此处为空
    if not text:
        # 提示开发者先执行OCR，避免模型接收空内容
        raise ValueError(f"{pdf_path.name}未检测到文本层，请先进行OCR")
    # 返回经过页码标记的文档文本
    return text

# 定义大模型字段抽取函数，输入文档文本并返回字典
def extract_invoice(text: str) -> dict:
    # 构造严格提示词，约束字段、类型和缺失值处理方式
    prompt = f"""你是企业发票结构化抽取引擎。
请从文档中提取以下字段：
invoice_no、invoice_date、seller、buyer、currency、
amount_without_tax、tax_amount、total_amount。
要求：
1. 日期统一为YYYY-MM-DD；
2. 金额必须为数值，不得包含货币符号；
3. 无法确认时返回null，不得推测；
4. 只返回一个合法JSON对象，不要输出Markdown。

文档内容：
{text}
"""
    # 设置Messages API请求头，包括鉴权和协议版本
    headers = {
        # 使用API密钥完成身份认证
        "x-api-key": API_KEY,
        # 声明Anthropic兼容协议版本
        "anthropic-version": "2023-06-01",
        # 声明请求体采用JSON格式
        "content-type": "application/json",
    }
    # 构造模型请求参数
    payload = {
        # 指定默认调用模型
        "model": MODEL,
        # 限制最大输出长度，发票字段无需过多Token
        "max_tokens": 1200,
        # 使用零温度提高批处理结果的一致性
        "temperature": 0,
        # 传入用户角色消息
        "messages": [{"role": "user", "content": prompt}],
    }
    # 发送POST请求，并设置超时时间防止任务永久阻塞
    response = requests.post(API_URL, headers=headers, json=payload, timeout=120)
    # 当HTTP状态码异常时抛出包含服务端信息的异常
    response.raise_for_status()
    # 将响应正文转换为Python字典
    result = response.json()
    # 获取第一个文本内容块
    model_text = result["content"][0]["text"].strip()
    # 兼容模型偶尔返回Markdown代码围栏的情况
    model_text = model_text.removeprefix("```json").removeprefix("```")
    # 移除末尾代码围栏和空白字符
    model_text = model_text.removesuffix("```").strip()
    # 解析JSON并返回结构化字典，非法格式会直接触发异常
    return json.loads(model_text)

# 定义允许写入CSV的字段，阻止模型生成额外字段
FIELDS = [
    # 保存原始文件名，便于追踪数据来源
    "source_file",
    # 保存发票号码
    "invoice_no",
    # 保存开票日期
    "invoice_date",
    # 保存销售方名称
    "seller",
    # 保存购买方名称
    "buyer",
    # 保存币种
    "currency",
    # 保存不含税金额
    "amount_without_tax",
    # 保存税额
    "tax_amount",
    # 保存含税总额
    "total_amount",
]

# 创建结果列表，用于汇总目录中的全部发票
rows = []

# 按文件名排序遍历所有PDF，保证多次运行顺序一致
for pdf_file in sorted(INPUT_DIR.glob("*.pdf")):
    # 输出当前文件名，便于观察批处理进度
    print(f"正在处理：{pdf_file.name}")
    # 读取当前PDF的文本内容
    pdf_text = read_pdf(pdf_file)
    # 调用大模型提取发票字段
    invoice = extract_invoice(pdf_text)
    # 仅保留字段白名单中的数据
    row = {field: invoice.get(field) for field in FIELDS}
    # 写入真实来源文件名，覆盖模型可能生成的同名字段
    row["source_file"] = pdf_file.name
    # 将当前记录加入最终结果集合
    rows.append(row)

# 以UTF-8 BOM编码创建CSV，保证Excel正确显示中文
with OUTPUT_FILE.open("w", newline="", encoding="utf-8-sig") as file:
    # 创建字典写入器，并固定列顺序
    writer = csv.DictWriter(file, fieldnames=FIELDS)
    # 写入CSV表头
    writer.writeheader()
    # 一次性写入全部发票记录
    writer.writerows(rows)

# 输出任务完成信息和结果文件位置
print(f"处理完成，共提取{len(rows)}份发票：{OUTPUT_FILE.resolve()}")

运行脚本后，每份PDF对应CSV中的一行记录。若需要生成Excel，可在结果校验后使用pandas.DataFrame.to_excel()完成格式转换。

四、工具/技术资源选型

文档流水线通常包含解析工具和推理模型两个层次。PyMuPDF适合读取文本型PDF，扫描件则需要额外接入OCR或版面分析服务；大模型负责语义理解、字段映射和异常内容判断。

本文使用自用开发平台薛定猫AI（xuedingmao.com）完成模型调用。平台聚合500余种主流模型，涵盖GPT-5.5、Claude 4.8、Gemini 3.1 Pro等模型，并提供新模型API能力。其统一OpenAI兼容接口能够减少不同供应商在鉴权、请求参数和响应结构上的适配工作；接口稳定性与响应速度可满足模型对比测试、批量任务及量产AI应用场景。

本文指定的/v1/messages属于Messages兼容端点。若项目需要在多个模型之间动态路由，可进一步封装统一客户端，将模型名称、超时和重试策略配置化。

五、注意事项

5.1 扫描件与复杂表格

PyMuPDF不能识别纯图片扫描件。生产环境应先判断字符数量，文本为空时进入OCR分支。跨页表格需要保留页码、标题和行列关系，否则模型可能将不同页面的金额错误合并。

5.2 数据可靠性与安全

金额、税号和日期必须执行二次校验，例如验证不含税金额 + 税额 = 总金额。低置信度结果应进入人工复核队列。合同、发票可能包含敏感信息，日志中不应记录API密钥、完整原文或个人身份数据。

5.3 性能优化

批量处理时应增加指数退避重试、并发上限和请求缓存。长文档可以按页或章节切分，但不要直接按固定字符截断表格。模型输出应保存来源文件、页码及任务版本，以支持审计和结果回溯。

六、全文总结

文档自动化的关键并非单纯调用大模型，而是建立"解析、约束、抽取、校验、落库"的完整闭环。本文通过Python实现了PDF发票批量读取、claude-opus-4-8结构化提取与CSV导出，并区分了API批处理和MCP交互式分析的适用场景。该架构还可扩展到合同审查、保险理赔、财务归档与企业知识库建设。

#AI #大模型 #Python #机器学习 #技术实战 #文档智能 #PDF解析