InsightFace人脸检测开发实验指南

一、核心原理

1. InsightFace是什么？
   InsightFace是一个现成的“人脸处理AI工具”，不用自己训练，拿来就能用，核心做两件事：

• 找人脸：在图片里标出人脸的位置（画个方框）和五官关键点（眼睛、鼻子、嘴巴）；
• 认人脸：给每张脸生成唯一的“数字身份证”（特征码），对比身份证就能知道是不是同一个人（本次试验只用“找人脸”功能）。

2. buffalo_l模型是什么？
   是InsightFace官方打包好的“人脸检测工具箱”（后缀l代表“高精度版”），里面装好了找人脸、提特征的所有“经验”，我们直接调用就行，不用自己写复杂代码。

二、试验准备

1. 环境要求

• 电脑系统：Windows
• 已安装：Conda（虚拟环境）、PyCharm（代码编辑器）
• 测试图片：准备2张图片（1张有人脸、1张没人脸，比如自拍和风景照）

2. 项目文件结构（照着建）
   你的项目文件夹（比如D:\face_test）
   │
   ├─ app
   │ └─ services
   │ └─ test001
   │ ├─ face_detect.py # 核心检测代码
   │ ├─ config.py # 模型配置
   │ ├─ utils.py # 日志工具
   │ └─ tests
   │ ├─ test_face_detect.py # 测试代码
   │ └─ init.py
   └─ 测试图片文件夹（比如D:\face_test\images）
   ├─ has_face.jpg # 有人脸的图片
   └─ no_face.jpg # 没人脸的图片

三、具体操作步骤
步骤1：激活虚拟环境
打开Windows命令行（CMD），输入以下命令激活你的Conda环境（比如环境名是tf_env）：
conda activate tf_env

步骤2：安装依赖包
在命令行输入，安装试验需要的所有工具：
pip install insightface pillow numpy pytest -i https://pypi.tuna.tsinghua.edu.cn/simple
（国内镜像更快，不用等太久）

步骤3：下载并放置模型文件

1. 下载模型包：buffalo_l.zip
2. 解压到指定位置：

• 新建文件夹：C:\Users\你的用户名.insightface\models\buffalo_l\
• 把zip里的所有.onnx文件直接解压到这个文件夹（不要留zip文件）
  步骤4：编写核心代码

1. config.py（模型配置）

配置人脸检测模型名称

FACE_DETECT_MODEL = “buffalo_l”

2. utils.py（日志工具）
   import logging

def setup_logger():
“”“初始化日志，方便看运行过程”“”
logging.basicConfig(
level=logging.INFO,
format=“%(asctime)s - %(levelname)s - %(message)s”
)
return logging.getLogger(name)

3. face_detect.py（人脸检测核心）
   import insightface
   from typing import Tuple, List
   from app.services.test001.config import FACE_DETECT_MODEL
   from app.services.test001.utils import setup_logger

class FaceDetectionError(Exception):
“”“自定义异常：没检测到人脸时抛出”“”
pass

def detect_face(image_path: str) -> Tuple[List, List]:
“”"
检测图片中的人脸
Args:
image_path: 图片文件路径
Returns:
(bbox, keypoints)：bbox是人脸框坐标，keypoints是五官关键点
“”"
# 初始化日志
logger = setup_logger()
logger.info(f"开始检测人脸：{image_path}")

try:
    # 加载模型（用CPU运行）
    model = insightface.app.FaceAnalysis(model=FACE_DETECT_MODEL, providers=['CPUExecutionProvider'])
    model.prepare(ctx_id=0, det_size=(640, 640))
    
    # 读取图片
    from PIL import Image
    import numpy as np
    image = Image.open(image_path)
    img_array = np.array(image)
    
    # 检测人脸
    faces = model.get(img_array)
    
    # 没检测到人脸就报错
    if not faces:
        logger.error("未检测到人脸")
        raise FaceDetectionError("未检测到人脸")
    
    # 取第一张人脸的框和关键点
    face = faces[0]
    bbox = face.bbox.tolist()  # 人脸框：[x1,y1,x2,y2]
    keypoints = face.kps.tolist()  # 关键点：[左眼,右眼,鼻尖,左嘴角,右嘴角]
    
    logger.info(f"检测成功！人脸框：{bbox}，关键点：{keypoints}")
    return bbox, keypoints

except Exception as e:
    logger.error(f"检测失败：{str(e)}")
    raise FaceDetectionError(f"人脸检测失败：{str(e)}")

步骤5：编写测试代码（test_face_detect.py）
import pytest
import sys, os

让Python能找到app文件夹

sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(file), ‘…/…/…/…’)))

from app.services.test001.face_detect import detect_face, FaceDetectionError

替换成你自己的图片路径！！！

VALID_FACE_IMAGE = “D:\face_test\images\has_face.jpg” # 有人脸的图片
NO_FACE_IMAGE = “D:\face_test\images\no_face.jpg” # 没人脸的图片

def test_detect_face_valid():
“”“测试：有人脸的图片能正常检测”“”
bbox, keypoints = detect_face(VALID_FACE_IMAGE)
# 验证结果格式是否正确
assert isinstance(bbox, list) and len(bbox) == 4 # 人脸框必须是4个数字
assert isinstance(keypoints, list) and len(keypoints) == 5 # 五官关键点必须是5个
assert all(len§ == 2 for p in keypoints) # 每个关键点都是x、y坐标

def test_detect_face_no_face():
“”“测试：没人脸的图片会抛出异常”“”
with pytest.raises(FaceDetectionError):
detect_face(NO_FACE_IMAGE)

if name == “main”:
pytest.main([file, “-v”])

四、运行测试（两种方式任选）
方式1：命令行运行（新手推荐）

1. 打开命令行，进入项目根目录：
   cd D:\face_test
2. 设置Python路径：
   set PYTHONPATH=D:\face_test
3. 运行测试：
   pytest app/services/test001/tests/test_face_detect.py -v
   方式2：PyCharm面板运行
4. 打开PyCharm，导入项目文件夹D:\face_test；
5. 点击顶部「Run」→「Edit Configurations」；
6. 点击「+」号，选择「pytest」；
7. 配置参数：

• Working directory：选项目根目录D:\face_test；
• Python interpreter：选你的Conda环境tf_env；
• Target：选测试文件test_face_detect.py；

8. 点击「运行」按钮，等待测试结果。
   五、测试结果解读

• ✅ 绿色对勾/提示“2 passed”：试验成功！
  • test_detect_face_valid通过：有人脸的图片正确检测出人脸框和关键点；
  • test_detect_face_no_face通过：没人脸的图片正确报错。
• ❌ 红色叉号：
  • 若提示“FileNotFoundError”：检查图片路径是否写对；
  • 若提示“FaceDetectionError”但图片有人脸：检查图片是否清晰，或模型文件是否放对位置；
  • 若提示“找不到app模块”：检查Python路径是否设置正确。
    六、注意事项

9. 第一次运行会加载本地模型，不会重复下载，耐心等几秒；
10. 运行时出现“FutureWarning”不用管，不影响测试结果；
11. 图片路径要用双反斜杠（\），比如D:\face_test\images\has_face.jpg；
12. 模型文件必须放在C:\Users\你的用户名.insightface\models\buffalo_l\，不能放错。
    总结
13. InsightFace核心是“找人脸+生成人脸特征码”，本次试验只用了找人脸功能；
14. 核心步骤：装依赖→放模型→写代码→跑测试，跟着步骤做就能成功；
15. 测试通过的关键：图片路径正确、模型文件放对位置、Python路径配置好。