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