extractflow 文档提取工作流

这是什么？适合谁？

extractflow 是一个可靠的、模式验证的结构化文档提取工具。它使用 LLM 从 PDF、DOCX、CSV、邮件等文档中提取结构化数据，并通过 JSON Schema / Pydantic 模型验证确保输出质量。

核心理念：传统的 LLM 文档提取是”尽力而为”——你让 LLM 提取发票信息，它可能返回 JSON，但字段名可能不一致、数据类型可能不对、必填字段可能缺失。extractflow 在 LLM 提取后增加了一层 Schema 验证，确保输出 100% 符合你定义的格式。与纯 LLM 提取的区别：纯 LLM 提取的结果不可靠（格式漂移），extractflow 通过 Schema 约束 + 有限重试 + 类型化错误路由，将可靠性提升到生产级。

适合需要从大量文档中批量提取结构化数据的场景（发票处理、合同信息提取、邮件分类、简历解析等）。不适合需要深度理解文档语义的场景（那是 LLM 的强项，不需要 Schema 约束）。项目处于早期阶段（GitHub ★4，13 commits），建议先在非关键流程中试用验证。

准备工作

1. Python 3.10+ 环境
2. Anthropic API Key（extractflow 首选 Claude 模型，通过环境变量 ANTHROPIC_API_KEY 配置）
3. 待提取的文档文件（PDF、DOCX、CSV、EML 邮件或纯文本）
4. 了解 Pydantic 模型或 JSON Schema 基本语法
5. 可选：Docker 环境（用于部署 webhook 服务）

提取流水线架构

文档输入 → 加载器(PDF/DOCX/CSV/EML) → 预处理(清理/截断保护)
  → LLM 提取(严格 Schema 约束) → 验证(+1 次修复重试)
  → 成功: 结构化数据 + 用量 + 成本  |  失败: 类型化错误(可路由到人工审核)

3 步核心流程

第 1 步：安装 extractflow

# 核心安装（如果已发布到 PyPI）
pip install extractflow

# 完整安装（含 Claude provider、PDF/DOCX 支持、webhook 服务）
pip install "extractflow[all]"

# 如果尚未发布到 PyPI，从源码安装
git clone https://github.com/adam-eques/extractflow.git
cd extractflow
pip install -e .

配置 LLM API Key（Claude provider 从环境变量读取）：

export ANTHROPIC_API_KEY="your-key-here"

预期产出：extractflow 安装成功，API Key 配置完毕。可以用 extractflow --help 验证 CLI 可用。

第 2 步：定义提取 Schema

用 Pydantic 模型定义你期望提取的结构。例如提取发票信息：

from pydantic import BaseModel

class Invoice(BaseModel):
    vendor: str
    invoice_number: str
    total: float
    currency: str
    line_items: list[str]

也支持 JSON Schema 文件（schema.json）格式定义，适合非 Python 用户或跨语言场景。

预期产出：一个 Pydantic 模型类或 JSON Schema 文件，描述了你需要从文档中提取的所有字段及其类型约束。

第 3 步：运行提取并验证

from extractflow import extract

result = extract("invoice.pdf", schema=Invoice)

print(result.data)        # -> Invoice(vendor='Acme', total=1240.5, ...)  (已验证)
print(result.cost_usd)    # -> 0.0021
print(result.usage)       # -> token 计数
print(result.attempts)    # -> 1 (首次成功) 或 2 (经过修复重试)

如果模型经过修复重试后仍无法产出合法输出，你会得到一个类型化错误，可以路由处理——流水线不会崩溃：

from extractflow import extract, ValidationFailedError

try:
    result = extract("garbled.pdf", schema=Invoice)
except ValidationFailedError as e:
    queue_for_human_review(e.raw_output, e.validation_errors)

预期产出：验证通过的结构化数据对象，附带本次调用的 token 用量和 USD 成本。失败时获得包含原始输出和验证错误的异常对象，可路由到人工审核队列。

CLI 用法

# 提取并输出验证后的 JSON 到 stdout
extractflow run invoice.pdf --schema ./schemas.py:Invoice --model claude-sonnet-4-6 --meta

# 管道输入
cat email.txt | extractflow run - --schema triage.json

--schema 接受 Pydantic 模型（module.py:ClassName）或 JSON Schema 文件（schema.json）。非零退出码表示不可恢复的失败，适合在 shell 脚本中做错误处理。

Webhook 部署（n8n / Make / Zapier 集成）

docker compose up        # 暴露 POST /extract 在 :8080 端口

接口规范：

• 请求：POST /extract，multipart 上传文件 + form 字段传 schema
• 成功：200 { "data": {...}, "usage": {...}, "cost_usd": 0.0021 }
• 失败：422 { "error": "validation_failed", "raw_output": "...", "validation_errors": [...] }

