VLMiner 是一个强大的 PDF 处理工具，支持多种视觉语言模型（VLM），能够将 PDF 文档高质量地转换为 Markdown 格式。
- 🎯 多 VLM 架构：支持 MinerU VLM、Gemini VLM、OpenAI VLM
- 🆓 免费本地处理：使用 MinerU 2.5 VLM 实现零成本处理
- ⚡ 混合处理模式：Pipeline 布局检测 + VLM 精准增强
- 🔄 自动版本检测：兼容 MinerU 2.0 和 2.5
- 📊 高精度识别：SOTA 级别的公式、表格、图像识别
- 🌐 灵活部署：本地部署或云端 API，按需选择
# 克隆仓库
git clone https://github.com/bogerman1/vlminer.git
cd vlminer
# 创建环境
conda create -n vlminer python=3.11 -y
conda activate vlminer
# 安装依赖（完整安装）
pip install -e ".[all]"
# 或基础安装（仅 Pipeline + Gemini）
pip install -e ".[mineru-core,gemini]"特别说明，本项目对cuda和pytorch的环境要求严格，如有gpu报错请查看cuda和pytorch的版本
# 使用 ModelScope 源（国内用户推荐）
python download_models.py --source modelscope
# 或使用 HuggingFace 源
python download_models.py# 启动 WebUI（推荐）
python main.py
# 或使用 CLI
python main.py --mode cli --input document.pdf --vlm-provider mineru访问 http://localhost:8091 使用 WebUI。
| 特性 | MinerU VLM | Gemini VLM | OpenAI VLM |
|---|---|---|---|
| 成本 | 🆓 免费 | 💰 付费 | 💰 付费 |
| 部署 | 本地 | 云端 | 云端/本地 |
| 速度 | ⚡⚡⚡ 快 | ⚡ 中等 | ⚡⚡ 较快 |
| 公式识别 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| 表格提取 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| 图像描述 | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| 离线支持 | ✅ | ❌ | 部分 |
python main.py --mode cli --input doc.pdf --backend hybrid --vlm-provider mineru- 使用 MinerU Pipeline 进行快速布局检测
- 使用 VLM 对公式、表格、图像进行精准增强
- 最佳平衡：速度快 + 精度高
python main.py --mode cli --input doc.pdf --backend pipeline --vlm-provider none- 仅使用 MinerU Pipeline（OCR + 规则）
- 最快速度，适合简单文档
python main.py --mode cli --input doc.pdf --backend pure-vlm --vlm-provider mineru- 整页使用 VLM 推理
- 最高精度，但速度较慢，MineruVLM可以用用试试，由于windows没有vllm可以用，所以建议还是把项目转到linux在用本地vlm
vlminer/
├── src/ # 源代码
│ ├── integrations/ # MinerU API 接口层
│ │ └── mineru_api/ # 版本抽象和适配器
│ ├── vlm/ # VLM 抽象层
│ │ ├── base.py # VLM 基类
│ │ ├── registry.py # 提供商注册表
│ │ └── providers/ # VLM 提供商实现
│ ├── processors/ # 核心处理器
│ │ ├── pdf_processor.py # PDF 处理协调器
│ │ ├── batch_processor.py # 批处理器
│ │ └── spatial_mapper.py # 空间映射
│ ├── webui/ # Gradio WebUI
│ │ └── gradio_ui_v3.py # 主界面
│ └── config/ # 配置和提示词
├── MinerU25/ # MinerU 2.5 源码
├── models/ # AI 模型（需下载）
├── config/ # 配置文件
│ └── mineru.json # MinerU 配置
├── download_models.py # 模型下载脚本
├── main.py # 主入口
└── pyproject.toml # 项目配置
详细架构说明请查看 ARCHITECTURE_V2.md
# Gemini API Key（使用 Gemini VLM 时需要）
export GEMINI_API_KEY="your-api-key"
# OpenAI API Key（使用 OpenAI VLM 时需要）
export OPENAI_API_KEY="your-api-key"
# 强制离线模式（可选）
export HF_HUB_OFFLINE=1
export TRANSFORMERS_OFFLINE=1from src.processors.pdf_processor import PDFProcessor
# 初始化处理器
processor = PDFProcessor()
# 配置
run_config = {
'vlm_provider': 'mineru', # 或 'gemini', 'openai', 'none'
'mineru_backend': 'hybrid', # 或 'pipeline', 'pure-vlm'
'formula_processing': True,
'table_processing': True,
'image_descriptions': True,
'max_tokens': 512,
'temperature': 0.0,
}
# 处理 PDF
result = processor.process_document(
pdf_path='document.pdf',
output_dir='output',
run_config=run_config
)
print(f"输出: {result['output_file']}")# 使用 MinerU VLM（免费本地）
python main.py --mode cli \
--input document.pdf \
--output output \
--vlm-provider mineru \
--backend hybrid
# 使用 Gemini VLM（付费云端）
python main.py --mode cli \
--input document.pdf \
--output output \
--vlm-provider gemini \
--api-key YOUR_GEMINI_KEY \
--backend hybrid
# 使用 OpenAI 兼容的本地模型
python main.py --mode cli \
--input document.pdf \
--output output \
--vlm-provider openai \
--backend hybrid- CPU: 4 核心
- RAM: 16 GB
- 磁盘: 20 GB（包含模型）
- Python: 3.10 - 3.13
- GPU: NVIDIA GPU with 8GB+ VRAM（支持 CUDA 11.8+）
- RAM: 32 GB
- 磁盘: 30 GB（包含模型和缓存）
- 无需 GPU
- 16 GB RAM 即可