qiming/qiming-mcp-proxy/document-parser/USER_MANUAL.md

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

联系支持

如果遇到问题：

1. 运行 document-parser troubleshoot 查看详细指南
2. 检查日志文件获取错误信息
3. 确保环境配置正确（Python版本、CUDA版本等）

---

注意：本手册基于当前版本编写，如有更新请参考最新文档。