简介这份资源面向希望深入理解人脸识别原理的开发者与学习者提供一套完全离线运行的头像对比与人脸识别源代码方案无需联网即可在本地完成检测、特征提取与相似度匹配的完整流程。压缩包共687个文件约88.34MB以621个dll依赖库为主辅以20个cs源文件、13个h头文件及xaml界面文件、exe可执行程序与sln解决方案等构成可直接编译运行的工程结构。资源围绕预处理、人脸检测、特征提取、特征匹配与结果输出等环节展开读者可据此研究Haar级联、LBPH或深度特征向量等算法的落地方式并参照工程组织修改优化。目前已有818人学习下载适合具备一定C#基础、想动手实践离线人脸识别与头像比对的中级开发者参考。1. 离线人脸比对这套源码解决的是“断网也要跑”的硬需求上个月有个做门禁改造的朋友找我说现场机房压根没有外网甲方又要求“刷脸开门 头像比对留痕”云端 API 一律不许调。这种场景下能救命的不是某个大模型而是一份完全离线、依赖本地权重、跑在普通工控机上的源代码。这份资源就是干这个的人脸检测、人脸对齐、特征提取、头像相似度比对整条链路都在本地完成不联网、不上传、不依赖任何在线服务。适合谁做安防门禁、考勤机、访客登记、会员头像核验的开发者以及想拿一份能跑通的人脸比对基线工程来二次开发的人。关键词就一个——源代码拿到手能编译、能换模型、能接自己的业务库而不是一个只能看不能动的黑匣子。2. 技术栈与目录结构先看清这套离线人脸比对工程的骨架2.1 为什么是“检测 对齐 特征”三段式而不是一把梭人脸比对这件事很多人第一反应是“丢给一个端到端模型不就行了”。真到工程里端到端模型对输入姿态、光照、遮挡极其敏感头像和现场抓拍往往不是一个域直接比对相似度会飘。合格的做法是拆成三段先用检测器把人脸框出来再按关键点做对齐把眼睛、鼻尖、嘴角摆正最后用特征提取网络输出一个定长向量比对时算余弦相似度。这套源码就是按这个思路组织的检测、对齐、特征三块各自独立换其中一块不影响另外两块这对二次开发太重要了——你嫌检测慢可以换轻量检测器嫌特征区分度不够可以换更大的骨干网接口是解耦的。常见做法是检测用轻量级单阶段网络对齐用五点或五点以上的关键点回归特征用带 ArcFace 类损失训练出来的骨干网。这套工程没有把三者焊死而是通过统一的FacePipeline串起来下面会看到具体代码。2.2 目录结构一眼找到该改的文件拿到源码先别急着编译先把目录扫一遍。这类离线人脸工程的典型结构是这样的不同版本文件名可能略有差异但分层逻辑一致face_offline/ ├── models/ # 本地权重检测/关键点/特征各一份 │ ├── det.onnx │ ├── landmark.onnx │ └── rec.onnx ├── src/ │ ├── detector.py # 人脸检测封装 │ ├── align.py # 关键点对齐、仿射变换 │ ├── feature.py # 特征提取与归一化 │ ├── matcher.py # 余弦相似度、阈值判定 │ └── pipeline.py # 三段式串联入口 ├── configs/ │ └── default.yaml # 阈值、输入尺寸、模型路径 ├── data/ │ ├── gallery/ # 底库头像 │ └── probe/ # 待比对图片 ├── tools/ │ ├── build_gallery.py # 批量建底库特征 │ └── compare.py # 单张比对命令行 └── requirements.txtmodels/放的是离线权重这是“完全离线”的关键——所有推理都读本地文件不发起任何网络请求。src/按职责拆文件pipeline.py是唯一对外入口。configs/default.yaml里最该关注三个参数检测输入尺寸、特征维度、比对阈值。tools/下两个脚本是给你快速验证用的build_gallery.py把底库头像批量转成特征存起来compare.py拿一张现场图去和底库比。新手先跑这两个脚本能出结果再谈改代码。2.3 依赖与运行环境离线不等于零依赖“完全离线”指的是运行时不联网不是说不装库。这类工程通常依赖 ONNX Runtime 做推理比直接上深度学习框架轻工控机上部署友好、OpenCV 做图像读写和仿射变换、NumPy 做向量运算。requirements.txt大致长这样# 推理与图像处理核心依赖 onnxruntime1.16.0 # CPU 推理工控机友好有 GPU 可换 onnxruntime-gpu opencv-python4.8.0.74 # 图像读写、仿射变换、绘制 numpy1.24.3 # 特征向量运算 pyyaml6.0 # 读取 configs/default.yaml装依赖这一步有个血泪经验ONNX Runtime 的版本要和模型导出时的算子集对得上版本差太多会报NOT_IMPLEMENTED之类的算子不支持错误。我一般先按requirements.txt原样装跑通了再考虑升级。另外工控机如果是 ARM 架构onnxruntime要换对应平台的 wheel别直接 pip 装 x86 的包装上了也 import 失败。3. 核心链路拆解从一张图到相似度分数的完整代码3.1 人脸检测先把脸框出来别急着提特征检测是整个链路的第一道关框歪了后面全歪。这套工程的检测封装大致如下输入一张 BGR 图输出若干人脸框和置信度import cv2 import numpy as np import onnxruntime as ort class FaceDetector: def __init__(self, model_path, input_size(640, 640), conf_thres0.5): # 离线加载本地权重providers 只留 CPU避免意外走网络或 GPU 依赖 self.session ort.InferenceSession( model_path, providers[CPUExecutionProvider] ) self.input_size input_size self.conf_thres conf_thres self.input_name self.session.get_inputs()[0].name def preprocess(self, img): # letterbox 缩放保持长宽比避免人脸被拉伸变形 h, w img.shape[:2] scale min(self.input_size[0] / w, self.input_size[1] / h) nw, nh int(w * scale), int(h * scale) resized cv2.resize(img, (nw, nh)) canvas np.zeros((self.input_size[1], self.input_size[0], 3), dtypenp.uint8) canvas[:nh, :nw] resized blob canvas[:, :, ::-1].transpose(2, 0, 1).astype(np.float32) / 255.0 return np.expand_dims(blob, 0), scale def detect(self, img): blob, scale self.preprocess(img) # 输出通常是 [N, 5]x1,y1,x2,y2,score 或带关键点按模型实际输出解析 outputs self.session.run(None, {self.input_name: blob})[0] boxes [] for det in outputs[0]: score float(det[4]) if score self.conf_thres: continue x1, y1, x2, y2 det[:4] / scale boxes.append([int(x1), int(y1), int(x2), int(y2), score]) return boxes这段代码有三个参数值得盯input_size决定检测精度和速度的平衡工控机上 640 是常见起点人脸特别小的场景可以提到 960conf_thres是置信度阈值调低会多框出误检调高会漏掉侧脸providers固定成 CPU是为了保证“离线可复现”别让环境差异把结果带偏。preprocess里的 letterbox 是重点直接resize会把脸拉扁关键点跟着错位后面特征就废了。检测输出格式各家模型不一样有的带关键点有的不带解析时先打印一次outputs[0].shape确认别照抄。3.2 关键点对齐把脸“摆正”再提特征对齐这一步最容易被新手跳过但它直接决定比对稳定性。原理是拿五个关键点左右眼、鼻尖、左右嘴角算一个仿射变换矩阵把脸旋转缩放到标准姿态。代码大致这样import cv2 import numpy as np # 标准五点模板112x112 是常见特征网络输入尺寸 REFERENCE np.array([ [38.29, 51.69], [73.53, 51.50], # 左右眼 [56.02, 71.73], # 鼻尖 [41.54, 92.36], [70.72, 92.20], # 左右嘴角 ], dtypenp.float32) def align_face(img, landmarks, out_size112): # landmarks: 5x2顺序与 REFERENCE 一致 src np.array(landmarks, dtypenp.float32) dst REFERENCE * (out_size / 112.0) # 相似变换只做旋转缩放平移不引入透视畸变 M, _ cv2.estimateAffinePartial2D(src, dst, methodcv2.LMEDS) aligned cv2.warpAffine(img, M, (out_size, out_size), borderValue0.0) return alignedestimateAffinePartial2D用的是相似变换只允许旋转、等比缩放、平移不允许错切这对人脸是合理的——人脸不会斜着拉伸。methodcv2.LMEDS是抗噪的最小中值估计关键点有个别抖动时比默认最小二乘稳。out_size要和特征网络的输入尺寸一致常见是 112×112改之前先看rec.onnx的输入 shape。对齐后的图再送特征网络同一张脸在不同角度下提取的向量才会靠得近这是比对能稳住的物理基础。3.3 特征提取与相似度比对余弦距离 阈值判定特征网络输出一个定长向量常见 512 维比对就是算两个向量的余弦相似度。代码不复杂但归一化和阈值这两处最容易翻车import numpy as np import onnxruntime as ort class FaceFeature: def __init__(self, model_path): self.session ort.InferenceSession( model_path, providers[CPUExecutionProvider] ) self.input_name self.session.get_inputs()[0].name def extract(self, aligned_face): # aligned_face: 112x112x3 BGR转 RGB、归一化到 [-1, 1] blob aligned_face[:, :, ::-1].astype(np.float32) blob (blob / 255.0 - 0.5) / 0.5 blob blob.transpose(2, 0, 1)[None, ...] feat self.session.run(None, {self.input_name: blob})[0][0] # L2 归一化之后点积即余弦相似度 feat feat / np.linalg.norm(feat) return feat def cosine_sim(f1, f2): return float(np.dot(f1, f2)) def is_same_person(f1, f2, threshold0.45): # 阈值不是拍脑袋要用自己的底库跑 ROC 曲线定 return cosine_sim(f1, f2) thresholdextract里的归一化方式必须和训练时一致(x/255 - 0.5)/0.5是常见配置但有的模型用(x - mean)/std照抄前先看模型说明或导出脚本。L2 归一化之后点积就是余弦相似度省一次除法。threshold0.45只是个起点不同特征网络、不同底库分布下最优阈值差别很大我一般会拿几十对同人/异人样本跑一遍看误接受率和误拒绝率的交叉点再定。这一步没有捷径玄学阈值背后其实是分布问题。3.4 三段式串联pipeline 把检测、对齐、特征接起来单模块跑通后用pipeline.py串成一条链对外只暴露一个比对方法class FacePipeline: def __init__(self, cfg): self.detector FaceDetector(cfg[det_model], cfg[det_size]) self.feature FaceFeature(cfg[rec_model]) self.threshold cfg[threshold] def embed(self, img): boxes self.detector.detect(img) if not boxes: return None # 取置信度最高的人脸多人场景按业务改 x1, y1, x2, y2, _ max(boxes, keylambda b: b[4]) face img[y1:y2, x1:x2] aligned align_face(face, self._landmarks(face)) return self.feature.extract(aligned) def compare(self, img_a, img_b): fa, fb self.embed(img_a), self.embed(img_b) if fa is None or fb is None: return {ok: False, reason: no_face} score cosine_sim(fa, fb) return {ok: True, score: score, same: score self.threshold}embed里“取置信度最高的人脸”是单目标场景的简化门禁、考勤通常够用访客登记这种可能一张图多人的要改成遍历所有框分别比对。compare返回结构里带reason是为了排查时能区分“没检测到脸”和“比对不通过”这两个问题的处理方式完全不同。整条链路没有任何网络调用providers全是 CPU权重全在models/下这就是“完全离线”的落地形态。4. 跑起来与避坑离线人脸比对工程最容易翻车的几个点4.1 从零跑通的最小步骤先把环境跑通再谈改代码。步骤不复杂但顺序别乱# 1. 建虚拟环境隔离依赖 python -m venv venv source venv/bin/activate # 2. 装依赖先按 requirements 原样装 pip install -r requirements.txt # 3. 确认模型文件齐全 ls models/ # 应看到 det.onnx / landmark.onnx / rec.onnx # 4. 批量建底库特征 python tools/build_gallery.py --gallery data/gallery --out gallery.npz # 5. 单张比对验证 python tools/compare.py --probe data/probe/test.jpg --gallery gallery.npz第 4 步的build_gallery.py会把data/gallery/下每张头像走一遍 pipeline特征存进gallery.npz后续比对直接读这个文件不用每次重算。第 5 步输出里会打印相似度和是否同人先拿一张明显是同一个人的图验证分数应该明显高于阈值再拿一张明显不同的人分数应该低。两头都对说明链路通了。4.2 避坑清单五个真实踩过的坑现象一检测框正常但比对分数永远很低。原因多半是对齐没生效或关键点顺序错了。五点模板的顺序是左眼、右眼、鼻尖、左嘴角、右嘴角如果检测模型输出的关键点顺序是右眼在前仿射矩阵就会把脸转反。解决打印关键点坐标画到图上肉眼确认顺序不对就在_landmarks里重排。现象二同一张图跑两次分数有微小波动。这在 CPU 推理上通常不该出现出现多半是预处理里有随机因素比如 resize 的插值方式不一致或者输入没做 letterbox 导致每次 padding 不同。解决固定cv2.resize的interpolation参数预处理写成纯函数别在里边读配置。现象三换了自己的底库头像后误识率飙升。原因往往是底库头像和现场图域差异太大——底库是精修证件照现场是逆光抓拍。解决底库尽量用和现场同源的图或者对底库做和现场一致的对齐裁剪阈值也要按新底库重新标定别沿用默认 0.45。现象四工控机上 import onnxruntime 直接报错。多半是架构不匹配x86 的 wheel 装到了 ARM 机器上或者 glibc 版本太低。解决确认uname -m输出装对应平台的包实在不行用源码编译但优先找现成 wheel。现象五多人场景只比对了其中一张脸。这是pipeline.py里“取置信度最高”的简化导致的不是 bug 是设计取舍。解决业务需要多人时把embed改成返回所有人脸特征列表compare里做一对多匹配取最高分并记录对应框位置。提示阈值标定这一步别省。拿至少 50 对同人、50 对异人样本跑一遍统计不同阈值下的误接受和误拒绝选业务能接受的那个点比拍脑袋定 0.45 靠谱得多。5. 二次开发换模型、接业务库、加活体检测的改造思路拿到这份源码真正值钱的是它的分层结构改起来有明确的切入点。换特征模型是最常见的需求把models/rec.onnx换成区分度更高的骨干网只要保证输入还是对齐后的 112×112、输出还是定长向量feature.py里的归一化方式跟着模型训练配置改一下其余代码不用动。换检测器同理detector.py的detect方法返回[x1,y1,x2,y2,score]列表内部怎么实现随你。这种“接口稳定、实现可换”的设计是这份工程最值得学的地方。接业务库的改造重点在build_gallery.py。现在的实现是把底库头像批量转特征存npz生产环境通常要接数据库员工表里存工号和人脸特征向量BLOB 或向量列比对时先按工号或分组捞候选再算余弦相似度。特征向量 512 维 float32 大约 2KB几千人的底库全量加载进内存完全扛得住没必要上向量数据库这是很多团队过度设计的点。我一般会加一层缓存底库特征启动时加载一次新增员工时增量更新避免每次比对都查库。加活体检测是门禁场景绕不开的。这份源码本身是纯比对没有活体模块但结构上留了口子在pipeline.py的embed之前插一个liveness判断输入是检测框内的人脸图输出是真人/攻击的概率不通过直接返回reason: not_live。活体模型同样走 ONNX 离线推理和现有链路一致。要注意的是活体阈值和比对阈值要分开标定别混在一起调否则出了问题分不清是活体误判还是比对误判。验证改造是否成功我习惯用一套固定的小测试集同人不同角度 20 对、同人不同光照 20 对、异人 40 对每次改完模型或阈值都跑一遍记录误接受率、误拒绝率和平均耗时。这套测试集不大但能挡住大部分“改完感觉变好了其实变差了”的情况。血泪经验是改特征模型时一定要重标阈值新模型的分数分布和旧模型完全不是一个尺度沿用旧阈值必然翻车。从那以后我每次换模型都强制先跑一遍这套测试集再上线再也不敢凭感觉调参了。希望帮到你。本文还有配套的精品资源点击获取