Docpick

Docpick

한국어 문서 · llms.txt

输入文档，输出结构化 JSON。在本地运行，使用你自己的架构。

docpick 是一款轻量、由架构驱动的文档提取流水线，结合本地 OCR 引擎与本地大模型，从任意文档中提取结构化 JSON，包括发票、收据、提单、税务表格等。

• 零云端依赖 — 完全在你的机器上运行（CPU 或 GPU）
• 自定义架构 — 定义自己的 Pydantic 模型，或使用 8 种内置文档架构
• 内置验证 — 校验码验证、跨字段规则、跨文档一致性
• Apache 2.0 — 无 GPL/AGPL 依赖

安装

pip install docpick            # core (LLM extraction only)
pip install docpick[paddle]    # + PaddleOCR (recommended)
pip install docpick[easyocr]   # + EasyOCR (Korean-optimized)
pip install docpick[got]       # + GOT-OCR2.0 (GPU, vision-language)
pip install docpick[all]       # all OCR backends

要求： Python 3.11+ / 大模型端点（vLLM、Ollama 或兼容 OpenAI 的端点）

快速开始

Python API

from docpick import DocpickPipeline
from docpick.schemas import InvoiceSchema

pipeline = DocpickPipeline()
result = pipeline.extract("invoice.pdf", schema=InvoiceSchema)

print(result.data)           # Structured dict matching schema
print(result.validation)     # Validation errors/warnings
print(result.confidence)     # Per-field confidence scores

命令行界面

# Extract structured data
docpick extract invoice.pdf --schema invoice --output result.json

# OCR only (no LLM)
docpick ocr document.png --lang ko,en

# Validate extracted JSON
docpick validate result.json --schema invoice

# Batch process a directory
docpick batch ./documents/ --schema invoice --output ./results/ --concurrency 4

# List available schemas
docpick schemas list

# Show schema details
docpick schemas show invoice

内置架构

架构	文档类型	关键验证
invoice	商业发票	明细项合计、税号校验码、日期顺序
receipt	零售/餐厅收据	总计 = 小计 + 税额 + 小费
bill_of_lading	海运/空运提单	集装箱重量合计、ISO 6346、HS 编码格式
purchase_order	采购订单	采购订单总额 = 明细项合计、交货日期顺序
kr_tax_invoice	韩国电子税务发票（세금계산서）	企业编号校验码（x2）、供应额/税额/总额合计
bank_statement	银行对账单	IBAN mod97、期间日期顺序
id_document	护照/身份证件（ICAO 9303）	机读区（MRZ）、ISO 3166 国家代码、日期范围
certificate_of_origin	原产地证书	ISO 3166 alpha-2 国家代码

自定义架构

使用 Pydantic 定义自己的架构：

from pydantic import BaseModel
from docpick import DocpickPipeline
from docpick.validation.rules import SumEqualsRule, RequiredFieldRule

class MyDocument(BaseModel):
    """Custom document schema."""
    company_name: str | None = None
    total_amount: float | None = None
    tax_amount: float | None = None
    net_amount: float | None = None
    items: list[dict] | None = None

    class ValidationRules:
        rules = [
            RequiredFieldRule("company_name"),
            SumEqualsRule(["net_amount", "tax_amount"], "total_amount"),
        ]

pipeline = DocpickPipeline()
result = pipeline.extract("my_document.pdf", schema=MyDocument)

或使用 JSON Schema 文件：

docpick extract document.pdf --schema my_schema.json

验证

校验码算法

算法	用途
kr_business_number	韩国企业注册号（10 位数字）
luhn	信用卡号
iso_6346	海运集装箱号
iban_mod97	国际银行账号
awb_mod7	航空运单号
mrz	机读区（护照/身份证件）

跨字段规则

规则	描述
SumEqualsRule	字段总和等于目标值（带容差）
DateBeforeRule	日期 A 必须早于日期 B
RequiredFieldRule	字段必须非空且不为 null
FieldEqualsRule	两个字段必须相等
RangeRule	数值字段处于最小值/最大值范围内
RegexRule	字段匹配正则表达式模式

跨文档验证

验证相关文档之间的一致性（例如：发票 + 提单 + 装箱单）：

from docpick.validation.cross_document import create_trade_document_validator

validator = create_trade_document_validator()
result = validator.validate({
    "invoice": invoice_data,
    "bl": bl_data,
    "packing_list": packing_list_data,
    "certificate": certificate_data,
})
print(result.is_valid)

OCR 引擎

引擎	类型	GPU	语言	最适用场景
PaddleOCR	传统 OCR	可选	111	通用文档（默认）
EasyOCR	传统 OCR	可选	80+	韩文文本
GOT-OCR2.0	视觉语言	必需	多种	复杂布局
VLM	视觉语言	必需	多种	直接从图像 → JSON

双层自动引擎

默认的 auto 引擎会根据置信度进行回退：

1. 第 1 层（CPU）： PaddleOCR → EasyOCR
2. 第 2 层（GPU）： GOT-OCR2.0 → VLM

如果第 1 层的平均置信度低于阈值（默认为 0.7），则会自动升级到第 2 层。

大模型提供商

提供商	端点	默认模型
vLLM	http://localhost:8000/v1	Qwen/Qwen3.5-32B-AWQ
Ollama	http://localhost:11434	qwen3.5:7b

通过命令行界面或 YAML 进行配置：

docpick config set llm.provider ollama
docpick config set llm.base_url http://localhost:11434
docpick config set llm.model qwen3.5:7b

错误处理

该流水线经过设计，具备良好的弹性：

• OCR 失败 → 自动回退到下一个可用引擎
• 大模型 JSON 解析失败 → 自动使用修正提示词重试（最多重试 1 次）
• 部分结果 → 返回已提取的内容，并将错误记录在 result.errors 中
• 文档加载失败 → 返回空结果和错误消息

result = pipeline.extract("damaged.pdf", schema=InvoiceSchema)
if result.errors:
    print("Pipeline warnings:", result.errors)
if result.data:
    print("Partial extraction:", result.data)

批处理

使用并行工作线程处理整个目录：

from docpick.batch import BatchProcessor
from docpick.schemas import InvoiceSchema

processor = BatchProcessor(concurrency=4)
result = processor.process_directory(
    "./invoices/",
    schema=InvoiceSchema,
    recursive=True,
)

print(f"Processed {result.succeeded}/{result.total} files")
for path, extraction in result.results.items():
    print(f"{path}: {extraction.data.get('total_amount')}")

架构

flowchart TD
    A["📄 Document\n(PDF / Image)"] --> B["DocumentLoader\n(pypdfium2)"]
    B --> C["Tier 1: OCR\n(PaddleOCR / EasyOCR)\nCPU"]
    C --> D{"Confidence\n≥ threshold?"}
    D -->|"yes"| F["LLM Extractor\n(vLLM / Ollama)\nSchema prompt"]
    D -->|"no"| E["Tier 2: VLM\n(GOT / VLM)\nGPU"]
    E --> F
    F --> G["Pydantic Validation"]
    G --> H["✅ ExtractionResult"]

许可证

Apache 2.0 — 所有依赖项均采用 Apache 2.0 或 MIT 许可证。

---

_{属于 QuartzUnit 生态系统 — 一系列可组合的 Python 库，用于数据收集、提取、搜索和 AI Agent 安全。}