fix(parser): PDF/DOCX 切片层级结构修复与 MinerU V2 解析增强
核心修复： - _post_process_chunks: 用 _buffer_has_body 标志替代 buffer.text_level=0， 标题+正文合并后保留 text_level 不置零，修复层级信息丢失 - heading_rules numeric_level2: 正则从 ^\d+\.\d+[\.、\s] 改为 ^\d+\.\d+(?!\.\d)，修复无空格标题如"2.1运行调度"无法匹配 - V2 title handler: heading_rules 优先（模式匹配可靠），VLM 仅兜底 （VLM 常给所有标题 level=1） MinerU V2 解析增强： - 两轮 TOC 过滤：多行目录块检测 + 孤立标题/单字符残留清理 - 封面 logo 过滤、重复标题去重 - chart VLM 描述和 Markdown 数据表提取 - ChromaDB metadata 新增 text_level/bbox/table_type/sub_type 字段 配置调整： - CLUSTER_SECTION_PREFIX_LEVELS 1→2（两级 section 聚类更精确） - MINERU_LOCAL_BACKEND 默认改为 pipeline 文档： - RAG检索流程逻辑.md 更新 MinerUChunk 字段、ChromaDB metadata、 MinerU 解析策略等章节 - 新增 RAG引用跳转-优化计划.md、云端MinerU输出分析与优化方案.md
This commit is contained in:
lacerate551
196
docs/云端MinerU输出分析与优化方案.md
Normal file
196
docs/云端MinerU输出分析与优化方案.md
Normal file
@@ -0,0 +1,196 @@
|
||||
## 云端 MinerU V4 输出分析 & 信息利用优化方案
|
||||
|
||||
### 一、测试环境
|
||||
|
||||
- 云端 API: MinerU V4 (`https://mineru.net/api/v4`)
|
||||
- 模型: `vlm`（高精度视觉语言模型）
|
||||
- DOCX 测试: `1.docx`（472KB）→ 5秒完成
|
||||
- PDF 测试: `三峡公报_1-15页.pdf`（2.7MB）→ 5秒完成
|
||||
|
||||
---
|
||||
|
||||
### 二、云端输出 Schema 对比
|
||||
|
||||
#### 2.1 DOCX（office 后端）
|
||||
|
||||
| 字段 | 状态 | 说明 |
|
||||
|------|------|------|
|
||||
| `type` | paragraph/table/image | 无独立 title 类型 |
|
||||
| `content.paragraph_content[].content` | 文本内容 | |
|
||||
| `content.paragraph_content[].style` | 仅 `bold` | 无 italic/underline/font_size |
|
||||
| `bbox` | **无** | DOCX 不做 OCR |
|
||||
| `anchor` | 偶有 | Word 书签（如 `_Toc423623536`） |
|
||||
| `table_type`/`table_nest_level` | 有 | 表格类型和嵌套层级 |
|
||||
| `image_source.path` | 有 | 图片路径 |
|
||||
|
||||
DOCX 的 V2 输出非常精简，与本地 `pipeline` 模式基本一致。
|
||||
|
||||
#### 2.2 PDF（hybrid 后端，VLM 模型）
|
||||
|
||||
| 字段 | 状态 | 说明 |
|
||||
|------|------|------|
|
||||
| `type` | paragraph/title/list/image/chart/table/page_header/footer/number | **丰富的类型区分** |
|
||||
| `bbox` | **全部有** | 96/96 项都有坐标 |
|
||||
| `title_content` (title 项) | 有 level 字段 | 标题层级 |
|
||||
| `paragraph_content` (paragraph 项) | 文本内容 | 无 style/font_size |
|
||||
| `sub_type` (image) | `natural_image` 等 | 图片子类型 |
|
||||
| `content.content` (chart) | **Markdown 表格** | VLM 从图表中提取的数据表 |
|
||||
| `content.content` (image) | **VLM 视觉描述** | 如 "Aerial view of a large dam..." |
|
||||
| `list_items` (list) | 结构化列表 | 目录条目等 |
|
||||
| `table_footnote` | 表格脚注 | |
|
||||
| `chart_caption`/`chart_footnote` | 图表元数据 | |
|
||||
| `image_source.path` | 图片路径 | 新格式（旧代码用 `img_path`） |
|
||||
|
||||
#### 2.3 V1 vs V2 格式差异
|
||||
|
||||
| 特性 | V1 (`content_list.json`) | V2 (`content_list_v2.json`) |
|
||||
|------|--------------------------|------------------------------|
|
||||
| 结构 | 扁平列表 | 按页嵌套 `[[page0], [page1]...]` |
|
||||
| title 文本 | `text` 字段 | `title_content` 字段 |
|
||||
| title 级别 | `text_level` 字段 | `level` 字段 |
|
||||
| bbox | 有 | 有 |
|
||||
| bold style | Markdown `**text**` | `style: ["bold"]` |
|
||||
| list 类型 | 有 `list_items` | 有 `list_items` |
|
||||
| chart 数据 | 无 markdown 表格 | `content.content` 含 markdown |
|
||||
| VLM 描述 | 无 | `content.content`（image 项） |
|
||||
|
||||
---
|
||||
|
||||
### 三、发现的严重 Bug（全部已修复 2026-06-19）
|
||||
|
||||
#### Bug #1: V2 title 文本全部丢失（严重）✅ 已修复
|
||||
|
||||
当前 `_parse_v2_content_list()` 处理 title 类型时：
|
||||
|
||||
```python
|
||||
elif v2_type == 'title':
|
||||
level = content.get('level', 0)
|
||||
text_parts = []
|
||||
para_content = content.get('paragraph_content', []) # ← 错误!
|
||||
for part in para_content:
|
||||
...
|
||||
```
|
||||
|
||||
但 PDF 的 title 项使用的是 `title_content` 字段，不是 `paragraph_content`：
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "title",
|
||||
"content": {
|
||||
"title_content": [{"type": "text", "content": "三峡工程公报"}],
|
||||
"level": 1
|
||||
},
|
||||
"bbox": [203, 138, 794, 211]
|
||||
}
|
||||
```
|
||||
|
||||
**影响**: 所有 PDF 标题的文本丢失 → section_path 为空 → 章节层级结构完全破坏。
|
||||
|
||||
#### Bug #2: list 类型未处理 ✅ 已修复
|
||||
|
||||
V1/V2 都有 `list` 类型（如目录条目），但当前 `_parse_v2_content_list()` 没有处理分支，直接被静默丢弃。
|
||||
|
||||
#### Bug #3: chart markdown 数据未提取 ✅ 已修复
|
||||
|
||||
V2 的 chart 类型在 `content.content` 中包含 VLM 提取的 Markdown 表格，当前代码只提取 `img_path` 和 `caption`，丢掉了结构化数据。
|
||||
|
||||
#### Bug #4: VLM 图片描述未利用 ✅ 已修复
|
||||
|
||||
V2 的 image 项的 `content.content` 包含 VLM 生成的视觉描述文本（如 "Aerial view of a large hydroelectric dam..."），可用于增强图片检索，当前被丢弃。
|
||||
|
||||
#### Bug #5: image_source 路径格式不兼容 ✅ 已修复
|
||||
|
||||
V2 图片路径从 `img_path` 改为 `image_source.path`，当前转换代码未适配。
|
||||
|
||||
---
|
||||
|
||||
### 四、优化方案
|
||||
|
||||
#### Phase 1: 修复 V2 解析 Bug（P0，已完成 2026-06-19）
|
||||
|
||||
**目标**: 修复 PDF 标题丢失等严重问题。
|
||||
|
||||
| 改动 | 文件 | 状态 |
|
||||
|------|------|------|
|
||||
| title 项读 `title_content` | `mineru_parser.py` `_parse_v2_content_list()` | ✅ 已完成 |
|
||||
| 添加 list 类型处理 | `mineru_parser.py` `_parse_v2_content_list()` | ✅ 已完成 |
|
||||
| image_source 路径兼容 | `mineru_parser.py` `_parse_v2_content_list()` | ✅ 已完成 |
|
||||
| chart markdown 提取 | `mineru_parser.py` `_parse_v2_content_list()` | ✅ 已完成 |
|
||||
| VLM 图片描述提取 | `mineru_parser.py` `_parse_v2_content_list()` | ✅ 已完成 |
|
||||
| MinerUChunk 新增 vlm_description/chart_markdown | `mineru_parser.py` | ✅ 已完成 |
|
||||
| 在线/本地路径同步更新 | `mineru_parser.py` | ✅ 已完成 |
|
||||
|
||||
#### Phase 1.5: 审计修复（已完成 2026-06-19）
|
||||
|
||||
**目标**: 修复审计发现的"提取但未用"字段和 bbox 存储断裂。
|
||||
|
||||
| 改动 | 文件 | 状态 |
|
||||
|------|------|------|
|
||||
| bbox 存入 ChromaDB metadata（JSON 序列化，DOCX None 保护） | `knowledge/manager.py` | ✅ 已完成 |
|
||||
| table_type/table_nest_level → MinerUChunk → ChromaDB | `mineru_parser.py` + `manager.py` | ✅ 已完成 |
|
||||
| sub_type → MinerUChunk → ChromaDB | `mineru_parser.py` + `manager.py` | ✅ 已完成 |
|
||||
| MINERU_LOCAL_BACKEND 改为 pipeline | `config.py` | ✅ 已完成 |
|
||||
|
||||
#### Phase 2: 增强信息利用（P1，待实施）
|
||||
|
||||
**目标**: 在检索管线中利用已存储的新元数据。
|
||||
|
||||
| 改动 | 文件 | 说明 |
|
||||
|------|------|------|
|
||||
| ~~VLM 图片描述存入 chunk~~ | ~~mineru_parser.py~~ | ✅ Phase 1 已完成 |
|
||||
| ~~bbox 存入 ChromaDB~~ | ~~manager.py~~ | ✅ Phase 1.5 已完成 |
|
||||
| ~~sub_type 存入 ChromaDB~~ | ~~manager.py~~ | ✅ Phase 1.5 已完成 |
|
||||
| bbox 空间感知检索 | `core/engine.py` | 同页内容优先聚合 |
|
||||
| VLM 描述增强图片检索 | `core/engine.py` | 图片 chunk 用描述文本做语义匹配 |
|
||||
| table_type 检索路由 | `core/engine.py` | 按表格类型区别处理 |
|
||||
|
||||
#### Phase 3: 检索管线利用（P2，中期）
|
||||
|
||||
**目标**: 在检索阶段利用新增的元数据。
|
||||
|
||||
| 改动 | 文件 | 说明 |
|
||||
|------|------|------|
|
||||
| bbox 空间感知检索 | `core/engine.py` | 同页内容优先聚合 |
|
||||
| VLM 描述增强图片检索 | `core/engine.py` | 图片 chunk 用描述文本做语义匹配 |
|
||||
| chart markdown 表格检索 | `core/engine.py` | 图表数据表按表格类型路由 |
|
||||
| table_footnote 上下文补充 | `core/engine.py` | 表格命中时附带脚注 |
|
||||
|
||||
#### Phase 4: 架构调整
|
||||
|
||||
| 改动 | 说明 |
|
||||
|------|------|
|
||||
| 云端优先 + 本地 pipeline 备选 | `MINERU_PREFER_ONLINE=True`, 失败回退 `pipeline` |
|
||||
| V2 默认启用 | `MINERU_PREFER_V2=True`（保持现状） |
|
||||
| 本地 backend 改为 `pipeline` | `MINERU_LOCAL_BACKEND="pipeline"`（快速备选） |
|
||||
|
||||
---
|
||||
|
||||
### 五、字段利用状态汇总（更新于 2026-06-19）
|
||||
|
||||
| 字段 | 来源 | 状态 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `title_content` | PDF V2 | ✅ 已利用 | Phase 1 修复，标题文本正确提取 |
|
||||
| `list_items` | PDF V1/V2 | ✅ 已利用 | Phase 1 拼接为段落文本 |
|
||||
| `content.content` (chart) | PDF V2 | ✅ 已利用 | Phase 1 存入 chart_markdown → ChromaDB |
|
||||
| `content.content` (image) | PDF V2 | ✅ 已利用 | Phase 1 存入 vlm_description → 嵌入 chunk content |
|
||||
| `bbox` | PDF V1/V2 | ✅ 已利用 | Phase 1.5 存入 ChromaDB（JSON 序列化） |
|
||||
| `table_type` | PDF V2 | ✅ 已利用 | Phase 1.5 存入 ChromaDB metadata |
|
||||
| `table_nest_level` | PDF V2 | ✅ 已利用 | Phase 1.5 存入 ChromaDB metadata |
|
||||
| `sub_type` | PDF V1/V2 | ✅ 已利用 | Phase 1.5 存入 ChromaDB metadata |
|
||||
| `table_footnote` | PDF V1/V2 | ✅ 已利用 | Phase 1 附加到表格 chunk content |
|
||||
| `anchor` | DOCX V2 | 暂不利用 | Word 书签/交叉引用，RAG 场景无需求 |
|
||||
| `chart_caption`/`chart_footnote` | PDF V2 | ✅ 已利用 | chart caption 已提取 |
|
||||
| `font_size`/`font_name` | 均无 | N/A | 云端 V4 不输出这些字段 |
|
||||
| `layout.json` | 两者 | 暂不利用 | 精细布局分析，当前无需求 |
|
||||
|
||||
---
|
||||
|
||||
### 六、DOCX vs PDF 策略差异
|
||||
|
||||
| 策略 | DOCX (office) | PDF (hybrid/VLM) |
|
||||
|------|---------------|-------------------|
|
||||
| 标题识别 | 依赖 heading_rules（正则+bold） | VLM 已识别 title+level，heading_rules 做补充校正 |
|
||||
| 图片检索 | 仅靠 caption | VLM 描述 + caption 双通道 |
|
||||
| 图表处理 | 无 | chart 类型含 markdown 数据表 |
|
||||
| 列表处理 | 无独立 list 类型 | list 类型保留结构化列表 |
|
||||
| 表格增强 | table_type/nest_level | table_type + footnote + 嵌入图片 |
|
||||
Reference in New Issue
Block a user