ocr_platform/docs/conda与uv包管理指南.md

Conda 与 uv 包管理指南

本文档说明 OCR Platform 及 MinerU 相关项目的 Python 环境管理策略：conda 管环境隔离，uv 管依赖安装。

结论概览

层级	推荐工具	作用
Python 版本 / 环境隔离	conda	固定 Python 3.10–3.13，多项目互不干扰
依赖安装	uv	官方推荐，解析与安装速度显著快于 pip/conda

不是二选一：本项目约定使用 conda activate mineru 创建/激活环境后，用 uv pip install 安装包。

MinerU 官方安装方式同样以 uv 为主（见 MinerU README），conda 在本项目中主要用于环境壳层，而非替代 pip 装包。

---

推荐工作流

1. 创建并激活 conda 环境

conda create -n mineru python=3.12
conda activate mineru

2. 用 uv 安装 MinerU

# 安装 uv（若尚未安装）
pip install uv -i https://mirrors.aliyun.com/pypi/simple

# PyPI 安装（用户）
uv pip install -U "mineru[all]" -i https://mirrors.aliyun.com/pypi/simple

# 源码开发安装（开发者）
cd /path/to/MinerU
uv pip install -U -e '.[all]' -i https://mirrors.aliyun.com/pypi/simple

3. 非交互式命令（脚本 / CI）

conda run -n mineru uv pip install -U "mineru[core]" -i https://mirrors.aliyun.com/pypi/simple
conda run -n mineru python -c "import torch; print(torch.__version__)"

4. 验证环境

conda activate mineru
python -c "import torch; print(f'PyTorch: {torch.__version__}, CUDA: {torch.cuda.is_available()}')"
python -c "import mineru; print('mineru OK')"

---

什么时候用 conda

1. 固定 Python 版本
   MinerU 要求 Python 3.10–3.13。Windows 上使用 vLLM 时，因 ray 限制暂不支持 3.13，建议使用 3.10–3.12。

2. CUDA / cuDNN 版本对齐困难时（Linux GPU）
   pip 的 torch / vllm wheel 自带部分 CUDA runtime，但仍需与 NVIDIA 驱动、Compute Capability 匹配。conda-forge / nvidia channel 可一次性安装 pytorch-cuda + cudnn，减少版本矩阵踩坑。

3. 需要编译的 C++ 扩展
   例如 DiT 布局检测 依赖的 detectron2，从源码编译时常需匹配的 gcc/clang 与 torch ABI；conda-forge 预编译包有时更省事。

4. 多项目环境隔离
   OCR Platform 同时涉及 MinerU、PaddleX、DotsOCR 等，用 conda 区分环境可避免依赖冲突。

---

什么时候用 uv

1. MinerU 本体及绝大部分 PyPI 依赖
   mineru[all] 中的 torch、transformers、vllm、onnxruntime、opencv-python、fastapi 等均有 PyPI wheel。

2. 日常开发、CI、重装依赖
   uv 解析与安装速度明显快于 conda SAT 求解。

3. 纯 Python 工具链
   mineru-vl-utils、gradio、项目内脚本依赖等。

4. 子项目独立 venv（可选）
   PaddleX 等可按 paddlex/README.md 使用 uv venv 单独建环境，与 MinerU 环境分离。

---

MinerU 核心依赖：uv/pip 能否安装

以下依赖来自 MinerU pyproject.toml，通常无需 conda 单独安装：

依赖	uv/pip	说明
torch / torchvision	✅	PyPI 提供 CPU/CUDA wheel；GPU 需选对 CUDA 版本 index
vllm	✅	Linux 上 pip 安装；生产环境也可使用官方 Docker 镜像
onnxruntime	✅	wheel 自带推理后端
opencv-python	✅	wheel 自带 OpenCV；Linux 无头环境可能还需系统 libGL
transformers / accelerate	✅	纯 Python
detectron2	⚠️	可从 git 源码编译；conda 预编译包有时更稳（见 DiT 模块）
PaddlePaddle	—	MinerU 核心不需要；模型已转为 PyTorch，见 mineru_处理流程.md

可选扩展（按后端选择安装）：

