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

Document Parser 故障排除指南

本指南提供了Document Parser服务常见问题的详细解决方案，特别是关于虚拟环境和依赖管理的问题。

📋 目录

1. FlashInfer编译失败
2. 虚拟环境问题
3. 依赖安装问题
4. 网络和下载问题
5. 系统环境问题
6. 常用诊断命令
7. 获取帮助

🚀 FlashInfer编译失败

问题: FlashInfer CUDA内核编译失败

症状:

• MinerU启动时出现 fatal error: math.h: 没有那个文件或目录 错误
• 错误发生在CUDA图捕获阶段
• FlashInfer ninja构建失败

原因: 系统缺少C标准库开发头文件，导致FlashInfer无法编译CUDA内核。这通常发生在Ubuntu 24.04等较新系统上。

诊断步骤:

# 检查系统头文件是否存在
ls -la /usr/include/math.h
ls -la /usr/include/c++/13/cmath

# 检查构建工具版本
gcc --version
ninja --version
nvcc --version

解决方案:

步骤1: 安装缺失的开发包

# 安装C标准库开发包
sudo apt install -y libc6-dev libm-dev

# 安装C++标准库开发包
sudo apt install -y libstdc++-13-dev

# 安装其他可能需要的包
sudo apt install -y build-essential ninja-build cmake

步骤2: 设置CUDA环境变量

# 设置CUDA相关环境变量
export CUDA_HOME=/usr/local/cuda
export PATH=$CUDA_HOME/bin:$PATH
export LD_LIBRARY_PATH=$CUDA_HOME/lib64:$LD_LIBRARY_PATH

# 将这些环境变量添加到 ~/.bashrc 或 ~/.zshrc
echo 'export CUDA_HOME=/usr/local/cuda' >> ~/.bashrc
echo 'export PATH=$CUDA_HOME/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=$CUDA_HOME/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc

步骤3: 清理缓存并重新安装

# 清理FlashInfer缓存
rm -rf ~/.cache/flashinfer

# 重新安装MinerU（确保包含正确的sglang版本）
pip uninstall mineru sglang -y
pip install -U "mineru[all]" -i https://mirrors.aliyun.com/pypi/simple

验证修复:

# 检查头文件是否存在
ls -la /usr/include/math.h
ls -la /usr/include/c++/13/cmath

# 检查CUDA头文件
ls -la /usr/local/cuda/include/cuda_runtime.h

# 重新启动服务测试
document-parser server

如果问题仍然存在:

# 尝试使用系统ninja而不是虚拟环境中的ninja
which ninja
# 如果显示虚拟环境路径，使用系统ninja
sudo apt install -y ninja-build
export PATH=/usr/bin:$PATH

# 或者尝试禁用CUDA图功能（性能会下降）
# 在启动MinerU时添加 --disable-cuda-graph 参数

🏠 虚拟环境问题

问题1: 虚拟环境创建失败

症状:

• document-parser uv-init 失败
• 错误信息包含 "权限拒绝" 或 "Permission denied"
• 无法在当前目录创建 venv 文件夹

诊断步骤:

# 检查当前目录权限
ls -la          # Linux/macOS
dir             # Windows

# 检查磁盘空间
df -h .         # Linux/macOS
dir             # Windows

# 检查是否存在同名文件
ls -la venv     # Linux/macOS
dir venv        # Windows

解决方案:

Linux/macOS:

# 修改目录权限
chmod 755 .

# 修改目录所有者
chown $USER .

# 删除现有的venv文件（如果存在）
rm -rf ./venv

# 重新初始化
document-parser uv-init

Windows:

# 以管理员身份运行命令提示符
# 删除现有的venv目录
rmdir /s .\venv

# 重新初始化
document-parser uv-init

问题2: 虚拟环境激活失败

症状:

• 激活命令执行后没有效果
• 命令提示符没有显示 (venv) 前缀
• Python路径仍指向系统Python

解决方案:

Linux/macOS (Bash/Zsh):

