OpenDataLoader PDF 完整教學

第 1 章:專案定位 (Project Positioning)

解決什麼問題

OpenDataLoader PDF 解決兩個核心痛點:

  1. PDF 資料擷取品質低落 (poor PDF data extraction quality):傳統 PDF 解析器無法正確保留閱讀順序、破壞表格結構、缺少元素座標。對 RAG (Retrieval-Augmented Generation) 管線來說,這意味著 LLM 收到的上下文可能是錯亂的,導致產生錯誤回答。

  2. PDF 無障礙合規成本過高 (high cost of PDF accessibility compliance):歐洲無障礙法案 (EAA, European Accessibility Act)、ADA Section 508、韓國數位包容法等法規要求 PDF 文件必須具備結構標記 (structure tags)。手動修復每份文件需 $50–200 美元,企業規模下完全不可擴展。

與競品比較

引擎整體準確率速度 (s/page)授權特色
OpenDataLoader [hybrid]0.9070.463Apache-2.0Bounding box + AI safety + auto-tagging
docling0.8820.762MIT強表格解析,但無 bounding box
marker0.86153.932GPL-3.0需 GPU,速度慢 1000x
pymupdf4llm0.7320.091AGPL-3.0快速但表格/標題準確率低
markitdown0.5890.114MIT無表格/標題偵測

適用場景

  • RAG pipeline (檢索增強生成管線) 的前處理
  • LLM context 準備(PDF → Markdown / JSON)
  • 大規模 PDF 無障礙修復 (accessibility remediation at scale)
  • 學術論文資料擷取(含公式、表格、圖表)
  • 法規合規自動化(EAA、ADA、Section 508)

第 2 章:安裝指南 (Installation Guide)

前置條件

  • Java 11+(必要):核心引擎以 Java 編寫
  • Python 3.10+(Python SDK)
  • Node.js 18+(Node.js SDK)
1# 檢查 Java 版本
2java -version
3
4# 若未安裝,從 Adoptium 安裝 JDK 11+
5# https://adoptium.net/

Python 安裝

1# 基本安裝(本地模式)
2pip install -U opendataloader-pdf
3
4# 含 hybrid 模式(複雜 PDF 需要)
5pip install -U "opendataloader-pdf[hybrid]"
6
7# MCP 伺服器(AI agent 整合)
8pip install -U opendataloader-pdf-mcp

Node.js 安裝

1npm install @opendataloader/pdf

Java 安裝(Maven)

1<dependency>
2  <groupId>org.opendataloader</groupId>
3  <artifactId>opendataloader-pdf-core</artifactId>
4  <version>2.4.7</version>
5</dependency>

驗證安裝

1# CLI 驗證
2opendataloader-pdf --version
3
4# Python 驗證
5python -c "import opendataloader_pdf; print('OK')"

第 3 章:核心架構解析 (Core Architecture Analysis)

整體架構

OpenDataLoader PDF 採用多層式架構 (multi-layered architecture),以 Java 為核心引擎,透過 subprocess 機制向 Python 和 Node.js SDK 提供功能。


