RAG-CUT/docx/mineru-integration.md

MinerU 解析层接入说明

RAG-cut 将 MinerU 作为可选的高质量文档解析后端，用于提升 PDF 的版面分析、OCR、图片/表格提取质量；切割策略仍由 RAG-cut 负责。

启用方式

默认模式：

RAG_CUT_PDF_ENGINE=auto

含义：

• 如果本机可用 mineru 或 magic-pdf 命令，优先调用 MinerU。
• 如果 MinerU 未安装或解析失败，自动回退到现有 PyMuPDF/pdfplumber 管线。

强制使用 MinerU：

RAG_CUT_PDF_ENGINE=mineru

强制使用原 PyMuPDF 管线：

RAG_CUT_PDF_ENGINE=pymupdf

如果命令不在 PATH 中，可指定：

RAG_CUT_MINERU_CMD=/path/to/mineru

大文档推荐配置

mineru CLI 默认会为每次调用临时启动 API 和模型进程。处理页数较多的 Office/PDF 文档时，建议单独启动一个常驻 MinerU API，避免重复加载模型。

先在一个终端启动服务：

python -m mineru.cli.fast_api --host 127.0.0.1 --port 30000

再在启动 RAG-cut 后端的终端中配置并启动：

$env:RAG_CUT_MINERU_API_URL = "http://127.0.0.1:30000"
$env:RAG_CUT_MINERU_TIMEOUT = "540"
python backend/run.py

未配置常驻 API 时，RAG-cut 仍可使用临时服务；若解析超时，会结束 MinerU 的完整 进程树，避免模型子进程残留并拖慢后续请求。

数据流

PDF
  -> MinerU 解析 content_list.json / 图片资产
  -> 转换为 RAG-cut Block
  -> RAG-cut 自动判断 PDF 策略
  -> feature_step_screenshot 或 outline_report 切割
  -> Chunk + metadata + embedding_text

统一 Block 映射

MinerU 内容	RAG-cut Block
title / heading / text_level	heading
text	paragraph
image / figure / chart / diagram / equation…	image（复制 img 资产）
table（含可选截图）	table（markdown + 可选 image_path）
code（有图则按图，否则按正文）	image / paragraph
page_footnote	paragraph（is_footnote）
header / footer / page_number	丢弃

图片若无 MinerU OCR，默认用本地 Tesseract 回填（繁体优先）：

RAG_CUT_MINERU_OCR=1   # 默认开启；设为 0 可关闭以加快大批量切分

保留字段：

• page
• bbox
• image_path
• ocr_text
• caption
• mineru_type
• parser=mineru

设计原则

MinerU 只提升解析质量，不决定 chunk 语义边界。不同文档类型的切割仍由 RAG-cut 策略层处理：

• 操作手册：功能章节 + 操作步骤 + 截图区域
• 年报/研报：章节报告
• 表格：表头 + 行组