# 标准激活方式
source ./venv/bin/activate

# 检查是否激活成功
which python
python --version

Linux/macOS (Fish Shell):

# Fish shell激活方式
source ./venv/bin/activate.fish

Windows (CMD):

# 激活虚拟环境
.\venv\Scripts\activate

# 检查是否激活成功
where python
python --version

Windows (PowerShell):

# 如果遇到执行策略限制
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# 激活虚拟环境
.\venv\Scripts\Activate.ps1

# 检查是否激活成功
Get-Command python
python --version

问题3: 虚拟环境路径问题

症状:

• 找不到Python可执行文件
• 路径指向错误的位置
• 跨平台兼容性问题

解决方案:

# 检查虚拟环境结构
ls -la ./venv/bin/     # Linux/macOS
dir .\venv\Scripts\    # Windows

# 手动验证Python路径
./venv/bin/python --version      # Linux/macOS
.\venv\Scripts\python --version  # Windows

# 如果路径错误，重新创建虚拟环境
rm -rf ./venv                    # Linux/macOS
rmdir /s .\venv                  # Windows
document-parser uv-init

📦 依赖安装问题

问题1: UV工具未安装或不可用

症状:

• uv: command not found
• UV版本过旧
• UV安装路径问题

解决方案:

官方安装脚本 (推荐):

# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# 重启终端或重新加载shell配置
source ~/.bashrc    # 或 ~/.zshrc

包管理器安装:

# macOS
brew install uv

# 通过pip安装
pip install uv

# Windows (winget)
winget install astral-sh.uv

验证安装:

uv --version
which uv    # Linux/macOS
where uv    # Windows

问题2: MinerU或MarkItDown安装失败

症状:

• 包下载超时
• 编译错误
• 依赖冲突

诊断步骤:

# 检查网络连接
ping pypi.org

# 检查Python版本
python --version

# 检查虚拟环境中的pip
./venv/bin/pip --version      # Linux/macOS
.\venv\Scripts\pip --version  # Windows

解决方案:

使用国内镜像源:

# 清华大学镜像源
uv pip install -i https://pypi.tuna.tsinghua.edu.cn/simple/ mineru[core]
uv pip install -i https://pypi.tuna.tsinghua.edu.cn/simple/ markitdown

# 阿里云镜像源
uv pip install -i https://mirrors.aliyun.com/pypi/simple/ mineru[core]

分步安装:

# 1. 升级pip
uv pip install --upgrade pip

# 2. 安装基础依赖
uv pip install wheel setuptools

# 3. 分别安装包
uv pip install mineru[core]
uv pip install markitdown

增加超时时间:

uv pip install --timeout 300 mineru[core]

清理缓存后重试:

uv cache clean
document-parser uv-init

🌐 网络和下载问题

问题1: 网络连接超时

症状:

• 下载包时超时
• 连接PyPI失败
• DNS解析问题

解决方案:

检查网络连接:

# 测试基本连接
ping pypi.org
ping pypi.tuna.tsinghua.edu.cn

# 测试HTTPS连接
curl -I https://pypi.org/simple/

配置代理 (如果需要):

# 设置HTTP代理
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

# Windows
set HTTP_PROXY=http://proxy.company.com:8080
set HTTPS_PROXY=http://proxy.company.com:8080

使用镜像源:

# 配置uv使用镜像源
uv pip install --index-url https://pypi.tuna.tsinghua.edu.cn/simple/ mineru[core]

问题2: 防火墙或安全软件阻止

解决方案:

• 临时关闭防火墙进行测试
• 将Python和uv添加到防火墙白名单
• 检查企业网络策略
• 联系网络管理员获取帮助

⚙️ 系统环境问题

问题1: Python版本不兼容

症状:

• Python版本低于3.8
• 缺少必要的Python模块
• 系统Python与虚拟环境冲突

检查Python版本:

python --version
python3 --version

解决方案:

Linux (Ubuntu/Debian):

