feat(新增Conda与uv包管理指南): 新增文档《Conda与uv包管理指南.md》，详细说明OCR Platform及MinerU项目的Python环境管理策略，推荐使用conda进行环境隔离，uv进行依赖安装，提升用户对环境配置的理解与使用指导。

docs/README.md

@@ -6,6 +6,7 @@
 
 ```
 docs/
+├── conda与uv包管理指南.md       # Conda 与 uv 环境/依赖管理策略
 ├── paddlex/                    # PaddleX 相关文档
 │   ├── README.md              # PaddleX 环境配置和使用说明
 │   ├── PaddleOCR-VL-说明.md   # PaddleOCR-VL 使用说明
@@ -36,6 +37,9 @@ docs/
 
 ## 快速导航
 
+### 环境与包管理
+- [Conda 与 uv 包管理指南](conda与uv包管理指南.md)
+
 ### PaddleX 文档
 - [环境配置和使用说明](paddlex/README.md)
 - [PaddleOCR-VL 使用说明](paddlex/PaddleOCR-VL-说明.md)

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

@@ -0,0 +1,213 @@
+# 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 层
+```