212 lines
5.3 KiB
Markdown
212 lines
5.3 KiB
Markdown
# MinerU 集成复盘报告
|
||
|
||
## 一、已完成的集成工作
|
||
|
||
### 1. 核心功能集成 ✅
|
||
- [x] MinerU 代码完整复制到 MaxKB 项目 (`/apps/common/handle/impl/mineru/`)
|
||
- [x] 创建 MaxKB 适配器 (`maxkb_adapter.py`)
|
||
- [x] 实现分段处理器 (`mineru_split_handle.py`)
|
||
- [x] 注册到文档处理流程（最高优先级）
|
||
|
||
### 2. 模型调用改造 ✅
|
||
- [x] 创建 MaxKB 模型客户端 (`maxkb_model_client.py`)
|
||
- [x] 替换 litellm 调用为 MaxKB 模型调用
|
||
- [x] 支持 LLM 和 Vision Model 两种模型
|
||
- [x] 实现模型响应对象的兼容层
|
||
|
||
### 3. 前端集成 ✅
|
||
- [x] 添加 MinerU 文档类型选项
|
||
- [x] 实现模型选择器（LLM + Vision Model）
|
||
- [x] 集成模型列表动态加载
|
||
- [x] 使用 Pinia store 管理状态
|
||
|
||
### 4. 后端支持 ✅
|
||
- [x] 文档序列化器支持额外参数传递
|
||
- [x] 支持 MinerU 特定的模型参数
|
||
- [x] 处理器支持 kwargs 参数
|
||
|
||
### 5. 依赖处理 ✅
|
||
- [x] 移除 gptbase.settings 依赖
|
||
- [x] 移除 litellm 直接调用
|
||
- [x] 实现本地 ImageOptimizer
|
||
- [x] 实现本地 utils 功能
|
||
|
||
## 二、需要注意的问题和待优化项
|
||
|
||
### 1. 缺失的功能模块 ⚠️
|
||
|
||
#### a. 图片上传功能
|
||
```python
|
||
# 当前在 maxkb_adapter.py 中是 TODO
|
||
# TODO: 实现图片上传逻辑
|
||
# uploaded_url = await upload_image(img_path, upload_options)
|
||
```
|
||
**需要实现**：集成 MaxKB 的文件存储系统用于图片上传
|
||
|
||
#### b. 追踪系统
|
||
```python
|
||
# parallel_processor.py 中注释了
|
||
# from loader.trace import set_trace_id
|
||
```
|
||
**建议**：使用 MaxKB 的日志系统替代
|
||
|
||
#### c. 缓存系统
|
||
- MinerU 原本有缓存机制，需要确认是否需要在 MaxKB 中实现
|
||
- 当前使用临时目录，可能需要更持久的缓存策略
|
||
|
||
### 2. API 调用问题 ⚠️
|
||
|
||
#### a. MinerU API 客户端
|
||
```python
|
||
# api_client.py 中的 MinerU API 调用
|
||
# 需要确认 MinerU API 服务是否可用
|
||
```
|
||
**需要确认**：
|
||
- MinerU API 服务地址和认证
|
||
- 是否需要自建 MinerU 服务
|
||
- API 调用的超时和重试策略
|
||
|
||
#### b. 并行处理
|
||
```python
|
||
# parallel_processor.py 和 parallel_processor_pool.py
|
||
# 使用了队列和线程池进行并行处理
|
||
```
|
||
**需要测试**：在 MaxKB 环境中的并发性能
|
||
|
||
### 3. 配置项检查 ⚠️
|
||
|
||
需要在 MaxKB 中添加的环境变量：
|
||
```bash
|
||
# MinerU API 配置
|
||
MINERU_API_KEY=xxx
|
||
MINERU_API_URL=https://mineru.net
|
||
MINERU_API_TYPE=cloud
|
||
|
||
# 处理配置
|
||
MAX_FILE_SIZE=52428800 # 50MB
|
||
LIBREOFFICE_PATH=libreoffice
|
||
CONVERSION_TIMEOUT=300
|
||
|
||
# 性能配置
|
||
MAX_CONCURRENT_UPLOADS=5
|
||
MAX_CONCURRENT_API_CALLS=3
|
||
MINERU_BATCH_PROCESSING=true
|
||
MINERU_BATCH_SIZE=20
|
||
```
|
||
|
||
### 4. 文件格式支持 ⚠️
|
||
|
||
当前支持的格式：
|
||
- PDF ✅
|
||
- PPT/PPTX ✅
|
||
|
||
需要确认的转换工具：
|
||
- LibreOffice（PPT 转 PDF）- 需要系统安装
|
||
- PyMuPDF (fitz) - 需要 pip 安装
|
||
|
||
### 5. 错误处理增强 🔧
|
||
|
||
建议添加的错误处理：
|
||
1. 模型调用失败的降级策略
|
||
2. MinerU API 不可用时的处理
|
||
3. 文件转换失败的处理
|
||
4. 大文件处理的内存管理
|
||
|
||
## 三、测试清单
|
||
|
||
### 1. 单元测试
|
||
- [ ] MaxKB 模型客户端测试
|
||
- [ ] MinerU 适配器测试
|
||
- [ ] 文件格式检测测试
|
||
- [ ] 图片处理测试
|
||
|
||
### 2. 集成测试
|
||
- [ ] PDF 文档解析测试
|
||
- [ ] PPT 文档解析测试
|
||
- [ ] 大文件处理测试（>10MB）
|
||
- [ ] 并发处理测试
|
||
- [ ] 模型调用测试
|
||
|
||
### 3. 端到端测试
|
||
- [ ] 完整的文档上传流程
|
||
- [ ] 模型选择和切换
|
||
- [ ] 解析结果的质量验证
|
||
- [ ] 向量化存储验证
|
||
|
||
## 四、部署准备
|
||
|
||
### 1. 系统依赖
|
||
```bash
|
||
# 需要安装的系统包
|
||
apt-get install -y libreoffice
|
||
apt-get install -y python3-pip
|
||
|
||
# Python 依赖
|
||
pip install pymupdf
|
||
pip install pillow
|
||
pip install beautifulsoup4
|
||
pip install tiktoken
|
||
```
|
||
|
||
### 2. 性能优化建议
|
||
1. 为 MinerU 处理设置独立的队列
|
||
2. 实现文档处理的异步化
|
||
3. 添加处理进度的实时反馈
|
||
4. 实现智能的批处理策略
|
||
|
||
### 3. 监控指标
|
||
- 文档处理时间
|
||
- 模型调用次数和耗时
|
||
- 内存使用情况
|
||
- 错误率统计
|
||
|
||
## 五、下一步行动计划
|
||
|
||
### 优先级 1 - 必须完成
|
||
1. **实现图片上传功能**
|
||
- 集成 MaxKB 文件存储
|
||
- 实现图片 URL 管理
|
||
|
||
2. **完善 MinerU API 配置**
|
||
- 确认 API 服务可用性
|
||
- 配置认证和超时
|
||
|
||
3. **添加基础错误处理**
|
||
- 模型调用失败处理
|
||
- 文件处理异常捕获
|
||
|
||
### 优先级 2 - 建议完成
|
||
1. **优化缓存机制**
|
||
- 实现持久化缓存
|
||
- 添加缓存清理策略
|
||
|
||
2. **增强日志记录**
|
||
- 添加详细的处理日志
|
||
- 实现处理追踪
|
||
|
||
3. **性能优化**
|
||
- 优化大文件处理
|
||
- 改进并发策略
|
||
|
||
### 优先级 3 - 可选增强
|
||
1. **添加更多文件格式支持**
|
||
2. **实现处理结果预览**
|
||
3. **添加处理统计和报告**
|
||
|
||
## 六、风险和注意事项
|
||
|
||
1. **许可证合规性**：确保 MinerU 的使用符合许可要求
|
||
2. **数据安全**：确保文档处理过程中的数据安全
|
||
3. **资源消耗**：MinerU 处理可能消耗大量 CPU/内存
|
||
4. **API 限制**：注意第三方 API 的调用限制
|
||
5. **模型成本**：Vision Model 调用可能产生较高成本
|
||
|
||
## 七、总结
|
||
|
||
MinerU 集成的核心功能已经完成，可以进行基础的文档解析。主要需要关注：
|
||
1. 完善图片上传功能
|
||
2. 确认 MinerU API 服务配置
|
||
3. 进行完整的测试
|
||
4. 优化性能和错误处理
|
||
|
||
建议先在测试环境中验证完整流程，确保稳定后再部署到生产环境。 |