Linux 虚拟机深度学习代码运行通用指南
📚文档说明：本文档旨在为研究人员和开发者提供一套标准的深度学习代码复现与运行流程。
💻适用环境：Windows 11 (WSL2) / Ubuntu 虚拟机
🎯目标：建立标准化工作流，解决环境配置、依赖管理、大文件传输及训练/推理过程中的常见问题。
📅最后更新：2025年12月
📋 目录
- 1. 基础环境与驱动准备
- 2. Python 虚拟环境构建
- 3. 代码部署与编译
- 4. 数据集与权重管理（防坑指南）
- 5. 运行配置与启动
- 6. 资源监控与性能分析
- 7. 常见报错排查 (FAQ)
1. 基础环境与驱动准备
在开始任何深度学习项目之前，必须确保底层硬件与操作系统之间的桥梁（驱动）是通畅的。
1.1 显卡驱动 (Host vs Guest)
WSL2 用户（重点）：
操作：只在 Windows 主机端安装最新的 NVIDIA 驱动（Game Ready 或 Studio 均可）。
禁忌：严禁在 WSL2 Linux 内部安装显卡驱动，否则会覆盖 Windows 的映射，导致 GPU 无法识别。
原生 Linux/独立虚拟机用户：
操作：需要在 Linux 系统内安装 NVIDIA Driver 和 CUDA Toolkit。
1.2 验证 GPU 穿透
在 Linux 终端执行以下命令，确认系统能识别到显卡：
nvidia-smi- 检查项：
- 显卡型号是否正确（如 RTX 4060）。
- CUDA Version 显示是否正常（这代表驱动支持的最高 CUDA 版本）。
- 显存（Memory Usage）是否为空闲状态。
2. Python 虚拟环境构建
使用 Conda 进行环境隔离是最佳实践，避免不同论文的代码因版本冲突而“打架”。
2.1 安装 Miniconda
Miniconda 比 Anaconda 更轻量，适合服务器和 WSL 环境。
# 下载与安装wgethttps://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.shbashMiniconda3-latest-Linux-x86_64.sh -b -u -p ~/miniconda3 ~/miniconda3/bin/conda initbashsource~/.bashrc2.2 创建专用环境
根据目标代码的README.md要求选择 Python 版本（常用 3.8, 3.10, 3.12）。
# 格式：conda create -n [环境名] python=[版本号] -yconda create -n deep_learning_envpython=3.10-y conda activate deep_learning_env2.3 安装 PyTorch (核心依赖)
原则：PyTorch 的 CUDA 版本必须低于或等于nvidia-smi显示的版本。
- 推荐安装方式（从官网获取命令）：
# 示例：安装支持 CUDA 12.1 的 PyTorchpipinstalltorch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121- 验证：
python -c"import torch; print(f'CUDA Available: {torch.cuda.is_available()}')"3. 代码部署与编译
绝大多数高性能深度学习模型（如检测、分割、视频压缩）都包含自定义的 C++/CUDA 算子，必须手动编译。
3.1 获取代码
优先使用 Git 克隆，保证版本控制；若使用压缩包，解压后注意检查文件权限。
gitclone https://github.com/username/project-name.gitcdproject-name3.2 安装 Python 依赖
通常项目根目录下有requirements.txt。
pipinstall-r requirements.txt3.3 编译扩展算子 (关键步骤)
如果项目中包含setup.py，且涉及 CUDA 加速（如 Deformable Conv, Correlation 等），必须执行编译。
预备工作：安装编译工具链
sudoapt-getupdatesudoapt-getinstallbuild-essential cmake g++编译方式 A (开发模式，修改代码即生效)：
python setup.py develop编译方式 B (安装模式，直接装入环境)：
pipinstall.注意：编译过程中如果报错
nvcc not found，通常是因为 CUDA Toolkit 的路径未加入环境变量。需检查/usr/local/cuda/bin是否在$PATH中。
4. 数据集与权重管理（防坑指南）
WSL2 与 Windows 的文件系统互通虽然方便，但在处理大文件（>1GB）时极易出现截断或权限错误。
4.1 权重下载 (Checkpoints)
- 推荐：直接在 Linux 终端使用
wget或curl下载。 - 替代：在 Windows 下载好，通过
cp命令复制到 Linux 目录。
4.2 数据传输规范
严禁直接通过文件资源管理器（Explorer.exe）拖拽大文件进 WSL 目录。
正确操作流程：
- 在 Windows 下载/解压数据。
- 在 Linux 终端执行复制命令：
# /mnt/c/ 代表 C 盘cp/mnt/c/Users/Administrator/Downloads/large_model.pth ./checkpoints/- 完整性校验（必做）：
使用ls -lh查看大小，或使用md5sum校验哈希值。
4.3 数据集路径配置
大多数深度学习代码通过配置文件（Config）或命令行参数指定数据路径。
- 建议使用绝对路径（如
/home/user/project/data），避免相对路径带来的层级混乱。
5. 运行配置与启动
5.1 显卡指定 (CUDA_VISIBLE_DEVICES)
如果系统有多张显卡，或者代码默认使用 GPU 0 但你想用 GPU 1，可以通过环境变量控制。
- 代码内部：
--cuda 0(常见参数) - 全局控制：
# 仅让程序看到 0 号卡CUDA_VISIBLE_DEVICES=0python train.py5.2 配置文件修改
对于复杂的模型，参数通常写在 YAML 或 JSON 文件中（如config.yaml）。
- 检查重点：
batch_size：根据显存大小调整（4060 8G 显存通常设为 4-16）。num_workers：Windows/WSL 下多进程加载数据容易报错，调试时建议设为1或0。
5.3 标准启动命令
建议将启动命令写入.sh脚本，方便记录实验参数。
# run_inference.shpython test.py--config configs/deploy.json--checkpoint checkpoints/model_best.pth--input_dir ./test_data--output_dir ./results--device cuda:06. 资源监控与性能分析
代码跑起来后，不要“盲等”，需确认硬件是否在正常工作。
6.1 GPU 监控
查看显存占用和利用率：
# 每秒刷新一次状态watch-n1nvidia-smi- Volatile GPU-Util：GPU 计算核心利用率。推理时通常是脉冲式的，训练时应维持高位。
- Memory-Usage：显存占用。如果为 0，说明模型还在 CPU 上，未加载到 GPU。
6.2 进程监控
查看 CPU 和内存占用，防止内存溢出（OOM）导致系统卡死。
htop7. 常见报错排查 (FAQ)
| 错误类型 | 典型报错信息 | 解决方案 |
|---|---|---|
| 显卡不可用 | AssertionError: Torch not compiled with CUDA enabled | PyTorch 版本装错了（装了 CPU 版），重装带 cuXXX 的版本。 |
| 文件损坏 | RuntimeError: PytorchStreamReader failed reading zip archive | 模型权重下载不完整。使用ls -lh检查大小，重新下载。 |
| 显存溢出 | CUDA out of memory | 减小batch_size；或者在推理时添加with torch.no_grad():。 |
| 路径错误 | FileNotFoundError/No such file or directory | 检查路径拼写；使用绝对路径；确认文件是否在 Windows 目录下未复制过来。 |
| 编译缺失 | ModuleNotFoundError: No module named '..._cpp' | 忘记执行pip install .编译 C++ 扩展；或编译环境缺少g++。 |
| 设备号错误 | RuntimeError: Device 1 not found | 指定了不存在的显卡编号（如--cuda 1）。笔记本通常只有 0 号卡。 |
🎉祝你天天开心，我将更新更多有意思的内容，欢迎关注！
最后更新：2025年11月
作者：Echo