Retinaface+CurricularFace镜像免配置教程：Docker run后直接执行python脚本

三冬评论员

704人浏览 · 2026-04-09 03:48:07

三冬评论员 · 2026-04-09 03:48:07 发布

Retinaface+CurricularFace镜像免配置教程：Docker run后直接执行python脚本

你是不是也遇到过这种情况？想试试某个厉害的人脸识别模型，结果光是配环境、装依赖、下模型就折腾了大半天，最后还可能因为版本冲突跑不起来。那种感觉，就像拿到一台新手机，却要先自己组装主板一样麻烦。

今天要介绍的Retinaface+CurricularFace镜像，就是来解决这个问题的。它把整个复杂的人脸识别环境都打包好了，你只需要一条Docker命令启动，然后直接运行Python脚本就能看到效果。整个过程简单到像是用手机App——点击、运行、出结果。

这篇文章，我就带你从零开始，手把手体验这个“开箱即用”的人脸识别方案。你会发现，原来技术可以这么简单。

1. 环境准备：一条命令启动所有

传统部署人脸识别模型，你需要准备Python环境、安装PyTorch、配置CUDA、下载模型权重……每一步都可能踩坑。而这个镜像把这些步骤都省了。

1.1 镜像启动：简单到难以置信

假设你已经安装了Docker，那么启动这个镜像只需要一行命令：

docker run -it --gpus all -p 7860:7860 --name face_recognition registry.cn-hangzhou.aliyuncs.com/modelscope-repo/modelscope:ubuntu20.04-cuda12.1.0-py3.11.14-torch2.5.0

让我解释一下这行命令的每个部分：

docker run -it：以交互模式运行容器，这样你可以在里面执行命令
--gpus all：把宿主机的GPU资源都给容器用（如果你有GPU的话）
-p 7860:7860：把容器的7860端口映射到宿主机，方便后续可能用到的Web界面
--name face_recognition：给容器起个名字，方便管理
最后那一长串就是镜像地址，里面包含了所有需要的软件

执行完这条命令，你就进入了一个全新的、已经配置好所有环境的Linux系统。接下来的一切操作都在这个“沙箱”里进行，不会影响你电脑上原有的任何环境。

1.2 进入工作目录：找到正确的起点

容器启动后，你会看到一个命令行界面。第一步是进入预置的工作目录：

cd /root/Retinaface_CurricularFace

这个目录里已经放好了所有需要的文件：推理脚本、示例图片、模型文件等等。你可以用ls命令看看里面有什么：

ls -la

你会看到类似这样的文件结构：

inference_face.py：主推理脚本，我们马上要用它
imgs/：目录，里面有几张示例人脸图片
其他一些配置文件和模型文件

1.3 激活预置环境：一键切换

镜像里已经创建好了一个名为torch25的Conda环境，里面安装了所有必要的Python包。激活它：

conda activate torch25

激活后，命令行提示符前面会出现(torch25)的字样，表示你现在在这个环境里了。你可以检查一下关键包的版本：

python -c "import torch; print(f'PyTorch版本: {torch.__version__}')"
python -c "import modelscope; print(f'ModelScope版本: {modelscope.__version__}')"

如果一切正常，你会看到PyTorch 2.5.0和ModelScope 1.13.0的输出。这意味着环境已经完全就绪，不需要你再安装任何东西。

2. 快速上手：第一次人脸比对

环境准备好了，现在让我们跑个最简单的例子，看看这个模型能做什么。

2.1 运行默认示例：最简体验

在工作目录下，直接运行：

python inference_face.py

脚本会使用内置的两张示例图片进行人脸比对。你会看到终端开始输出信息：

正在加载模型...
检测到人脸...
提取特征...
计算相似度...

大概几秒钟后（第一次运行会慢一些，因为要下载模型），你会看到类似这样的结果：

图片1检测到1张人脸
图片2检测到1张人脸
相似度得分: 0.856
判定结果: 同一人

这意味着模型认为两张图片里的是同一个人，而且相似度得分高达0.856（满分是1.0）。这个分数已经相当高了，说明模型很有信心。

2.2 理解输出结果：分数背后的含义

你可能好奇这个“相似度得分”是什么意思。简单来说：

分数范围在-1到1之间
分数越接近1，说明两张脸越像
分数越接近-1，说明两张脸越不像
分数在0附近，说明没什么关系

模型内置的默认判断标准是：如果分数大于0.4，就认为是同一个人。这个阈值是经过大量测试得出的平衡点，既能保证准确率，又不会漏掉太多。

