309 lines
6.3 KiB
Markdown
309 lines
6.3 KiB
Markdown
# Document Parser 用户使用手册
|
||
|
||
## 快速开始
|
||
|
||
### 系统依赖安装
|
||
|
||
|
||
```shell
|
||
|
||
sudo apt update
|
||
sudo apt install --reinstall build-essential libc6-dev linux-libc-dev
|
||
|
||
|
||
sudo apt install gcc-multilib g++-multilib
|
||
|
||
|
||
```
|
||
|
||
|
||
### 1. 环境初始化
|
||
```bash
|
||
# 在当前目录初始化uv虚拟环境和依赖
|
||
document-parser uv-init
|
||
```
|
||
|
||
这个命令会：
|
||
- 检查并安装uv工具
|
||
- 创建虚拟环境 `./venv/`
|
||
- 安装MinerU和MarkItDown依赖
|
||
- 自动检测CUDA环境并安装相应版本
|
||
|
||
### 2. 启动服务
|
||
```bash
|
||
# 启动文档解析服务
|
||
document-parser server
|
||
```
|
||
|
||
服务启动后会自动：
|
||
- 激活虚拟环境
|
||
- 检查环境状态
|
||
- 启动HTTP服务器（默认端口8087）
|
||
|
||
## CUDA环境配置（GPU加速）
|
||
|
||
### 1. 检查CUDA环境
|
||
```bash
|
||
# 检查NVIDIA驱动和CUDA
|
||
nvidia-smi
|
||
|
||
# 检查CUDA版本
|
||
nvcc --version
|
||
```
|
||
|
||
### 2. 手动安装sglang（GPU加速必需）
|
||
|
||
**重要**：不要直接安装sglang，应该使用MinerU官方推荐的安装方式，确保版本兼容性。
|
||
|
||
```bash
|
||
# 激活虚拟环境
|
||
source ./venv/bin/activate
|
||
|
||
# 使用MinerU官方命令安装（推荐）
|
||
uv pip install -U "mineru[all]" -i https://mirrors.aliyun.com/pypi/simple
|
||
|
||
# 或者使用pip安装
|
||
pip install -U "mineru[all]" -i https://mirrors.aliyun.com/pypi/simple
|
||
```
|
||
|
||
**注意**：`mineru[all]` 会自动安装兼容的sglang版本，避免版本冲突问题。
|
||
|
||
### 3. 验证sglang安装
|
||
```bash
|
||
# 检查sglang版本
|
||
python -c "import sglang; print('SGLang版本:', sglang.__version__)"
|
||
|
||
# 检查sglang server是否可用
|
||
python -m sglang.srt.server --help
|
||
```
|
||
|
||
### 4. 验证CUDA编译器头文件查找
|
||
```bash
|
||
# 测试CUDA编译器是否能找到math.h头文件
|
||
nvcc -v -x cu - -o /dev/null <<< '#include <math.h>'
|
||
|
||
# 如果成功，应该显示编译信息
|
||
# 如果失败，会显示 "fatal error: math.h: 没有那个文件或目录"
|
||
```
|
||
|
||
## 配置MinerU使用sglang加速
|
||
|
||
### 1. 修改配置文件
|
||
编辑 `config.yml` 文件：
|
||
|
||
```yaml
|
||
# MinerU配置
|
||
mineru:
|
||
backend: "vlm-sglang-engine" # 启用sglang后端以支持GPU加速
|
||
python_path: "./venv/bin/python"
|
||
max_concurrent: 3
|
||
queue_size: 100
|
||
batch_size: 1
|
||
quality_level: "Balanced"
|
||
```
|
||
|
||
### 2. 或者通过命令行指定
|
||
```bash
|
||
# 启动服务时指定后端
|
||
document-parser server --mineru-backend vlm-sglang-engine
|
||
```
|
||
|
||
## 验证MinerU是否使用sglang加速
|
||
|
||
### 1. 检查服务日志
|
||
启动服务后，查看日志中是否有以下信息：
|
||
```
|
||
INFO 虚拟环境已自动激活
|
||
INFO MinerU配置: backend=vlm-sglang-engine
|
||
```
|
||
|
||
### 2. 测试PDF解析
|
||
上传一个PDF文件进行解析，查看日志输出：
|
||
```
|
||
DEBUG MinerU完整命令: .../mineru -p input.pdf -o output -b vlm-sglang-engine
|
||
```
|
||
|
||
### 3. 检查GPU使用情况
|
||
在另一个终端中运行：
|
||
```bash
|
||
# 实时监控GPU使用
|
||
watch -n 1 nvidia-smi
|
||
|
||
# 或者使用htop查看进程
|
||
htop
|
||
```
|
||
|
||
如果看到MinerU进程占用GPU资源，说明sglang加速正常工作。
|
||
|
||
## 故障排除
|
||
|
||
### 1. sglang安装失败
|
||
```bash
|
||
# 检查Python版本（需要3.8+）
|
||
python --version
|
||
|
||
# 检查pip版本
|
||
pip --version
|
||
|
||
# 尝试升级pip
|
||
pip install --upgrade pip
|
||
|
||
# 重新安装sglang
|
||
pip uninstall sglang -y
|
||
pip install "sglang[all]"
|
||
```
|
||
|
||
### 2. 版本兼容性问题
|
||
如果遇到transformers版本兼容问题：
|
||
```bash
|
||
# 安装兼容的transformers版本
|
||
pip install "transformers>=4.36.0,<4.40.0"
|
||
|
||
# 重新安装MinerU（会自动安装兼容的sglang版本）
|
||
pip install -U "mineru[all]" -i https://mirrors.aliyun.com/pypi/simple
|
||
```
|
||
|
||
### 3. CUDA编译器头文件问题
|
||
如果遇到 `fatal error: math.h: 没有那个文件或目录` 错误：
|
||
|
||
```bash
|
||
# 验证CUDA编译器是否能找到math.h头文件
|
||
/usr/bin/nvcc -v -x cu - -o /dev/null <<< '#include <math.h>'
|
||
|
||
# 如果失败，安装缺失的开发包
|
||
sudo apt install -y libc6-dev libstdc++-13-dev
|
||
|
||
# 设置正确的CUDA环境变量
|
||
export CUDA_HOME=/usr
|
||
export PATH=/usr/lib/cuda/bin:$PATH
|
||
export LD_LIBRARY_PATH=/usr/lib/cuda/lib64:$LD_LIBRARY_PATH
|
||
|
||
# 清理FlashInfer缓存
|
||
rm -rf ~/.cache/flashinfer
|
||
```
|
||
|
||
**重要提示**：如果之前直接安装了sglang，建议先卸载再重新安装MinerU：
|
||
```bash
|
||
# 卸载可能不兼容的sglang版本
|
||
pip uninstall sglang -y
|
||
|
||
# 重新安装MinerU（包含兼容的sglang）
|
||
pip install -U "mineru[all]" -i https://mirrors.aliyun.com/pypi/simple
|
||
```
|
||
|
||
### 3. 虚拟环境问题
|
||
```bash
|
||
# 检查虚拟环境状态
|
||
document-parser check
|
||
|
||
# 重新初始化环境
|
||
rm -rf ./venv
|
||
document-parser uv-init
|
||
```
|
||
|
||
### 4. 权限问题
|
||
```bash
|
||
# 检查目录权限
|
||
ls -la
|
||
|
||
# 修改权限（如果需要）
|
||
chmod 755 .
|
||
chown $USER .
|
||
```
|
||
|
||
## 常用命令
|
||
|
||
### 环境诊断
|
||
```bash
|
||
# 验证CUDA编译器头文件查找
|
||
/usr/bin/nvcc -v -x cu - -o /dev/null <<< '#include <math.h>'
|
||
|
||
# 检查系统头文件是否存在
|
||
ls -la /usr/include/math.h
|
||
ls -la /usr/include/c++/13/cmath
|
||
|
||
# 检查CUDA安装路径
|
||
find /usr -name "cuda_runtime.h" 2>/dev/null
|
||
which nvcc
|
||
```
|
||
|
||
### 环境管理
|
||
```bash
|
||
# 检查环境状态
|
||
document-parser check
|
||
|
||
# 显示故障排除指南
|
||
document-parser troubleshoot
|
||
|
||
# 重新初始化环境
|
||
document-parser uv-init
|
||
```
|
||
|
||
### 服务管理
|
||
```bash
|
||
# 启动服务（默认端口8087）
|
||
document-parser server
|
||
|
||
# 指定端口启动
|
||
document-parser server --port 8088
|
||
|
||
# 指定配置文件
|
||
document-parser server --config custom_config.yml
|
||
```
|
||
|
||
### 文件解析
|
||
```bash
|
||
# 解析单个文件
|
||
document-parser parse --input input.pdf --output output.md --parser mineru
|
||
```
|
||
|
||
## 性能优化建议
|
||
|
||
### 1. GPU加速
|
||
- 确保安装了 `sglang[all]`
|
||
- 使用 `vlm-sglang-engine` 后端
|
||
- 监控GPU内存使用情况
|
||
|
||
### 2. 并发控制
|
||
根据服务器性能调整配置：
|
||
```yaml
|
||
mineru:
|
||
max_concurrent: 2 # 根据GPU内存调整
|
||
batch_size: 1 # 小批次处理
|
||
```
|
||
|
||
### 3. 超时设置
|
||
```yaml
|
||
document_parser:
|
||
processing_timeout: 3600 # 60分钟超时
|
||
```
|
||
|
||
## 日志查看
|
||
|
||
### 1. 实时日志
|
||
```bash
|
||
# 查看当天日志
|
||
tail -f logs/log.$(date +%Y-%m-%d)
|
||
|
||
# 查看最新日志
|
||
tail -f logs/log.*
|
||
```
|
||
|
||
### 2. 日志级别
|
||
在 `config.yml` 中调整日志级别：
|
||
```yaml
|
||
log:
|
||
level: "debug" # 可选: debug, info, warn, error
|
||
```
|
||
|
||
## 联系支持
|
||
|
||
如果遇到问题：
|
||
1. 运行 `document-parser troubleshoot` 查看详细指南
|
||
2. 检查日志文件获取错误信息
|
||
3. 确保环境配置正确（Python版本、CUDA版本等）
|
||
|
||
---
|
||
|
||
**注意**：本手册基于当前版本编写，如有更新请参考最新文档。
|