# 安装Python 3.11
sudo apt update
sudo apt install python3.11 python3.11-venv python3.11-pip

# 使用特定版本创建虚拟环境
python3.11 -m venv ./venv

macOS:

# 使用Homebrew安装
brew install python@3.11

# 或使用pyenv管理多版本
brew install pyenv
pyenv install 3.11.0
pyenv local 3.11.0

Windows:

• 从 python.org 下载并安装Python 3.11+
• 确保勾选 "Add Python to PATH"
• 重启命令提示符

问题2: CUDA环境配置 (可选)

检查CUDA:

nvidia-smi
nvcc --version

安装CUDA (如果需要GPU加速):

• 安装NVIDIA驱动程序
• 下载并安装CUDA Toolkit (推荐11.8或12.x)
• 验证安装: nvidia-smi 和 nvcc --version

注意: CPU模式也可正常工作，GPU仅用于加速。

🔍 常用诊断命令

环境检查命令

# 完整环境检查
document-parser check

# 详细故障排除指南
document-parser troubleshoot

# 重新初始化环境
document-parser uv-init

手动验证命令

# 检查工具版本
uv --version
python --version

# 检查虚拟环境
./venv/bin/python --version      # Linux/macOS
.\venv\Scripts\python --version  # Windows

# 检查已安装的包
./venv/bin/pip list              # Linux/macOS
.\venv\Scripts\pip list          # Windows

# 测试MinerU
./venv/bin/mineru --help         # Linux/macOS
.\venv\Scripts\mineru --help     # Windows

# 测试MarkItDown
./venv/bin/python -m markitdown --help      # Linux/macOS
.\venv\Scripts\python -m markitdown --help  # Windows

日志查看

# 查看当天日志 (Linux/macOS)
tail -f logs/log.$(date +%Y-%m-%d)

# 查看最新日志
ls -la logs/
tail -f logs/log.*

# Windows
dir logs\
type logs\log.%date:~0,10%

清理和重置

# 清理UV缓存
uv cache clean

# 完全重置虚拟环境
rm -rf ./venv                    # Linux/macOS
rmdir /s .\venv                  # Windows
document-parser uv-init

# 清理日志文件
rm -rf logs/*                    # Linux/macOS
del /q logs\*                    # Windows

🆘 获取帮助

自助诊断步骤

1. 运行诊断命令:

   document-parser check
   document-parser troubleshoot
   

2. 收集系统信息:

   • 操作系统版本
   • Python版本
   • 当前工作目录
   • 完整的错误消息

3. 检查日志文件:

   ls -la logs/
   tail -100 logs/log.*
   

4. 尝试在新目录中测试:

   mkdir test-document-parser
   cd test-document-parser
   document-parser uv-init
   

常见解决方案总结

问题类型	快速解决方案
权限问题	chmod 755 . (Linux/macOS) 或以管理员身份运行 (Windows)
网络问题	使用镜像源: -i https://pypi.tuna.tsinghua.edu.cn/simple/
虚拟环境损坏	rm -rf ./venv && document-parser uv-init
UV未安装	curl -LsSf https://astral.sh/uv/install.sh | sh
Python版本过旧	安装Python 3.8+
磁盘空间不足	清理磁盘，确保至少500MB可用空间

最后的建议

如果所有方法都无法解决问题：

1. 完全重新开始:

   # 创建新的工作目录
   mkdir fresh-document-parser
   cd fresh-document-parser
   
   # 重新初始化
   document-parser uv-init
   

2. 检查系统限制:

   • 企业网络策略
   • 防病毒软件设置
   • 磁盘配额限制
   • 用户权限限制

3. 寻求帮助时提供:

   • 完整的错误消息
   • 系统信息 (uname -a 或 systeminfo)
   • Python版本 (python --version)
   • 执行的完整命令序列
   • 相关日志文件内容

---

记住: 大多数问题都可以通过重新运行 document-parser uv-init 来解决。这个命令会自动检测和修复常见的环境问题。