你可能会问：“为什么是0.4？不是0.5或者0.6？”这是因为人脸识别任务比较特殊——即使是同一个人，在不同光线、角度、表情下，特征也会有差异。0.4这个阈值在实践中被证明效果最好。

3. 使用自己的图片：真实场景测试

用示例图片跑通了，现在试试你自己的图片。这是最有意思的部分。

3.1 准备测试图片：注意事项

在测试之前，有几个小建议：

图片质量：尽量用清晰、正面的人脸照片
人脸大小：人脸在图片中不要太小，至少占图片面积的1/10
光线：避免过暗或过曝的照片
角度：正面照效果最好，侧脸也可以但分数可能低一些

你可以用手机拍两张自己的照片，或者从网上找两张明星的照片来测试。

3.2 上传图片到容器：两种方法

方法一：使用Docker的拷贝命令（从宿主机复制到容器）

# 在宿主机上执行（不是在容器里）
docker cp /path/to/your/photo1.jpg face_recognition:/root/Retinaface_CurricularFace/
docker cp /path/to/your/photo2.jpg face_recognition:/root/Retinaface_CurricularFace/

方法二：直接使用网络图片URL 如果你有图片的在线链接，可以直接用，不需要下载。比如：

python inference_face.py -i1 https://example.com/person1.jpg -i2 https://example.com/person2.jpg

3.3 运行自定义比对：看到实际效果

假设你已经把图片放到了容器的工作目录，现在可以运行：

python inference_face.py --input1 ./my_photo1.jpg --input2 ./my_photo2.jpg

或者用简写参数：

python inference_face.py -i1 ./my_photo1.jpg -i2 ./my_photo2.jpg

脚本会自动完成以下步骤：

读取两张图片
用RetinaFace检测每张图片中最大的人脸（是的，它会自动找脸，你不需要提前裁剪）
把人脸对齐到标准位置
用CurricularFace提取人脸特征
计算两个特征的相似度
输出结果

整个过程都是自动的，你只需要提供图片就行。

4. 调整参数：让模型更符合你的需求

默认设置适合大多数情况，但有时候你可能需要微调。脚本提供了几个参数让你控制比对过程。

4.1 调整判定阈值：控制严格程度

如果你觉得默认的0.4太宽松了（容易把不同人认成同一个人），可以提高阈值：

python inference_face.py -i1 ./img1.jpg -i2 ./img2.jpg --threshold 0.6

这样，只有当相似度大于0.6时，才会判定为“同一人”。适合对准确率要求极高的场景，比如门禁系统。

相反，如果你不想漏掉任何可能的匹配（宁可错认，不可漏认），可以降低阈值：

python inference_face.py -i1 ./img1.jpg -i2 ./img2.jpg --threshold 0.3

4.2 使用网络图片：直接链接测试

前面提到过，你可以直接用图片URL，这在测试网络图片时特别方便：

python inference_face.py -i1 https://img.example.com/face1.png -i2 https://img.example.com/face2.png

脚本会自动下载图片并进行比对。注意网络图片的加载时间会影响整体速度。

4.3 查看帮助信息：所有可用参数

如果你忘了参数怎么用，可以随时查看帮助：

python inference_face.py --help

这会显示所有可用参数及其说明，包括默认值。

5. 实际应用示例：几个实用场景

了解了基本用法后，我们来看看这个模型在实际中能做什么。

5.1 场景一：照片整理

假设你手机里有几千张照片，想找出所有包含某个人的照片。你可以写个简单的脚本：

import os
from PIL import Image
import subprocess

# 目标人物的照片
target_photo = "./target_person.jpg"

# 遍历照片文件夹
photo_folder = "./my_photos/"
for filename in os.listdir(photo_folder):
    if filename.lower().endswith(('.jpg', '.jpeg', '.png')):
        photo_path = os.path.join(photo_folder, filename)
        
        # 调用我们的脚本进行比对
        result = subprocess.run(
            ["python", "inference_face.py", "-i1", target_photo, "-i2", photo_path],
            capture_output=True,
            text=True
        )
        
        # 检查输出中是否包含"同一人"
        if "同一人" in result.stdout:
            print(f"找到匹配: {filename}")

这个脚本会遍历文件夹里的所有照片，把每张照片都和目标照片比对，找出相似度高的。

5.2 场景二：简单考勤系统

如果你有个小团队，想做个简单的面部打卡系统：

import datetime
import subprocess

