# MinerU 文档解析集成指南

## 概述

本文档说明了如何在 MaxKB 中使用 MinerU 高质量文档解析功能。MinerU 是一个强大的文档解析工具，特别适合处理包含复杂表格、图片、公式等内容的 PDF 和 PPT 文档。

## 最新更新

- ✅ MinerU 代码已完整集成到 MaxKB 项目中
- ✅ 支持选择大语言模型和视觉模型进行文档解析
- ✅ 前端界面支持模型选择器
- ✅ 后端支持传递模型参数到 MinerU 解析器

## 功能特点

- **高质量解析**：支持复杂文档结构的精确解析
- **多格式支持**：支持 PDF、PPT、PPTX 文件格式
- **智能处理**：自动识别并处理表格、图片、公式等复杂内容
- **分页处理**：支持按页独立处理，提高处理效率
- **上下文保持**：保持文档的上下文关系，提高检索质量

## 使用方法

### 1. 配置模型

MinerU 解析需要配置两种模型：

- **大语言模型 (LLM)**：用于内容理解和增强
- **视觉模型 (Vision Model)**：用于图片识别和处理

在 MaxKB 管理后台的模型管理页面（http://localhost:3000/admin/model）添加所需的模型。

### 2. 上传文档

1. 进入知识库管理页面
2. 点击"上传文档"按钮
3. 在文档类型选择中，选择"MinerU"选项
4. 选择合适的大语言模型和视觉模型
5. 上传 PDF 或 PPT 文档
6. 系统会自动使用选定的模型进行智能解析

### 3. 文档处理流程

当选择 MinerU 解析时，系统会：

1. **文件检测**：自动识别文件格式（PDF/PPT）
2. **智能解析**：使用 MinerU 引擎进行深度解析
3. **内容提取**：提取文本、表格、图片等内容
4. **分段处理**：根据设置的规则进行智能分段
5. **向量化存储**：将处理后的内容进行向量化存储

## 技术实现

### 后端集成

MinerU 解析器已集成到 MaxKB 的文档处理流程中：

- **MinerU 核心代码**：`/apps/common/handle/impl/mineru/`
- **处理器适配器**：`/apps/common/handle/impl/mineru/maxkb_adapter.py`
- **分段处理器**：`/common/handle/impl/text/mineru_split_handle.py`
- **优先级**：MinerU 处理器具有最高优先级，优先处理支持的文档格式
- **模型集成**：支持动态选择和配置 LLM 和 Vision 模型
- **异步处理**：使用异步方式调用 MinerU API，提高处理效率

### 前端支持

前端已完整支持 MinerU 功能：

- **上传组件**：支持选择 MinerU 作为解析方式
- **模型选择器**：可选择大语言模型和视觉模型
- **文件过滤**：自动过滤仅显示支持的文件格式（PDF、PPT、PPTX）
- **进度显示**：实时显示文档处理进度
- **状态管理**：使用 Pinia store 管理模型选择状态

## 支持的文件格式

- **PDF 文档**：`.pdf`
- **PowerPoint 演示文稿**：`.ppt`, `.pptx`

## 注意事项

1. **文件大小限制**：遵循知识库设置的文件大小限制
2. **处理时间**：复杂文档可能需要较长处理时间
3. **资源消耗**：MinerU 解析需要较多计算资源，建议合理安排处理任务

## 故障排查

### 常见问题

1. **MinerU 未初始化**
   - 检查 gptbase-parser 路径是否正确
   - 确认依赖已正确安装

2. **文档解析失败**
   - 检查文档格式是否支持
   - 查看日志获取详细错误信息

3. **处理超时**
   - 考虑分批处理大型文档
   - 调整超时设置

## 日志位置

MinerU 相关日志会记录在 MaxKB 的标准日志中，使用 `mineru-parser` 前缀标识。

## 未来优化

- [ ] 支持更多文档格式
- [ ] 优化图片处理流程
- [ ] 添加解析质量评分
- [ ] 支持自定义解析参数
- [ ] 增加批量处理能力

## 联系支持

如遇到问题，请查看系统日志或联系技术支持团队。