Ubuntu20.04下Retinaface+CurricularFace开发环境一键配置

Ubuntu20.04下Retinaface+CurricularFace开发环境一键配置

每次想跑个人脸识别的项目，光是配环境就能劝退一大半人。CUDA版本不对、依赖包冲突、编译报错...这些问题我踩过的坑，可能比你写过的代码都多。特别是Retinaface和CurricularFace这种组合，一个负责检测，一个负责识别，听起来很美好，但环境搭建起来简直是“地狱难度”。

今天，我就把自己折腾了无数次的配置经验，打包成一个自动化脚本。你只需要在Ubuntu20.04系统上运行它，大概10分钟左右，就能得到一个完整可用的开发环境。脚本会帮你搞定CUDA、PyTorch、各种依赖，甚至包括一些常见的编译错误。咱们的目标是：让环境搭建这件事，变得像双击一个图标那么简单。

1. 准备工作：检查你的“地基”

在开始“一键配置”之前，咱们得先确保地基是稳的。这个脚本是为Ubuntu 20.04 LTS设计的，其他版本的系统可能会遇到一些意想不到的问题。

1.1 系统与硬件确认

首先，打开你的终端，输入以下命令看看系统版本：

lsb_release -a

你应该能看到类似Ubuntu 20.04.x LTS的输出。如果不是，建议你先升级或重装系统，避免后续出现兼容性问题。

接下来，检查一下你的显卡。Retinaface和CurricularFace在CPU上也能跑，但速度会慢很多。为了获得最佳体验，我们需要一块NVIDIA显卡。运行：

nvidia-smi

如果这条命令报错或者没显示显卡信息，那可能是你的显卡驱动还没装好。别担心，我们的脚本会尝试帮你安装合适的驱动。如果命令成功执行，你会看到显卡型号和CUDA版本信息，记下这个CUDA版本（比如11.4），后面可能会用到。

1.2 获取我们的自动化脚本

脚本我已经放在了一个公开的Gist上。你只需要用wget命令把它下载到你的电脑里。

cd ~ wget https://gist.githubusercontent.com/your_username/your_script_id/raw/retinaface_curricularface_setup.sh

下载完成后，别忘了给它加上可执行的权限：

chmod +x retinaface_curricularface_setup.sh

现在，你的主目录下应该有一个名为retinaface_curricularface_setup.sh的脚本文件，这就是我们今天的“主角”。

2. 一键配置：让脚本替你干活

准备工作做完，就可以进入正题了。这个脚本我设计成了交互式的，它会问你几个问题，然后根据你的回答自动执行所有步骤。

2.1 运行脚本并选择配置

在终端里直接运行它：

./retinaface_curricularface_setup.sh

脚本启动后，你首先会看到一个欢迎信息，然后它会问你第一个也是最重要的问题：是否安装NVIDIA显卡驱动？

如果你之前运行nvidia-smi已经成功了，这里可以选n（不安装）。如果失败了，或者你想更新到更新的驱动，那就选y。脚本会为你添加官方的显卡驱动PPA，并安装一个比较稳定的版本。

接下来，脚本会询问你希望安装的CUDA版本。它会自动检测你系统可能已经存在的版本，并给出推荐（通常是11.3或11.4，这两个版本与Ubuntu 20.04和PyTorch的兼容性最好）。我建议你直接按回车，使用脚本的推荐版本。

然后是关于PyTorch的安装。脚本会默认安装与所选CUDA版本匹配的PyTorch 1.12.1。这个版本经过测试，与我们要用的Retinaface和CurricularFace代码兼容性很好。除非你有特殊需求，否则也直接按回车确认就好。

2.2 脚本在背后做了什么？

在你喝着咖啡等待的时候，脚本正在忙这些事：

1. 更新系统包列表：确保能下载到最新的软件包。
2. 安装基础编译工具：比如gcc,g++,make,cmake，没有它们很多Python包是编译不了的。
3. 安装Python环境：脚本会安装Python 3.8和pip，并为你创建一个独立的Python虚拟环境（venv），名叫retinaface_env。这样做的好处是，所有依赖都装在这个“小房子”里，不会把你系统的Python环境搞乱。
4. 处理CUDA和PyTorch：根据你的选择，从NVIDIA官方仓库安装CUDA Toolkit和cuDNN。然后，在虚拟环境里安装指定版本的PyTorch和TorchVision。
5. 安装核心的Python依赖：这包括opencv-python（处理图像）、scipy、numpy这些科学计算库。
6. 解决特定的编译难题：这里有个“坑”需要重点说一下。Retinaface依赖的mxnet库在安装时，可能会因为numpy版本太新而编译失败。我们的脚本已经预见到了这个问题，它会先安装一个稍旧但兼容的numpy版本（1.23.5），然后再安装mxnet-cuXXX（XXX对应你的CUDA版本）。最后，再帮你把numpy升级回较新的版本。这个顺序非常关键，能帮你省去几个小时查错的时间。
7. 安装Retinaface和CurricularFace：脚本会直接从GitHub上克隆最常用的Retinaface实现（通常来自bubbliiiing或deepinsights的仓库）和CurricularFace的PyTorch实现，并运行setup.py或pip install -e .命令将它们安装到当前环境中。
8. 下载预训练模型：脚本会尝试自动下载Retinaface和CurricularFace的预训练模型文件，放到~/.insightface/models/目录下。如果网络慢，这一步可能会耗时较长，脚本也会给出手动下载的链接。