def check_in(employee_photo, current_photo):
    """员工打卡验证"""
    # 运行人脸比对
    result = subprocess.run(
        ["python", "inference_face.py", "-i1", employee_photo, "-i2", current_photo, "-t", "0.5"],
        capture_output=True,
        text=True
    )
    
    if "同一人" in result.stdout:
        # 提取相似度分数
        for line in result.stdout.split('\n'):
            if "相似度得分:" in line:
                score = float(line.split(":")[1].strip())
                break
        
        # 记录打卡
        timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
        with open("attendance.log", "a") as f:
            f.write(f"{timestamp} - 员工验证通过，相似度: {score}\n")
        return True
    else:
        return False

# 使用示例
employee_photo = "./employees/john.jpg"  # 员工注册照
current_photo = "./checkin/photo.jpg"    # 当前打卡照片

if check_in(employee_photo, current_photo):
    print("打卡成功！")
else:
    print("验证失败，请重试。")

5.3 场景三：家庭相册智能搜索

给家里的老照片建立索引，方便搜索：

import json
import subprocess
from pathlib import Path

def build_face_index(photos_folder, index_file="face_index.json"):
    """建立人脸索引"""
    index = {}
    
    photos = list(Path(photos_folder).glob("*.jpg")) + \
             list(Path(photos_folder).glob("*.png")) + \
             list(Path(photos_folder).glob("*.jpeg"))
    
    for i, photo in enumerate(photos):
        print(f"处理第 {i+1}/{len(photos)} 张: {photo.name}")
        
        # 这里简化处理，实际应该提取特征向量存储
        # 我们只记录文件路径
        index[str(photo)] = {
            "path": str(photo),
            "processed": True
        }
    
    # 保存索引
    with open(index_file, "w") as f:
        json.dump(index, f, indent=2)
    
    return index

def search_similar_face(query_photo, index_file="face_index.json", threshold=0.4):
    """搜索相似人脸"""
    results = []
    
    with open(index_file, "r") as f:
        index = json.load(f)
    
    for photo_path, info in index.items():
        # 跳过未处理的照片
        if not info.get("processed", False):
            continue
        
        # 比对
        result = subprocess.run(
            ["python", "inference_face.py", "-i1", query_photo, "-i2", photo_path],
            capture_output=True,
            text=True
        )
        
        # 提取分数
        for line in result.stdout.split('\n'):
            if "相似度得分:" in line:
                score = float(line.split(":")[1].strip())
                if score > threshold:
                    results.append({
                        "photo": photo_path,
                        "score": score
                    })
                break
    
    # 按分数排序
    results.sort(key=lambda x: x["score"], reverse=True)
    return results

# 使用示例
# 先建立索引（只需要做一次）
# build_face_index("./family_photos/")

# 搜索包含某个人的所有照片
# similar = search_similar_face("./query_face.jpg")
# for item in similar[:10]:  # 显示前10个结果
#     print(f"相似度 {item['score']:.3f}: {item['photo']}")

6. 常见问题与技巧

在实际使用中，你可能会遇到一些问题。这里总结了一些常见情况和解决方法。

6.1 图片处理问题

问题： 图片里有多个人脸，模型只检测了其中一个。

原因： 脚本默认只处理每张图片中最大的人脸。这是设计如此，因为大多数应用场景（如身份验证）只需要关注最主要的人脸。

解决方案： 如果你需要检测多个人脸，可以修改脚本。不过对于简单的“两张图比对”任务，默认行为通常是最合适的。

问题： 侧脸或遮挡严重的人脸分数很低。

原因： 人脸识别模型在正面、清晰、无遮挡的照片上表现最好。侧脸、戴口罩、戴墨镜等都会影响特征提取。

建议：

尽量使用正面照
确保人脸部分清晰可见
如果必须处理侧脸，可以适当降低判定阈值

6.2 性能优化建议

GPU内存不足： 如果遇到CUDA内存错误，可以尝试：

减小同时处理的图片数量
降低图片分辨率（脚本内部会调整，但你可以先压缩原图）
如果没有GPU，脚本会自动使用CPU，只是速度会慢一些

速度慢： 第一次运行会比较慢，因为要下载模型文件（大约几百MB）。下载完成后，后续运行就快了。

GPU上：单次比对通常在1-3秒
CPU上：可能需要5-10秒

6.3 准确率提升技巧

图片预处理：在比对前，可以先用简单的图像处理：

from PIL import Image

def preprocess_image(image_path):
    """简单的图片预处理"""
    img = Image.open(image_path)
    
    # 调整大小（保持长宽比）
    max_size = 1024
    if max(img.size) > max_size:
        ratio = max_size / max(img.size)
        new_size = tuple(int(dim * ratio) for dim in img.size)
        img = img.resize(new_size, Image.Resampling.LANCZOS)
    
    # 转换为RGB（处理可能的RGBA或灰度图）
    if img.mode != 'RGB':
        img = img.convert('RGB')
    
    return img