| name | dl-env-setup |
| description | Automatically configure deep learning environments (Conda + PyTorch/TensorFlow/JAX + CUDA) for any research repo. Use this skill when the user wants to: set up a deep learning or ML training/inference environment, reproduce a paper's code or configure a research repo's runtime, install PyTorch (or TensorFlow/JAX) with GPU/CUDA support, troubleshoot PyTorch + CUDA environment issues, or create a conda/venv environment for any DL project. Do NOT trigger for: general Python project setup without DL frameworks, pure data science (pandas/sklearn) without GPU needs, or frontend/web/non-ML projects. |
自动配置深度学习环境（Conda + PyTorch + CUDA）
目标
对任意"论文/项目代码仓库"（训练/推理/复现）自动完成：
- 创建隔离环境（优先 conda/mamba，其次 venv）
- 安装匹配的 PyTorch（CPU 或 GPU，自动推断 CUDA 版本）
- 安装项目依赖（requirements / pyproject / environment.yml）
- 如需编译 CUDA 扩展则完成编译或给出可执行替代方案
- 运行最小验证（smoke test），产出可复现锁定文件与日志
输入（可选参数）
| 参数 | 默认值 | 说明 |
|---|
| repo_path | 当前目录 | 本地仓库路径（已 clone） |
| repo_url | — | 仓库地址（若 repo_path 不存在则 clone） |
| mode | 自动检测 | gpu / cpu |
| python_version | 3.10 | 若项目声明则遵从 |
| env_manager | 自动选择 | conda / mamba / micromamba / venv（优先 micromamba > conda > venv） |
| torch_cuda | 自动推断 | 如 cu118 / cu121 / cu124（GPU 模式） |
| dl_framework | pytorch | pytorch / tensorflow / jax（根据项目依赖自动判断） |
| mirrors | 自动选择 | conda_channel / pip_index（根据网络环境决定） |
| extras | — | notebooks / dev / train / demo（若项目支持 .[extra]） |
输出（交付物）
必须产出：
verify_env.py：环境验证脚本（导入关键包 + CUDA 检测 + 小 tensor 运算）install.log：完整安装日志
可选产出（用户要求时生成）：
requirements.lock.txt：pip freeze 锁定environment.lock.yml：conda env export --from-history（若使用 conda）smoke_test.sh：一键验证脚本
安全与边界
- 不运行长时间训练；只做秒/分钟级 smoke test
- 不读取/上传仓库中的私密数据
- GPU 工具链缺失时，优先提供 CPU 可运行方案 + 明确提示缺什么
- 不修改系统级 conda/pip 配置（镜像通过命令行参数临时指定）
平台检测与适配（实战经验）
平台判断
uname -s 2>/dev/null
记录变量：platform = linux / windows / macos
Windows 平台关键限制
1. conda run 注意事项：
--no-banner 在部分 conda 版本不支持，不要使用- 多行
python -c "..." 在 Windows 上会报错，必须将代码写入 .py 文件再执行
- 必须加
--cwd <repo_path> 指定工作目录（Claude Code 默认在 system32）
2. Windows 不兼容包清单（遇到时自动跳过，不要等安装失败）：
| 包 | Windows 状态 | 替代方案 |
|---|
| deepspeed | 不支持 | 跳过，训练需在 Linux |
| flash-attn | 不支持（需 Linux + nvcc 编译） | 跳过，模型会自动回退到标准 attention |
| triton | 不支持 | 跳过 |
| bitsandbytes < 0.43.0 | 不支持 | 升级到 >= 0.43.0 |
| bitsandbytes >= 0.44.0 | 可能需要更新 torch | 需检查与项目 torch 版本的兼容性 |
3. 路径与命令差异：
- 使用
/c/Users/... 风格路径（Git Bash）
$HOME / $USERPROFILE 可能为空，用绝对路径- 不要用
tee（部分场景不可用），用 > file 2>&1 重定向
conda run 统一用法（跨平台）
conda run -n <env_name> --cwd <repo_path> pip install <pkg>
conda run -n <env_name> --cwd <repo_path> python verify_env.py
CONDA_PREFIX=$(conda info --envs | grep <env_name> | awk '{print $NF}')
$CONDA_PREFIX/bin/pip install torch
source /path/to/venv/bin/activate && pip install torch
整个 skill 中所有 pip/python 命令都必须遵守此规则。
所有验证代码必须写入 .py 文件执行，禁止依赖多行 python -c。
Step 0：仓库探测（Repo Discovery）
- 确保仓库存在（必要时
git clone）
- 探测依赖清单（按优先级扫描）：
environment.yml / environment.yamlpyproject.toml / poetry.lockrequirements.txt / requirements/*.txt / constraints.txtsetup.py / setup.cfgINSTALL.md / README.md / docs/installation*
- 自动判断
dl_framework：
- 依赖中含
torch / torchvision -> pytorch
- 依赖中含
tensorflow / tf-* -> tensorflow
- 依赖中含
jax / jaxlib -> jax
- 均无 -> 默认 pytorch
- 解析项目要求的 Python 版本；无声明则用 3.10
- 判断 requirements.txt 质量（实战经验：很多项目的 requirements.txt 是 pip freeze 导出）：
- 行数 > 100 -> 大概率是 freeze dump
- 包含非公开包名（如
byted-*、internal-*、公司内部包） -> 不能直接用
- 同时存在 pyproject.toml 的 extras -> 优先用 extras，requirements.txt 仅作版本参考
- 标记变量：
req_txt_quality = clean / freeze_dump / has_private_pkgs
记录变量：
detected_manifests：找到的依赖文件列表declared_python：项目声明的 Python 版本detected_extras：可用的 extrasdl_framework：推断的框架req_txt_quality：requirements.txt 质量评估
Step 1：硬件与系统检测
1.1 GPU 检测
nvidia-smi --query-gpu=driver_version,name,memory.total --format=csv,noheader 2>/dev/null
- 有输出 ->
mode=gpu，记录 Driver Version
- 无输出 / 命令不存在 ->
mode=cpu
1.2 CUDA 版本自动推断（GPU 模式）
nvidia-smi | grep "CUDA Version" | awk '{print $9}'
推断 torch_cuda 的逻辑：
- 取 nvidia-smi 报告的 CUDA Version（如 12.8）
- 映射到 PyTorch 支持的最近 wheel 标签：
- CUDA 12.8+ ->
cu128（若 PyTorch 已发布）否则 cu124
- CUDA 12.1~12.7 ->
cu121
- CUDA 11.8~11.x ->
cu118
- CUDA < 11.8 -> 警告驱动过旧，建议升级，回退
cpu
- 若项目明确指定了 CUDA 版本，以项目为准
1.3 补充规则
- Driver Version >= CUDA Runtime Version 才能运行
- PyTorch 的 pip wheel 自带 CUDA runtime，多数情况无需单独装 CUDA Toolkit
- 仅"需要编译 CUDA 扩展"的项目才强依赖
nvcc
记录变量：
mode：gpu / cpudriver_versioncuda_version（Driver 支持的最高版本）torch_cuda：推断的 wheel 标签（如 cu121）
Step 2：镜像与通道策略
2.1 网络环境检测
timeout 5 curl -s -o /dev/null -w "%{time_total}" https://pypi.org/simple/ 2>/dev/null || echo "timeout"
- 延迟 < 2s -> 使用官方源
- 延迟 >= 2s 或超时 -> 使用国内镜像
2.2 Conda 镜像（临时指定，不改全局配置）
conda create -n <env> python=3.10 -c https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main -y
可选镜像：
- 清华：
https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main
- 北外：
https://mirrors.bfsu.edu.cn/anaconda/pkgs/main
- 阿里：
http://mirrors.aliyun.com/anaconda/pkgs/main
2.3 Pip 镜像
pip install <pkg> -i https://pypi.tuna.tsinghua.edu.cn/simple
PyTorch 安装始终使用官方 index-url（https://download.pytorch.org/whl/cuXXX），不走国内 pip 镜像。
记录变量：
use_mirror：true / falseconda_channelpip_index
Step 3：创建虚拟环境
3.0 前置检查：conda/Python 是否存在（实战经验）
若 conda/mamba/micromamba/python 均不存在，需先安装：
micromamba --version 2>/dev/null || mamba --version 2>/dev/null || conda --version 2>/dev/null || python --version 2>/dev/null
若全部不存在 -> 询问用户选择安装方式：
- Miniconda（推荐）：轻量，自带 Python
- Miniforge：社区版，默认 conda-forge
安装流程（以 Miniconda 为例）：
curl -LO https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh -b -p $HOME/miniconda3
curl -LO https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe
start //wait <installer>.exe /InstallationType=JustMe /RegisterPython=1 /AddToPath=1 /S /D=C:\Users\<user>\miniconda3
安装后必须处理 conda TOS（新版 conda 要求）：
conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/main
conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/r
conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/msys2
3.1 检测可用的环境管理器
micromamba --version 2>/dev/null || mamba --version 2>/dev/null || conda --version 2>/dev/null || python -m venv --help >/dev/null 2>&1
3.2 环境命名
格式：dl_<项目名>_py<版本>，如 dl_yolov8_py310
3.3 创建环境
conda create -n <env_name> python=<python_version> -y [-c <conda_channel>]
python -m venv /path/to/<env_name>
3.4 检查已有环境（避免冲突）
conda env list | grep <env_name>
若已存在，询问用户：复用 / 删除重建 / 换名
记录变量：
env_manager：实际使用的管理器env_namepython_version
Step 4：安装 DL 框架
4.1 PyTorch（dl_framework=pytorch）
GPU 模式：
conda run -n <env_name> --no-banner pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/<torch_cuda>
CPU 模式：
conda run -n <env_name> --no-banner pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
说明：
torchvision：图像相关项目必装torchaudio：音频相关项目才装，否则可省略- 始终使用 PyTorch 官方 index-url，不走国内 pip 镜像
- Windows 平台：先检查"Windows 不兼容包清单"，跳过不支持的包
4.4 版本钉死与防篡改策略（实战经验）
问题： pip 安装后续包时会静默升级 numpy/torch 等关键包，导致环境崩溃。
安装 PyTorch 后立即钉死 numpy：
conda run -n <env_name> pip install torch==X.X.X ... --index-url ...
conda run -n <env_name> pip install "numpy<2"
每批依赖安装后执行版本一致性检查：
conda run -n <env_name> --cwd <repo_path> python _check_versions.py
_check_versions.py 内容：
import torch
assert "cu" in torch.__version__ or "cpu" in torch.__version__, f"torch 被替换为 PyPI 版本: {torch.__version__}"
import numpy; assert int(numpy.__version__.split('.')[0]) < 2, f"numpy 被升级到 2.x: {numpy.__version__}"
print("Version check OK")
若版本被篡改，立即回退：
conda run -n <env_name> pip install torch==X.X.X --index-url https://download.pytorch.org/whl/<torch_cuda> --force-reinstall --no-deps
conda run -n <env_name> pip install "numpy<2"
4.2 TensorFlow（dl_framework=tensorflow）
conda run -n <env_name> --no-banner pip install tensorflow
conda run -n <env_name> --no-banner pip install tensorflow-cpu
4.3 JAX（dl_framework=jax）
conda run -n <env_name> --no-banner pip install "jax[cuda12]"
conda run -n <env_name> --no-banner pip install jax
Step 5：验证框架安装（必须闭环）
重要：所有验证代码必须写入 .py 文件执行，不要用多行 python -c（Windows 不支持）。
5.1 生成框架验证脚本 _verify_framework.py
根据 dl_framework 生成对应内容，写入文件后执行：
import torch
print('torch:', torch.__version__)
print('cuda_available:', torch.cuda.is_available())
print('cuda_version:', torch.version.cuda)
if torch.cuda.is_available():
print('gpu_name:', torch.cuda.get_device_name(0))
x = torch.randn(2,3).cuda()
print('gpu_tensor_ok:', x.device)
执行方式：
conda run -n <env_name> --cwd <repo_path> python _verify_framework.py
5.2 GPU 模式下验证失败的排查
若 torch.cuda.is_available() == False（或 TF/JAX 无 GPU）：
- 确认
nvidia-smi 正常输出
- 检查是否误装了 CPU 版 -> 卸载后重装 GPU 版
- 检查
torch_cuda 版本是否与 Driver 兼容
- 重装命令加
--force-reinstall
Step 6：安装项目依赖
6.0 requirements.txt 质量预处理（实战经验）
根据 Step 0 的 req_txt_quality 判断：
若 freeze_dump 或 has_private_pkgs：
- 不直接
pip install -r requirements.txt
- 优先用 pyproject.toml 的 extras（如
pip install -e ".[train]"）
- 仅将 requirements.txt 作为版本参考（查看项目实际用了哪些版本）
若 clean：
- 可直接使用
pip install -r requirements.txt
6.1 优先级策略
按以下顺序处理（不互斥，可能需要组合）：
情况 A：有 environment.yml
conda env update -n <env_name> -f environment.yml
if [ -f requirements.txt ]; then
conda run -n <env_name> --no-banner pip install -r requirements.txt
fi
情况 B：有 requirements.txt（无 environment.yml）
conda run -n <env_name> --no-banner pip install -r requirements.txt [-i <pip_index>]
情况 C：Python 包项目（setup.py / pyproject.toml）
conda run -n <env_name> --no-banner pip install -e . [-i <pip_index>]
conda run -n <env_name> --no-banner pip install -e ".[notebooks,dev]"
6.2 依赖冲突处理
- 若
pip install -r requirements.txt 失败，尝试去掉严格版本锁定（== -> >=）
- 常见冲突源：
numpy、opencv-python、protobuf 版本与 torch 不兼容
- 冲突无法自动解决时，向用户报告具体冲突并建议手动调整
6.3 git 依赖安装失败的回退策略（实战经验）
pyproject.toml 中常见 pkg@git+https://...@<commit_hash> 格式的依赖。
失败原因： 浅克隆无法 fetch 到指定 commit / 仓库已删除 / 网络问题
回退流程：
- 从 requirements.txt 中查找该包的实际版本号（如
transformers==4.40.0.dev0）
- 安装最接近的正式发布版（如
transformers==4.40.0）
- 向用户说明替代情况及可能的兼容性风险
6.4 Windows 平台：跳过不兼容包（实战经验）
安装前先过滤 Windows 不兼容的包（参见"平台检测与适配"章节的清单）：
deepspeed -> 跳过flash-attn -> 跳过triton -> 跳过bitsandbytes -> 若项目指定 < 0.43.0，升级到 0.43.0（首个 Windows 版本），但需检查与项目 torch 版本的兼容性
6.5 每批安装后执行版本一致性检查
每安装一批依赖后，运行 _check_versions.py（见 Step 4.4）确认 torch/numpy 未被篡改。若被篡改则立即回退修复。
Step 7：CUDA 扩展编译（可选）
7.1 检测是否需要编译
扫描以下信号：
setup.py 含 CUDAExtension / torch.utils.cpp_extensionREADME / INSTALL 提到 nvcc / CUDA toolkit / build from source- 存在
.cu / .cuh 文件
7.2 编译流程
conda run -n <env_name> --no-banner nvcc --version 2>/dev/null
conda run -n <env_name> --no-banner pip install -e . 2>&1 | tee -a install.log
7.3 nvcc 缺失时的处理
优先级：
- 检查项目是否支持跳过编译（如
SKIP_CUDA_BUILD=1、NO_CUDA=1）
- 检查是否有预编译 wheel 可用
- 若都不行 -> 明确提示用户：
需要安装 CUDA Toolkit（版本需匹配 torch.version.cuda = <cuda_version>）
下载地址：https://developer.nvidia.com/cuda-toolkit-archive
- 同时提供 CPU 回退方案（如果项目支持）
Step 8：Smoke Test
8.1 生成 verify_env.py
"""环境验证脚本 - 自动生成"""
import sys
def check():
errors = []
try:
import torch
print(f"torch: {torch.__version__}")
print(f"cuda_available: {torch.cuda.is_available()}")
print(f"cuda_version: {torch.version.cuda}")
if torch.cuda.is_available():
x = torch.randn(2, 3).cuda()
print(f"gpu_tensor: {x.device} OK")
except Exception as e:
errors.append(f"torch: {e}")
for pkg in [<detected_core_packages>]:
try:
__import__(pkg)
print(f"{pkg}: OK")
except ImportError as e:
errors.append(f"{pkg}: {e}")
if errors:
print(f"\nFAILED ({len(errors)} errors):")
for e in errors:
print(f" - {e}")
sys.exit(1)
else:
print("\nAll checks passed.")
if __name__ == "__main__":
check()
8.2 运行验证
conda run -n <env_name> --no-banner python verify_env.py 2>&1 | tee -a install.log
8.3 可选：项目级 demo
- 若仓库有
demo/ / inference.py / predict.py，用最小输入跑一次
- 仅在明确轻量时运行，不跑完整训练
pytest 仅在项目测试明确很轻量时才运行
8.4 生成 smoke_test.sh
#!/bin/bash
set -e
echo "=== DL Environment Smoke Test ==="
conda run -n <env_name> --no-banner python verify_env.py
echo "=== Smoke test passed ==="
Step 9：可复现导出
conda run -n <env_name> --no-banner pip freeze > requirements.lock.txt
conda env export -n <env_name> --from-history > environment.lock.yml
最终交付文件清单：
verify_env.py - 环境验证脚本install.log - 安装日志smoke_test.sh - 一键验证（可选）requirements.lock.txt - pip 锁定（可选）environment.lock.yml - conda 锁定（可选）
常见错误排查
遇到安装或运行问题时，查阅 references/troubleshooting.md（18 条实战经验，覆盖 Windows 兼容性、版本篡改、依赖冲突等）。
完成条件（Completion Criteria）
全部满足才算完成：
python verify_env.py 成功退出（exit code 0）- GPU 模式下
torch.cuda.is_available() == True（或对应框架的 GPU 检测通过）
- 项目核心 import 全部成功
- 至少一个最小 demo/入口可运行（如项目提供）
verify_env.py 和 install.log 已生成
若无法全部满足，向用户明确报告：
- 哪些条件已满足
- 哪些条件未满足及原因
- 建议的下一步操作
