RetinaFace+CurricularFace 人脸识别推理脚本调试与避坑指南
你是不是也遇到过这样的情况：镜像拉下来了，环境看着都对，可一跑推理脚本就报错？要么是模块找不到，要么是 CUDA 版本不匹配，再或者相似度结果忽高忽低、完全没法判断准不准……别急，这篇教程就是为你写的。我们不讲大道理，不堆参数表，只聚焦一个目标：让你在 Python 3.11.14 环境下，把 RetinaFace+CurricularFace 这套人脸检测 + 识别流程，稳稳当当地跑通、调顺、用明白。全程基于预设镜像环境实测，所有命令、路径、报错和解法，都是从真实终端里一行行敲出来的。
1. 先搞懂这个镜像是什么，别急着跑代码
很多人一上来就 cd、python、conda activate，结果卡在第一步——连自己用的是什么都不知道。咱们先把底子理清楚。
这个镜像不是简单拼凑的'RetinaFace + CurricularFace'，而是一套经过工程验证的端到端人脸识别流水线：
- RetinaFace 负责'找脸'——它能在各种角度、光照、遮挡下，精准定位图像中所有人脸，并自动选出最大、最完整的一张作为后续处理对象；
- CurricularFace 负责'认人'——它把这张脸对齐、归一化后，提取出高区分度的 128 维特征向量，再通过余弦相似度比对两张脸是否属于同一人。
关键在于，这两部分不是独立运行的，而是深度耦合的：RetinaFace 的检测框直接喂给 CurricularFace 做对齐，中间没有手动裁剪、缩放、格式转换这些容易出错的环节。你传进去的是原图，输出的是一个干净的分数。
镜像里已经帮你配好了所有依赖，不用你一个个 pip install 或编译 CUDA 扩展。但正因如此，环境细节反而成了最容易踩坑的地方——比如 Python 3.11.14 对某些旧版库的兼容性、PyTorch 2.5.0+cu121 对显卡驱动的要求、甚至 Conda 环境激活后 PATH 变量的细微变化，都可能让脚本在最后一行崩溃。
所以，别跳过环境说明。下面这张表，不是摆设，是你排查问题的第一张地图：
| 组件 | 版本 | 关键说明 |
|---|---|---|
| Python | 3.11.14 | 注意：此版本不兼容部分用 Cython 写的旧包（如某些老版本 Pillow），镜像已预装适配版 |
| PyTorch | 2.5.0+cu121 | 必须搭配 CUDA 12.1 驱动，若 nvidia-smi 显示驱动版本低于 535，需升级驱动 |
| CUDA / cuDNN | 12.1 / 8.9 | 镜像内已静态链接，无需额外安装，但 nvcc --version 应显示 12.1 |
| ModelScope | 1.13.0 | 用于自动下载模型权重，首次运行会联网拉取，确保网络通畅 |
| 代码位置 | /root/Retinaface_CurricularFace | 所有脚本、模型、示例图都在这里，别 cd 错目录 |
记住一点：这个镜像的设计哲学是'开箱即用，但拒绝黑盒'。它省去了你搭环境的麻烦，却把调试的关键线索都留在了路径、版本和日志里。接下来每一步，我们都会告诉你'为什么是这个命令'，而不是只给你一行代码。
2. 从零开始跑通第一轮推理：避开最经典的三个坑
现在，打开你的终端，让我们真正动手。别复制粘贴完就走，每一步后面，我都标出了常见报错、原因和当场解决办法。