仓库内置一个可导入的 n8n 工作流（examples/n8n/workflow.json）：Webhook → ExtractFlow → Google Sheet，开箱即用。

离线测试（无需 API Key）

extractflow 内置 FakeLLMClient，可以在不调用真实模型的情况下验证 Schema 和编写 CI：

from extractflow import extract_text, FakeLLMClient

result = extract_text("any text", schema=Invoice, provider=FakeLLMClient())
assert isinstance(result.data, Invoice)

支持的输入格式与模型

输入格式：PDF、DOCX、TXT/Markdown、CSV、JSON、EML（邮件）、原始文本/字节。

支持的模型（Claude 优先）：

• claude-haiku-4-5：高频简单提取（最便宜）
• claude-sonnet-4-6：大多数文档（均衡——默认）
• claude-opus-4-8：最复杂/高要求提取

核心是 provider 无关的——provider 位于一个单方法协议之后，可以替换 Claude 为其他后端而不触动提取流水线。

示例项目

仓库 examples/ 目录包含：

• examples/invoice/：PDF/文本发票 → Invoice 模型
• examples/email_triage/：.eml → {category, priority, summary, action}
• examples/resume_parse/：简历文本 → 结构化候选人记录
• examples/n8n/：可导入的自动化工作流

适用场景

• 发票/合同批量提取结构化数据
• 邮件自动分类与路由
• 简历解析为结构化候选人档案
• 任何”文档 → JSON”的自动化流水线场景

常见踩坑

1. Schema 定义过于严格会导致 LLM 提取结果频繁验证失败——建议必填字段只设真正必需的，非关键字段设为 Optional。

2. 复杂嵌套 Schema 的提取成功率低于扁平 Schema——尽量扁平化设计，用 list[str] 代替深度嵌套的对象数组。

3. PDF 中的扫描件需要 OCR 预处理，extractflow 本身不包含 OCR 能力——先用 pytesseract 或商业 OCR 服务转换为文本。

4. LLM 提取有成本——每份文档都会调用 API，批量处理时注意费用。extractflow 会报告每次调用的 cost_usd，可以据此做预算控制。

5. 修复重试也会消耗 API 额度——默认 1 次修复重试，如果频繁触发说明 Schema 设计或文档质量有问题。

6. 项目刚发布（★4，13 commits），README 声称 pip install extractflow 但截至 2026-07-08 尚未在 PyPI 上找到——建议从 GitHub 源码安装。

7. 目前仅支持 Claude 模型——如果你的基础设施依赖 OpenAI，需要自行实现 provider 协议或等待社区贡献。

FAQ

Q1: extractflow 和直接让 ChatGPT/Claude 提取文档有什么区别？

ChatGPT/Claude 直接提取的结果格式不稳定——同一份文档两次提取可能返回不同结构的 JSON。extractflow 通过 Schema 验证确保输出格式一致，并在失败时提供类型化错误而非静默失败。此外，extractflow 报告每次调用的精确成本（cost_usd），便于成本管理。

Q2: extractflow 和 Instructor（★13.4K）有什么区别？

Instructor 是更成熟的 Schema 约束库，支持多种 LLM provider 和更丰富的重试策略。extractflow 的差异在于：①面向文档提取场景（内置 PDF/DOCX/CSV/EML 加载器），②提供 CLI 和 webhook 部署模式，③内置 n8n 集成示例，④提供类型化错误路由而非简单的验证失败。但 Instructor 在社区成熟度、provider 覆盖度和稳定性方面远超 extractflow。

Q3: 支持哪些文档格式？

PDF、DOCX、TXT/Markdown、CSV、JSON、EML（邮件）、原始文本/字节。不支持图片和扫描件（需要先 OCR 转换为文本）。

Q4: 提取一份文档大概花多少钱？

取决于文档长度和使用的模型。使用 claude-haiku-4-5 处理一页 PDF 发票约 $0.001-0.005。extractflow 每次调用都会报告 cost_usd，可以精确追踪。

Q5: 可以用于生产环境吗？

项目刚发布（★4，13 commits），建议先在非关键流程中试用验证。Schema 验证机制本身是生产级设计（类型化错误、成本追踪、修复重试），但项目成熟度需要时间检验。如果需要生产级稳定性，建议评估 Instructor（★13.4K，1,563 commits）作为替代。

参考资料

• extractflow GitHub 仓库 —— 官方源码、文档和示例
• JSON Schema 规范 —— Schema 定义标准
• Pydantic 文档 —— Python 数据验证库
• Instructor 库 —— 更成熟的 Schema 约束 LLM 输出方案（★13.4K）
• Outlines 库 —— 结构化输出生成方案（★14.4K）

---

本文基于官方文档和公开资料整理，AI 辅助生成，MagicNetWorld 尚未完成独立实测。如有错误或过时信息，请通过 contact@magicnetworld.com 反馈。