一、Docker环境构建要点补充

镜像选择建议

# 对于NVIDIA 50系显卡，推荐使用更新的版本
docker pull registry.cn-hangzhou.aliyuncs.com/vllm/vllm-openai:latest

# 或从官方拉取（国内可能较慢）
docker pull vllm/vllm-openai:v0.10.1.1

容器启动优化

docker run -itd \
  --name mineru-dev \
  --gpus all \
  --ipc=host \
  -p 7860:7860 \  # Gradio默认端口
  -p 8000:8000 \  # API服务端口
  -v /path/to/local/models:/root/.cache/mineru \  # 挂载模型目录
  -v /path/to/your/pdfs:/pdfs \  # 挂载PDF目录
  --shm-size=8g \  # 增加共享内存
  vllm/vllm-openai:v0.10.1.1 \
  tail -f /dev/null

二、MinerU源码安装注意事项

1. 源码获取优化

# 如果网络不佳，可以使用代理或镜像
git clone https://github.com.cnpmjs.org/opendatalab/MinerU.git --branch mineru-2.6.2-released --depth 1

# 或者使用Gitee镜像（如有）
git clone https://gitee.com/mirrors/MinerU.git --branch mineru-2.6.2-released --depth 1

2. 安装依赖加速

cd MinerU-mineru-2.6.2-released

# 使用国内源加速安装
pip install -e .[all] \
  -i https://pypi.tuna.tsinghua.edu.cn/simple \
  --trusted-host pypi.tuna.tsinghua.edu.cn

3. 模型下载配置

# 设置环境变量（国内用户必需）
export MINERU_MODEL_SOURCE=modelscope
export MODELSCOPE_CACHE=/root/.cache/modelscope

# 下载模型
mineru-models-download -s modelscope -m all

# 如果下载慢，可以单独下载需要的模型
mineru-models-download -s modelscope -m mineru-layout-1.8b-v1.0
mineru-models-download -s modelscope -m mineru-ocr-v1.0

三、MinerU启动方式详解

1. Gradio Web界面（推荐新手）

# 启动Gradio服务
mineru-gradio \
  --server-name 0.0.0.0 \
  --server-port 7860 \
  --concurrency-count 5 \
  --layout-model-path /root/.cache/mineru/modelscope/mineru-layout-1.8b-v1.0 \
  --ocr-model-path /root/.cache/mineru/modelscope/mineru-ocr-v1.0

# 访问地址：http://localhost:7860

2. FastAPI后端服务

# 启动API服务
mineru-api \
  --host 0.0.0.0 \
  --port 8000 \
  --reload  # 开发模式下自动重载

# API文档：http://localhost:8000/docs
# 示例API调用：
curl -X POST "http://localhost:8000/api/v1/parse" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@document.pdf" \
  -F "output_format=markdown"

3. vLLM服务器模式

# 高性能推理服务
vllm serve mineru-layout-1.8b-v1.0 \
  --host 0.0.0.0 \
  --port 8001 \
  --gpu-memory-utilization 0.9 \
  --max-model-len 4096 \
  --tensor-parallel-size 1

四、常用使用示例

命令行直接使用

# 转换单个PDF
mineru parse input.pdf --output-format markdown --output output.md

# 转换整个目录
mineru batch_parse /path/to/pdfs --output-dir ./outputs --format json

# 启用OCR
mineru parse scanned.pdf --enable-ocr --ocr-lang chi_sim+eng

# 提取表格
mineru parse document.pdf --extract-tables --table-format html

Python API使用

from mineru import MinerU

# 初始化
mineru = MinerU(
    layout_model="mineru-layout-1.8b-v1.0",
    ocr_model="mineru-ocr-v1.0",
    device="cuda"  # 或 "cpu"
)

# 解析文档
result = mineru.parse(
    "document.pdf",
    output_format="markdown",
    enable_ocr=True,
    ocr_lang=["chi_sim", "eng"]
)

# 获取不同格式的输出
markdown_text = result.to_markdown()
json_data = result.to_json()

五、故障排除

常见问题解决

1. CUDA内存不足

# 减少批处理大小
mineru-gradio --max-batch-size 2
# 或使用CPU模式
export CUDA_VISIBLE_DEVICES=""

2. 字体缺失问题

# 在容器内安装更多字体
apt-get install -y fonts-wqy-zenhei fonts-wqy-microhei ttf-mscorefonts-installer
fc-cache -fv

3. 模型下载失败

# 手动下载模型
# 从 https://modelscope.cn/models/OpenDataLab 下载
# 放置到 ~/.cache/mineru/modelscope/

性能优化建议

# 1. 启用量化（减少显存）
mineru-gradio --quantization bitsandbytes

# 2. 调整工作进程
export OMP_NUM_THREADS=4
export MKL_NUM_THREADS=4

# 3. 使用内存映射
mineru parse --use-mmap

六、生产环境部署

Docker Compose部署

version: '3.8'
services:
  mineru:
    build: .
    image: mineru:2.6.2
    container_name: mineru
    ports:
      - "7860:7860"
      - "8000:8000"
    volumes:
      - ./models:/root/.cache/mineru
      - ./pdfs:/pdfs
    environment:
      - MINERU_MODEL_SOURCE=modelscope
      - CUDA_VISIBLE_DEVICES=0
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
    command: mineru-gradio --server-name 0.0.0.0 --server-port 7860

这份指南涵盖了从安装到生产的完整流程。根据您的具体需求（开发测试还是生产部署），可以选择合适的启动方式和配置参数。