复现开源代码仓库时自动配置 Python/C++/PyTorch/CUDA/MMCV 等技术栈的 conda 环境,先产出 requirements.txt 和安装方案,再通过 tmux 串行执行 conda/pip/编译命令,适用于视觉、三维重建、自动驾驶等仓库。
适用于自动驾驶、视觉感知、三维重建等开源仓库复现,技术栈涵盖 Python、C++、PyTorch、CUDA、MMCV 等。
阶段 1:方案设计与依赖整理 → 用户审批 → 阶段 2:tmux 中执行安装 → 阶段 3:验证与汇报
原则:
requirements.txt,不要等到安装阶段再临时拼。conda 命令都在 tmux 中运行,日志落到 /tmp/,不要在前台直接跑长命令,不要在 Codex 前台/沙箱里直接跑 conda info、conda env list、conda install。http_proxy/https_proxy。按优先级依次读取以下文件:
README.md / README.rst
requirements.txt / requirements*.txt
setup.py / setup.cfg / pyproject.toml
environment.yml / conda.yaml
docs/install.md / INSTALL.md
任何 setup.sh / install.sh 脚本
同时扫描源码中的关键导入,交叉验证依赖声明:
rg -n "^(import|from) " --glob '*.py' .
rg -n "torch\.|mmcv|mmdet|mmseg|mmdet3d" --glob '*.py' .
重点检查:
torch.utils.cpp_extension 仍可能依赖 pkg_resources,必要时使用 setuptools<81。常用兼容判断:
cu118,优先使用系统 /usr/local/cuda-11.8。系统全局 CUDA 为 11.8(/usr/local/cuda-11.8):
export CUDA_HOME=/usr/local/cuda-11.8
export PATH=$CUDA_HOME/bin:$PATH
export LD_LIBRARY_PATH=$CUDA_HOME/lib64:$LD_LIBRARY_PATH
CUDA_HOME=$CONDA_PREFIX。若仓库根目录没有合适的 requirements.txt,或现有文件明显缺失/混乱,则在方案设计阶段直接生成或更新根目录 requirements.txt,来源包括:
environment.yml 中的 pip 依赖requirements*.txt生成后要在方案里明确说明:
requirements.txt 是新建还是修订默认顺序:
Step 1: 创建 conda 环境
Step 2: [若需要] 安装环境内 CUDA toolkit
Step 3: 安装 numpy
Step 4: 安装 torch / torchvision / torchaudio
Step 5: 调整 setuptools 版本
Step 6: [若使用 MMCV 生态] 安装 openmim,通过 mim 安装 mmcv/mmdet/mmseg/mmdet3d
Step 7: 安装其余 Python 依赖(requirements.txt)
Step 8: 编译 CUDA / C++ 扩展
Step 9: 安装其他库(如有)
Step 10: 验证环境
把 README 中提到的数据集、权重、预处理步骤列成清单。
将方案写入项目内 docs/env-setup-plan.md,同时在对话里展示摘要。
文档至少包含:
# 环境配置方案 — <项目名>
## 基本信息
- conda 环境名
- Python 版本
- CUDA 来源与版本
- torch 版本
## 版本冲突分析
- 冲突项
- 解决方式
## requirements.txt 设计
- 新建或修订说明
- 关键包来源与版本调整
## 安装步骤
- 按顺序列出完整命令
## 数据与模型准备
- 仅清单,不执行
等待用户审批后再进入阶段 2。
所有会修改环境、联网下载、编译扩展的命令,都必须在 tmux 会话中执行。
标准做法:
env_install、repo_env_installconda 相关命令一律在该会话的宿主机 shell 中执行tmux send-keys 发进去/tmp/<repo>_env_install.logtmux capture-pane 和 tail 轮询进度推荐模式:
tmux new-session -d -s <session>
tmux send-keys -t <session> "cd <repo> && <command> |& tee -a /tmp/<log>.log" C-m
tmux capture-pane -t <session> -p | tail -n 40
tail -n 40 /tmp/<log>.log
在实际安装中,优先遵循以下经验:
source ~/.bashrc,确保宿主 shell 能正确拿到 conda 初始化。tmux capture-pane 能看到实时状态,但 tee/pip 有时会缓冲;必要时同时检查 /tmp/*.log 和进程状态。ps、日志一起判断。$PYTHON 做验证,不要依赖前台 conda info / conda env list。source ~/.bashrc 2>/dev/null || true
which conda && conda --version
ls /usr/local/cuda*/version.txt 2>/dev/null || nvcc --version 2>/dev/null
conda create -n <env_name> python=<version> pip -y
若 conda 因插件、虚拟包或求解器报错,优先尝试:
export CONDA_NO_PLUGINS=true
conda create --solver=classic -n <env_name> python=<version> pip -y
创建后统一使用绝对路径:
CONDA_PREFIX=/home/dzp62442/miniconda3/envs/<env_name>
PYTHON=$CONDA_PREFIX/bin/python
PIP="$PYTHON -m pip"
优先使用环境内 Python 直接调用 pip,不要默认用 conda run -n ... pip 跑大下载任务。
$PIP install --upgrade pip wheel
$PIP install "numpy==<version>"
$PIP install torch==<version> torchvision==<version> torchaudio==<version> \
--index-url https://download.pytorch.org/whl/cu<cuda_suffix>
若项目后续编译扩展,且 torch 的 C++ 扩展需要 pkg_resources,则在扩展编译前先执行:
$PIP install 'setuptools<81'
$PIP install -r requirements.txt
安装后需要重新核对以下核心版本是否被覆盖:
若与方案不符,要记录并决定是否回钉。
仅在项目实际使用 MMCV 生态时安装:
$PIP install openmim
$CONDA_PREFIX/bin/mim install mmcv-full==<version>
$CONDA_PREFIX/bin/mim install mmdet==<version>
$CONDA_PREFIX/bin/mim install mmsegmentation==<version>
$CONDA_PREFIX/bin/mim install mmdet3d==<version>
编译前先设置:
export CUDA_HOME=/usr/local/cuda-11.8
export PATH=$CUDA_HOME/bin:$PATH
export LD_LIBRARY_PATH=$CUDA_HOME/lib64:$LD_LIBRARY_PATH
统一经验:
--no-build-isolation,避免隔离环境看不到 torch。simple-knn 和 diff-gaussian-rasterization 可直接用同一模式安装:$PIP install -v --no-build-isolation submodules/simple-knn
$PIP install -v --no-build-isolation submodules/diff-gaussian-rasterization
croco/models/curope 和 dust3r/croco/models/curope,要按实际导入路径编译;很多仓库实际走 dust3r/croco,此时不能只编根目录副本:cd croco/models/curope && $PYTHON setup.py build_ext --inplace
cd <repo_root>
cd dust3r/croco/models/curope && $PYTHON setup.py build_ext --inplace
优先使用环境内 Python 验证,不直接依赖 conda info / conda env list。
优先验证:
$PYTHON - <<'EOF'
import torch
print('torch', torch.__version__)
print('cuda', torch.version.cuda)
print('cuda_available', torch.cuda.is_available())
EOF
若直接导入自定义扩展报 libc10.so / libtorch*.so 找不到,先显式 import torch,必要时补:
export LD_LIBRARY_PATH=$CONDA_PREFIX/lib/python3.11/site-packages/torch/lib:$CUDA_HOME/lib64:$LD_LIBRARY_PATH
验证时按“通用扩展 → 项目入口”两层做:
$PYTHON - <<'EOF'
import torch
import simple_knn._C
import diff_gaussian_rasterization
print('gaussian extensions ok')
EOF
然后补充项目实际入口导入,例如 from mast3r.model import AsymmetricMASt3R、import mmcv、import pointops。若不再出现 Warning, cannot find cuda-compiled version of RoPE2D,说明对应 curope 已编译到实际导入路径。
汇报必须包含:
requirements.txt 是否新建或修订| 问题 | 原因 | 解决方案 |
|---|---|---|
| conda 因插件或虚拟包报错 | 插件环境异常 | export CONDA_NO_PLUGINS=true,必要时加 --solver=classic |
| torch / 本地 CUDA 扩展编译异常 | torch 未先安装,或 build isolation 隔离了 torch | 先装 torch,再用 pip install --no-build-isolation <local_pkg> |
torch.utils.cpp_extension 报 pkg_resources 缺失 | setuptools 过新 | pip install 'setuptools<81' |
直接导入自定义扩展时报 libc10.so 缺失 | torch 动态库未预加载 | 先 import torch,或补 LD_LIBRARY_PATH |
只编了根目录 curope 仍出现 RoPE 警告 | 实际导入走的是 dust3r/croco | 再编 dust3r/croco/models/curope |
| pip 大轮子下载时日志不动 | 输出缓冲,不一定卡死 | 同时检查 tmux pane、日志、进程和临时文件大小 |
conda run -n ... pip 表现异常 | 包装层额外引入问题 | 优先用 $CONDA_PREFIX/bin/python -m pip |