first commit

Co-authored-by: Cursor <cursoragent@cursor.com>

docx/mineru-integration.md

@@ -0,0 +1,103 @@
+# 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 策略层处理：
+
+- 操作手册：功能章节 + 操作步骤 + 截图区域
+- 年报/研报：章节报告
+- 表格：表头 + 行组