# 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](https://github.com/opendatalab/MinerU/blob/master/README_zh-CN.md)），conda 在本项目中主要用于环境壳层，而非替代 pip 装包。

---

## 推荐工作流

### 1. 创建并激活 conda 环境

```bash
conda create -n mineru python=3.12
conda activate mineru
```

### 2. 用 uv 安装 MinerU

```bash
# 安装 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）

```bash
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. 验证环境

```bash
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 布局检测](../ocr_tools/universal_doc_parser/dit_support/README.md) 依赖的 **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](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](mineru/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：

```bash
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/README.md) | MinerU 环境变量、vLLM 服务、批量处理 |
| [paddlex/README.md](paddlex/README.md) | PaddleX 独立 `uv venv` 与 paddlepaddle 安装 |
| [ocr_tools/universal_doc_parser/dit_support/README.md](../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](https://opendatalab.github.io/MinerU/zh/faq/#windows-cuda-acceleration)。确认 Python 版本 ≤ 3.12，并安装与驱动匹配的 torch CUDA wheel。

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

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

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