菜鸟研0 | 深度学习论文复现全流程指南

目标：以 PicT 论文复现项目（仓库：https://github.com/DearCaat/PicT ）为例，带领初学者从零开始，在实验室服务器上完成一次完整的深度学习论文复现，并沉淀流程化、可复用的实践经验。

适用人群：刚接触实验室服务器、深度学习项目复现的本科生。

---

目录

1. 准备工作总览
2. Step1：使用 VSCode 远程连接实验室服务器
3. Step2：上传论文代码到服务器
4. Step3：在服务器创建虚拟环境
5. Step4：安装依赖并匹配 GPU 环境
6. Step5：运行 PicT 代码训练模型
7. 附录：常见目录结构与常用命令合集
8. 参考资料

---

准备工作总览

阶段	核心任务	说明
Step1	VSCode 远程连接服务器	获取实验室服务器账号、密码，配置 SSH 连接
Step2	上传项目/数据	从 GitHub 下载代码 → 上传到服务器（FileZilla / WinSCP）
Step3	创建 Python 虚拟环境	conda 或 python -m venv，隔离不同项目环境
Step4	安装依赖 + 匹配 CUDA	根据服务器 GPU 型号安装对应版本的 PyTorch、CUDA 等
Step5	运行训练脚本	理解命令含义、监控日志、找到输出模型权重

Tips：建议全程记录指令和日志，便于复现和问题排查。

---

Step1：使用 VSCode 远程连接实验室服务器

1. 向老师/管理员申请服务器账号
   • 获取内容：IP 地址、用户名、密码 / 私钥。
2. 安装 VSCode（本地）
   • 官网下载：https://code.visualstudio.com/Download
   • 安装 Remote Development 插件合集，至少包括：Remote - SSH。
3. 配置 VSCode 远程连接
   • 快捷键 Ctrl + Shift + P → 输入 Remote-SSH: Connect to Host → Add New SSH Host。
   • 录入命令： ssh 用户名@服务器IP，选择本地 ~/.ssh/config 保存配置。
   • 连接时输入密码或选择对应私钥。参考图示。
4. 连接成功
   • VSCode 左下角显示远程主机名称；
   • 可以在 Explorer 中浏览远程服务器文件。

---

Step2：上传论文代码到服务器

1. 从 GitHub 下载论文代码到本地

   git clone https://github.com/DearCaat/PicT.git

2. 选择文件传输工具（任选其一）
   • FileZilla 图形界面
     1. 主机填 服务器IP，用户名/密码与 SSH 相同；
     2. 左侧窗口拖入本地代码文件夹，右侧窗口选择远程目标目录。
   • WinSCP 图形界面
     1. 新建 SFTP 会话，输入 IP、端口（默认22）、用户名、密码；
     2. 连接后拖动文件/文件夹上传。
3. 服务器端检查，项目已就绪
   • 例：上传到 /home/用户名/PicT/。

提示：数据集较大（例如 CQU-BPDD ~ 57GB），建议先上传到服务器 /data/ 分区。

---

Step3：在服务器创建虚拟环境

目的：隔离不同项目依赖，避免冲突。

方式 A：使用 Conda（推荐）

1. 检查是否安装 conda：conda -V。
2. 创建新环境：

   conda create -n pict python=3.10 -y
   conda activate pict

3. 查看当前环境：conda info --envs。

方式 B：使用 venv

python3 -m venv ~/envs/pict
source ~/envs/pict/bin/activate

若服务器未安装 Python，可向管理员申请或使用 Anaconda 静态版安装。参考教程。

---

Step4：安装依赖并匹配 GPU 环境

1. 检查硬件/驱动信息

# 查看 GPU 信息
nvidia-smi

# 查看 CUDA 驱动版本
cat /usr/local/cuda/version.txt  # 若存在

# 查看操作系统、CPU 等
echo "OS:" && cat /etc/os-release | grep PRETTY_NAME
echo "CPU:" && lscpu | grep "Model name"

注意：PyTorch + CUDA 必须兼容服务器的 NVIDIA 驱动版本。具体兼容矩阵可参考 PyTorch 官网。

2. 安装 pip 与常规依赖

python -m ensurepip --upgrade
python -m pip install --upgrade pip setuptools wheel

3. 安装 PyTorch & CUDA

• 示例命令（请根据 nvidia-smi 输出选择适当版本）：

  # 以 CUDA 11.8 + PyTorch 2.0 为例
  pip install torch==2.0.1+cu118 torchvision==0.15.2+cu118 torchaudio==2.0.2 --extra-index-url https://download.pytorch.org/whl/cu118

• CPU-only（若服务器无 GPU）：

  pip install torch==2.0.1 torchvision==0.15.2 torchaudio==2.0.2

4. 安装项目所需依赖

• 进入项目目录：cd /home/用户名/PicT/
• 查看并安装依赖文件 requirements.txt / environment.yaml

  pip install -r requirements.txt

• 若缺乏 requirements 文件，可根据 README 手动添加：

  pip install timm==0.6.12 scikit-learn==1.2.2 opencv-python==4.8.0 tqdm pandas matplotlib tensorboard

建议：记录所有安装指令，以便环境迁移和问题排查。

---

Step5：运行 PicT 代码训练模型

1. 了解项目目录结构（以当前仓库为例）