整个过程，你会在终端上看到大量的日志在滚动。只要没有出现红色的ERROR字样，并且最终脚本提示“环境配置完成！”，那就说明一切顺利。

3. 验证环境：跑个例子试试看

脚本跑完了，咱们得验收一下成果。激活脚本为我们创建的虚拟环境：

source ~/retinaface_env/bin/activate

你的命令行提示符前面应该会出现(retinaface_env)的字样，这说明你已经在这个独立环境里了。

3.1 快速验证脚本

我还在脚本里附带了一个极简的验证程序。运行它，可以一次性测试几个关键功能：

python ~/test_retinaface_curricularface.py

这个测试脚本会做三件事：

1. 检查CUDA和PyTorch是否可用，并打印出版本信息。
2. 尝试加载Retinaface检测模型，并对一张内置的示例图片进行人脸检测和关键点定位。
3. 尝试加载CurricularFace识别模型，并计算一个示例人脸的特征向量。

如果一切正常，你会看到类似下面的输出，其中包含了检测到的人脸框坐标和计算出的512维特征向量的一部分：

[INFO] CUDA is available! PyTorch version: 1.12.1+cu113 [INFO] RetinaFace model loaded successfully. [INFO] Detected 1 face(s). [INFO] CurricularFace model loaded successfully. [INFO] Face feature vector shape: (512,)

3.2 常见问题与手动检查

如果验证脚本报错了，别慌。我们可以一步步手动检查。

问题一：PyTorch无法使用GPU在Python交互环境里（还是要在retinaface_env下），输入：

import torch print(torch.__version__) print(torch.cuda.is_available())

如果第二行打印False，说明PyTorch没有用GPU版本，或者CUDA安装有问题。可以检查一下PyTorch版本是否包含+cuXXX的后缀。

问题二：mxnet导入错误如果错误提到mxnet，很可能是之前说的numpy兼容性问题。可以尝试在虚拟环境中手动修复：

pip install numpy==1.23.5 --force-reinstall pip install mxnet-cu113==1.9.1 --force-reinstall # 请将cu113替换为你的CUDA版本

问题三：模型下载失败脚本可能因为网络问题没下载到模型。你可以根据脚本最后输出的提示，手动去ModelScope或GitHub Release页面下载retinaface_r50_v1和curricularface的模型文件，然后放到~/.insightface/models/目录下对应的文件夹里。

4. 开始你的第一个项目

环境妥了，我们来点实际的。这里给你一个最简单的代码示例，实现一个“人脸检测+特征提取”的管道。

import cv2 import torch from retinaface import RetinaFace # 假设安装的包提供了这个接口 from curricularface import CurricularFace # 假设安装的包提供了这个接口 # 1. 初始化模型 device = 'cuda' if torch.cuda.is_available() else 'cpu' print(f"Using device: {device}") detector = RetinaFace(prefix='~/.insightface/models/retinaface_r50_v1/retinaface', epoch=0, ctx_id=0 if device=='cuda' else -1) recognizer = CurricularFace(model_path='~/.insightface/models/curricularface/backbone.pth').to(device) recognizer.eval() # 2. 读取图片 img_path = "your_photo.jpg" img = cv2.imread(img_path) img_rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB) # 3. 人脸检测和对齐 faces = detector.detect(img_rgb) if faces is not None: # 这里通常需要根据检测到的关键点（5点或106点）进行人脸对齐 # 对齐后的脸应该是112x112大小 aligned_face = align_face(img_rgb, faces[0]['kps']) # align_face需要你自己实现或使用库函数 aligned_face_tensor = torch.from_numpy(aligned_face).permute(2,0,1).unsqueeze(0).float().to(device) # 4. 特征提取 with torch.no_grad(): feature = recognizer(aligned_face_tensor) print(f"Extracted feature shape: {feature.shape}") else: print("No face detected.")

这段代码勾勒出了核心流程。真正的项目里，你还需要完善人脸对齐的代码、处理批量图片、以及构建一个基于特征比对的人脸识别系统。但有了这个可用的环境，剩下的就是快乐的编码时间了。

5. 总结与后续建议

走完这一趟，你应该已经成功在Ubuntu 20.04上把Retinaface和CurricularFace的环境搭起来了。这个脚本解决的核心痛点，就是把那些繁琐、易错的步骤给自动化、标准化了，尤其是处理了CUDA版本和mxnet编译依赖这些老大难问题。

实际使用中，如果你需要更换不同的Retinaface实现（比如用官方InsightFace里的版本），或者尝试其他的人脸识别模型（比如ArcFace、CosFace），只需要在我们的虚拟环境里，用pip安装新的包即可，它们的基础依赖（PyTorch, CUDA）已经齐备了。

最后提醒一点，深度学习环境有时像一门“玄学”，同样的步骤在不同机器上可能结果略有差异。如果遇到脚本没覆盖的奇怪错误，别犹豫，把错误信息复制下来去搜索引擎找找，大概率已经有前辈踩过同样的坑了。祝你开发顺利！

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。