README.md

---
license: unknown
tags:
- face-recognition
- cvlface
- adaface
- swin-transformer
- lora
- pytorch
pretty_name: Lab1 CVLFace Code
---

# Lab1 CVLFace Code

本仓库用于备份 Lab1 人脸识别实验中使用的 CVLFace 代码和训练脚本。

代码来自服务器实验目录：

```text
/root/Lab1/project/cvlface
```

上传时已经排除数据集、实验输出、缓存和大模型权重。模型权重请放在独立的 checkpoint 仓库中管理。

## 主要内容

```text
cvlface/
  research/
    recognition/
      code/
        run_v1/
          scripts/
            train_plan4_adaface_swin.py
            prepare_kaggle_verification_protocol.py
            generate_plan8_report.py
            configs/
              *.yaml
            test_*.py
```

其中 `train_plan4_adaface_swin.py` 是当前主要训练脚本。

## 当前训练脚本支持的功能

- Swin-S 224 backbone + AdaFace 分类头训练。
- 全量微调 backbone。
- 冻结 backbone 后只训练分类头。
- LoRA 微调：
  - `--use-lora`
  - `--lora-rank`
  - `--lora-alpha`
  - `--lora-dropout`
  - `--lora-target-modules`
- eval-only 验证模式：
  - `--eval-only`
  - `--eval-checkpoint`
  - `--eval-pairs-csv`
- YAML config：
  - `--config configs/xxx.yaml`
  - 命令行参数会覆盖 config 中的默认值。
- epoch 级日志：
  - `training_config.json`
  - `epoch_metrics.csv`
  - 每个 epoch 记录 loss。
  - 可按固定 epoch 间隔记录验证集 acc。

## 相关数据仓库

本代码仓库不包含数据集。当前项目中用到的数据备份在以下仓库：

- WebFace224 完整训练集：`lhx05/WebFace224`
- 多协议 224 验证集：`lhx05/lab1-resized-face-datasets`
- FGNET AGE-30 验证协议：`lhx05/fgnet-age30-protocol`
- AgeDB 224 身份分类数据集：`lhx05/agedb-224-by-identity`

## 相关权重仓库

模型权重和训练 checkpoint 放在：

```text
lhx05/lab1-face-recognition-checkpoints
```

本代码仓库不上传 `.pt`、`.pth`、`.safetensors` 等大权重文件。

## 示例命令

全量微调示例：

```bash
cd /root/Lab1/project/cvlface/research/recognition/code/run_v1/scripts
source /root/Lab1/venv/bin/activate

python train_plan4_adaface_swin.py \
  --train-root /root/Lab1/data/processed/agedb_harmonliu05_224_by_identity \
  --output-dir /root/Lab1/experiments/agedb567_full_finetune_20epoch \
  --ckpt /root/Lab1/project/cvlface/pretrained_models/model.safetensors \
  --epochs 20 \
  --batch-size 128 \
  --eval-every-epochs 5 \
  --eval-pairs-csv /root/Lab1/data/processed/fgnet_age30_protocol/facerec_val/fgnet_age30/pairs.csv
```

使用 YAML config 示例：

```bash
python train_plan4_adaface_swin.py \
  --config configs/agedb567_lora_r4_fgnet_age30.yaml
```

## 注意事项

- 代码中的绝对路径来自服务器实验环境，换机器使用时需要按本地目录调整。
- 上传版本主要用于备份和复现实验，不保证是原始 CVLFace 官方仓库的完整发布版本。
- 如果只需要运行当前实验，优先查看 `research/recognition/code/run_v1/scripts/` 目录。