extra	主要依赖	平台
pipeline	torch, torchvision, onnxruntime	全平台，支持纯 CPU
vlm	torch, transformers	全平台
vllm	vllm	Linux
mlx	mlx-vlm	macOS (Apple Silicon)
lmdeploy	lmdeploy	Windows
gradio	gradio	全平台

---

哪些情况 conda / 系统包仍不可少

uv 不能替代以下层级；缺了会在 import 或 GPU 初始化阶段失败：

1. NVIDIA 驱动

uv 不安装驱动。需本机 nvidia-smi 可用，且驱动版本满足所选 CUDA / torch wheel 要求。

2. CUDA 版本矩阵

torch + vllm + 驱动 + CUDA 必须对齐。uv 可以装 wheel，但选错版本会导致 CUDA available: False。裸机 Linux GPU 若反复踩坑，可改用：

• conda 安装 pytorch-cuda + cudnn；或
• MinerU 官方 Docker 镜像（已打包 torch + vllm + CUDA）。

3. 系统级 C 库

典型报错：ImportError: libGL.so.1: cannot open shared object file

这是系统库缺失，需用系统包管理器安装，例如 WSL2 / Ubuntu：

sudo apt-get install libgl1-mesa-glx

conda 和 uv 均不能直接解决。

4. 从源码编译的扩展

detectron2 等需要本地编译器与 torch 版本匹配。uv 只能触发 pip 编译，不保证在所有平台一次成功。

---

能力边界示意

┌─────────────────────────────────────────────────────────┐
│  uv / pip 能管                                           │
│  PyPI Python 包：torch, vllm, opencv-python, mineru…    │
└─────────────────────────────────────────────────────────┘
                          ↓ 依赖
┌─────────────────────────────────────────────────────────┐
│  uv / pip 管不了（需 conda / apt / brew / 驱动安装）     │
│  · NVIDIA 驱动                                          │
│  · CUDA Toolkit / cuDNN 与驱动对齐                       │
│  · libGL、libgomp 等系统 .so                             │
│  · C++ 编译 toolchain（detectron2 等）                   │
└─────────────────────────────────────────────────────────┘

---

按场景选择

场景	建议
macOS 本地开发	conda create -n mineru python=3.12 + uv pip install -e '.[all]'；VLM 可用 MLX 或远程 vLLM 服务
Linux GPU 生产	优先 Docker 官方镜像；裸机则用 conda 对齐 CUDA 栈 + uv 装 mineru
仅 MinerU CLI/API	可完全 uv venv + uv pip install mineru[all]，不必 conda
OCR Platform 全家桶（PaddleX + DiT + MinerU）	conda 做环境隔离；各子项目用 uv 装包；Paddle 可单独 uv venv
CI / 脚本	conda run -n mineru ... 避免 activate 未生效

---

与本仓库其他文档的关系

文档	内容
mineru/README.md	MinerU 环境变量、vLLM 服务、批量处理
paddlex/README.md	PaddleX 独立 uv venv 与 paddlepaddle 安装
ocr_tools/universal_doc_parser/dit_support/README.md	detectron2 编译安装
项目 .cursor/rules/project-conventions.mdc	全局约定：conda activate mineru / conda run -n mineru

---

常见问题

Q: 能否完全不用 conda，只用 uv？

可以。MinerU 官方支持 uv venv + uv pip install mineru[all]。本项目因多工具并存、团队已有 mineru conda 环境，仍推荐 conda 做环境壳。

Q: 能否完全不用 uv，只用 conda install？

不推荐。MinerU 未提供 conda 配方，conda 直接装 PyPI 包速度慢且易与 channel 冲突。应用 conda 管 Python，uv 管 PyPI 依赖。

Q: Windows 上 CUDA 不可用怎么办？

参考 MinerU Windows CUDA FAQ。确认 Python 版本 ≤ 3.12，并安装与驱动匹配的 torch CUDA wheel。

Q: 当前环境装了哪些是通过 conda、哪些是通过 pip？

典型 mineru 环境中，conda 仅提供 Python + 基础系统库（openssl、zlib 等），torch、vllm、onnxruntime、opencv、detectron2 等均为 pip/uv 安装。可用以下命令自查：

conda list -n mineru | head -30          # conda 层
conda list -n mineru | rg "pypi_0"       # pip/uv 层