简介：这是一份面向开发者与计算机视觉学习者的离线人脸识别与头像对比源代码资源，无需联网即可在本地完成人脸检测、特征提取与相似度匹配，适合研究生物识别原理或搭建私有化比对工具。压缩包共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] # 右嘴角 ], dtype=np.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, borderValue=0.0) return aligned这段代码的逻辑是：先定义一组标准人脸关键点位置，再用estimateAffinePartial2D求出从实际关键点到标准点的变换矩阵，最后把原图 warp 到目标尺寸。参数上output_size必须和特征模型训练时的输入尺寸一致，常见是 112x112，如果模型是 160x160 的就要改，改错了特征会整体偏移。borderValue=0.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, threshold=0.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 python=3.9 -y conda activate face_offline # onnxruntime 分 CPU 和 GPU 两个版本，离线场景多数用 CPU pip install onnxruntime==1.16.0 pip install opencv-python==4.8.1.78 pip install numpy==1.24.3 pip install pillow==10.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_size=60): """ 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, dtype=np.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, key=lambda 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, threshold=0.45): with open(gallery_path, 'rb') as f: gallery = pickle.load(f) img = cv2.imdecode(np.fromfile(query_path, dtype=np.uint8), cv2.IMREAD_COLOR) faces = detect_faces(img) if not faces: return None, 'no_face_detected' face = max(faces, key=lambda 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, axis=1, keepdims=True) feats = feats / np.clip(norms, 1e-10, None) return ids, feats def search_1n(query_feat, ids, feats, top_k=5): """一次矩阵乘法算出所有相似度，返回 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两个字段，业务层根据这两个值做分流。这样虽然会拒掉一部分图，但留下来的比对结果可信度高很多。
从那以后我每次拿到新的离线人脸包，都强制先跑一遍质量分过滤和阈值回归，再谈上线。希望帮到你。
本文还有配套的精品资源，点击获取