Pavement-Distress-Classification/
├── code/                    # 主要代码目录
│   ├── configs/             # 配置文件（模型、训练参数）
│   ├── dataloader/          # 数据加载与预处理脚本
│   ├── engine/              # 训练/验证核心逻辑
│   ├── models/              # 模型结构定义（PicT、WSPLIN 等）
│   └── main.py             # 入口脚本
├── data/                    # 数据集（CQU-BPDD 等）
├── output/                  # 训练日志、模型权重、结果输出
├── temp_weights/            # 手动下载的预训练权重缓存
├── setup_pretrained_weights.sh
└── README.md

常见目录约定：

• data/：原始数据、划分后的训练/验证集；
• code/：源代码、配置文件；
• output/：日志、模型权重、预测结果；
• scripts/：shell 脚本、自动化工具（若有）。

2. 准备数据 & 预训练权重

1. 数据集（CQU-BPDD）

   • 官方地址：https://github.com/DearCaat/CQU-BPDD
   • 解压后目录结构示例：

     CQU-BPDD/
     ├── train/
     │   ├── normal/
     │   ├── crack/
     │   └── ...（共 8 个类别）
     ├── val/
     └── test/
     

   • 放置位置：/home/用户名/Pavement-Distress-Classification/data/CQU-BPDD/

2. 预训练权重（Swin-Small）

   • Hugging Face 模型仓库：https://huggingface.co/timm/swin_small_patch4_window7_224.ms_in22k_ft_in1k
   • 已编写脚本 setup_pretrained_weights.sh，会把下载好的 pytorch_model.bin、config.json 放到 HF_HOME 缓存目录。

3. 运行训练命令

cd /home/limeijia/Pavement-Distress-Classification
export HF_HOME=$HOME/hf_cache
export HF_HUB_OFFLINE=1
python3 code/main.py \
  --data-path=/home/limeijia/Pavement-Distress-Classification/data/CQU-BPDD \
  --output=/home/limeijia/Pavement-Distress-Classification/output \
  --project=pict \
  --cfg code/configs/baseline/swin_small_1rec.yaml code/configs/pict_1rec.yaml \
  --title=pict

命令讲解：

• cd ...：切换到项目根目录；
• export HF_HOME：指定 Hugging Face 缓存目录；
• export HF_HUB_OFFLINE=1：启用离线模式（避免联网失败）；
• python3 code/main.py：启动训练入口脚本；
• --data-path：指定数据集路径；
• --output：训练输出目录（日志、模型权重、配置备份）；
• --project：项目名，影响 output 下的子目录；
• --cfg：依次加载多个配置文件，后者会覆盖前者；
• --title：实验名称，用于日志命名。

若需要缩短测试时间，可使用快速配置（每类子集 + 3 个 epoch）：

python3 code/main.py \
  --data-path=/home/limeijia/Pavement-Distress-Classification/data/CQU-BPDD-quick \
  --output=/home/limeijia/Pavement-Distress-Classification/output \
  --project=pict-quick \
  --cfg code/configs/baseline/swin_small_1rec_quick.yaml code/configs/pict_1rec_quick.yaml \
  --title=pict-quick

4. 监控日志 & 查看模型权重

• 实时查看日志（训练中）：

  tail -f output/pict/log/log_rank0.txt

• 训练完成后查看最好模型：

  output/pict/model/pict_pict-quick_main_btml.pth
  output/pict/model/pict_main_hbtml.pth
  

• 日志中可看到训练/验证的 loss、macro_f1、acc1 等指标。

5. 常见问题

• 训练中断，日志无输出？→ 检查 nohup、tmux 或 screen 使用是否正确。
• CUDA 不可用错误？→ 检查 nvidia-smi，确认是否在 GPU 环境下运行；若无 GPU，需配置 CPU-only 版本 PyTorch，并在配置和代码中显式使用 CPU。
• 权重加载失败？→ 检查 Hugging Face 缓存目录，确认 pytorch_model.bin、config.json 是否存在。

---

附录：常见目录结构与常用命令合集

目录结构记忆表

目录	常放内容	提示
data/	原始数据、数据集划分	大文件建议放数据盘
code/configs/	YAML 配置文件	模型参数、训练策略集中管理
code/models/	模型结构定义	可继承/扩展新的 backbone
code/engine/	训练、验证循环	统一处理 metrics、优化器
output/	日志、模型权重、结果	每次训练都会生成新的子目录
scripts/	批处理运行脚本	自行整理，便于复用

常用命令速查

# GPU 信息
nvidia-smi

# 查看显存占用
watch -n 1 nvidia-smi

# 查看 CPU/GPU 温度、利用率（需管理员安装）
nvtop

# 激活虚拟环境
conda activate pict

# 查看当前 Python 环境路径
which python

# pip 安装某个工具
pip install tqdm pandas

# 监控日志
tail -f output/pict/log/log_rank0.txt

# 后台运行训练
nohup python3 code/main.py ... > train.log 2>&1 &

---

参考资料

1. VSCode 连接远程服务器（知乎）
2. PicT 官方仓库
3. CQU-BPDD 数据集说明
4. 在服务器上创建虚拟环境（CSDN）
5. 查看 GPU 型号与 CUDA 版本命令合集
6. PyTorch 官网安装指南
7. Hugging Face timm/swin_small_patch4_window7_224.ms_in22k_ft_in1k

---

📌 结语：复现论文不仅是跑通代码，更是理解整个科研流程的绝佳练习。希望本文档能帮助你快速入门，也欢迎把笔记分享到 GitHub，与更多学弟学妹一起进步！