简介这是一份面向开发者与计算机视觉学习者的离线人脸识别与头像对比源代码资源无需联网即可在本地完成人脸检测、特征提取与相似度匹配适合研究生物识别原理或搭建私有化比对工具。压缩包共687个文件约88.34MB以621个dll运行库、20个cs源码、13个h头文件为主另含xaml界面文件、exe可执行程序及csproj、sln工程文件构成一套可编译运行的完整项目。核心模块覆盖图像预处理、人脸检测、特征提取与特征匹配等环节FaceDistinguish工程可直接编译调试便于读者理解从灰度化、归一化到特征向量比对的完整链路并在此基础上修改优化。目前已有818人学习下载适合具备一定C#与图像处理基础、希望深入掌握离线人脸识别实现细节的开发者参考。1. 离线人脸识别源码包断网环境下的头像比对到底靠不靠谱上个月帮某公司做门禁考勤的离线改造现场是内网环境连不了云服务客户又不想把员工照片传到第三方接口。翻了一圈开源方案最后锁定一套完全离线的人脸识别与头像对比源代码包。它把检测、对齐、特征提取、相似度比对整条链路都封装在本地不依赖任何在线 API模型文件随包附带跑起来就是纯本地推理。适合做考勤机、访客系统、相册聚类、身份核验这类对数据隐私敏感的场景。我拿到手第一件事不是跑 demo而是先确认它到底用了哪套人脸检测和特征模型因为这直接决定了后续阈值怎么调、误识率能不能压住。下面把我拆包、跑通、调参、踩坑的全过程摊开讲新手能照着复现熟手能直接看边界参数。2. 拆开源码包检测、对齐、特征提取三段链路怎么串2.1 目录结构与核心模块定位拿到源码包先别急着装依赖花五分钟把目录扫一遍能省掉后面一半的排错时间。常见的人脸识别离线包一般会分成四个部分模型文件目录、推理封装层、业务逻辑层、示例脚本。我手上这套的结构大致是这样face_offline/ ├── models/ # 离线模型权重随包附带 │ ├── det_face.onnx # 人脸检测模型 │ ├── landmark.onnx # 五点/关键点对齐模型 │ └── rec_face.onnx # 特征提取模型输出 512 维向量 ├── core/ │ ├── detector.py # 检测封装输入 BGR 图输出人脸框 │ ├── aligner.py # 对齐封装按关键点做仿射变换 │ ├── extractor.py # 特征提取输出归一化向量 │ └── matcher.py # 余弦相似度比对与阈值判定 ├── utils/ │ ├── image_io.py # 读写图片处理中文路径 │ └── visualize.py # 画框、画关键点调试用 ├── examples/ │ ├── compare_two.py # 两张头像比对示例 │ └── build_gallery.py # 批量建底库示例 └── requirements.txt这里最关键的是models/下三个 onnx 文件。检测模型负责从整张图里框出人脸对齐模型负责把人脸摆正特征模型负责把摆正后的人脸压成一个向量。三者缺一不可少任何一个都会导致比对结果飘。我见过有人图省事跳过对齐直接送特征模型结果侧脸和正脸的相似度直接掉到 0.3 以下这就是典型的链路缺失。2.2 检测与对齐为什么不能跳过这一步人脸检测的输出是一个矩形框但矩形框里包含的背景、角度、尺度都不一致。如果直接把裁剪出来的人脸送进特征模型同一个人不同角度拍的两张照片特征向量可能差得很远。对齐的作用就是根据关键点通常左右眼、鼻尖、左右嘴角五个点做仿射变换把眼睛拉到水平、人脸缩放到固定尺寸。import cv2 import numpy as np def align_face(img, landmarks, output_size(112, 112)): img: 原始 BGR 图像 landmarks: 5x2 的关键点坐标顺序为左眼、右眼、鼻尖、左嘴角、右嘴角 output_size: 对齐后输出尺寸常见 112x112 或 160x160 # 标准人脸五点位置基于 112x112 的参考系 ref np.array([ [38.2946, 51.6963], # 左眼 [73.5318, 51.5014], # 右眼 [56.0252, 71.7366], # 鼻尖 [41.5493, 92.3655], # 左嘴角 [70.7299, 92.2041] # 右嘴角 ], dtypenp.float32) # 根据输出尺寸缩放参考点 scale output_size[0] / 112.0 ref ref * scale # 计算相似变换矩阵并做仿射变换 tform, _ cv2.estimateAffinePartial2D(landmarks.astype(np.float32), ref) aligned cv2.warpAffine(img, tform, output_size, borderValue0.0) return aligned这段代码的逻辑是先定义一组标准人脸关键点位置再用estimateAffinePartial2D求出从实际关键点到标准点的变换矩阵最后把原图 warp 到目标尺寸。参数上output_size必须和特征模型训练时的输入尺寸一致常见是 112x112如果模型是 160x160 的就要改改错了特征会整体偏移。borderValue0.0表示填充黑色有些实现用均值填充差别不大但最好和训练时保持一致。提示关键点顺序一定要和参考点顺序严格对应左眼对左眼、右眼对右眼。顺序错了不会报错但比对分数会莫名其妙地低这种玄学问题排查起来很费时间。2.3 特征提取与相似度比对阈值到底怎么定特征提取模型输出的是一个 512 维浮点向量通常已经做过 L2 归一化。比对时用余弦相似度值域在 -1 到 1 之间越接近 1 越像。判定是否为同一人靠的是一个阈值。import numpy as np def cosine_similarity(feat1, feat2): 两个已归一化的特征向量点积即为余弦相似度 return float(np.dot(feat1, feat2)) def is_same_person(feat1, feat2, threshold0.45): threshold: 判定阈值常见范围 0.35 ~ 0.55 阈值越高越严格误识率降低但拒识率升高 sim cosine_similarity(feat1, feat2) return sim threshold, sim阈值这个东西没有万能值。我一般会先用一批已知同人和不同人的照片跑一遍画出相似度分布然后取两条分布曲线的交叉点附近作为初始阈值。如果业务上更不能容忍误识比如门禁放行阈值往 0.5 以上调如果更不能容忍拒识比如相册聚类阈值可以降到 0.35 左右。源码包里matcher.py通常会留一个DEFAULT_THRESHOLD常量改这里就行但改完一定要用真实数据回归一遍。3. 从零跑通比对环境、底库、批量脚本三步落地3.1 环境搭建与依赖安装离线包最大的好处就是依赖可控但前提是你得把 onnxruntime 和 opencv 这两个核心库装对版本。我一般用 conda 建一个干净环境避免和系统里的其他包打架。conda create -n face_offline python3.9 -y conda activate face_offline # onnxruntime 分 CPU 和 GPU 两个版本离线场景多数用 CPU pip install onnxruntime1.16.0 pip install opencv-python4.8.1.78 pip install numpy1.24.3 pip install pillow10.0.1 # 验证 onnxruntime 能否正常加载模型 python -c import onnxruntime as ort; print(ort.get_available_providers())这里版本号不是随便写的。onnxruntime 1.16 对 onnx opset 的支持比较稳opencv 4.8 的estimateAffinePartial2D行为没有变动。如果装成 opencv 4.10 以上某些老代码里的cv2.findContours返回值数量会变导致检测后处理报错。get_available_providers()输出里如果有CPUExecutionProvider就说明 CPU 推理可用有CUDAExecutionProvider则说明 GPU 也可用。离线机器一般只有 CPU推理一张 112x112 的人脸大概 20 到 50 毫秒批量建库时要有心理预期。3.2 建底库批量提取特征并持久化头像比对不是每次拿两张图现算实际业务里通常是先建一个底库把已知人员的特征向量存下来比对时只算待查图片的特征然后和底库里的向量逐一比对。建库脚本要处理几个细节跳过检测不到人脸的图、过滤掉太小的人脸、保存时带上人员 ID。import os import pickle import cv2 import numpy as np from core.detector import detect_faces from core.aligner import align_face from core.extractor import extract_feature def build_gallery(image_dir, output_path, min_face_size60): image_dir: 底库图片目录文件名建议为 人员ID.jpg output_path: 特征库保存路径pkl 格式 min_face_size: 最小人脸边长小于此值跳过 gallery {} skipped [] for fname in os.listdir(image_dir): if not fname.lower().endswith((.jpg, .jpeg, .png)): continue person_id os.path.splitext(fname)[0] img_path os.path.join(image_dir, fname) img cv2.imdecode(np.fromfile(img_path, dtypenp.uint8), cv2.IMREAD_COLOR) if img is None: skipped.append((fname, read_failed)) continue faces detect_faces(img) if len(faces) 0: skipped.append((fname, no_face)) continue # 取面积最大的那张脸 face max(faces, keylambda f: (f[bbox][2]-f[bbox][0]) * (f[bbox][3]-f[bbox][1])) w face[bbox][2] - face[bbox][0] h face[bbox][3] - face[bbox][1] if min(w, h) min_face_size: skipped.append((fname, face_too_small)) continue aligned align_face(img, face[landmarks]) feat extract_feature(aligned) gallery[person_id] feat with open(output_path, wb) as f: pickle.dump(gallery, f) print(f底库人数: {len(gallery)}, 跳过: {len(skipped)}) for s in skipped: print( 跳过:, s) return gallery这段脚本的关键点有三个。第一用cv2.imdecode加np.fromfile读图而不是cv2.imread因为imread在 Windows 下遇到中文路径会返回 None这是血泪经验。第二一张图里可能有多张脸取面积最大的那张作为该人员的主脸避免合影干扰。第三min_face_size设 60 像素太小的脸特征质量差放进底库反而拉低整体准确率。跑完之后会打印跳过清单如果跳过比例超过 10%说明底库图片质量有问题得回头筛图。3.3 单张比对与批量验证底库建好之后比对就是加载底库、提取待查特征、逐一算相似度、取最高分。import pickle import cv2 import numpy as np from core.detector import detect_faces from core.aligner import align_face from core.extractor import extract_feature from core.matcher import cosine_similarity def compare_with_gallery(query_path, gallery_path, threshold0.45): with open(gallery_path, rb) as f: gallery pickle.load(f) img cv2.imdecode(np.fromfile(query_path, dtypenp.uint8), cv2.IMREAD_COLOR) faces detect_faces(img) if not faces: return None, no_face_detected face max(faces, keylambda f: (f[bbox][2]-f[bbox][0]) * (f[bbox][3]-f[bbox][1])) aligned align_face(img, face[landmarks]) query_feat extract_feature(aligned) best_id, best_sim None, -1.0 for pid, feat in gallery.items(): sim cosine_similarity(query_feat, feat) if sim best_sim: best_sim, best_id sim, pid if best_sim threshold: return best_id, best_sim return None, best_sim参数上threshold默认 0.45实际部署前一定要用一批标注好的测试集跑一遍统计准确率和误识率。我一般会准备至少 50 组同人不同图和 50 组不同人图跑完看误识有几个、拒识有几个再决定阈值往哪边挪。批量验证时把结果写成 CSV方便后续分析哪些图容易翻车。4. 避坑与排查离线人脸比对最容易翻车的五个点4.1 检测不到人脸但肉眼明明看得到现象一张清晰的正脸照detect_faces返回空列表。原因通常是检测模型的输入尺寸和预处理不匹配。很多检测模型要求输入是 640x640 且做过归一化如果源码里预处理写的是除以 255 但模型期望的是减均值除方差检测置信度就会整体偏低。解决方法是打开detector.py确认预处理里的均值和方差参数和模型导出时的配置对齐。另一个常见原因是图片通道顺序opencv 读进来是 BGR模型可能期望 RGB转一下通道往往就恢复了。4.2 同一个人两张照片相似度只有 0.2现象同人比对分数极低甚至低于不同人的分数。原因八成出在对齐环节。检查关键点顺序是否和参考点一致检查output_size是否和特征模型训练尺寸一致。还有一种情况是检测框偏了关键点落在背景上对齐后的人脸是歪的。解决方法是把visualize.py里的画框和画关键点打开肉眼确认关键点是否落在眼睛和嘴角上。如果关键点本身就飘说明检测模型质量不行得换模型。4.3 底库建好了但比对时加载报错现象pickle.load时报ModuleNotFoundError或AttributeError。原因是建库时用的类定义路径和加载时不一致pickle 会记录类的模块路径。解决方法是底库只存 numpy 数组不存自定义对象。上面建库脚本里gallery[person_id] feat存的就是纯 numpy 数组这样跨环境加载不会出问题。如果已经存了对象重新建一次库比改代码快。4.4 CPU 推理太慢批量建库要跑几个小时现象一千张图建库跑了半小时以上。原因是 onnxruntime 默认线程数可能没吃满 CPU或者模型本身太大。解决方法是在创建推理会话时显式设置线程数import onnxruntime as ort sess_options ort.SessionOptions() sess_options.intra_op_num_threads 8 # 根据 CPU 核心数调整 sess_options.inter_op_num_threads 2 session ort.InferenceSession(models/rec_face.onnx, sess_options, providers[CPUExecutionProvider])intra_op_num_threads设成物理核心数inter_op_num_threads设成 2 左右。另外可以开多进程建库把图片列表切分成几份并行跑速度能再翻几倍。但注意 onnxruntime 会话不要跨进程共享每个进程单独创建。4.5 阈值调好了换一批数据又不行了现象在测试集上准确率 95%上线后误识频发。原因是测试集和实际数据分布不一致比如测试集都是正脸实际场景有侧脸、戴口罩、光照差。解决方法是阈值不要一刀切可以按人脸质量分档。检测置信度高、人脸尺寸大的阈值可以设 0.5质量差的设 0.35 并标记为待人工复核。源码包里matcher.py可以扩展一个adaptive_threshold函数根据检测分数和人脸尺寸动态返回阈值。这个改动不大但能明显降低实际场景的翻车率。5. 进阶技巧用特征库做 1:N 检索与质量分过滤底库人数少的时候逐一比对没问题但人数上千之后每次比对都要遍历整个底库延迟会线性增长。这时候可以把特征矩阵化用矩阵乘法一次算完所有相似度。import numpy as np def build_matrix_gallery(gallery_dict): 把字典形式的底库转成矩阵加速 1:N 检索 ids list(gallery_dict.keys()) feats np.stack([gallery_dict[i] for i in ids]) # shape: (N, 512) # 预先做 L2 归一化保证点积等于余弦相似度 norms np.linalg.norm(feats, axis1, keepdimsTrue) feats feats / np.clip(norms, 1e-10, None) return ids, feats def search_1n(query_feat, ids, feats, top_k5): 一次矩阵乘法算出所有相似度返回 top_k query_feat query_feat / np.clip(np.linalg.norm(query_feat), 1e-10, None) sims feats query_feat # shape: (N,) idx np.argsort(-sims)[:top_k] return [(ids[i], float(sims[i])) for i in idx]矩阵化的好处是 numpy 底层走 BLAS一千人底库一次检索不到一毫秒比 Python 循环快两个数量级。参数上top_k取 5 就够返回前五名候选业务层再根据阈值和业务规则决定是否放行。如果底库上到十万级可以考虑用 faiss 建索引但那是另一个话题了离线包里一般用不上。另一个实用技巧是质量分过滤。不是所有人脸都值得送进特征模型检测置信度低于 0.8 的、人脸尺寸小于 80 像素的、关键点置信度低的直接标记为低质量不参与比对或者只做候选不自动放行。我一般会在detector.py返回的结果里加上det_score和landmark_score两个字段业务层根据这两个值做分流。这样虽然会拒掉一部分图但留下来的比对结果可信度高很多。从那以后我每次拿到新的离线人脸包都强制先跑一遍质量分过滤和阈值回归再谈上线。希望帮到你。本文还有配套的精品资源点击获取