docs(asl): Complete Tool 3 extraction workbench V2.0 development plan (v1.5)
ASL Tool 3 Development Plan: - Architecture blueprint v1.5 (6 rounds of architecture review, 13 red lines) - M1/M2/M3 sprint checklists (Skeleton Pipeline / HITL Workbench / Dynamic Template Engine) - Code patterns cookbook (9 chapters: Fan-out, Prompt engineering, ACL, SSE dual-track, etc.) - Key patterns: Fan-out with Last Child Wins, Optimistic Locking, teamConcurrency throttling - PKB ACL integration (anti-corruption layer), MinerU Cache-Aside, NOTIFY/LISTEN cross-pod SSE - Data consistency snapshot for long-running extraction tasks Platform capability: - Add distributed Fan-out task pattern development guide (7 patterns + 10 anti-patterns) - Add system-level async architecture risk analysis blueprint - Add PDF table extraction engine design and usage guide (MinerU integration) - Add table extraction source code (TableExtractionManager + MinerU engine) Documentation updates: - Update ASL module status with Tool 3 V2.0 plan readiness - Update system status document (v6.2) with latest milestones - Add V2.0 product requirements, prototypes, and data dictionary specs - Add architecture review documents (4 rounds of review feedback) - Add test PDF files for extraction validation Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
584
docs/02-通用能力层/02-文档处理引擎/03-PDF表格提取引擎设计方案.md
Normal file
584
docs/02-通用能力层/02-文档处理引擎/03-PDF表格提取引擎设计方案.md
Normal file
@@ -0,0 +1,584 @@
|
||||
# PDF 表格提取引擎设计方案
|
||||
|
||||
> **文档版本**: v1.0
|
||||
> **创建日期**: 2026-02-23
|
||||
> **最后更新**: 2026-02-23
|
||||
> **文档目的**: 定义 PDF 表格提取引擎的统一架构，为系统综述/Meta 分析等场景提供精确的结构化表格数据
|
||||
> **核心原则**: 引擎对使用者透明 — 提交 PDF，返回结构化表格，无需关心底层实现
|
||||
> **当前状态**: MinerU Cloud API (VLM) 已接入并完成测试，其他引擎待逐步评测
|
||||
|
||||
---
|
||||
|
||||
## 1. 业务背景
|
||||
|
||||
### 1.1 核心需求
|
||||
|
||||
ASL 智能文献模块的**全文复筛**环节，需要从医学 PDF 文献中精确提取数据表格：
|
||||
|
||||
- **系统综述 (Systematic Review)**: 基线特征表、结局指标表、不良事件表
|
||||
- **Meta 分析**: 效应值、置信区间、样本量等关键数值
|
||||
- **数据核验**: 数值必须与原文 100% 一致，不容许任何精度损失
|
||||
|
||||
### 1.2 为什么独立建设
|
||||
|
||||
当前文档处理引擎基于 `pymupdf4llm`，定位是 **PDF → Markdown 全文文本转换**，在表格提取场景中存在严重缺陷：
|
||||
|
||||
| 问题 | 实测数据 |
|
||||
|------|----------|
|
||||
| 8 篇 PDF 仅 1 篇输出结构化表格 | 表格检出率 12.5% |
|
||||
| 其余 7 篇表格退化为纯文本 | 行列结构完全丢失 |
|
||||
| 不支持合并单元格 | 医学表格大量使用 rowspan/colspan |
|
||||
|
||||
**结论：全文文本提取和结构化表格提取是两个不同的能力，需要分别建设。**
|
||||
|
||||
---
|
||||
|
||||
## 2. 引擎架构设计
|
||||
|
||||
### 2.1 核心理念
|
||||
|
||||
> **使用者不需要关心底层用了什么技术，只需要：提交 PDF → 获取结构化表格。**
|
||||
|
||||
底层引擎可以是 MinerU、Qwen-VL、PaddleOCR、Docling 或任意其他方案，通过统一接口抽象，实现热切换和渐进升级。
|
||||
|
||||
### 2.2 统一架构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 业务层 (使用者) │
|
||||
│ ASL 全文复筛 / 系统综述数据提取 / Meta 分析 │
|
||||
│ │
|
||||
│ const tables = await tableEngine.extract(pdfBuffer); │
|
||||
│ // 只关心输入 PDF 和输出 tables，不关心底层引擎 │
|
||||
└───────────────────────────┬─────────────────────────────────┘
|
||||
│
|
||||
┌───────────────────────────▼─────────────────────────────────┐
|
||||
│ PDF 表格提取引擎 (统一抽象层) │
|
||||
│ │
|
||||
│ interface TableExtractionEngine { │
|
||||
│ extract(pdf: Buffer): Promise<ExtractedTable[]> │
|
||||
│ extractFromUrl(url: string): Promise<ExtractedTable[]> │
|
||||
│ } │
|
||||
│ │
|
||||
│ 统一输出：ExtractedTable[] │
|
||||
│ ┌──────────────────────────────────────────────────────┐ │
|
||||
│ │ { title, headers, rows, mergedCells, footnotes, │ │
|
||||
│ │ pageNumber, confidence, rawHtml } │ │
|
||||
│ └──────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ 引擎适配器 (可插拔) │
|
||||
│ │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ MinerU │ │ Qwen3-VL │ │ PaddleOCR-VL │ │
|
||||
│ │ Cloud API │ │ 多模态 LLM │ │ 百度 OCR │ │
|
||||
│ │ (VLM) │ │ │ │ │ │
|
||||
│ │ ✅ 已接入 │ │ 📋 待评测 │ │ 📋 待评测 │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||
│ │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ Qwen-OCR + │ │ Docling │ │ DeepSeek │ │
|
||||
│ │ Qwen-Long │ │ (IBM) │ │ LLM │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ 📋 待评测 │ │ 📋 待评测 │ │ ✅ 已测试 │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 2.3 统一输出格式
|
||||
|
||||
无论底层使用哪个引擎，输出都遵循统一的 `ExtractedTable` 结构：
|
||||
|
||||
```typescript
|
||||
interface ExtractedTable {
|
||||
/** 表格标题 (如 "Table 1 Baseline characteristics") */
|
||||
title: string;
|
||||
/** 表头行 */
|
||||
headers: string[];
|
||||
/** 数据行 (二维数组) */
|
||||
rows: string[][];
|
||||
/** 合并单元格信息 */
|
||||
mergedCells?: MergedCell[];
|
||||
/** 脚注 */
|
||||
footnotes?: string[];
|
||||
/** 所在 PDF 页码 */
|
||||
pageNumber?: number;
|
||||
/** 引擎自信度 (0-1) */
|
||||
confidence?: number;
|
||||
/** 原始 HTML (供前端渲染或调试) */
|
||||
rawHtml?: string;
|
||||
/** 原始 Markdown (备选格式) */
|
||||
rawMarkdown?: string;
|
||||
}
|
||||
|
||||
interface MergedCell {
|
||||
row: number;
|
||||
col: number;
|
||||
rowSpan: number;
|
||||
colSpan: number;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 候选引擎全景
|
||||
|
||||
### 3.1 引擎候选清单
|
||||
|
||||
| 引擎 | 类型 | 特点 | 成本 | 状态 |
|
||||
|------|------|------|------|------|
|
||||
| **MinerU Cloud API** | VLM 云端 | 表格结构最完整，rowspan/colspan 支持 | 2000 页/天免费 | ✅ 已接入 |
|
||||
| **Qwen3-VL** | 多模态 LLM | 多模态理解最强，复杂表格语义识别好 | 按 token 计费 | 📋 待评测 |
|
||||
| **Qwen-OCR + Qwen-Long** | OCR + LLM 组合 | 成本最低、功能最全的组合方案 | 极低 | 📋 待评测 |
|
||||
| **百度 PaddleOCR-VL 1.5** | VL OCR | 医学场景案例多，准确率高，免费额度最多 | 官方免费额度多 | 📋 待评测 |
|
||||
| **Docling (IBM)** | 本地部署 | MIT 开源，TableFormer 模型，可完全离线 | 免费 (本地部署) | 📋 待评测 |
|
||||
| **DeepSeek LLM** | 文本 LLM | 从原始文本重构表格，Markdown 输出 | ~0.14 元/万 token | ✅ 已测试 |
|
||||
|
||||
### 3.2 推荐分类
|
||||
|
||||
**最佳性价比组合：**
|
||||
1. **Qwen-OCR + Qwen-Long** — 成本最低，功能最全
|
||||
2. **百度 PaddleOCR-VL** — 官方免费额度最多，技术最成熟
|
||||
|
||||
**医学文献表格提取最佳选择：**
|
||||
1. **Qwen3-VL** — 多模态理解最强，支持复杂表格
|
||||
2. **百度 PaddleOCR-VL 1.5** — 医学场景案例多，准确率高
|
||||
|
||||
**数据合规 / 离线场景：**
|
||||
1. **Docling (IBM)** — MIT 开源，完全本地部署
|
||||
|
||||
### 3.3 评测计划
|
||||
|
||||
按优先级逐步评测，使用同一组 8 篇医学 PDF 文献作为基准：
|
||||
|
||||
| 阶段 | 引擎 | 优先级 | 评测重点 |
|
||||
|------|------|--------|----------|
|
||||
| ✅ 已完成 | MinerU Cloud API | — | 作为 baseline |
|
||||
| ✅ 已完成 | DeepSeek LLM | — | 文本 LLM 方案的上限 |
|
||||
| P1 待测 | Qwen3-VL | 高 | 多模态 vs MinerU VLM 的表格精度 |
|
||||
| P1 待测 | PaddleOCR-VL 1.5 | 高 | 免费额度 + 医学场景准确率 |
|
||||
| P2 待测 | Qwen-OCR + Qwen-Long | 中 | 验证最低成本方案的可行性 |
|
||||
| P2 待测 | Docling | 中 | 离线方案，评估部署成本 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 已完成测试：MinerU vs pymupdf4llm vs DeepSeek
|
||||
|
||||
### 4.1 测试概要
|
||||
|
||||
- **测试对象**: 8 篇真实医学 PDF 文献（含 1 篇中文），涵盖 RCT、队列研究
|
||||
- **测试方法**: pymupdf4llm (本地) / MinerU Cloud API (VLM) / DeepSeek LLM (deepseek-chat)
|
||||
|
||||
### 4.2 核心结果
|
||||
|
||||
| 指标 | pymupdf4llm | MinerU API (VLM) | DeepSeek LLM |
|
||||
|------|-------------|------------------|--------------|
|
||||
| 结构化表格检出 | 3 个 (12.5%) | **28 个 (100%)** | 24 个 (85%) |
|
||||
| 输出格式 | 纯文本 | **HTML `<table>`** | Markdown `\|..\|` |
|
||||
| 合并单元格 | ❌ | **✅ rowspan/colspan** | ⚠️ 文字描述 |
|
||||
| 数值精度 | ✅ 原始 | **✅ 100% 保真** | ⚠️ 可能翻译 |
|
||||
| 总耗时 (8 篇) | 16.1s | ~50s | 234.6s |
|
||||
| 综合评分 | 2.7/5 | **4.6/5** | 3.4/5 |
|
||||
|
||||
### 4.3 逐文件对比
|
||||
|
||||
| # | 文件 | pymupdf4llm | MinerU API | DeepSeek LLM |
|
||||
|---|------|-------------|------------|--------------|
|
||||
| 1 | S2589537025 (EClinMed) | 0 表格 | **1 HTML** | 1 MD |
|
||||
| 2 | Dongen 2003 | 0 结构化 | **4 HTML** | 3 MD |
|
||||
| 3 | Ginkgo+Donepezil | 0 结构化 | **3 HTML** | 3 MD |
|
||||
| 4 | Ginkgo Community | 0 结构化 | **6 HTML** | 6 MD |
|
||||
| 5 | Ginkgo NPS | 3 MD | **3 HTML** | 3 MD |
|
||||
| 6 | Herrschaft 2012 | 0 结构化 | **3 HTML** | 3 MD |
|
||||
| 7 | Ihl 2011 | 0 结构化 | **3 HTML** | 3 MD |
|
||||
| 8 | NIRS 队列研究 (中文) | 0 结构化 | **5 HTML** | 2 MD |
|
||||
|
||||
### 4.4 质量深度分析 (Herrschaft 2012 — Table 1)
|
||||
|
||||
原始表格: 5 列、18 行，"Type of dementia" 合并 3 行。
|
||||
|
||||
| 特征 | pymupdf4llm | MinerU API | DeepSeek LLM |
|
||||
|------|-------------|------------|--------------|
|
||||
| 列数正确 | ❌ 无结构 | **✅ 5 列** | ✅ 4 列 |
|
||||
| 行数完整 | ✅ 数据在 | **✅ 18 行** | ✅ 18 行 |
|
||||
| 合并单元格 | ❌ | **✅ rowspan=3** | ⚠️ 加粗标注 |
|
||||
| 数值保真 | ✅ | **✅ 含 ±** | ⚠️ 翻译行名 |
|
||||
|
||||
### 4.5 综合评分
|
||||
|
||||
| 维度 | pymupdf4llm | MinerU API | DeepSeek LLM |
|
||||
|------|:-----------:|:----------:|:------------:|
|
||||
| 表格检测率 | 1/5 | **5/5** | 4/5 |
|
||||
| 结构保真度 | 1/5 | **5/5** | 4/5 |
|
||||
| 数值精度 | 5/5 | **5/5** | 4/5 |
|
||||
| 速度 | 5/5 | 3/5 | 2/5 |
|
||||
| 合并单元格 | 1/5 | **5/5** | 3/5 |
|
||||
| 中文支持 | 3/5 | **5/5** | 4/5 |
|
||||
| 成本 | 5/5 | 4/5 | 3/5 |
|
||||
| **综合** | **2.7** | **4.6** | **3.4** |
|
||||
|
||||
---
|
||||
|
||||
## 5. 技术实现设计
|
||||
|
||||
### 5.1 接口抽象
|
||||
|
||||
```typescript
|
||||
// common/document/tableExtraction/types.ts
|
||||
|
||||
/** 统一引擎接口 — 所有适配器必须实现 */
|
||||
interface ITableExtractionEngine {
|
||||
readonly name: string;
|
||||
extract(pdf: Buffer, options?: ExtractionOptions): Promise<ExtractionResult>;
|
||||
}
|
||||
|
||||
interface ExtractionOptions {
|
||||
language?: 'ch' | 'en' | 'auto';
|
||||
/** 指定页码范围，如 "1-5,8" */
|
||||
pageRanges?: string;
|
||||
/** 是否启用公式识别 */
|
||||
enableFormula?: boolean;
|
||||
}
|
||||
|
||||
interface ExtractionResult {
|
||||
tables: ExtractedTable[];
|
||||
/** 引擎名称 */
|
||||
engine: string;
|
||||
/** 处理耗时 (ms) */
|
||||
duration: number;
|
||||
/** PDF 总页数 */
|
||||
pageCount: number;
|
||||
/** 原始 Markdown 全文 (可选) */
|
||||
fullMarkdown?: string;
|
||||
}
|
||||
```
|
||||
|
||||
### 5.2 引擎管理器
|
||||
|
||||
```typescript
|
||||
// common/document/tableExtraction/engineManager.ts
|
||||
|
||||
class TableExtractionEngineManager {
|
||||
private engines: Map<string, ITableExtractionEngine> = new Map();
|
||||
private defaultEngine: string = 'mineru';
|
||||
|
||||
/** 注册引擎适配器 */
|
||||
register(engine: ITableExtractionEngine): void {
|
||||
this.engines.set(engine.name, engine);
|
||||
}
|
||||
|
||||
/** 设置默认引擎 */
|
||||
setDefault(name: string): void {
|
||||
this.defaultEngine = name;
|
||||
}
|
||||
|
||||
/** 提取表格 — 使用者唯一入口 */
|
||||
async extract(
|
||||
pdf: Buffer,
|
||||
options?: ExtractionOptions & { engine?: string }
|
||||
): Promise<ExtractionResult> {
|
||||
const engineName = options?.engine || this.defaultEngine;
|
||||
const engine = this.engines.get(engineName);
|
||||
if (!engine) throw new Error(`Engine not found: ${engineName}`);
|
||||
return engine.extract(pdf, options);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 5.3 MinerU 适配器 (第一个实现)
|
||||
|
||||
```typescript
|
||||
// common/document/tableExtraction/engines/mineruEngine.ts
|
||||
|
||||
class MinerUEngine implements ITableExtractionEngine {
|
||||
readonly name = 'mineru';
|
||||
|
||||
async extract(pdf: Buffer, options?: ExtractionOptions): Promise<ExtractionResult> {
|
||||
// 1. 请求上传 URL
|
||||
// 2. 上传 PDF
|
||||
// 3. 轮询等待解析完成
|
||||
// 4. 下载结果 ZIP
|
||||
// 5. 解析 HTML 表格 → ExtractedTable[]
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 5.4 未来适配器 (预留接口)
|
||||
|
||||
```typescript
|
||||
// 后续逐步实现
|
||||
class Qwen3VLEngine implements ITableExtractionEngine { ... }
|
||||
class PaddleOCRVLEngine implements ITableExtractionEngine { ... }
|
||||
class QwenOCRLongEngine implements ITableExtractionEngine { ... }
|
||||
class DoclingEngine implements ITableExtractionEngine { ... }
|
||||
```
|
||||
|
||||
### 5.5 文件规划
|
||||
|
||||
```
|
||||
backend/src/common/document/tableExtraction/
|
||||
├── types.ts # 统一类型定义
|
||||
├── engineManager.ts # 引擎管理器 (统一入口)
|
||||
├── htmlTableParser.ts # HTML <table> → ExtractedTable 转换
|
||||
├── engines/
|
||||
│ ├── mineruEngine.ts # MinerU Cloud API 适配器 ✅ 首个实现
|
||||
│ ├── qwen3vlEngine.ts # Qwen3-VL 适配器 (待实现)
|
||||
│ ├── paddleOcrEngine.ts # PaddleOCR-VL 适配器 (待实现)
|
||||
│ ├── qwenOcrLongEngine.ts # Qwen-OCR + Qwen-Long 适配器 (待实现)
|
||||
│ ├── doclingEngine.ts # Docling 适配器 (待实现)
|
||||
│ └── deepseekEngine.ts # DeepSeek LLM 适配器 (已测试，可选)
|
||||
└── index.ts # 导出统一入口
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 使用方式
|
||||
|
||||
### 6.1 业务层调用 (使用者视角)
|
||||
|
||||
```typescript
|
||||
import { getTableExtractionEngine } from '@/common/document/tableExtraction';
|
||||
|
||||
// 使用者不需要知道底层是 MinerU 还是 Qwen-VL
|
||||
const engine = getTableExtractionEngine();
|
||||
const result = await engine.extract(pdfBuffer, { language: 'auto' });
|
||||
|
||||
for (const table of result.tables) {
|
||||
console.log(`${table.title}: ${table.rows.length} 行 × ${table.headers.length} 列`);
|
||||
// 直接使用结构化数据
|
||||
}
|
||||
```
|
||||
|
||||
### 6.2 管理员切换引擎
|
||||
|
||||
```bash
|
||||
# backend/.env — 切换默认引擎
|
||||
TABLE_EXTRACTION_ENGINE=mineru # 当前默认
|
||||
# TABLE_EXTRACTION_ENGINE=qwen3vl # 未来切换
|
||||
# TABLE_EXTRACTION_ENGINE=paddle # 未来切换
|
||||
|
||||
# MinerU 配置
|
||||
MINERU_API_TOKEN=your_token
|
||||
MINERU_API_BASE=https://mineru.net/api/v4
|
||||
MINERU_MODEL_VERSION=vlm
|
||||
```
|
||||
|
||||
### 6.3 场景决策矩阵
|
||||
|
||||
| 场景 | 推荐引擎 | 说明 |
|
||||
|------|----------|------|
|
||||
| ASL 标题摘要初筛 | pymupdf4llm (文本引擎) | 不需要表格，只需全文文本 |
|
||||
| ASL 全文复筛 — 表格提取 | **PDF 表格提取引擎** | 自动选择最优引擎 |
|
||||
| 系统综述数据提取 | **PDF 表格提取引擎** | 需要精确数值表格 |
|
||||
| Meta 分析效应值识别 | 表格引擎 + LLM 语义理解 | 提取 → 理解两步走 |
|
||||
| PKB 知识库入库 | pymupdf4llm (文本引擎) | 只需 Markdown 文本 |
|
||||
|
||||
---
|
||||
|
||||
## 7. MinerU Cloud API 接入指南 (当前默认引擎)
|
||||
|
||||
### 7.1 API 概览
|
||||
|
||||
| 项目 | 说明 |
|
||||
|------|------|
|
||||
| 服务商 | OpenDataLab (上海人工智能实验室) |
|
||||
| API 地址 | `https://mineru.net/api/v4` |
|
||||
| 认证方式 | Bearer Token |
|
||||
| 模型版本 | `vlm` (视觉语言模型，推荐) |
|
||||
| 免费额度 | 2000 页/天 |
|
||||
| 文件限制 | 单文件 ≤ 200MB，≤ 600 页 |
|
||||
|
||||
### 7.2 核心流程
|
||||
|
||||
```
|
||||
PDF 文件
|
||||
│
|
||||
▼
|
||||
Step 1: POST /file-urls/batch → 获取预签名上传 URL + batch_id
|
||||
│
|
||||
▼
|
||||
Step 2: PUT {pre-signed URL} → 上传 PDF 文件
|
||||
│
|
||||
▼
|
||||
Step 3: 云端 VLM 模型自动解析 → 识别表格/文本/图片
|
||||
│
|
||||
▼
|
||||
Step 4: GET /extract-results/batch/{batch_id} → 轮询状态
|
||||
│
|
||||
▼
|
||||
Step 5: 下载结果 ZIP → 含 .md (内嵌 HTML 表格) + .json + images
|
||||
```
|
||||
|
||||
### 7.3 代码示例
|
||||
|
||||
```python
|
||||
import requests, time, zipfile, io
|
||||
|
||||
TOKEN = "your_token"
|
||||
API = "https://mineru.net/api/v4"
|
||||
headers = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}
|
||||
|
||||
# Step 1: 请求上传 URL
|
||||
resp = requests.post(f"{API}/file-urls/batch", headers=headers, json={
|
||||
"files": [{"name": "paper.pdf", "data_id": "paper1"}],
|
||||
"enable_table": True,
|
||||
"model_version": "vlm",
|
||||
})
|
||||
batch_id = resp.json()["data"]["batch_id"]
|
||||
upload_url = resp.json()["data"]["file_urls"][0]
|
||||
|
||||
# Step 2: 上传文件
|
||||
with open("paper.pdf", "rb") as f:
|
||||
requests.put(upload_url, data=f)
|
||||
|
||||
# Step 3-4: 轮询等待
|
||||
while True:
|
||||
time.sleep(10)
|
||||
r = requests.get(f"{API}/extract-results/batch/{batch_id}", headers=headers)
|
||||
results = r.json()["data"]["extract_result"]
|
||||
if all(x["state"] in ("done", "failed") for x in results):
|
||||
break
|
||||
|
||||
# Step 5: 下载解析
|
||||
for result in results:
|
||||
if result["state"] == "done":
|
||||
zr = requests.get(result["full_zip_url"])
|
||||
with zipfile.ZipFile(io.BytesIO(zr.content)) as zf:
|
||||
for name in zf.namelist():
|
||||
if name.endswith('.md'):
|
||||
md = zf.read(name).decode('utf-8')
|
||||
# md 中包含 HTML <table> 格式的表格
|
||||
```
|
||||
|
||||
### 7.4 输出格式
|
||||
|
||||
MinerU 的表格以 HTML `<table>` 嵌入 Markdown 中，完整保留合并单元格：
|
||||
|
||||
```html
|
||||
<table>
|
||||
<tr><td rowspan="3">Type of dementia</td><td>Probable AD</td><td>107 (54)</td></tr>
|
||||
<tr><td>Possible AD with CVD</td><td>73 (36)</td></tr>
|
||||
<tr><td>Probable VaD</td><td>20 (10)</td></tr>
|
||||
</table>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 成本估算
|
||||
|
||||
### 8.1 MinerU (当前)
|
||||
|
||||
| 场景 | 文献数 | 平均页数 | 总页数 | 天数 | 费用 |
|
||||
|------|--------|----------|--------|------|------|
|
||||
| 小型综述 | 20 篇 | 10 页 | 200 页 | 1 天 | 免费 |
|
||||
| 中型综述 | 100 篇 | 10 页 | 1000 页 | 1 天 | 免费 |
|
||||
| 大型综述 | 500 篇 | 10 页 | 5000 页 | 3 天 | 免费 |
|
||||
|
||||
### 8.2 各引擎预估成本对比
|
||||
|
||||
| 引擎 | 免费额度 | 超出后单价 | 500 篇 (5000 页) 预估 |
|
||||
|------|----------|-----------|----------------------|
|
||||
| MinerU | 2000 页/天 | 待确认 | 免费 (分 3 天) |
|
||||
| Qwen-OCR + Qwen-Long | 按 token | ~0.004 元/千 token | 约 10-20 元 |
|
||||
| PaddleOCR-VL | 官方免费额度多 | 极低 | 接近免费 |
|
||||
| Qwen3-VL | 按 token | ~0.02 元/千 token | 约 50-100 元 |
|
||||
| Docling | 本地部署 | 仅算力成本 | 免费 |
|
||||
| DeepSeek LLM | 按 token | ~0.14 元/万 token | 约 30-50 元 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 测试脚本
|
||||
|
||||
### 9.1 已有脚本
|
||||
|
||||
| 脚本 | 路径 | 功能 |
|
||||
|------|------|------|
|
||||
| 三方对比测试 | `extraction_service/test_pdf_table_extraction.py` | pymupdf4llm / MinerU / DeepSeek 完整对比 |
|
||||
| 结果分析 | `extraction_service/analyze_table_results.py` | 从提取结果生成对比报告 |
|
||||
|
||||
### 9.2 运行方法
|
||||
|
||||
```bash
|
||||
cd AIclinicalresearch
|
||||
|
||||
# 运行全部三个方法
|
||||
python extraction_service/test_pdf_table_extraction.py
|
||||
|
||||
# 单独运行某个方法
|
||||
python extraction_service/test_pdf_table_extraction.py pymupdf
|
||||
python extraction_service/test_pdf_table_extraction.py mineru
|
||||
python extraction_service/test_pdf_table_extraction.py deepseek
|
||||
|
||||
# 生成对比报告
|
||||
python extraction_service/analyze_table_results.py
|
||||
```
|
||||
|
||||
### 9.3 测试输出
|
||||
|
||||
```
|
||||
extraction_service/test_output/pdf_table_extraction/
|
||||
├── pymupdf4llm/ # pymupdf4llm 提取结果
|
||||
├── mineru/ # MinerU 提取结果
|
||||
├── deepseek/ # DeepSeek 提取结果
|
||||
├── raw_results.json # 原始测试数据
|
||||
└── comparison_report.md # 综合对比报告
|
||||
```
|
||||
|
||||
### 9.4 后续评测扩展
|
||||
|
||||
新引擎的评测脚本将遵循同样的结构，添加到 `test_pdf_table_extraction.py` 中：
|
||||
|
||||
```bash
|
||||
python extraction_service/test_pdf_table_extraction.py qwen3vl
|
||||
python extraction_service/test_pdf_table_extraction.py paddle
|
||||
python extraction_service/test_pdf_table_extraction.py qwenocr
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. 路线图
|
||||
|
||||
### Phase 1: 基础框架 + MinerU (当前)
|
||||
|
||||
- [x] MinerU Cloud API 对比测试
|
||||
- [x] DeepSeek LLM 对比测试
|
||||
- [ ] 实现统一接口 `ITableExtractionEngine`
|
||||
- [ ] 实现 `MinerUEngine` 适配器
|
||||
- [ ] 实现 `engineManager` 引擎管理器
|
||||
- [ ] ASL 全文复筛集成
|
||||
|
||||
### Phase 2: 多引擎评测
|
||||
|
||||
- [ ] Qwen3-VL 评测 + 适配器
|
||||
- [ ] PaddleOCR-VL 1.5 评测 + 适配器
|
||||
- [ ] 同一基准集横向对比报告
|
||||
- [ ] 确定最优引擎组合策略
|
||||
|
||||
### Phase 3: 性价比优化
|
||||
|
||||
- [ ] Qwen-OCR + Qwen-Long 评测 (最低成本方案)
|
||||
- [ ] Docling 本地部署评测 (离线方案)
|
||||
- [ ] 引擎路由策略 (按文档复杂度自动选择引擎)
|
||||
|
||||
### Phase 4: 生产加固
|
||||
|
||||
- [ ] 提取结果缓存 (避免重复解析)
|
||||
- [ ] 批量提取队列 (pg-boss 异步任务)
|
||||
- [ ] 质量监控 (空表格/异常值检测)
|
||||
- [ ] 引擎降级策略 (主引擎不可用时自动切换)
|
||||
|
||||
---
|
||||
|
||||
## 11. 相关文档
|
||||
|
||||
- [文档处理引擎 README](./README.md) — 引擎总览 (含全文文本提取)
|
||||
- [文档处理引擎设计方案 V1](./01-文档处理引擎设计方案.md) — pymupdf4llm 全文文本架构
|
||||
- [文档处理引擎使用指南](./02-文档处理引擎使用指南.md) — 现有 API 调用指南
|
||||
- [MinerU 官方文档](https://mineru.net/doc/docs/index_en/) — MinerU Cloud API 在线文档
|
||||
- [对比测试报告](../../../extraction_service/test_output/pdf_table_extraction/comparison_report.md) — 完整测试数据
|
||||
|
||||
---
|
||||
|
||||
**维护人**: 技术架构师
|
||||
**设计原则**: 引擎对使用者透明，底层可热切换，以测试数据驱动选型
|
||||
471
docs/02-通用能力层/02-文档处理引擎/04-PDF表格提取引擎使用指南.md
Normal file
471
docs/02-通用能力层/02-文档处理引擎/04-PDF表格提取引擎使用指南.md
Normal file
@@ -0,0 +1,471 @@
|
||||
# PDF 表格提取引擎使用指南
|
||||
|
||||
> **文档版本**: v1.0
|
||||
> **最后更新**: 2026-02-23
|
||||
> **状态**: ✅ 已测试通过（MinerU 引擎）
|
||||
> **目标读者**: 业务模块开发者（ASL 全文复筛、系统综述数据提取等）
|
||||
> **前置条件**: `backend/.env` 中已配置 `MINERU_API_TOKEN`
|
||||
|
||||
---
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 5 秒上手
|
||||
|
||||
```typescript
|
||||
import { getTableExtractionManager } from '../common/document/tableExtraction/index.js';
|
||||
|
||||
const manager = getTableExtractionManager();
|
||||
const result = await manager.extractTables(pdfBuffer, 'paper.pdf');
|
||||
|
||||
for (const table of result.tables) {
|
||||
console.log(`${table.title}: ${table.rows.length} 行 × ${table.headers.length} 列`);
|
||||
}
|
||||
```
|
||||
|
||||
### 完整调用示例
|
||||
|
||||
```typescript
|
||||
import fs from 'fs';
|
||||
import { getTableExtractionManager } from '../common/document/tableExtraction/index.js';
|
||||
|
||||
const manager = getTableExtractionManager();
|
||||
|
||||
// 读取 PDF 文件
|
||||
const pdf = fs.readFileSync('/path/to/medical-paper.pdf');
|
||||
|
||||
// 提取表格（自动使用默认引擎 MinerU）
|
||||
const result = await manager.extractTables(pdf, 'medical-paper.pdf', {
|
||||
keepRaw: true, // 保留原始 Markdown
|
||||
});
|
||||
|
||||
console.log(`引擎: ${result.engine}`); // "mineru"
|
||||
console.log(`耗时: ${result.duration}ms`); // ~6000-20000ms
|
||||
console.log(`表格数: ${result.tables.length}`);
|
||||
|
||||
// 遍历每个表格
|
||||
for (const table of result.tables) {
|
||||
console.log(`\n[${table.title}]`);
|
||||
console.log(` 列: ${table.headers.join(' | ')}`);
|
||||
console.log(` 行数: ${table.rows.length}`);
|
||||
console.log(` 合并单元格: ${table.mergedCells.length}`);
|
||||
|
||||
// 访问具体数据
|
||||
for (const row of table.rows) {
|
||||
// row 是 string[]，与 headers 一一对应
|
||||
console.log(` ${row.join(' | ')}`);
|
||||
}
|
||||
|
||||
// 原始 HTML（可直接渲染到前端）
|
||||
if (table.rawHtml) {
|
||||
console.log(` [HTML] ${table.rawHtml.substring(0, 100)}...`);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 核心概念
|
||||
|
||||
### 架构设计
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────────────┐
|
||||
│ 业务代码（ASL / 系统综述 / Meta 分析） │
|
||||
│ │
|
||||
│ manager.extractTables(pdf, filename) │
|
||||
│ → 返回 ExtractedTable[] │
|
||||
└──────────────────────┬─────────────────────────────┘
|
||||
│
|
||||
┌──────────────────────▼─────────────────────────────┐
|
||||
│ TableExtractionManager (统一入口) │
|
||||
│ │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────┐ │
|
||||
│ │ MinerU (VLM) │ │ Qwen-VL │ │ Paddle │ │
|
||||
│ │ ✅ 已接入 │ │ 📋 待接入 │ │ 📋 待接入 │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────┘ │
|
||||
└────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**核心原则：使用者不需要关心底层引擎。** 提交 PDF → 获取结构化表格。
|
||||
|
||||
### 数据结构
|
||||
|
||||
```typescript
|
||||
// 提取结果
|
||||
interface ExtractionResult {
|
||||
tables: ExtractedTable[]; // 表格列表
|
||||
engine: string; // 使用的引擎名
|
||||
duration: number; // 耗时 (ms)
|
||||
pageCount?: number; // PDF 页数
|
||||
fullMarkdown?: string; // 完整 Markdown (需 keepRaw: true)
|
||||
}
|
||||
|
||||
// 单个表格
|
||||
interface ExtractedTable {
|
||||
title: string; // "Table 1 Baseline characteristics"
|
||||
headers: string[]; // 表头列名
|
||||
rows: string[][]; // 数据行（二维数组）
|
||||
mergedCells: MergedCell[]; // 合并单元格
|
||||
footnotes: string[]; // 脚注
|
||||
pageNumber?: number; // 页码
|
||||
rawHtml?: string; // 原始 HTML
|
||||
rawMarkdown?: string; // 原始 Markdown
|
||||
}
|
||||
|
||||
// 合并单元格
|
||||
interface MergedCell {
|
||||
row: number; // 起始行 (0-based)
|
||||
col: number; // 起始列 (0-based)
|
||||
rowSpan: number;
|
||||
colSpan: number;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API 参考
|
||||
|
||||
### `getTableExtractionManager()`
|
||||
|
||||
获取全局管理器单例。首次调用时自动注册 MinerU 引擎。
|
||||
|
||||
```typescript
|
||||
import { getTableExtractionManager } from '../common/document/tableExtraction/index.js';
|
||||
|
||||
const manager = getTableExtractionManager();
|
||||
```
|
||||
|
||||
### `manager.extractTables(pdf, filename, options?)`
|
||||
|
||||
提取 PDF 中的表格。
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `pdf` | `Buffer` | ✅ | PDF 文件内容 |
|
||||
| `filename` | `string` | ✅ | 文件名（含 .pdf 后缀） |
|
||||
| `options.language` | `'zh' \| 'en' \| 'auto'` | ❌ | 语言提示 |
|
||||
| `options.pages` | `number[]` | ❌ | 指定页码 |
|
||||
| `options.keepRaw` | `boolean` | ❌ | 保留原始 Markdown |
|
||||
| `options.engine` | `EngineType` | ❌ | 覆盖默认引擎 |
|
||||
|
||||
返回：`Promise<ExtractionResult>`
|
||||
|
||||
### `manager.availableEngines()`
|
||||
|
||||
返回已注册的引擎名称列表。
|
||||
|
||||
```typescript
|
||||
console.log(manager.availableEngines()); // ['mineru']
|
||||
```
|
||||
|
||||
### `manager.getEngine(name?)`
|
||||
|
||||
获取指定引擎实例。
|
||||
|
||||
### `manager.setDefault(name)`
|
||||
|
||||
切换默认引擎。
|
||||
|
||||
---
|
||||
|
||||
## 实战场景
|
||||
|
||||
### 场景 1：ASL 全文复筛 — 提取基线特征表
|
||||
|
||||
```typescript
|
||||
import { getTableExtractionManager } from '../common/document/tableExtraction/index.js';
|
||||
|
||||
async function extractBaselineTable(pdfBuffer: Buffer, filename: string) {
|
||||
const manager = getTableExtractionManager();
|
||||
const result = await manager.extractTables(pdfBuffer, filename);
|
||||
|
||||
// 找到 "Table 1" 或包含 "Baseline" 的表格
|
||||
const baseline = result.tables.find(
|
||||
(t) =>
|
||||
/table\s*1\b/i.test(t.title) ||
|
||||
/baseline/i.test(t.title),
|
||||
);
|
||||
|
||||
if (baseline) {
|
||||
return {
|
||||
title: baseline.title,
|
||||
columns: baseline.headers,
|
||||
data: baseline.rows,
|
||||
hasMergedCells: baseline.mergedCells.length > 0,
|
||||
};
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
```
|
||||
|
||||
### 场景 2：系统综述 — 提取所有表格为 JSON
|
||||
|
||||
```typescript
|
||||
async function extractAllTablesAsJson(pdfBuffer: Buffer, filename: string) {
|
||||
const manager = getTableExtractionManager();
|
||||
const result = await manager.extractTables(pdfBuffer, filename);
|
||||
|
||||
return result.tables.map((table) => ({
|
||||
title: table.title,
|
||||
headers: table.headers,
|
||||
rows: table.rows.map((row) => {
|
||||
const obj: Record<string, string> = {};
|
||||
table.headers.forEach((h, i) => {
|
||||
obj[h] = row[i] || '';
|
||||
});
|
||||
return obj;
|
||||
}),
|
||||
}));
|
||||
}
|
||||
|
||||
// 输出示例:
|
||||
// [
|
||||
// {
|
||||
// title: "Table 1 Baseline characteristics",
|
||||
// headers: ["", "", "EGb 761®(N=200)", "Placebo(N=202)", "p-value"],
|
||||
// rows: [
|
||||
// { "": "Sex female", "": "", "EGb 761®(N=200)": "139 (69.5)", ... },
|
||||
// ...
|
||||
// ]
|
||||
// }
|
||||
// ]
|
||||
```
|
||||
|
||||
### 场景 3：Meta 分析 — 提取效应值
|
||||
|
||||
```typescript
|
||||
async function extractEffectSizes(pdfBuffer: Buffer, filename: string) {
|
||||
const manager = getTableExtractionManager();
|
||||
const result = await manager.extractTables(pdfBuffer, filename);
|
||||
|
||||
// 找结局指标表
|
||||
const outcomeTable = result.tables.find(
|
||||
(t) => /outcome|result|efficacy|effect/i.test(t.title),
|
||||
);
|
||||
|
||||
if (!outcomeTable) return [];
|
||||
|
||||
return outcomeTable.rows.map((row) => ({
|
||||
measure: row[0],
|
||||
treatment: row[1],
|
||||
control: row[2],
|
||||
pValue: row[3],
|
||||
}));
|
||||
}
|
||||
```
|
||||
|
||||
### 场景 4：在 API 路由中使用
|
||||
|
||||
```typescript
|
||||
import { getTableExtractionManager } from '../../../common/document/tableExtraction/index.js';
|
||||
|
||||
async function handleTableExtraction(request: FastifyRequest, reply: FastifyReply) {
|
||||
const data = await request.file();
|
||||
if (!data) return reply.status(400).send({ error: 'No file uploaded' });
|
||||
|
||||
const buffer = await data.toBuffer();
|
||||
const manager = getTableExtractionManager();
|
||||
const result = await manager.extractTables(buffer, data.filename);
|
||||
|
||||
return reply.send({
|
||||
success: true,
|
||||
engine: result.engine,
|
||||
duration: result.duration,
|
||||
tables: result.tables.map((t) => ({
|
||||
title: t.title,
|
||||
headers: t.headers,
|
||||
rowCount: t.rows.length,
|
||||
rows: t.rows,
|
||||
mergedCells: t.mergedCells,
|
||||
})),
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 环境配置
|
||||
|
||||
### 必需环境变量
|
||||
|
||||
```bash
|
||||
# backend/.env
|
||||
|
||||
# MinerU Cloud API（必需）
|
||||
MINERU_API_TOKEN=your_mineru_api_token
|
||||
MINERU_API_BASE=https://mineru.net/api/v4
|
||||
MINERU_MODEL_VERSION=vlm
|
||||
```
|
||||
|
||||
### 获取 MinerU Token
|
||||
|
||||
1. 注册 [OpenDataLab](https://sso.openxlab.org.cn/login)
|
||||
2. 登录 [MinerU 控制台](https://mineru.net/)
|
||||
3. 个人中心 → API Token → 复制
|
||||
4. 写入 `backend/.env` 的 `MINERU_API_TOKEN`
|
||||
|
||||
### 免费额度
|
||||
|
||||
| 项目 | 限制 |
|
||||
|------|------|
|
||||
| 日解析页数 | 2000 页 |
|
||||
| 单文件大小 | ≤ 200 MB |
|
||||
| 单文件页数 | ≤ 600 页 |
|
||||
|
||||
小型综述 20 篇 (200 页) → 1 天免费完成。大型综述 500 篇 (5000 页) → 分 3 天免费完成。
|
||||
|
||||
---
|
||||
|
||||
## 运行测试
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
|
||||
# 测试指定 PDF（推荐）
|
||||
npx tsx src/tests/test-table-extraction.ts "../docs/03-业务模块/ASL-AI智能文献/05-测试文档/PDF/Herrschaft 2012.pdf"
|
||||
|
||||
# 自动选取测试目录中的第一个 PDF
|
||||
npx tsx src/tests/test-table-extraction.ts
|
||||
```
|
||||
|
||||
### 期望输出
|
||||
|
||||
```
|
||||
========================================
|
||||
PDF 表格提取引擎 — 集成测试
|
||||
========================================
|
||||
|
||||
文件: Herrschaft 2012.pdf
|
||||
引擎: mineru
|
||||
耗时: 6.5s
|
||||
检出表格: 3 个
|
||||
|
||||
────────────────────────────────────────
|
||||
表格 1: Table 1 Baseline characteristics...
|
||||
列数: 5
|
||||
行数: 18
|
||||
合并单元格: 2
|
||||
表头: ... | EGb 761®(N = 200) | Placebo(N = 202) | p-value
|
||||
|
||||
表格 2: Table 2
|
||||
列数: 4
|
||||
行数: 10
|
||||
|
||||
表格 3: Table 3 Adverse events...
|
||||
列数: 6
|
||||
行数: 7
|
||||
合并单元格: 4
|
||||
|
||||
测试通过
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 文件清单
|
||||
|
||||
```
|
||||
backend/src/common/document/tableExtraction/
|
||||
├── types.ts # 统一接口 + 类型定义
|
||||
├── htmlTableParser.ts # HTML <table> → ExtractedTable 解析器
|
||||
├── TableExtractionManager.ts # 引擎管理器（使用者入口）
|
||||
├── engines/
|
||||
│ └── MinerUEngine.ts # MinerU Cloud API 适配器
|
||||
└── index.ts # 统一导出 + 全局单例
|
||||
|
||||
backend/src/tests/
|
||||
└── test-table-extraction.ts # 集成测试脚本
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 扩展新引擎
|
||||
|
||||
添加新引擎只需 3 步：
|
||||
|
||||
### Step 1: 实现接口
|
||||
|
||||
```typescript
|
||||
// engines/Qwen3VLEngine.ts
|
||||
import type { ITableExtractionEngine, ExtractionOptions, ExtractionResult } from '../types.js';
|
||||
|
||||
export class Qwen3VLEngine implements ITableExtractionEngine {
|
||||
readonly name = 'qwen3vl';
|
||||
readonly displayName = 'Qwen3-VL 多模态';
|
||||
|
||||
async extractTables(
|
||||
pdf: Buffer,
|
||||
filename: string,
|
||||
options?: ExtractionOptions,
|
||||
): Promise<ExtractionResult> {
|
||||
// 实现提取逻辑 ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 2: 注册引擎
|
||||
|
||||
```typescript
|
||||
// index.ts 中添加
|
||||
import { Qwen3VLEngine } from './engines/Qwen3VLEngine.js';
|
||||
|
||||
// 在 getTableExtractionManager() 中
|
||||
if (process.env.QWEN3VL_API_KEY) {
|
||||
_instance.register(new Qwen3VLEngine());
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3: 使用
|
||||
|
||||
```typescript
|
||||
const manager = getTableExtractionManager();
|
||||
|
||||
// 显式指定引擎
|
||||
const result = await manager.extractTables(pdf, 'paper.pdf', {
|
||||
engine: 'qwen3vl',
|
||||
});
|
||||
|
||||
// 或切换默认引擎
|
||||
manager.setDefault('qwen3vl');
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Q: 提取耗时多久？
|
||||
|
||||
MinerU Cloud API 通常 5-20 秒（取决于 PDF 页数和云端负载）。首次请求可能较慢（云端冷启动），后续请求更快。
|
||||
|
||||
### Q: 没有检出表格？
|
||||
|
||||
1. 确认 PDF 中确实包含表格（扫描件图片中的表格也能识别）
|
||||
2. 检查 `fullMarkdown` 输出中是否有 `<table>` 标签
|
||||
3. MinerU 对极端复杂的嵌套表格可能识别不完整
|
||||
|
||||
### Q: 合并单元格数据如何处理？
|
||||
|
||||
`ExtractedTable.mergedCells` 记录了所有合并单元格的位置和跨度。在 `rows` 中，被合并的单元格只在起始位置有值，其余位置为空字符串。
|
||||
|
||||
### Q: 和文档处理引擎 (pymupdf4llm) 的关系？
|
||||
|
||||
两者分别负责不同场景：
|
||||
|
||||
| 引擎 | 路径 | 场景 |
|
||||
|------|------|------|
|
||||
| 文档处理引擎 | `ExtractionClient.ts` | 全文文本提取（标题摘要初筛、PKB 入库） |
|
||||
| **PDF 表格提取引擎** | `tableExtraction/` | 结构化表格提取（全文复筛、Meta 分析） |
|
||||
|
||||
---
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [PDF 表格提取引擎设计方案](./03-PDF表格提取引擎设计方案.md) — 架构设计 + 候选引擎 + 对比测试
|
||||
- [文档处理引擎使用指南](./02-文档处理引擎使用指南.md) — 全文文本提取 (pymupdf4llm)
|
||||
- [文档处理引擎 README](./README.md) — 引擎总览
|
||||
|
||||
---
|
||||
|
||||
**维护人**: 技术架构师
|
||||
**核心依赖**: `adm-zip` (ZIP 解析), `axios` (HTTP 请求)
|
||||
@@ -3,8 +3,8 @@
|
||||
> **能力定位：** 通用能力层
|
||||
> **复用率：** 86% (6个模块依赖)
|
||||
> **优先级：** P0
|
||||
> **状态：** 🔄 升级中（pymupdf4llm + 统一架构）
|
||||
> **最后更新：** 2026-01-20
|
||||
> **状态：** ✅ V2 — pymupdf4llm (全文) + MinerU (表格) 双引擎架构
|
||||
> **最后更新：** 2026-02-23
|
||||
|
||||
---
|
||||
|
||||
@@ -16,14 +16,46 @@
|
||||
|
||||
1. **多格式支持** - 覆盖医学科研领域 20+ 种文档格式
|
||||
2. **LLM 友好输出** - 统一输出结构化 Markdown
|
||||
3. **表格保真** - 完整保留文献中的表格信息（临床试验核心数据）
|
||||
3. **表格精准提取** - MinerU VLM 引擎支持合并单元格、数值 100% 保真（V2 新增）
|
||||
4. **可扩展架构** - 方便添加新格式支持
|
||||
|
||||
---
|
||||
|
||||
## 🔄 重大更新（2026-01-20）
|
||||
## 🔄 重大更新（2026-02-23）
|
||||
|
||||
### PDF 处理方案升级
|
||||
### V2: PDF 表格提取引擎 — 统一抽象 + 多引擎可插拔
|
||||
|
||||
新建 **PDF 表格提取引擎**，核心理念：**使用者只需提交 PDF、获取结构化表格，无需关心底层引擎实现**。
|
||||
|
||||
已完成 8 篇真实医学文献的首轮对比测试（pymupdf4llm / MinerU / DeepSeek），MinerU Cloud API 作为首个接入引擎：
|
||||
|
||||
| 对比项 | pymupdf4llm | MinerU API (VLM) | DeepSeek LLM |
|
||||
|--------|-------------|------------------|--------------|
|
||||
| 结构化表格检出 | 3 个 (12.5%) | **28 个 (100%)** | 24 个 (85%) |
|
||||
| 合并单元格 | ❌ | **✅ rowspan/colspan** | ⚠️ 文字描述 |
|
||||
| 数值精度 | ✅ | **✅ 100% 保真** | ⚠️ 可能翻译 |
|
||||
| 综合评分 | 2.7/5 | **4.6/5** | 3.4/5 |
|
||||
|
||||
**V2 分层架构（全文 + 表格 分离）：**
|
||||
|
||||
| 引擎 | 定位 | 适用场景 |
|
||||
|------|------|----------|
|
||||
| **pymupdf4llm** | 全文文本提取 | 标题摘要初筛、PKB 入库、全文检索 |
|
||||
| **PDF 表格提取引擎** | 结构化表格 | 全文复筛、系统综述、Meta 分析 |
|
||||
|
||||
**表格提取引擎候选 (可插拔)：**
|
||||
|
||||
| 引擎 | 状态 | 特点 |
|
||||
|------|------|------|
|
||||
| MinerU Cloud API (VLM) | ✅ 已接入 (默认) | 表格结构最完整 |
|
||||
| Qwen3-VL | 📋 待评测 | 多模态理解最强 |
|
||||
| PaddleOCR-VL 1.5 | 📋 待评测 | 医学场景案例多，免费额度最多 |
|
||||
| Qwen-OCR + Qwen-Long | 📋 待评测 | 成本最低 |
|
||||
| Docling (IBM) | 📋 待评测 | MIT 开源，离线部署 |
|
||||
|
||||
详见：[PDF 表格提取引擎设计方案](./03-PDF表格提取引擎设计方案.md)
|
||||
|
||||
### V1 (2026-01-20): PDF 文本提取升级
|
||||
|
||||
| 变更 | 旧方案 | 新方案 |
|
||||
|------|--------|--------|
|
||||
@@ -32,11 +64,6 @@
|
||||
| 多栏布局 | 手动处理 | ✅ 自动重排 |
|
||||
| 依赖复杂度 | 高（GPU） | ✅ 低 |
|
||||
|
||||
**关键决策：**
|
||||
- `pymupdf4llm` 是 PyMuPDF 的上层封装，**自动包含 pymupdf 依赖**
|
||||
- 移除 Nougat 依赖，简化部署
|
||||
- 扫描版 PDF 单独使用 OCR 方案处理
|
||||
|
||||
---
|
||||
|
||||
## 📊 支持格式
|
||||
@@ -75,21 +102,31 @@
|
||||
|
||||
## 🏗️ 技术架构
|
||||
|
||||
### 统一处理器架构
|
||||
### V2 双引擎架构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ DocumentProcessor │
|
||||
│ (统一入口：自动检测文件类型，调用对应处理器) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ 文档处理引擎 (V2) │
|
||||
├──────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─────────────────────┐ ┌─────────────────────────────┐ │
|
||||
│ │ 全文文本提取 (V1) │ │ PDF 表格提取引擎 (V2 新增) │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ pymupdf4llm │ │ 统一抽象层 (可插拔引擎) │ │
|
||||
│ │ ───────────── │ │ ───────────────────── │ │
|
||||
│ │ • PDF → Markdown │ │ 当前: MinerU VLM │ │
|
||||
│ │ • 速度快、免费 │ │ 待测: Qwen3-VL / Paddle │ │
|
||||
│ │ • 不依赖网络 │ │ 待测: Qwen-OCR / Docling │ │
|
||||
│ │ │ │ • 统一 ExtractedTable 输出 │ │
|
||||
│ └─────────────────────┘ └─────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
|
||||
│ │ PDF │ │ Word │ │ PPT │ │ Excel │ │
|
||||
│ │ Processor │ │ Processor │ │ Processor │ │ Processor │ │
|
||||
│ │pymupdf4llm│ │ mammoth │ │python-pptx│ │ pandas │ │
|
||||
│ │ Word │ │ PPT │ │ Excel │ │ CSV │ │
|
||||
│ │ mammoth │ │python-pptx│ │ pandas │ │ pandas │ │
|
||||
│ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ 输出: 统一 Markdown 格式 │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
├──────────────────────────────────────────────────────────────┤
|
||||
│ 输出: Markdown 文本 / HTML 结构化表格 │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 目录结构
|
||||
@@ -186,15 +223,27 @@ rispy>=0.7.0
|
||||
|
||||
## 🔗 相关文档
|
||||
|
||||
- [详细设计方案](./01-文档处理引擎设计方案.md) - 完整实现细节
|
||||
- [PDF 表格提取引擎使用指南](./04-PDF表格提取引擎使用指南.md) - **5 秒上手 + 实战场景** ⭐ 推荐
|
||||
- [PDF 表格提取引擎设计方案](./03-PDF表格提取引擎设计方案.md) - 统一抽象 + 多引擎可插拔架构
|
||||
- [详细设计方案](./01-文档处理引擎设计方案.md) - V1 pymupdf4llm 架构
|
||||
- [使用指南](./02-文档处理引擎使用指南.md) - 全文文本提取 API 调用指南
|
||||
- [通用能力层总览](../README.md)
|
||||
- [PKB 知识库](../../03-业务模块/PKB-个人知识库/00-模块当前状态与开发指南.md)
|
||||
- [Dify 替换计划](../../03-业务模块/PKB-个人知识库/04-开发计划/01-Dify替换为pgvector开发计划.md)
|
||||
|
||||
---
|
||||
|
||||
## 📅 更新日志
|
||||
|
||||
### 2026-02-23 PDF 表格提取引擎升级 (V2)
|
||||
|
||||
- 🆕 **新建 PDF 表格提取引擎 — 统一抽象层，底层引擎可插拔**
|
||||
- 🆕 MinerU Cloud API (VLM) 作为首个接入引擎 (默认)
|
||||
- 🆕 完成 pymupdf4llm / MinerU / DeepSeek 三方对比测试 (8 篇医学文献)
|
||||
- 📊 MinerU 综合评分 4.6/5，作为默认引擎
|
||||
- 📋 后续评测计划：Qwen3-VL / PaddleOCR-VL / Qwen-OCR+Qwen-Long / Docling
|
||||
- 📝 创建 [PDF 表格提取引擎设计方案](./03-PDF表格提取引擎设计方案.md)
|
||||
- 🏗️ 确立分层架构：pymupdf4llm (全文文本) + PDF 表格提取引擎 (结构化表格)
|
||||
|
||||
### 2026-01-20 架构升级
|
||||
|
||||
- 🆕 PDF 处理升级为 `pymupdf4llm`
|
||||
|
||||
Reference in New Issue
Block a user