OpenDataLoader PDF 教程：先测 Fast，再决定是否启用 Hybrid

OpenDataLoader PDF 用 Java 核心把 PDF 转成 Markdown、HTML、文本或带坐标的 JSON。普通数字 PDF 可以先走本地 Fast 路径；扫描件、复杂表格、公式和图片描述才需要考虑 Hybrid。这样测试，才能知道额外服务到底解决了什么问题。

1. 固定环境和版本

java -version
python3 -m venv .venv
source .venv/bin/activate
python -m pip install opendataloader-pdf==2.5.11

先确认 Java 可用，再安装 Python 包。Python 和 Node.js 都会调用 Java 核心，缺少 JVM 时只排查上层代码没有意义。

2. 准备三类测试文件

各准备一份有文本层的普通 PDF、扫描 PDF 和复杂表格 PDF，并记录页数、标题顺序与关键单元格。使用无敏感内容的副本。项目只处理 PDF，DOCX、XLSX 和 PPTX 应放到别的工具测试。

3. 一次调用批量运行 Fast

python - <<'PY'
import opendataloader_pdf
opendataloader_pdf.convert(
    input_path=["samples/text.pdf", "samples/table.pdf"],
    output_dir="output/fast",
    format="markdown,json"
)
PY

官方 README 明确说每次 convert() 都会启动 JVM。把多个文件放进一次调用，能减少反复启动的开销。JSON 要检查元素类型、页码和 bounding box；Markdown 要对照原页检查阅读顺序。

4. 只在需要时测试 Hybrid

python -m pip install "opendataloader-pdf[hybrid]==2.5.11"
opendataloader-pdf-hybrid --port 5002 --force-ocr
opendataloader-pdf --hybrid docling-fast samples/scan.pdf -o output/hybrid

Hybrid 是单独的服务路径。扫描件可启用 OCR，公式和图片描述还要配置相应增强项。不要把结构树模式和 Hybrid 混在同一次判断中：README 说明 --use-struct-tree 会优先，届时不会调用 Hybrid 后端。

5. 把 Tagged PDF 与合规分开

开源核心可以输出 Tagged PDF，但“有标签”不等于“已经通过 PDF/UA”。项目把 PDF/UA-1、PDF/UA-2 导出和可视化编辑器列为企业功能。无障碍交付还应使用目标标准的验证器，并用实际辅助技术检查阅读顺序、标题、表格和替代文本。

6. 记录可以复查的结果

为每种样本保留输入文件哈希、命令、版本、耗时和错误日志。逐页记录缺字、错序、表格错位与坐标偏差。项目方基准只能说明其测试条件，不能替代你的合同、论文或扫描档案。

常见问题