## 云端 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 + 嵌入图片 |