flowchart TB
    subgraph SDK["SDK Layer (SDK 層)"]
        PY["Python SDK
wrapper.py → subprocess"] NODE["Node.js SDK
index.ts → child_process"] JAVA_API["Java API
OpenDataLoaderPDF.processFile()"] MCP["MCP Server
FastMCP → convert_pdf()"] end subgraph Core["Java Core Engine (Java 核心引擎)"] CONFIG["Config
922 行設定管理"] DOC_PROC["DocumentProcessor
主處理管線"] TRIAGE["TriageProcessor
頁面複雜度分流"] AUTO_TAG["AutoTagger
結構標記生成"] end subgraph Output["Output Generators (輸出生成器)"] MD["MarkdownGenerator"] JSON_GEN["JSONGenerator"] HTML_GEN["HTMLGenerator"] TEXT_GEN["TextGenerator"] TAG_PDF["TaggedPDFWriter"] end subgraph Hybrid["Hybrid Backend (混合後端)"] HYBRID_SRV["hybrid_server.py
FastAPI + docling"] DOCLING["DoclingFastServerClient"] HANCOM["HancomClient
企業級 AI"] end subgraph Entities["Semantic Entities (語義實體)"] PICTURE["SemanticPicture"] FORMULA["SemanticFormula"] FOOTNOTE["SemanticFootnote"] end PY --> |subprocess 呼叫 JAR| DOC_PROC NODE --> |child_process 呼叫 JAR| DOC_PROC JAVA_API --> DOC_PROC MCP --> PY DOC_PROC --> CONFIG DOC_PROC --> TRIAGE DOC_PROC --> AUTO_TAG TRIAGE --> |複雜頁面| DOCLING TRIAGE --> |簡單頁面| MD DOCLING --> HYBRID_SRV DOC_PROC --> MD DOC_PROC --> JSON_GEN DOC_PROC --> HTML_GEN DOC_PROC --> TEXT_GEN DOC_PROC --> TAG_PDF DOC_PROC --> PICTURE DOC_PROC --> FORMULA DOC_PROC --> FOOTNOTE style SDK fill:#e3f2fd style Core fill:#fff3e0 style Output fill:#e8f5e9 style Hybrid fill:#fce4ec style Entities fill:#f3e5f5

核心元件說明

1. Java 核心引擎 (Java Core Engine)

  • OpenDataLoaderPDF:主入口類別 (main entry class),暴露 processFile(inputPdfName, config) 靜態方法
  • Config:龐大的設定物件 (922 行),管理所有選項:輸出格式、hybrid 設定、OCR 參數、安全過濾、密碼等
  • DocumentProcessor:主處理管線 (main processing pipeline),協調整個 PDF 解析流程
  • TriageProcessor:hybrid 模式的頁面分流器 (page triage),1132 行,判斷哪些頁面需要 AI 處理

2. Python SDK 架構

Python SDK 的核心設計非常輕量:

  • runner.py:底層 JAR 執行器 (low-level JAR runner),透過 subprocess.run()subprocess.Popen() 呼叫 bundled JAR
  • wrapper.py:高階 API (high-level API),提供 convert() 函式及 CLI 入口 main()
  • convert_generated.py:自動生成的 convert() 函式,將 Python 參數轉換為 Java CLI 引數
  • hybrid_server.py:FastAPI 伺服器 (1033 行),使用 docling DocumentConverter singleton 處理複雜頁面

3. Hybrid 模式運作方式

Hybrid 模式 (hybrid mode) 結合了快速的本地 Java 解析與 AI 後端 (AI backend) 處理:

  1. 本地分析 (local analysis):Java 引擎先分析每一頁的結構複雜度
  2. 頁面分流 (page triage)TriageProcessor 判斷頁面是否需要 AI 處理(例如複雜表格、掃描影像、公式)
  3. AI 處理 (AI processing):複雜頁面送到 hybrid_server.py(FastAPI + docling SDK),由 DoclingFastServerClient 負責通訊
  4. 結果合併 (result merging)HybridSchemaTransformer / DoclingSchemaTransformer 將 AI 結果轉換回統一格式

目錄結構

 1opendataloader-pdf/
 2├── java/
 3   ├── opendataloader-pdf-core/   # Java 核心引擎(105 個 .java 檔案)
 4      └── src/main/java/org/opendataloader/pdf/
 5          ├── api/               # 主入口、Config、AutoTagger
 6          ├── hybrid/            # Hybrid 模式(TriageProcessor、Client)
 7          ├── processors/        # 文件處理器、reading order
 8          ├── markdown/          # Markdown 生成器
 9          ├── json/              # JSON 生成器
10          ├── html/              # HTML 生成器
11          ├── autotagging/       # 自動標記引擎
12          └── entities/          # 語義實體
13   └── opendataloader-pdf-cli/    # CLI 入口 (CLIMain.java)
14├── python/
15   ├── opendataloader-pdf/        # Python SDK
16      └── src/opendataloader_pdf/
17          ├── wrapper.py         # 高階 API + CLI 入口
18          ├── runner.py          # JAR 執行器
19          ├── convert_generated.py # 自動生成的 convert()
20          └── hybrid_server.py   # FastAPI hybrid 後端
21   └── opendataloader-pdf-mcp/    # MCP 伺服器
22├── node/opendataloader-pdf/       # Node.js SDK (TypeScript)
23├── samples/                       # 範例 PDF 檔案
24├── examples/python/               # Python 使用範例
25├── scripts/                       # 建置與測試腳本
26└── docs/                          # 設計文件

第 4 章:使用方式詳解 (Detailed Usage Guide)

4.1 基本轉換 (Basic Conversion)

Python

1import opendataloader_pdf
2
3# 批次轉換多檔案 — 每次 convert() 啟動一個 JVM 程序,重複呼叫效能差
4opendataloader_pdf.convert(
5    input_path=["file1.pdf", "file2.pdf", "folder/"],
6    output_dir="output/",
7    format="markdown,json"
8)

CLI

1# 預設輸出 JSON
2opendataloader-pdf file1.pdf file2.pdf folder/
3
4# 指定格式
5opendataloader-pdf --format markdown,json file1.pdf folder/

Node.js

1import { convert } from '@opendataloader/pdf';
2
3await convert(['file1.pdf', 'folder/'], {
4  outputDir: 'output/',
5  format: 'markdown,json'
6});

4.2 Hybrid 模式 (Hybrid Mode)

適用於複雜表格、掃描 PDF、公式、圖表等需要 AI 處理的場景。

1# 安裝 hybrid 依賴
2pip install -U "opendataloader-pdf[hybrid]"
3
4# Terminal 1:啟動 hybrid 後端
5opendataloader-pdf-hybrid --port 5002
6
7# Terminal 2:處理 PDF
8opendataloader-pdf --hybrid docling-fast file1.pdf file2.pdf folder/
1# Python API
2opendataloader_pdf.convert(
3    input_path=["file1.pdf", "folder/"],
4    output_dir="output/",
5    hybrid="docling-fast"
6)

4.3 OCR 掃描 PDF (OCR for Scanned PDFs)

1# 啟動 hybrid 後端 + OCR
2opendataloader-pdf-hybrid --port 5002 --force-ocr
3
4# 非英語文件(指定語言)
5opendataloader-pdf-hybrid --port 5002 --force-ocr --ocr-lang "ko,en"
6
7# 支援語言:en, ko, ja, ch_sim, ch_tra, de, fr, ar 等 80+

4.4 公式擷取 (Formula Extraction)

1# 後端啟用公式 enrichment
2opendataloader-pdf-hybrid --enrich-formula
3
4# 客戶端需加 --hybrid-mode full
5opendataloader-pdf --hybrid docling-fast --hybrid-mode full paper.pdf

4.5 圖表描述 (Chart & Image Description)

1# 後端啟用圖片描述(使用 SmolVLM 256M)
2opendataloader-pdf-hybrid --enrich-picture-description
3
4# 客戶端
5opendataloader-pdf --hybrid docling-fast --hybrid-mode full report.pdf

4.6 自動標記 → Tagged PDF (Auto-Tagging)

1# 將未標記 PDF 轉為 Tagged PDF
2opendataloader_pdf.convert(
3    input_path=["untagged.pdf"],
4    output_dir="output/",
5    format="tagged-pdf"
6)
1# CLI
2opendataloader-pdf --format tagged-pdf untagged.pdf

4.7 Tagged PDF 結構擷取 (Structure Tree Extraction)

1# 讀取已標記 PDF 的原生結構
2opendataloader_pdf.convert(
3    input_path=["tagged.pdf"],
4    output_dir="output/",
5    use_struct_tree=True
6)

4.8 AI 安全過濾 (AI Safety Filtering)

1# 預設啟用:自動過濾隱藏文字、頁外內容、可疑隱形圖層
2
3# 敏感資料遮蔽(email、URL、電話 → 佔位符)
4opendataloader-pdf file1.pdf --sanitize
5
6# 關閉安全過濾(不建議)
7opendataloader-pdf file1.pdf --content-safety-off all

4.9 MCP 伺服器 (MCP Server)

1# 安裝
2pip install opendataloader-pdf-mcp
3
4# 啟動 MCP 伺服器
5opendataloader-pdf-mcp

MCP 伺服器提供 convert_pdf 工具,支援所有轉換選項,可直接由 Claude Code 或其他 AI agent 呼叫。

4.10 LangChain 整合 (LangChain Integration)

1pip install -U langchain-opendataloader-pdf
1from langchain_opendataloader_pdf import OpenDataLoaderPDFLoader
2
3loader = OpenDataLoaderPDFLoader(
4    file_path=["file1.pdf", "folder/"],
5    format="text"
6)
7documents = loader.load()

第 5 章:應用場景 (Use Cases)

5.1 RAG Pipeline 前處理

OpenDataLoader 是 RAG pipeline (檢索增強生成管線) 的理想前處理工具:

  1. 解析 PDF → Markdownformat="markdown" 保留標題、表格、清單結構
  2. 語義切割 (semantic chunking):配合 LangChain RecursiveCharacterTextSplitter 依標題分割
  3. 來源追溯 (source citation):JSON 輸出的 bounding box + page number 可實現「點擊定位原文」功能
1# Step 1: PDF → JSON(含 bounding box)
2opendataloader_pdf.convert(
3    input_path=["research_paper.pdf"],
4    output_dir="parsed/",
5    format="json,markdown",
6    hybrid="docling-fast"   # 複雜文件用 hybrid
7)

5.2 大規模 PDF 無障礙修復

1# 批次處理整個資料夾
2opendataloader-pdf --format tagged-pdf /path/to/untagged_pdfs/

5.3 學術論文資料擷取

1# 含公式 + 圖表描述
2opendataloader_pdf.convert(
3    input_path=["paper.pdf"],
4    output_dir="output/",
5    format="json",
6    hybrid="docling-fast",
7    hybrid_mode="full"  # 啟用公式與圖片 enrichment
8)

5.4 法規合規自動化

支援 EAA (European Accessibility Act)、ADA Section 508、韓國數位包容法等法規的合規工作流:

1未標記 PDF → 稽核 (audit) → 自動標記 (auto-tag) → Tagged PDF → PDF/UA 匯出(企業版)

第 6 章:資安掃描報告 (Security Scan Report)

掃描方法

對整個程式碼庫進行靜態掃描,搜尋以下模式:eval(), exec(), os.system(), subprocess, shell=True, pickle.load(), __import__(), Runtime.getRuntime(), ProcessBuilder, .exec(), 硬編碼密碼/金鑰/Token, urlopen, requests.get/post

掃描結果

🟢 硬編碼密碼/金鑰/Token

  • CI/CD secrets.github/workflows/ 中使用 ${{ secrets.* }} 引用(CODECOV_TOKEN、MAVEN_CENTRAL_PASSWORD、NPM_TOKEN、GITHUB_TOKEN),這是 GitHub Actions 標準做法,無安全疑慮
  • PDF 密碼參數Config.javaCLIMain.javawrapper.pyserver.py 中的 password 參數是功能性設計(用於解鎖加密 PDF),不是硬編碼密碼,無安全疑慮
  • Token 變數名稱ChunksWriter.javaPDFStreamWriter.java 中的 token 是 PDF 語法分析用的 token (符號),與安全無關,無安全疑慮

🟡 Subprocess 使用

  • runner.py:使用 subprocess.run()subprocess.Popen() 執行 bundled JAR。命令由程式碼組裝,未接受外部 shell 命令,風險低。未使用 shell=True
  • wrapper.py:透過 runner.run_jar() 間接使用 subprocess,風險低
  • scripts/experiments/:benchmark 腳本使用 subprocess.Popen()requests.post(),僅用於內部效能測試,風險低

🟡 __import__ 使用

  • test_hybrid_server_ocr_options.py:測試程式碼中使用 monkeypatch.setitem(__import__("sys").modules, ...) 來 mock 模組,僅在測試環境中使用,風險低

🟢 Runtime.getRuntime()

  • Config.java:894Runtime.getRuntime().availableProcessors() 用於限制執行緒數量,標準 Java 做法,無安全疑慮

🟢 HTTP 請求

  • benchmark 腳本requests.post() / requests.get() 僅用於內部效能測試(連接 localhost 的 docling/FastAPI 伺服器),無安全疑慮

總體評級

🟢 安全等級:良好 (Good)

未發現硬編碼密碼、危險的 eval/exec 呼叫、或 shell injection 風險。Subprocess 使用遵循安全慣例(不使用 shell=True、命令由程式碼組裝)。CI/CD secrets 使用 GitHub Actions 標準機制。整體程式碼安全品質優良。


第 7 章:FAQ — 常見問題 (Frequently Asked Questions)

Q1:需要 GPU 嗎?

不需要。 本地模式完全在 CPU 上運行,每秒處理 60+ 頁。Hybrid 模式的 docling 後端也可在 CPU 上運行,但 GPU 可加速 OCR 與公式擷取。

Q2:如何處理中文/日文/韓文 PDF?

數位 PDF 直接支援。掃描 PDF 需使用 hybrid 模式 + OCR:

1opendataloader-pdf-hybrid --force-ocr --ocr-lang "ch_tra,en"

Q3:每次 convert() 都啟動新 JVM 嗎?

是的。Python/Node.js SDK 透過 subprocess 呼叫 bundled JAR,每次呼叫 convert() 都啟動一個新的 JVM 程序。因此建議批次處理:在單次 convert() 中傳入多個檔案或資料夾。

Q4:支援哪些輸出格式?

JSON、Markdown、HTML、Text、Annotated PDF、Tagged PDF。可組合使用:format="json,markdown,tagged-pdf"

Q5:本地模式和 hybrid 模式有什麼差別?

特性本地模式Hybrid 模式
速度0.015 s/page0.463 s/page
準確率0.8310.907
需額外服務需啟動 hybrid 後端
適用場景標準數位 PDF複雜表格、掃描件、公式

Q6:授權有什麼限制?

Apache 2.0 完全自由商用。自動標記 → Tagged PDF 也是 Apache 2.0。只有 PDF/UA 匯出和無障礙工作室是企業版付費功能。

Q7:如何確保資料不外洩?

完全本地執行 (100% local),無 API 呼叫,無資料傳輸。Hybrid 模式後端也在本地運行。適合法律、醫療、金融等敏感領域。


第 8 章:進階技巧 (Advanced Techniques)

8.1 效能最佳化 (Performance Optimization)

 1# 批次處理(推薦)— 單次 JVM 啟動處理多個檔案
 2opendataloader_pdf.convert(
 3    input_path=["file1.pdf", "file2.pdf", "entire_folder/"],
 4    output_dir="output/",
 5    format="markdown"
 6)
 7
 8# 避免在迴圈中重複呼叫 convert()(每次啟動新 JVM)
 9# ❌ 效能差
10for f in files:
11    opendataloader_pdf.convert(input_path=f, ...)
12
13# ✅ 效能好
14opendataloader_pdf.convert(input_path=files, ...)

8.2 頁面範圍擷取 (Page Range Extraction)

1# 只擷取特定頁面
2opendataloader-pdf --pages "1,3,5-10" document.pdf
1opendataloader_pdf.convert(
2    input_path="document.pdf",
3    output_dir="output/",
4    pages="1,3,5-10"
5)

8.3 影像處理選項 (Image Output Options)

1opendataloader_pdf.convert(
2    input_path="document.pdf",
3    output_dir="output/",
4    format="markdown-with-images",
5    image_output="embedded",    # "off", "embedded" (Base64), "external"
6    image_format="jpeg"         # "png" 或 "jpeg"
7)

8.4 Java API 直接使用

1import org.opendataloader.pdf.api.Config;
2import org.opendataloader.pdf.api.OpenDataLoaderPDF;
3
4Config config = new Config();
5config.setFormat("json,markdown");
6config.setHybrid("docling-fast");
7
8OpenDataLoaderPDF.processFile("input.pdf", config);
9OpenDataLoaderPDF.shutdown();  // 釋放 HTTP client 等資源

8.5 自動標記 API (Auto-Tagging API)

 1import org.opendataloader.pdf.api.AutoTagger;
 2import org.opendataloader.pdf.api.Config;
 3import org.opendataloader.pdf.api.TaggingResult;
 4
 5Config config = new Config();
 6config.setHybrid("docling-fast");
 7
 8try (TaggingResult result = AutoTagger.tag("input.pdf", config)) {
 9    // 取得記憶體中的 tagged PDDocument
10    var tagged = result.getDocument();
11    // 進一步處理...
12}

8.6 Hybrid 後端進階設定

 1# 自訂 OCR 引擎(Tesseract,支援 EasyOCR 不支援的語言)
 2opendataloader-pdf-hybrid --ocr-engine tesseract --ocr-lang mal
 3
 4# 停用 OCR(當 PDF 已有可靠嵌入文字時)
 5opendataloader-pdf-hybrid --no-ocr
 6
 7# 自訂圖片描述 prompt
 8opendataloader-pdf-hybrid --enrich-picture-description --picture-description-prompt "Describe this chart in detail."
 9
10# 限制上傳檔案大小
11opendataloader-pdf-hybrid --max-file-size 100  # MB

第 9 章:整合進其他工作流 (Integration with Other Workflows)

9.1 整合 LangChain RAG Pipeline

 1from langchain_opendataloader_pdf import OpenDataLoaderPDFLoader
 2from langchain.text_splitter import RecursiveCharacterTextSplitter
 3from langchain_community.vectorstores import Chroma
 4
 5# Step 1: 解析 PDF
 6loader = OpenDataLoaderPDFLoader(
 7    file_path=["research_papers/"],
 8    format="text"
 9)
10documents = loader.load()
11
12# Step 2: 切割
13splitter = RecursiveCharacterTextSplitter(chunk_size=1000, chunk_overlap=200)
14chunks = splitter.split_documents(documents)
15
16# Step 3: 向量化存入
17vectorstore = Chroma.from_documents(chunks, embedding_model)

9.2 整合 AI Agent (MCP)

在 Claude Desktop 或其他支援 MCP 的 AI 工具設定中加入:

1{
2  "mcpServers": {
3    "opendataloader-pdf": {
4      "command": "opendataloader-pdf-mcp"
5    }
6  }
7}

AI agent 即可直接呼叫 convert_pdf 工具解析 PDF。

9.3 搭配 AI Knowledge Template 使用

 1# 在 AI-knowledge_template v1 中使用 docling skill(內部使用 opendataloader-pdf 替代)
 2# docling: research_paper.pdf
 3
 4# 或直接使用 Python SDK
 5python -c "
 6import opendataloader_pdf
 7opendataloader_pdf.convert(
 8    input_path='inbox/paper.pdf',
 9    output_dir='inbox/',
10    format='markdown'
11)
12"

9.4 JSON 來源引用 (Source Citation)

 1import json
 2
 3# 讀取 JSON 輸出
 4with open("output/paper.json") as f:
 5    elements = json.load(f)
 6
 7# 每個元素都有 bounding box 可追溯來源
 8for elem in elements:
 9    if elem["type"] == "table":
10        page = elem["page number"]
11        bbox = elem["bounding box"]  # [left, bottom, right, top]
12        print(f"Table on page {page} at {bbox}")

第 10 章:重點摘要 Checklist (Key Summary Checklist)

開始使用前

  • 確認 Java 11+ 已安裝(java -version
  • 安裝 Python SDK:pip install opendataloader-pdf
  • 若需處理複雜 PDF:pip install "opendataloader-pdf[hybrid]"

選擇正確模式

  • 標準數位 PDF → 本地模式(預設)
  • 複雜表格 / 掃描件 → Hybrid 模式 (--hybrid docling-fast)
  • 掃描 + 非英語 → Hybrid + OCR (--force-ocr --ocr-lang "xx")
  • 公式 / 圖表 → Hybrid + --hybrid-mode full
  • 無障礙修復 → --format tagged-pdf

效能最佳化

  • 使用批次轉換(單次 convert() 傳入多檔案)
  • 避免迴圈中重複呼叫 convert()
  • 不需要的格式不要產生(減少 I/O)

安全考量

  • 確認 --sanitize 在處理敏感文件時已啟用
  • 不要關閉 content safety(--content-safety-off)除非有充分理由
  • Hybrid 後端全程本地運行,無資料外洩風險

整合檢查

  • RAG pipeline:使用 JSON 輸出的 bounding box 做來源引用
  • LangChain:安裝 langchain-opendataloader-pdf
  • AI Agent:安裝 MCP 伺服器 opendataloader-pdf-mcp

第 11 章:進一步閱讀 (Further Reading)

官方文件

相關資源

競品與替代方案

工具特色授權
docling強表格解析,MITMIT
markerGPU 加速,高品質GPL-3.0
pymupdf4llm速度快,API 簡潔AGPL-3.0
unstructured通用文件處理Apache-2.0
markitdown多格式轉換MIT