# MinerU 解析层接入说明

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

## 启用方式

默认模式：

```bash
RAG_CUT_PDF_ENGINE=auto
```

含义：

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

强制使用 MinerU：

```bash
RAG_CUT_PDF_ENGINE=mineru
```

强制使用原 PyMuPDF 管线：

```bash
RAG_CUT_PDF_ENGINE=pymupdf
```

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

```bash
RAG_CUT_MINERU_CMD=/path/to/mineru
```

## 大文档推荐配置

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

先在一个终端启动服务：

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

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

```powershell
$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 的完整
进程树，避免模型子进程残留并拖慢后续请求。

## 数据流

```text
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 回填（繁体优先）：

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

保留字段：

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

## 设计原则

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

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