rag/docs/云端MinerU输出分析与优化方案.md

云端 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 类型时：

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：

{
  "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 + 嵌入图片