DocJev 是对复杂文档包进行分类和拆分的最快方法 ⚡️（默认选项完全免费且为开源！）

我制作了一个炫酷的演示视频（见下）。感谢 Opus 5.5 🙏

查看视频：https://t.co/fgSUUCWcwI https://t.co/7VbUMgCtyH

jerryjliu/docjev

来源：https://github.com/jerryjliu/docjev

DocJev

使用 Jev、LiteParse 以及可选的 LlamaParse 进行文档分类与拆分。

将 PDF、DOCX 或 PPTX 文件以及自然语言类别规则提供给 Python 库、命令行工具或本地应用。LiteParse 在本地提取完整的页面文本；Jev 预测文档类别或其组成文档之间的边界。可选的 LlamaParse 级别提供云端 OCR 以处理困难输入。

真实文档演示使用了原始的 IRS、Treasury、BEA 和 SEC 出版物。其 15 页的文档包包含两个类别相同的相邻 Treasury 拍卖结果。拆分器将它们识别为独立的文档，并保持一个 10 页的 BEA 报告（包括其密集的统计表格）完整无缺。

• 分类： 一个文档 → 一个类别、概率和审核标记。
• 拆分： 一个文档包 → 有序的类别和页面范围，可选按文档导出 PDF。
• 衡量： 分离 OCR 和决策时间、提供商使用情况，以及小型 LLM 对比。

这是一个独立的开源实现。它不调用 LlamaIndex 的托管 Classify 或 Split API，也不使用其内部实现。LlamaParse 仅用于可选的 OCR。Jev 是托管服务；本地 OCR 不进行离线推理。

