opendataloader-project--opendataloader-pdf/README.md

<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/opendataloader-project/opendataloader-pdf) · [上游 README](https://github.com/opendataloader-project/opendataloader-pdf/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

<!-- AI-AGENT-SUMMARY
name: opendataloader-pdf
category: PDF data extraction, PDF accessibility automation
license: Apache-2.0
solves: [PDF to structured data for RAG/LLM pipelines, accelerate PDF accessibility remediation — layout analysis + auto-tagging to Tagged PDF as foundation for PDF/UA (first open-source end-to-end)]
input: PDF files (digital, scanned, tagged)
output: Markdown, JSON (with bounding boxes), HTML, Tagged PDF, PDF/UA (enterprise)
sdk: Python, Node.js, Java
requirements: Java 11+
pricing: open-source core (data extraction, layout analysis, auto-tagging to Tagged PDF), enterprise add-on (PDF/UA export, accessibility studio)
extraction-benchmark: #1 overall extraction accuracy (0.907) in hybrid mode, 0.928 table extraction accuracy, 0.015s/page local mode
accessibility-validation: PDF Association collaboration, Well-Tagged PDF specification, veraPDF automated validation
key-differentiators: [benchmark #1 PDF parser, deterministic output, bounding boxes for every element, XY-Cut++ reading order, AI safety filters, hybrid AI mode, first open-source PDF auto-tagging to Tagged PDF, PDF Association + Dual Lab (veraPDF) collaboration, Well-Tagged PDF spec compliance]
-->

# OpenDataLoader PDF

**面向 AI 就绪数据的 PDF 解析器。自动化 PDF 无障碍处理。开源。**

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/LICENSE)
[![PyPI version](https://img.shields.io/pypi/v/opendataloader-pdf.svg)](https://pypi.org/project/opendataloader-pdf/)
[![npm version](https://img.shields.io/npm/v/@opendataloader/pdf.svg)](https://www.npmjs.com/package/@opendataloader/pdf)
[![Maven Central](https://img.shields.io/maven-central/v/org.opendataloader/opendataloader-pdf-core.svg)](https://search.maven.org/artifact/org.opendataloader/opendataloader-pdf-core)
[![Java](https://img.shields.io/badge/Java-11%2B-blue.svg)](https://github.com/opendataloader-project/opendataloader-pdf#java)

<a href="https://trendshift.io/repositories/21917" target="_blank"><img src="https://trendshift.io/api/badge/repositories/21917" alt="opendataloader-project%2Fopendataloader-pdf | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>

🔍 **面向 AI 数据提取的 PDF 解析器** — 从任意 PDF 提取 Markdown、JSON（含边界框）和 HTML。基准测试排名第一（0.907 综合得分）。确定性本地模式 + AI 混合模式，应对复杂页面。

- **准确度如何？** — 基准测试排名第一：综合得分 0.907，表格准确度 0.928，覆盖 200 份真实世界 PDF，包括多栏版式和科技论文。确定性本地模式 + AI 混合模式应对复杂页面（[基准测试](#extraction-benchmarks)）
- **扫描版 PDF 和 OCR？** — 支持。混合模式内置 OCR（80+ 种语言）。适用于 300 DPI 及以上低质量扫描件（[混合模式](#hybrid-mode-1-accuracy-for-complex-pdfs)）
- **表格、公式、图片、图表？** — 支持。复杂/无边框表格、LaTeX 公式，以及 AI 生成的图片/图表描述，均通过混合模式实现（[混合模式](#hybrid-mode-1-accuracy-for-complex-pdfs)）
- **如何用于 RAG？** — `pip install opendataloader-pdf`，三行代码即可完成转换。输出结构化 Markdown 用于分块，带边界框的 JSON 用于来源引用，以及 HTML。提供 LangChain 集成。提供 Python、Node.js、Java SDK（[快速开始](#get-started-in-30-seconds) | [LangChain](#langchain-integration)）

♿ **PDF 无障碍自动化** — 大规模将未标注 PDF 自动标注为屏幕阅读器可用的 Tagged PDF。首个端到端生成 Tagged PDF 的开源工具。

- **问题是什么？** — 无障碍法规已在全球范围内强制执行。人工 PDF 修复每份文档成本 50–200 美元，且无法规模化（[法规](#pdf-accessibility--pdfua-conversion)）
- **免费部分有哪些？** — 版式分析 + 自动标注（Apache 2.0）。未标注 PDF 输入 → Tagged PDF 输出。无需依赖专有 SDK（[自动标注](#auto-tagging)）
- **PDF/UA 合规性如何？** — 将 Tagged PDF 转换为 PDF/UA-1 或 PDF/UA-2 属于企业版附加功能。自动标注生成 Tagged PDF；PDF/UA 导出是最后一步（[流水线](#accessibility-pipeline)）
- **为何值得信赖？** — 与 [Dual Lab](https://duallab.com)（[veraPDF](https://verapdf.org) 开发者）合作构建，基于 [PDF Association](https://pdfa.org) 规范、[PDF Community](https://pdfa.org/community/). 最佳实践指南与专业知识。自动标注遵循 [Well-Tagged PDF specification](https://pdfa.org/wtpdf/),，并通过 veraPDF 验证（[合作](https://opendataloader.org/docs/tagged-pdf-collaboration))

## 30 秒快速开始

**要求**：Java 11+ 和 Python 3.10+（亦提供 [Node.js](https://opendataloader.org/docs/quick-start-nodejs) | [Java](https://opendataloader.org/docs/quick-start-java)）

> 开始之前：运行 `java -version`。若未找到，请从 [Adoptium](https://adoptium.net/). 安装 JDK 11+

```bash
pip install -U opendataloader-pdf
```

```python
import opendataloader_pdf

# Batch all files in one call — each convert() spawns a JVM process, so repeated calls are slow
opendataloader_pdf.convert(
    input_path=["file1.pdf", "file2.pdf", "folder/"],
    output_dir="output/",
    format="markdown,json"
)
```

![OpenDataLoader PDF layout analysis — headings, tables, images detected with bounding boxes](https://raw.githubusercontent.com/opendataloader-project/opendataloader-pdf/main/samples/image/example_annotated_pdf.png)

*标注后的 PDF 输出 — 每个元素（标题、段落、表格、图片）均检测出边界框和语义类型。*

## 解决哪些问题？

| 问题 | 解决方案 | 状态 |
|---------|----------|--------|
| **解析时 PDF 结构丢失** — 阅读顺序错误、表格破损、无元素坐标 | 确定性本地 PDF 转 Markdown/JSON（含边界框），XY-Cut++ 阅读顺序 | 已发布 |
| **复杂表格、扫描版 PDF、公式、图表** 需要 AI 级理解 | 混合模式将复杂页面路由至 AI 后端（基准测试排名第一） | 已发布 |
| **人工 PDF 修复成本高** — 无障碍法规（EAA、ADA、Section 508）要求 Tagged PDF。人工修复每份 50–200 美元 | 自动将未标注 PDF 标注为 Tagged PDF（免费，Apache 2.0）。PDF/UA 工作流的基础；完整 PDF/UA-1/2 导出为企业版附加功能 | 自动标注：已发布。PDF/UA 导出：企业版 |

## 能力矩阵

| 能力 | 支持 | 层级 |
|------------|-----------|------|
| **数据提取** | | |
| 按正确阅读顺序提取文本 | 是 | 免费 |
| 每个元素的边界框 | 是 | 免费 |
| 表格提取（简单边框） | 是 | 免费 |
| 表格提取（复杂/无边框） | 是 | 免费（Hybrid） |
| 标题层级检测 | 是 | 免费 |
| 列表检测（编号、项目符号、嵌套） | 是 | 免费 |
| 带坐标的图片提取 | 是 | 免费 |
| AI 图表/图片描述 | 是 | 免费（Hybrid） |
| 扫描版 PDF 的 OCR | 是 | 免费（Hybrid） |
| 公式提取（LaTeX） | 是 | 免费（Hybrid） |
| Tagged PDF 结构提取 | 是 | 免费 |
| AI 安全（提示注入过滤） | 是 | 免费 |
| 页眉/页脚/水印过滤 | 是 | 免费 |
| **无障碍** | | |
| 自动标注 → 将未标注 PDF 转为 Tagged PDF | 是 | 免费（Apache 2.0） |
| PDF/UA-1、PDF/UA-2 导出 | 💼 可用 | 企业版 |
| 无障碍工作室（可视化编辑器） | 💼 可用 | 企业版 |
| **限制** | | |
| 处理 Word/Excel/PPT | 否 | — |
| 需要 GPU | 否 | — |

## 提取基准测试

**opendataloader-pdf [hybrid] 综合排名第一（0.907）**，涵盖阅读顺序、表格和标题提取准确度。

| 引擎 | 综合 | 阅读顺序 | 表格 | 标题 | 速度（秒/页） | 许可证 |
|--------|---------|---------------|-------|---------|----------------|---------|
| **opendataloader [hybrid]** | **0.907** | **0.934** | **0.928** | 0.821 | 0.463 | Apache-2.0 |
| nutrient | 0.885 | 0.925 | 0.708 | 0.819 | **0.008** | Commercial |
| docling | 0.882 | 0.898 | 0.887 | **0.824** | 0.762 | MIT |
| marker | 0.861 | 0.890 | 0.808 | 0.796 | 53.932 | GPL-3.0 |
| unstructured [hi_res] | 0.841 | 0.904 | 0.588 | 0.749 | 3.008 | Apache-2.0 |
| edgeparse | 0.837 | 0.894 | 0.717 | 0.706 | 0.036 | Apache-2.0 |
| opendataloader | 0.831 | 0.902 | 0.489 | 0.739 | 0.015 | Apache-2.0 |
| mineru | 0.831 | 0.857 | 0.873 | 0.743 | 5.962 | AGPL-3.0 |
| pymupdf4llm | 0.732 | 0.885 | 0.401 | 0.412 | 0.091 | AGPL-3.0 |
| unstructured | 0.686 | 0.882 | 0.000 | 0.388 | 0.077 | Apache-2.0 |
| markitdown | 0.589 | 0.844 | 0.273 | 0.000 | 0.114 | MIT |
| liteparse | 0.576 | 0.866 | 0.000 | 0.000 | 1.061 | Apache-2.0 |

> 分数已归一化到 [0, 1]。准确度越高越好；速度越低越好。**粗体** = 最佳。[完整基准测试详情](https://github.com/opendataloader-project/opendataloader-bench)

[![Benchmark](https://github.com/opendataloader-project/opendataloader-bench/raw/refs/heads/main/charts/benchmark.png)](https://github.com/opendataloader-project/opendataloader-bench)

[![Quality Breakdown](https://github.com/opendataloader-project/opendataloader-bench/raw/refs/heads/main/charts/benchmark_quality.png)](https://github.com/opendataloader-project/opendataloader-bench)

## 我该用哪种模式？

| 你的文档 | 模式 | 安装 | 服务端命令 | 客户端命令 |
|---------------|------|---------|----------------|----------------|
| 标准数字 PDF | Fast（默认） | `pip install opendataloader-pdf` | 无需 | `opendataloader-pdf file1.pdf file2.pdf folder/` |
| 复杂或嵌套表格 | **Hybrid** | `pip install "opendataloader-pdf[hybrid]"` | `opendataloader-pdf-hybrid --port 5002` | `opendataloader-pdf --hybrid docling-fast file1.pdf file2.pdf folder/` |
| 扫描件 / 基于图像的 PDF | Hybrid + OCR | `pip install "opendataloader-pdf[hybrid]"` | `opendataloader-pdf-hybrid --port 5002 --force-ocr` | `opendataloader-pdf --hybrid docling-fast file1.pdf file2.pdf folder/` |
| 非英文扫描 PDF | Hybrid + OCR | `pip install "opendataloader-pdf[hybrid]"` | `opendataloader-pdf-hybrid --port 5002 --force-ocr --ocr-lang "ko,en"` | `opendataloader-pdf --hybrid docling-fast file1.pdf file2.pdf folder/` |
| 数学公式 | Hybrid + formula | `pip install "opendataloader-pdf[hybrid]"` | `opendataloader-pdf-hybrid --enrich-formula` | `opendataloader-pdf --hybrid docling-fast --hybrid-mode full file1.pdf file2.pdf folder/` |
| 需要描述的图表 | Hybrid + picture | `pip install "opendataloader-pdf[hybrid]"` | `opendataloader-pdf-hybrid --enrich-picture-description` | `opendataloader-pdf --hybrid docling-fast --hybrid-mode full file1.pdf file2.pdf folder/` |
| 需要无障碍的无标签 PDF | Auto-tagging → Tagged PDF | `pip install opendataloader-pdf` | 无需 | `opendataloader-pdf --format tagged-pdf file1.pdf file2.pdf folder/` |

## 快速开始

### Python

```bash
pip install -U opendataloader-pdf
```

```python
import opendataloader_pdf

# Batch all files in one call — each convert() spawns a JVM process, so repeated calls are slow
opendataloader_pdf.convert(
    input_path=["file1.pdf", "file2.pdf", "folder/"],
    output_dir="output/",
    format="markdown,json"
)
```

### Node.js

```bash
npm install @opendataloader/pdf
```

```typescript
import { convert } from '@opendataloader/pdf';

await convert(['file1.pdf', 'file2.pdf', 'folder/'], {
  outputDir: 'output/',
  format: 'markdown,json'
});
```

### Java

```xml
<dependency>
  <groupId>org.opendataloader</groupId>
  <artifactId>opendataloader-pdf-core</artifactId>
</dependency>
```

[Python 快速开始](https://opendataloader.org/docs/quick-start-python) | [Node.js 快速开始](https://opendataloader.org/docs/quick-start-nodejs) | [Java 快速开始](https://opendataloader.org/docs/quick-start-java)

## Hybrid 模式：复杂 PDF 的 #1 准确度

Hybrid 模式将快速的本地 Java 处理与 AI 后端相结合。简单页面留在本地处理（0.02s）；复杂页面路由到 AI，表格准确度提升 +90%。

```bash
pip install -U "opendataloader-pdf[hybrid]"
```

**终端 1** — 启动后端服务：

```bash
opendataloader-pdf-hybrid --port 5002
```

**终端 2** — 处理 PDF：

```bash
# Batch all files in one call — each invocation spawns a JVM process, so repeated calls are slow
opendataloader-pdf --hybrid docling-fast file1.pdf file2.pdf folder/
```

**Python：**

```python
# Batch all files in one call — each convert() spawns a JVM process, so repeated calls are slow
opendataloader_pdf.convert(
    input_path=["file1.pdf", "file2.pdf", "folder/"],
    output_dir="output/",
    hybrid="docling-fast"
)
```

### 扫描 PDF 的 OCR

对没有可选中文本的基于图像 PDF，使用 `--force-ocr` 启动后端：

```bash
opendataloader-pdf-hybrid --port 5002 --force-ocr
```

对于非英文文档，请指定语言：

```bash
opendataloader-pdf-hybrid --port 5002 --force-ocr --ocr-lang "ko,en"
```

支持的语言：`en`、`ko`、`ja`、`ch_sim`、`ch_tra`、`de`、`fr`、`ar`，以及更多。

### 公式提取（LaTeX）

从科学 PDF 中提取数学公式为 LaTeX：

```bash
# Server: enable formula enrichment
opendataloader-pdf-hybrid --enrich-formula

# Batch all files in one call — each invocation spawns a JVM process, so repeated calls are slow
opendataloader-pdf --hybrid docling-fast --hybrid-mode full file1.pdf file2.pdf folder/
```

JSON 输出：
```json
{
  "type": "formula",
  "page number": 1,
  "bounding box": [226.2, 144.7, 377.1, 168.7],
  "content": "\\frac{f(x+h) - f(x)}{h}"
}
```

> **注意**：公式与图片描述增强功能需要在客户端使用 `--hybrid-mode full`。

### 图表与图片描述

为图表和图像生成 AI 描述 — 适用于 RAG 检索与无障碍 alt 文本：

```bash
# Server
opendataloader-pdf-hybrid --enrich-picture-description

# Batch all files in one call — each invocation spawns a JVM process, so repeated calls are slow
opendataloader-pdf --hybrid docling-fast --hybrid-mode full file1.pdf file2.pdf folder/
```

JSON 输出：
```json
{
  "type": "picture",
  "page number": 1,
  "bounding box": [72.0, 400.0, 540.0, 650.0],
  "description": "A bar chart showing waste generation by region from 2016 to 2030..."
}
```

> 使用 SmolVLM（256M），一款轻量级视觉模型。可通过 `--picture-description-prompt` 自定义提示词。

### Hancom Data Loader 集成 — 即将推出

通过 [Hancom Data Loader](https://sdk.hancom.com/en/services/1?utm_source=github&utm_medium=readme&utm_campaign=opendataloader-pdf) 提供企业级 AI 文档分析 — 基于你领域专属文档训练的定制化模型。支持 30+ 种元素类型（表格、图表、公式、题注、脚注等）、基于 VLM 的图像/图表理解、复杂表格提取（合并单元格、嵌套表格）、带 SLA 保障的扫描文档 OCR，以及原生 HWP/HWPX 支持。支持 PDF、DOCX、XLSX、PPTX、HWP、PNG、JPG。[在线演示](https://livedemo.sdk.hancom.com/en/dataloader?utm_source=github&utm_medium=readme&utm_campaign=opendataloader-pdf)

[Hybrid 模式指南](https://opendataloader.org/docs/hybrid-mode)

## 输出格式

| 格式 | 使用场景 |
|--------|----------|
| **JSON** | 带边界框与语义类型的结构化数据 |
| **Markdown** | 适用于 LLM 上下文、RAG 分块的整洁文本 |
| **HTML** | 带样式的网页展示 |
| **Annotated PDF** | 可视化调试 — 查看检测到的结构（[示例](https://opendataloader.org/demo/samples/01030000000000)) |
| **Text** | 纯文本提取 |

组合多种格式：`format="json,markdown"`

### JSON 输出示例

```json
{
  "type": "heading",
  "id": 42,
  "level": "Title",
  "page number": 1,
  "bounding box": [72.0, 700.0, 540.0, 730.0],
  "heading level": 1,
  "font": "Helvetica-Bold",
  "font size": 24.0,
  "text color": "[0.0]",
  "content": "Introduction"
}
```

| 字段 | 说明 |
|-------|-------------|
| `type` | 元素类型：heading、paragraph、table、list、image、caption、formula |
| `id` | 用于交叉引用的唯一标识符 |
| `page number` | 从 1 开始的页码引用 |
| `bounding box` | PDF 点（72pt = 1 英寸）中的 `[left, bottom, right, top]` |
| `heading level` | 标题层级（1+） |
| `content` | 提取的文本 |

[完整 JSON Schema](https://opendataloader.org/docs/reference/json-schema)

## 高级功能

### Tagged PDF 支持

当 PDF 带有结构标签时，OpenDataLoader 会提取作者**原本意图的精确版式** — 无需猜测，无需启发式规则。标题、列表、表格与阅读顺序均从源文件保留。

> **输出质量取决于标签质量。** 并非所有 Tagged PDF 都标注良好。对于标签稀疏或错误的 PDF，默认启发式模式或 `--hybrid docling-fast` 往往能产生更好的结果。

```python
# Batch all files in one call — each convert() spawns a JVM process, so repeated calls are slow
opendataloader_pdf.convert(
    input_path=["file1.pdf", "file2.pdf", "folder/"],
    output_dir="output/",
    use_struct_tree=True           # Use native PDF structure tags
)
```

大多数 PDF 解析器会完全忽略结构标签。[了解更多](https://opendataloader.org/docs/tagged-pdf)

### AI 安全：提示注入（Prompt Injection）防护

PDF 可能包含隐藏的提示注入攻击。OpenDataLoader 会自动过滤：

- 隐藏文本（透明、零尺寸字体）
- 页面外内容
- 可疑的不可见图层

要对敏感数据（电子邮件、URL、电话号码 → 占位符）进行脱敏，需显式启用：

```bash
# Batch all files in one call — each invocation spawns a JVM process, so repeated calls are slow
opendataloader-pdf file1.pdf file2.pdf folder/ --sanitize
```

[AI 安全指南](https://opendataloader.org/docs/ai-safety)

### LangChain 集成

```bash
pip install -U langchain-opendataloader-pdf
```

```python
from langchain_opendataloader_pdf import OpenDataLoaderPDFLoader

loader = OpenDataLoaderPDFLoader(
    file_path=["file1.pdf", "file2.pdf", "folder/"],
    format="text"
)
documents = loader.load()
```

[LangChain 文档](https://docs.langchain.com/oss/python/integrations/document_loaders/opendataloader_pdf) | [GitHub](https://github.com/opendataloader-project/langchain-opendataloader-pdf) | [PyPI](https://pypi.org/project/langchain-opendataloader-pdf/)

### 高级选项

```python
# Batch all files in one call — each convert() spawns a JVM process, so repeated calls are slow
opendataloader_pdf.convert(
    input_path=["file1.pdf", "file2.pdf", "folder/"],
    output_dir="output/",
    format="json,markdown,pdf",
    image_output="embedded",        # "off", "embedded" (Base64), or "external" (default)
    image_format="jpeg",            # "png" or "jpeg"
    use_struct_tree=True,           # Use native PDF structure
)
```

[完整 CLI 选项参考](https://opendataloader.org/docs/reference/cli-options)

## PDF 无障碍与 PDF/UA 转换

**问题**：数百万现有 PDF 缺少结构标签，无法满足无障碍法规要求（EAA、ADA/Section 508、韩国《数字包容法》）。人工修复每份文档成本为 $50–200，且无法规模化。

**OpenDataLoader 的方案**：与 [PDF Association](https://pdfa.org) 和 [Dual Lab](https://duallab.com)（[veraPDF](https://verapdf.org), 的开发者，后者是业界参考的开源 PDF/A 与 PDF/UA 验证器）合作构建。自动标记遵循 [Well-Tagged PDF 规范](https://pdfa.org/resource/well-tagged-pdf/)，并使用 veraPDF 进行程序化验证 — 针对 PDF 无障碍标准进行自动化一致性检查，而非人工审查。现有开源工具均无法端到端生成 Tagged PDF — 大多数在标签写入步骤依赖专有 SDK。OpenDataLoader 在 Apache 2.0 下实现全部功能。（[合作详情](https://opendataloader.org/docs/tagged-pdf-collaboration))

| 法规 | 截止日期 | 要求 |
|------------|----------|-------------|
| **European Accessibility Act (EAA)** | June 28, 2025 | 欧盟范围内的无障碍数字产品 |
| **ADA & Section 508** | In effect | 美国联邦机构及公共场所 |
| **Digital Inclusion Act** | In effect | 韩国数字服务无障碍 |

### 标准与验证

| 方面 | 详情 |
|--------|--------|
| **规范** | [Well-Tagged PDF](https://pdfa.org/resource/well-tagged-pdf/)（PDF Association 发布） |
| **验证** | [veraPDF](https://verapdf.org) — 业界参考的开源 PDF/A 与 PDF/UA 验证器 |
| **合作** | PDF Association + [Dual Lab](https://duallab.com)（veraPDF 开发者）共同开发标记与验证 |
| **许可证** | 自动标记 → Tagged PDF：Apache 2.0（免费）。PDF/UA 导出：企业版 |

### 无障碍流水线

| 步骤 | 功能 | 状态 | 层级 |
|------|---------|--------|------|
| 1. **审计** | 读取现有 PDF 标签，检测未标记的 PDF | Shipped | 免费 |
| 2. **自动标记 → Tagged PDF** | 为未标记的 PDF 生成结构标签 | Shipped | 免费（Apache 2.0） |
| 3. **导出 PDF/UA** | 转换为符合 PDF/UA-1 或 PDF/UA-2 标准的文件 | 💼 可用 | 企业版 |
| 4. **可视化编辑** | 无障碍工作室 — 审查并修复标签 | 💼 可用 | 企业版 |

> **💼 企业版功能** 可按需获取。[联系我们](https://opendataloader.org/contact) 开始使用。

### 自动标记

从未标记的 PDF 生成 Tagged PDF — 输出为带有结构标签（标题、段落、列表、表格、阅读顺序）的屏幕阅读器可用 PDF。

```python
import opendataloader_pdf

# Untagged PDF in → Tagged PDF out
opendataloader_pdf.convert(
    input_path=["file1.pdf", "file2.pdf", "folder/"],
    output_dir="output/",
    format="tagged-pdf"
)
```

```bash
# CLI
opendataloader-pdf --format tagged-pdf file1.pdf file2.pdf folder/
```

可与其他格式组合使用：`format="json,tagged-pdf"`。

### 端到端合规工作流

```
Existing PDFs (untagged)
    │
    ▼
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐    ┌──────────────────┐
│  1. Audit       │───>│  2. Auto-Tag     │───>│  3. Export      │───>│  4. Studio       │
│  (check tags)   │    │  (→ Tagged PDF)  │    │  (PDF/UA)       │    │  (visual editor) │
└─────────────────┘    └──────────────────┘    └─────────────────┘    └──────────────────┘
        │                       │                       │                      │
        ▼                       ▼                       ▼                      ▼
  use_struct_tree      format="tagged-pdf"        PDF/UA export       Accessibility Studio
  (Available now)      (Available, Apache 2.0)    (Enterprise)        (Enterprise)
```

[PDF 无障碍指南](https://opendataloader.org/docs/accessibility-compliance)

## 路线图

| 功能 | 时间线 | 层级 |
|---------|----------|------|
| **[Hancom Data Loader](https://sdk.hancom.com/en/services/1?utm_source=github&utm_medium=readme&utm_campaign=opendataloader-pdf)** — 企业级 AI 文档分析、客户定制模型、基于 VLM 的图表/图像理解、生产级 OCR | Q2-Q3 2026 | 计划中 |
| **结构验证** — 验证 PDF 标签树 | Q3 2026 | 计划中 |

[完整路线图](https://opendataloader.org/docs/upcoming-roadmap)

## 常见问题

### RAG 场景下最好的 PDF 解析器是什么？

对于 RAG 流水线，你需要一款能保留文档结构、维持正确阅读顺序，并为引用提供元素坐标的解析器。OpenDataLoader 正是为此设计 — 它输出带有边界框（bounding boxes）的结构化 JSON，使用 XY-Cut++ 处理多栏布局，且无需 GPU 即可在本地运行。在 hybrid 模式下，它在基准测试中综合排名第一（0.907）。

### 最好的开源 PDF 解析器是什么？

OpenDataLoader PDF 是唯一结合以下能力的开源解析器：基于规则的确定性提取（无需 GPU）、每个元素的边界框、XY-Cut++ 阅读顺序、内置 AI 安全过滤器、原生 Tagged PDF 支持，以及用于复杂文档的 hybrid AI 模式。它在 CPU 本地运行时综合准确率排名第一（0.907）。

### 如何从 PDF 中提取表格供 LLM 使用？

OpenDataLoader 通过边框分析和文本聚类检测表格，保留行列结构。对于复杂表格，启用 hybrid 模式可将准确率提升 90% 以上（TEDS 分数从 0.489 提升至 0.928）：

```python
# Batch all files in one call — each convert() spawns a JVM process, so repeated calls are slow
opendataloader_pdf.convert(
    input_path=["file1.pdf", "file2.pdf", "folder/"],
    output_dir="output/",
    format="json",
    hybrid="docling-fast"           # For complex tables
)
```

### 它与 docling、marker 或 pymupdf4llm 相比如何？

OpenDataLoader [hybrid] 在阅读顺序、表格和标题准确率方面综合排名第一（0.907）。主要差异：docling（0.882）表现强劲，但缺少边界框和 AI 安全过滤器。marker（0.861）需要 GPU，且速度慢 1000 倍（53.932 秒/页）。pymupdf4llm（0.732）速度快，但表格（0.401）和标题（0.412）准确率较差。OpenDataLoader 是唯一结合确定性本地提取、每个元素的边界框以及内置提示注入防护的解析器。详见[完整基准测试](https://github.com/opendataloader-project/opendataloader-bench).

### 能否在不将数据发送到云端的情况下使用？

是的。OpenDataLoader 完全在本地运行。无需 API 调用，不会传输数据——你的文档永远不会离开你的环境。混合模式（hybrid mode）后端也会在你的机器上本地运行。非常适合法律、医疗和金融类文档。

### 是否支持对扫描版 PDF 进行 OCR？

是的，通过混合模式。使用 `pip install "opendataloader-pdf[hybrid]"` 安装，用 `--force-ocr` 启动后端，然后照常处理。通过 `--ocr-lang` 支持韩语、日语、中文、阿拉伯语等多种语言。

### 是否支持韩语、日语或中文文档？

是的。对于数字 PDF，文本提取开箱即用。对于扫描版 PDF，请使用混合模式配合 `--force-ocr --ocr-lang "ko,en"`（或 `ja`、`ch_sim`、`ch_tra`）。即将推出：[Hancom Data Loader](https://sdk.hancom.com/en/services/1?utm_source=github&utm_medium=readme&utm_campaign=opendataloader-pdf) integration — 企业级 AI 文档分析，内置生产级 OCR，以及针对你的特定文档类型和工作流程优化的客户定制模型。

### 速度有多快？

本地模式在 CPU 上每秒可处理 60+ 页（0.02 秒/页）。混合模式每秒可处理 2+ 页（0.46 秒/页），对复杂文档的准确率显著更高。无需 GPU。在 Apple M4 上完成基准测试。[Full benchmark details](https://github.com/opendataloader-project/opendataloader-bench). 通过多进程批量处理，在 8+ 核机器上吞吐量可超过每秒 100 页。

### 是否支持多栏版式？

是的。OpenDataLoader 使用 XY-Cut++ 阅读顺序分析，可在多栏页面、侧边栏和混合版式中正确排序文本。这在本地模式和混合模式下均可使用，无需任何配置。

### 什么是混合模式？

混合模式将快速的本地 Java 处理与 AI 后端相结合。简单页面在本地处理（0.02 秒/页）；复杂页面（表格、扫描内容、公式、图表）会自动路由到 AI 后端以获得更高准确率。后端在你的机器上本地运行——无需云端。请参阅 [Which Mode Should I Use?](#which-mode-should-i-use) 和 [Hybrid Mode Guide](https://opendataloader.org/docs/hybrid-mode).

### 是否可与 LangChain 配合使用？

是的。安装 `langchain-opendataloader-pdf` 即可获得官方 LangChain 文档加载器集成。请参阅 [LangChain docs](https://docs.langchain.com/oss/python/integrations/document_loaders/opendataloader_pdf).

### 如何为 RAG 对 PDF 进行分块？

OpenDataLoader 输出结构化 Markdown，保留标题、表格和列表——非常适合作为语义分块的输入。JSON 输出中的每个元素都包含 `type`、`heading level` 和 `page number`，因此你可以按章节或页面边界进行拆分。对于大多数 RAG 流水线：使用 `format="markdown"` 解析文本块，或在需要元素级控制时使用 `format="json"`。配合 LangChain 的 `RecursiveCharacterTextSplitter` 或你自己的基于标题的分割器可获得最佳效果。

### 如何在 RAG 回答中引用 PDF 来源？

JSON 输出中的每个元素都包含 `bounding box`（PDF 点坐标中的 `[left, bottom, right, top]`）和 `page number`。当 RAG 流水线返回答案时，将来源块映射回其边界框，以在原始 PDF 中高亮显示确切位置。这实现了「点击溯源」用户体验——用户可以看到答案来自哪个段落、表格或图表。没有其他开源解析器默认提供每个元素的边界框。

### 如何将 PDF 转换为 Markdown 供 LLM 使用？

```python
import opendataloader_pdf

# Batch all files in one call — each convert() spawns a JVM process, so repeated calls are slow
opendataloader_pdf.convert(
    input_path=["file1.pdf", "file2.pdf", "folder/"],
    output_dir="output/",
    format="markdown"
)
```

OpenDataLoader 在 Markdown 输出中保留标题层级、表格结构和阅读顺序。对于包含无边框表格或扫描页面的复杂文档，请使用混合模式（`hybrid="docling-fast"`）以获得更高准确率。输出足够干净，可直接输入 LLM 上下文窗口或 RAG 分块流水线。

### 是否有自动化的 PDF 无障碍修复工具？

是的。OpenDataLoader 是首个端到端自动化 PDF 无障碍处理的开源工具。与 [PDF Association](https://pdfa.org) and [Dual Lab](https://duallab.com)（veraPDF 开发者）合作构建，自动标记遵循 Well-Tagged PDF 规范，并使用 veraPDF 进行程序化验证。版式分析引擎可检测文档结构（标题、表格、列表、阅读顺序）并自动生成无障碍标签。自动标记在 Apache 2.0 下将无标签 PDF 转换为 Tagged PDF——无需专有 SDK 依赖。使用 `format="tagged-pdf"`（Python/Node.js）或 `--format tagged-pdf`（CLI）。对于需要完整 PDF/UA 合规性的组织，企业附加组件提供 PDF/UA 导出和可视化标签编辑器。这可取代通常每份文档花费 $50–200+ 的手动修复工作流。

### 这真的是首个开源 PDF 自动标记工具吗？

是的。现有工具要么依赖专有 SDK 来写入结构标签，要么仅输出非 PDF 格式（例如，Docling 输出 Markdown/JSON 但无法生成 Tagged PDF），要么需要人工干预。OpenDataLoader 是首个在开源许可证（Apache 2.0）下完整实现版式分析 → 标签生成 → Tagged PDF 输出的工具，无专有依赖。自动标记遵循 PDF Association 的 Well-Tagged PDF 规范，并使用 veraPDF（行业参考级的开源 PDF/A 和 PDF/UA 验证器）进行验证。

### 如何将现有 PDF 转换为 PDF/UA？

OpenDataLoader 提供端到端流水线：审计现有 PDF 的标签（`use_struct_tree=True`）、将无标签 PDF 自动标记为 Tagged PDF（`format="tagged-pdf"`，在 Apache 2.0 下免费），并导出为 PDF/UA-1 或 PDF/UA-2（企业附加组件）。自动标记遵循 PDF Association 的 Well-Tagged PDF 规范，并使用 veraPDF 进行验证。自动标记生成 Tagged PDF；PDF/UA 导出是最后一步。[Contact us](https://opendataloader.org/contact) for enterprise integration.

### 如何使 PDF 符合 EAA 合规要求？

《欧洲无障碍法案》（European Accessibility Act）要求于 2025 年 6 月 28 日前提供无障碍数字产品。OpenDataLoader 支持完整的修复工作流：审计 → 自动标记 → Tagged PDF → PDF/UA 导出。自动标记遵循 PDF Association 的 Well-Tagged PDF 规范，并使用 veraPDF 进行验证，确保符合标准的输出。自动标记为 Tagged PDF 在 Apache 2.0 下开源。PDF/UA 导出和无障碍工作室（accessibility studio）为企业附加组件。请参阅我们的 [Accessibility Guide](https://opendataloader.org/docs/accessibility-compliance).

### OpenDataLoader PDF 是否免费？

核心库**在 Apache 2.0 下开源**——可免费用于商业用途。这包括所有提取功能（文本、表格、图片、OCR、公式、通过混合模式的图表）、AI 安全过滤器、Tagged PDF 支持，以及自动标记为 Tagged PDF。我们承诺保持核心无障碍流水线（版式分析 → 自动标记 → Tagged PDF）免费且开源。企业附加组件（PDF/UA 导出、无障碍工作室）可供需要端到端监管合规的组织使用。

### 许可证为何从 MPL 2.0 更改为 Apache 2.0？

MPL 2.0 要求文件级 copyleft，这通常会在企业采用前触发法律审查。Apache 2.0 完全宽松——无 copyleft 义务，更易集成到商业项目中。如果你使用的是 2.0 之前的版本，它仍受 MPL 2.0 约束，你可以继续使用。升级到 2.0+ 意味着你的项目遵循 Apache 2.0 条款，该条款严格来说更加宽松——无额外义务，你无需采取任何行动。

## 文档

- [快速入门（Python）](https://opendataloader.org/docs/quick-start-python)
- [快速入门（Node.js）](https://opendataloader.org/docs/quick-start-nodejs)
- [快速入门（Java）](https://opendataloader.org/docs/quick-start-java)
- [JSON Schema 参考](https://opendataloader.org/docs/reference/json-schema)
- [CLI 选项](https://opendataloader.org/docs/reference/cli-options)
- [混合模式指南](https://opendataloader.org/docs/hybrid-mode)
- [Tagged PDF 支持](https://opendataloader.org/docs/tagged-pdf)
- [AI 安全功能](https://opendataloader.org/docs/ai-safety)
- [PDF 无障碍](https://opendataloader.org/docs/accessibility-compliance)

## 贡献

欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解贡献指南。

## 许可证

[Apache License 2.0](LICENSE)

> **注意：** 2.0 之前的版本采用 [Mozilla Public License 2.0](https://www.mozilla.org/MPL/2.0/).

---

**觉得有帮助？** 给我们点个 Star，帮助更多人发现 OpenDataLoader。