用UniFace搭建人脸搜索系统FAISS向量库从单参考到多身份检索实战【免费下载链接】unifaceUniFace: A Unified Face Analysis Library for Python | Detection, alignment, landmarks, face-mesh, recognition, parsing, gaze, attributes and anti-spoofing under one API.项目地址: https://gitcode.com/gh_mirrors/un/unifaceUniFace是一个统一的人脸分析 Python 库把人脸检测、对齐、关键点、人脸网格、人脸识别、语义解析、视线估计、属性预测和活体防伪封装在同一套 API 之下。本文带你用它一步步搭建人脸搜索系统先用一张参考照片做实时比对再升级到基于FAISS 向量库的多身份检索实现这个人是谁的数据库式查找。两种人脸搜索方式单参考 vs 向量检索UniFace 内置了两条搜索路线覆盖从简单到复杂的场景搜索方式典型问题对应工具参考图搜索这个特定的人在视频里吗tools/search.pyFAISS 向量检索这个人是谁对已入库人脸库tools/faiss_search.py单参考模式把每张图里检出的所有人脸与一张参考照片计算余弦相似度超过阈值即判定匹配。适合安保盯人、家人查找等一打一场景。向量库模式把多个人、多张照片预先编码成 512 维嵌入向量存入 FAISS 索引查询时一次检索即可从成千上万条记录中找出最相似的身份。适合门禁、相册管理、监控检索等一对多场景。两者的核心都是人脸识别嵌入embedding检测器定位人脸识别器如 ArcFace提取归一化向量向量越接近相似度越高。上图即相似度机制的直观体现同一人不同时期的照片得分 0.7 左右MATCH不同人之间接近 0 甚至为负NO MATCH。快速安装UniFace FAISS 依赖配置一键安装步骤只需两条命令需 Python 3.10pip install uniface[cpu] # CPU 推理NVIDIA 显卡可改用 uniface[gpu] pip install faiss-cpu # FAISS 向量库GPU 用户装 faiss-gpu模型权重会在首次使用时自动下载缓存到本地无需手动配置。FAISS 向量库是如何工作的向量库的实现位于 uniface/stores/faiss.py核心设计非常简洁底层索引FAISSIndexFlatIP内积索引。向量入库前必须做 L2 归一化这样内积就等价于余弦相似度——UniFace 的识别器get_normalized_embedding()输出的正是归一化向量可直接使用。元数据随行每个向量可携带任意 JSON 字典如person_id、source图片路径检索命中后直接返回身份信息见 uniface/stores/base.py。持久化store.save()会在db_path下写出两个文件——faiss_index.bin二进制索引和metadata.json元数据数组下次store.load()秒级加载无需重建。按条件删除store.remove(person_id, bob)可一键移除某身份的全部向量并自动重建索引方便人员变更。完整 API 参考见官方文档 docs/modules/stores.md。第 1 步单参考图实时搜索最简起点先跑通最简单的模式验证环境没问题。Python 版只需几十行import cv2 from uniface.detection import RetinaFace from uniface.recognition import ArcFace from uniface.face_utils import compute_similarity detector RetinaFace() recognizer ArcFace() ref_faces detector.detect(cv2.imread(reference.jpg)) ref_emb recognizer.get_normalized_embedding(cv2.imread(reference.jpg), ref_faces[0].landmarks) image cv2.imread(group_photo.jpg) for face in detector.detect(image): sim compute_similarity(ref_emb, recognizer.get_normalized_embedding(image, face.landmarks)) print(f{Match if sim 0.4 else Unknown} ({sim:.2f}))不想写代码直接用 CLI支持图片、视频、摄像头三种输入源python tools/search.py --reference ref.jpg --source video.mp4 python tools/search.py --reference ref.jpg --source 0 # 接摄像头实时比对第 2 步准备数据集构建 FAISS 人脸向量索引 多身份检索的关键是按人组织照片一人一个子文件夹dataset/ ├── alice/ │ ├── 001.jpg │ └── 002.jpg ├── bob/ │ └── 001.jpg └── charlie/ ├── 001.jpg └── 002.jpg用 CLI 一条命令建索引每张图取检出的第一张人脸编码后连同身份元数据入库python tools/faiss_search.py build --faces-dir dataset/ --db-path ./vector_index运行结束会打印类似Index saved to ./vector_index (5 vectors, 3 persons)索引文件即刻落盘。Python API 手动建索引想自定义逻辑时源码见 tools/faiss_search.pyfrom pathlib import Path import cv2 from uniface.detection import RetinaFace from uniface.recognition import ArcFace from uniface.stores import FAISS detector, recognizer RetinaFace(), ArcFace() store FAISS(db_path./vector_index) for person_dir in sorted(Path(dataset).iterdir()): for img in person_dir.glob(*.jpg): image cv2.imread(str(img)) faces detector.detect(image) if faces: emb recognizer.get_normalized_embedding(image, faces[0].landmarks) store.add(emb, {person_id: person_dir.name, source: str(img)}) store.save() print(fIndex saved: {store}) 每个人放 3~10 张覆盖不同角度、光照的照片能显著提升检索鲁棒性——同一人在不同帧里的向量会散布在一个邻域内样本越全邻域覆盖越好。第 3 步对视频流与摄像头执行多身份检索索引建好后run子命令即可在视频或摄像头画面上逐帧检索命中身份显示绿色框与person_id (相似度)未命中显示红色Unknown# 处理视频文件结果保存到 outputs/ python tools/faiss_search.py run --db-path ./vector_index --source video.mp4 # 接摄像头实时检索按 q 退出 python tools/faiss_search.py run --db-path ./vector_index --source 0核心逻辑非常轻量见 tools/faiss_search.py 中的process_frame每帧检测人脸 → 提取嵌入 →store.search(embedding, threshold0.4)一次内积检索 → 根据是否命中绘制标签。CPU 上处理单帧通常只需几十到几百毫秒实时应用完全可行。索引的日常管理增删查与持久化向量库不是建完就完人员进出都需要维护from uniface.stores import FAISS store FAISS(db_path./vector_index) store.load() print(fTotal vectors: {len(store)}) # 查看库内向量总数 removed store.remove(person_id, bob) # 移除某人的全部向量 print(fRemoved {removed} entries) store.save() # 记得持久化常见管理动作速查需求操作新增人员在其子文件夹放入照片后重新build或用 Python API 逐条add删除人员store.remove(person_id, bob)save()查看规模len(store)/store.size换机器迁移直接拷贝db_path目录含两个文件相似度阈值怎么调人脸搜索效果校准指南search()的threshold默认0.4是召回优先的起步值。经验参考来自 docs/concepts/thresholds-calibration.md阈值判定适用场景0.4低安全宁可多报配合人工复核0.5均衡大多数场景0.6高安全误报代价高如门禁0.7极严格安全关键应用⚠️ 注意阈值是起点不是铁律。年龄跨度大、画质差、跨年份的老照片同一人的相似度会明显下降例如 26 年前的照片对仍可达 0.58。建议在接近自己业务数据的样本上实测校准用 CLI 试调也很方便python tools/faiss_search.py run --db-path ./vector_index --source video.mp4 --threshold 0.6进阶建议与相关资源换识别器提精度默认 ArcFace MNET仅 8 MB速度极快追求精度可换AdaFaceIR-101IJB-C 达 97.66%或ArcFace(RESNET)识别模型全览见 docs/modules/recognition.md。调检测器人群密集场景可提高nms_threshold或换更大的input_size参考 docs/concepts/thresholds-calibration.md。视频实时化配合 docs/recipes/video-webcam.md 的摄像头流式处理技巧把检索做成常驻服务。相关源码路径向量库实现 uniface/stores/faiss.py、人脸识别模块 uniface/recognition/、完整食谱 docs/recipes/face-search.md。从一张参考照片到十万级人脸库UniFace 用同一套 API 帮你平滑升级。现在打开终端建一个dataset/目录五分钟跑通你的第一个人脸搜索系统吧 【免费下载链接】unifaceUniFace: A Unified Face Analysis Library for Python | Detection, alignment, landmarks, face-mesh, recognition, parsing, gaze, attributes and anti-spoofing under one API.项目地址: https://gitcode.com/gh_mirrors/un/uniface创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考