DocJev 视觉基准报告：40 个真实 PDF，8 个文档包，Jev 和 Luna 的准确率及决策延迟 (https://jerryjliu.github.io/docjev/)

探索视觉报告 (https://jerryjliu.github.io/docjev/) — 浏览所有 40 个文档，比较文档包边界，回放记录的中位时间，并检查那一个额外的拆分。

快速开始

需要 Python 3.11+ 和 TypeSafe API 密钥 (https://console.typesafe.ai/)。克隆 DocJev (https://github.com/jerryjliu/docjev) 并安装：

``sh git clone https://github.com/jerryjliu/docjev.git cd docjev uv sync uv run docjev doctor –smoke

包和主命令行工具名为 `docjev`；`jev-docs` 保留为兼容性质别名。Python 导入（`jev_docs`）、环境变量（`JEV_DOCS_*`）和 `.jev-docs/` 缓存保持其现有名称。

在运行 Jev 决策之前，在您的 shell 中导出 `TYPESAFE_API_KEY`。[`.env.example`](.env.example) 列出了支持的环境变量，其值故意留空；命令行工具不会自动加载 `.env` 文件。`LLAMA_CLOUD_API_KEY` 和 `OPENAI_API_KEY` 是可选的，分别用于云端 OCR 和基线比较。请将实际值保持在版本控制和记录之外。

``sh
# 分类一个原始的 10 页 BEA 报告。
uv run docjev classify examples/real/originals/r04.pdf \
  --rules examples/real/classify/rules.yaml

# 分类完整的五文档公共财政收件箱；输出为 JSONL。
uv run docjev classify examples/real/originals \
  --rules examples/real/classify/rules.yaml \
  --output output/real-inbox.jsonl

# 拆分组装好的文档包并导出每个原始出版物。
uv run docjev split examples/real/public-finance-packet.pdf \
  --rules examples/real/split/rules.yaml \
  --export-dir output/real-segments \
  --output output/real-split.json

默认保留输出文件；请使用 --overwrite 明确替换它们。结果输出到标准输出，进度/错误输出到标准错误。目录分类为每个支持的文件写入一条成功/错误记录，如果任何文件失败则返回非零退出状态。

DOCX 和 PPTX 需要 LibreOffice (https://www.libreoffice.org/)。其页面编号指的是保留的 PDF 渲染：DOCX 分页遵循该渲染，PPTX 每张幻灯片使用一页。原生 PDF 输入不需要 LibreOffice。首次扫描的 LiteParse 解析可能会下载英语 OCR 语言数据；doctor --smoke 检查仅光栅的 PDF。参见 兼容性和页面契约。

本地可视化应用与视频

``sh uv sync –extra demo –extra baseline uv run docjev demo

打开 localhost:8765 (http://127.0.0.1:8765)。应用默认为**原始公共文档**，具有可编辑的类别、源文件预览、实时分类/拆分和 PDF 下载。要加载单独的合成夹具，请使用 `JEV_DOCS_DEMO_SET=synthetic uv run docjev demo` 启动它。比较面板明确标注了保存的试点结果及其样本大小；密钥保留在本地服务器上。

要进行实时并排比较，请打开 localhost:8765/race (http://127.0.0.1:8765/race)。它准备好一次 LiteParse 文本，然后在您点击 **运行两个模型** 时同时启动 Jev 和 GPT-5.6 Luna。此比较需要两个 API 密钥。模型决策时间不包括 OCR，OCR 会单独显示。每次准备允许一次比较；规则可在启动前编辑。

**简短社交演示：** [分类](docs/media/social/classification.mp4) · [拆分](docs/media/social/splitting.mp4)。两者都直接在应用上打开，运行点击在第一秒内，原始页面较大，实时模型结果并排显示。包含[缩略图、说明、确切时间和运行证据](docs/media/social/README.md)。

更长的演练：[出版物收件箱](docs/media/classification.mp4) · [15 页文档包](docs/media/splitting.mp4)。所有视频都有字幕、无声 1080p 屏幕录制；保留的处理以正常速度播放。[实际的拆分 PDF 和结果 JSON](docs/media/split-output.zip) 来自更长的演练。参见[发布说明](docs/publishing.md)以共享准备好的仓库和视频资产。

**准确性结果：** 单独的 [40 文档准确性试点](benchmarks/results/real-small-v1-run01/report.md) 已完成。两个引擎都正确分类了 40/40 个原始文件；Jev 精确拆分了 7/8 个文档包，Luna 拆分了 8/8 个。视频演示仍然是独立的证据。

[下一个 40 文档挑战](datasets/real-challenge/README.md)针对扫描件、模糊类别和附件边界。它是一个准备协议，而不是另一个测量结果。

## 规则与结果

规则使用稳定的类别 ID 和文档用途描述：

``yaml
categories:
  - id: invoice
    description: A seller's request for payment for goods or services already supplied.
  - id: purchase_order
    description: A buyer's authorization to supply goods or services.
  - id: other
    description: Content that does not fit the defined categories.
instructions: Classify the whole document by its main purpose.
splitting_instructions: Keep continuation pages together. Different invoice references identify separate documents, even when adjacent documents share a category.

如果省略，会自动添加 other。真实演示的分类规则区分税表、特定交易的财务报告、叙述性新闻稿和法律通知。其拆分规则区分出版物内的新出版物、章节、凭证、表格和技术说明。

测量的文档包生成以下四个段落（页码从 1 开始）：

``json { “segments”: [ {“id”: “segment-001”, “category”: “tax_form”, “pages”: [1, 2, 3]}, {“id”: “segment-002”, “category”: “financial_report”, “pages”: [4]}, {“id”: “segment-003”, “category”: “financial_report”, “pages”: [5]}, {“id”: “segment-004”, “category”: “press_release”, “pages”: [6, 7, 8, 9, 10, 11, 12, 13, 14, 15]} ] }

此摘录省略了完整结果中的来源、页面决策、审核标记和指标。每次成功的拆分都恰好覆盖每个规范页面一次。空 OCR 仅在保守的视觉检查后才被接受为空白页；明显非空白但文本无法识别的页面会明确失败。导出时会验证规范 PDF 哈希并保留精确的页面归属。

段落包含带有页码的结构化 `review_reasons`。默认情况下，Jev 边界分数在决策阈值 0.1 以内会触发对切割或延续的审核；不确定的切割会标记两个相邻段落。使用 `--boundary-review-margin 0` 禁用此信号。它不更改页面范围，不标记确定性空白页边界，也不会为基线发明边界分数。类别不确定性、`other` 和类别/边界冲突仍然是独立的原因。参见[边界审核](docs/boundary-review.md)。

Jev 的选定类别概率和提供商置信度是不同的值。两者都不声称是校准的。一个段落的平均类别概率是页面分数的平均值，而不是联合概率。Jev 提供决策和分布，因此该包不发明解释性理由。

## Python API

``python
from jev_docs import classify_document, load_rules, parse_document, split_document
from jev_docs.export import export_segments

classification = classify_document(
    "examples/real/originals/r04.pdf",
    load_rules("examples/real/classify/rules.yaml"),
)
print(classification.category)

document = parse_document("examples/real/public-finance-packet.pdf")
splitting = split_document(document, load_rules("examples/real/split/rules.yaml"))
export_segments(document, splitting, "output/python-segments")
print(splitting.model_dump_json(indent=2))

aclassify_document 和 asplit_document 支持异步应用。传递先前解析过的文档可重用其页面文本。库结果携带其解析来源和指标；使用 metrics.decision_ms 获取推理延迟。基准测试明确重置了历史 OCR 时间/成本，仅测量决策。

OCR 选项

``sh uv sync –extra llamaparse

需要 LLAMA_CLOUD_API_KEY 以及 TYPESAFE_API_KEY。

uv run docjev classify examples/real/originals/r04.pdf
–rules examples/real/classify/rules.yaml
–ocr llamaparse –tier agentic-plus

检查 OCR 而不进行决策引擎调用。

uv run docjev parse examples/real/originals/r04.pdf –output output/pages.json

使用 `--parser-version` 固定一个有效的特定级别已发布 LlamaParse 版本。默认是 `latest`；未解析的版本会被明确报告，本地 `latest` 缓存条目在 24 小时后过期。`--no-cache` 绕过本地 OCR 重用并禁用 LlamaParse 服务器缓存。规范 PDF 仍然可用于预览和导出。本地 `.jev-docs/` 缓存包含提取的文本和文档字节，被 Git 忽略。

PDF 字节仅在选择 LlamaParse 时上传。标准化的页面文本被发送到所选的决策引擎——默认是 TypeSafe，或用于可选基线的 OpenAI。LiteParse 没有 OCR API 费用；计算资源和托管决策调用仍然有成本。

## 小型真实文档准确性基准

**40 个真实 PDF，每个类别 8 个，在八个构建的五文档文档包中重复使用。** 这个精选的英国公共部门样本包含 116 个唯一页面。[冻结数据集](datasets/real-small/v1/DATASET_CARD.md)包含完整的原始出版物、来源特定的权利、代理审核的标签和经过验证的文档包边界。未执行人工标注审核。

一次测量运行完成了所有 96 个任务，加上四个被排除的热身。两个引擎接收相同的 LiteParse 文本。决策时间不包括 OCR；并发数为一，禁用重试。

| 任务 | Jev 1.13.0 质量 | GPT-5.6 Luna 质量 | Jev 中位数 | Luna 中位数 | Luna/Jev 中位时间比 |
|---|---:|---:|---:|---:|---:|
| 分类 | 40/40 正确 | 40/40 正确 | 138.6 ms | 794.3 ms | 5.73× |
| 拆分 | 7/8 精确文档包 | 8/8 精确文档包 | 209.6 ms | 1,352.3 ms | 6.45× |

时间比使用每个引擎相同的 40 个完成的分类输入和 8 个完成的拆分输入。两者都找到了所有 32 个真实文档包边界（包括所有四个相邻相同类别边界），并正确标记了所有 116 个文档包页面。Jev 在一个美联储声明的实施附件之前添加了一个额外的边界；冻结规则将其视为原始出版物的一部分。参见[错误审查](benchmarks/results/real-small-v1-run01/error-analysis.md)。

测量的决策成本估计为 **Jev $0.011663** 和 **Luna $0.046894**。整个运行（包括热身）成本为 **$0.068050**，记录了所有提供商使用情况。本地准备耗时 56.6 秒；付费阶段耗时 58.1 秒。LiteParse 没有 API 费用；本地计算没有定价。两个热身输入使用了缓存的 OCR，因此准备并非完全冷启动。

这些是在小型便利样本上得出的描述性结果，具有共享的来源/模板系列和不受控制的提供商缓存。任务重用相同的原始文件并单独报告。八个文档包不能确立普遍的拆分准确性；未做出推断性置信区间或重复稳定性声明。

[完整报告](benchmarks/results/real-small-v1-run01/report.md) · [原始结果](benchmarks/results/real-small-v1-run01/raw.jsonl) · [指标 CSV](benchmarks/results/real-small-v1-run01/metrics.csv) · [冻结运行清单](benchmarks/results/real-small-v1-run01/manifest.json) · [数据集和说明](datasets/real-small/README.md) · [方法论](docs/benchmark-methodology.md)

准确性试点决策延迟

要运行您自己的单次比较：

``sh
uv sync --all-extras --locked
uv run python datasets/real-small/prepare.py --verify
uv run python -m benchmarks.run --config benchmarks/configs/real-small-v1.yaml --dry-run

# 仅本地 OCR 和实际文本准入；无推理调用。
uv run python -m benchmarks.run --config benchmarks/configs/real-small-v1.yaml \
  --prepare-only --output output/my-real-small-preflight

# 需要 TYPESAFE_API_KEY 和 OPENAI_API_KEY；此收据只能使用一次。
uv run python -m benchmarks.run --config benchmarks/configs/real-small-v1.yaml \
  --prepared output/my-real-small-preflight/preparation.json \
  --output benchmarks/results/my-real-small-run

# 离线重建保存的结果，无需密钥。
uv run python -m benchmarks.report benchmarks/results/my-real-small-run

配置文件强制执行 2 美元的本地估计保护、60 秒的 OCR/任务限制、600 秒的准备限制和 300 秒的付费阶段限制。它在服务故障时停止，并在原始分母中保留不完整的结果。保护不是提供商的计费上限；准备收据不能用于另一次付费尝试。

早期的真实文档计时试点

一个 10 页 BEA 文档和一个 15 页文档包，每个引擎计时重复三次。这是一个演示计时试点，不是保留的准确性基准。 每个引擎/任务条件之前有一个被排除的热身。两个引擎消耗相同的 LiteParse 页面文本，使用重用的客户端，顺序执行，无重试。OCR 不包括在这些决策时间中。

两个引擎在所有三次计时重复中都重现了声明的类别和所有四个文档包段落，包括相邻 Treasury 结果之间的边界。所有 16 个任务调用（包括热身）均已完成。整个试点的估计 API 成本为 $0.01694，根据报告的使用情况和标价计算。

Luna 的计时