CompreFace 自定义构建（Custom Builds）实战指南：按硬件选择人脸模型、运行 GPU 构建与自构镜像-北京尧图网络

人工智能计算机视觉后端AI 应用【免费下载链接】CompreFaceLeading free and open-source face recognition system项目地址https://gitcode.com/gh_mirrors/co/CompreFace点击查看免费下载本文以 CompreFace 仓库中的 Custom-builds 文档为核心系统讲解官方自定义构建custom-builds的设计动机、完整构建清单、选型原则与运行方法并结合custom-builds/目录下各构建的 docker-compose 配置和embedding-calculator服务的插件源码说明如何通过构建参数替换人脸检测/识别模型、启用 GPU 与 Intel MKL 优化最终帮助你为不同硬件条件挑选或构建最合适的 CompreFace 部署方案。一、为什么需要 Custom Builds精度、吞吐与硬件的三角权衡人脸系统的设计永远存在一个三角权衡识别精度accuracy、最大吞吐量throughput与硬件支持hardware support。CompreFace 的默认发布构建default build选择了一种最大兼容性策略默认构建面向最广泛的硬件设计可以在尽可能多的机器上跑起来代价是它没有针对最新一代 CPU 指令集做优化也不支持 GPU此外从源码结构看默认构建FaceNet 后端要求 CPU 支持 AVX 指令见 custom-builds 清单中 Support CPU without AVX2 的说明即仅要求 AVX、不要求 AVX2。因此 CompreFace 维护了一组 custom-builds尽可能覆盖各种场景。文档同时明确提示这些自定义构建的测试覆盖度不如默认构建完善社区被鼓励报告相关 bug。二、官方 Custom Builds 完整清单官方维护的构建清单位于 custom-builds/README.md仓库中每个构建对应一个独立目录与一份docker-compose.yml。清单内容如下精度数据来自该清单文档构建基础库CPU 要求GPU人脸检测模型 / WIDER Face (Hard) 精度识别模型 / LFW 精度年龄/性别检测口罩检测定位FaceNet (default)FaceNetx86 (AVX)不支持MTCNN / 80.9%FaceNet (20180402-114759) / 99.63%自定义AgeGenderDeepLearning自定义模型通用支持无 AVX2 的 CPUFaceNet Masked (Experimental)FaceNetx86 (AVX)不支持MTCNN / 80.9%inception_v3_on_mafa_kaggle123 / 98.73%自定义自定义模型通用支持无 AVX2 的 CPUMobilenetInsightFacex86 (AVX2)不支持RetinaFace-MobileNet0.25 / 82.5%MobileFaceNet,ArcFace / 99.50%InsightFace自定义模型纯 CPU 模型中最快Mobilenet-gpuInsightFacex86 (AVX2)GPU需 CUDARetinaFace-MobileNet0.25 / 82.5%MobileFaceNet,ArcFace / 99.50%InsightFace自定义模型整体最快SubCenter-ArcFace-r100InsightFacex86 (AVX2)不支持retinaface_r50_v1 / 91.4%arcface-r100-msfdrop75 / 99.80%InsightFace自定义模型精度最高但 CPU 上最慢SubCenter-ArcFace-r100-gpuInsightFacex86 (AVX2)GPU需 CUDAretinaface_r50_v1 / 91.4%arcface-r100-msfdrop75 / 99.80%InsightFace自定义模型精度最高对应目录结构一目了然每个构建就是一个自包含的 compose 项目custom-builds/FaceNet/docker-compose.ymlcustom-builds/Mobilenet/docker-compose.ymlcustom-builds/Mobilenet-gpu/docker-compose.ymlcustom-builds/SubCenter-ArcFace-r100/docker-compose.ymlcustom-builds/SubCenter-ArcFace-r100-gpu/docker-compose.ymlcustom-builds/Single-Docker-File/单容器一体化构建见第五节源码佐证模型即可插拔配置清单中的模型名并非随意标注。以 InsightFace 后端的识别插件为例insightface.py 中Calculator类的ml_models元组注册了全部可选模型模型名、Google Drive 文件 ID、距离阈值参数、batch sizeclass Calculator(InsightFaceMixin, mixins.CalculatorMixin, base.BasePlugin): ml_models ( (arcface_mobilefacenet, 17TpxpyHuUc1ZTm3RIbfvhnBcZqhyKszV, (1.26538905, 5.552089201), 200), (arcface_r100_v1, 11xFaEHIQLNze3-2RUV1cQfT-q6PKKfYp, (1.23132175, 6.602259425), 400), (arcface_resnet34, 1ECp5XrLgfEAnwyTYFEhJgIsOAw6KaHa7, (1.2462842, 5.981636853), 400), (arcface_resnet50, 1a9nib4I9OIVORwsqLB0gz0WuLC32E8gf, (1.2375747, 5.973354538), 400), (arcface-r50-msfdrop75, 1gNuvRNHCNgvFtz7SjhW82v2-znlAYaRO, (1.2350148, 7.071431642), 400), (arcface-r100-msfdrop75, 1lAnFcBXoMKqE-SkZKTmi6MsYAmzG0tFw, (1.224676, 6.322647217), 400), (arcface_mobilefacenet_casia_masked, 1ltcJChTdP1yQWF9e1ESpTNYAVwxLSNLP, (1.22507105, 7.321198934), 200), )这正是清单中 arcface-r100-msfdrop75SubCenter-ArcFace 系列LFW 99.80%与 MobileFaceNet99.50%的来源检测模型则由 FaceDetector.ml_models 注册retinaface_mnet025_v1/v2、retinaface_r50_v1。FaceNet 后端同理facenet.py 的Calculator.ml_models注册了 20180402-114759、20180408-102900 与口罩增强模型 inception_resnetv1_casia_masked。三、如何选择合适的构建官方文档给出的选型规则直接可用核心思想是精度差异不大但硬件资源需求差异巨大实时人脸识别→ 选择支持 GPU 的构建Mobilenet-gpu 或 SubCenter-ArcFace-r100-gpu老旧或低性能系统→ 选择为移动设备设计的模型Mobilenet / MobileFaceNet 系列InsightFace 后端不要盲目追求最准的模型各模型间精度差异并不显著但所需硬件资源可能天差地别。例如 SubCenter-ArcFace-r100 在纯 CPU 上是最准也最慢的组合而 Mobilenet 是纯 CPU 模型中最快的组合。四、运行 Custom Builds命令与三个关键注意点运行流程与默认构建几乎一致——进入对应构建目录执行docker-compose up -d即可。例如使用 GPU 版 SubCenter-ArcFacecd custom-builds/SubCenter-ArcFace-r100-gpu docker-compose up -d但文档特别强调了三点实际部署时务必注意数据卷是全新的。从 custom-build 目录启动会创建新的 docker volume你之前保存的人脸数据不会出现在新实例里。若想带着旧数据跑 custom-build需要把原构建目录中的文件复制到 custom-build 目录并覆盖原文件保证 compose 配置与既有卷定义兼容。模型通常不可互换。不同构建使用的人脸识别模型算出的 embedding 不通用在旧构建中保存的示例/人脸在新构建上无法直接识别。可选的迁移方案见人脸数据迁移文档。不要不改端口就跑两个实例。若同一台机器要同时运行多个 CompreFace需修改对应docker-compose文件中compreface-fe容器的端口映射各 custom-build 的 compose 文件默认都映射8000:80。各构建 compose 文件的差异细节对照仓库中的实际 compose 文件可以观察到几个有价值的差异GPU 构建通过deploy.resources.reservations.devices声明 NVIDIA 设备以 Mobilenet-gpu 为例compreface-core: image: ${registry}compreface-core:${CORE_VERSION} container_name: compreface-core environment: - ML_PORT3000 - UWSGI_PROCESSES${uwsgi_processes:-1} - UWSGI_THREADS${uwsgi_threads:-1} deploy: resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu]uWSGI 进程数不同GPU 版 Mobilenet 的默认UWSGI_PROCESSES为 1单进程即可喂饱 GPU而 CPU 构建如 FaceNet 版默认为 2可通过.env中的uwsgi_processes覆盖。服务拓扑一致所有构建都包含五个服务——compreface-postgres-db、compreface-admin、compreface-api、compreface-fe端口 8000:80与compreface-coreML 端口 3000环境变量通过${变量}占位符注入如max_file_size、max_request_size、connection_timeout默认 10000、read_timeout默认 60000方便用.env统一配置。五、Single-Docker-File 构建一个容器跑整个系统除了按 compose 拆分容器custom-builds/Single-Docker-File 提供了一体化方案把 PostgreSQL、admin、api、前端 nginx 和 compreface-core 全部打进同一个镜像用 supervisord 管理多进程。从 Dockerfile 可以看到其构建要点以exadel/compreface-core:latestBASE_IMAGE构建参数为底座默认UWSGI_PROCESSES2、UWSGI_THREADS1安装 PostgreSQL 13使用 postgresql.conf 定制配置并执行 initdb.sql 初始化数据库从eclipse-temurin:17.0.8_7-jdk-jammy镜像中提取 JDK 17分别挂载 admin-Xmx1g端口 8081与 api-Xmx4g端口 8080应用的 app.jar前端静态文件来自 compreface-fe 镜像配合 nginx.conf 完成反向代理最终以/usr/bin/supervisord作为 CMD由 supervisord.conf 与 startup.sh 拉起全部进程。该方案适合希望以最小运维成本一个docker run体验完整系统的场景而需要独立伸缩、GPU 直通或资源隔离的生产部署仍建议使用分容器的 compose 构建。六、构建自己的 Custom Build自定义模型与构建参数官方文档指出CompreFace 支持FaceNet 与 InsightFace 两个人脸识别库因此任何能被这两个库运行的模型都可以被集成。构建自定义模型的完整流程是第 1 步向Calculator类注册你的模型将你的模型如上传到 Google Drive 获得文件 ID添加到对应插件文件的Calculator类ml_models元组中FaceNet 后端embedding-calculator/src/services/facescan/plugins/facenet/facenet.pyInsightFace 后端embedding-calculator/src/services/facescan/plugins/insightface/insightface.py例如 InsightFace 元组的每个元素形如(模型名, Google Drive 文件 ID, (阈值参数1, 阈值参数2), batch_size)其中阈值参数对应 ArcFace 的余弦距离 margin/threshold 校准值batch_size 控制 embedding 计算批大小如 mobilefacenet 用 200r100 用 400。第 2 步以dev目录的 compose 文件为模板取 dev/docker-compose.yml 作为模板。与 custom-builds 目录中直接拉取镜像的版本不同dev 模板会为compreface-core指定build: context: ../embedding-calculator并通过args注入模型选择——这正是构建参数机制的入口compreface-core: image: ${registry}compreface-core:${CORE_VERSION} container_name: compreface-core ports: - 3300:3000 build: context: ../embedding-calculator environment: - ML_PORT3000第 3 步在 build args 中指定新模型名embedding-calculator 的 README 给出了构建参数的权威说明。官方文档中的 GPU 自定义构建示例如下compreface-core: image: ${registry}compreface-core:${CORE_VERSION} container_name: compreface-core ports: - 3300:3000 runtime: nvidia build: context: ../embedding-calculator args: - FACE_DETECTION_PLUGINinsightface.FaceDetectorretinaface_r50_v1 - CALCULATION_PLUGINinsightface.Calculatorarcface_r100_v1 - EXTRA_PLUGINSinsightface.LandmarksDetector,insightface.GenderDetector,insightface.AgeDetector,insightface.facemask.MaskDetector,insightface.PoseEstimator - BASE_IMAGEcompreface-core-base:base-cuda100-py37 - GPU_IDX0 environment: - ML_PORT3000参数语义详解均来自 embedding-calculator/README.md构建参数作用默认值FACE_DETECTION_PLUGIN人脸检测插件可用追加预训练模型名facenet.FaceDetectorCALCULATION_PLUGINembedding 计算插件可用追加模型名facenet.CalculatorEXTRA_PLUGINS逗号分隔的附加插件年龄/性别/关键点/口罩/姿态facenet.LandmarksDetector,agegender.GenderDetector,agegender.AgeDetector,facenet.facemask.MaskDetector,facenet.PoseEstimatorGPU_IDXNVIDIA GPU 设备序号从 0 开始留空或 -1 表示禁用禁用INTEL_OPTIMIZATION是否启用 Intel MKL 优化true/false未启用可选插件矩阵README 插件表插件Slug框架GPU 支持facenet.FaceDetectordetectorTensorFlow (MTCNN)无facenet.CalculatorcalculatorTensorFlow无insightface.FaceDetectordetectorMXNet有insightface.CalculatorcalculatorMXNet有agegender.AgeDetector / GenderDetectorage / genderTensorFlow无insightface.AgeDetector / GenderDetectorage / genderMXNet有facenet/insightface.LandmarksDetectorlandmarksTF / MXNet有insightface.Landmarks2d106Detectorlandmarks2d106MXNet有facenet/insightface.facemask.MaskDetectormaskTF / MXNet有facenet/insightface.PoseEstimatorposeTF / MXNet有预训练模型清单用插件名模型名指定facenet.Calculator20180402-114759默认、20180408-102900insightface.FaceDetectorretinaface_r50_v1默认、retinaface_mnet025_v1、retinaface_mnet025_v2insightface.Calculatorarcface_r100_v1默认、arcface_resnet34、arcface_resnet50、arcface_mobilefacenet、arcface-r50-msfdrop75、arcface-r100-msfdrop75口罩检测模型facenet 后端支持 inception_v3 / mobilenet_v2 两种 mafa 数据集模型insightface 后端支持 mobilenet_v2 / resnet18。GPU 镜像的构建方式README 给出的 GPU 构建三步曲基于 gpu.Dockerfiledocker build . -t embedding-calculator-cuda -f gpu.Dockerfile docker build . -t embedding-calculator-gpu --build-arg GPU_IDX0 --build-arg BASE_IMAGEembedding-calculator-cuda docker run -p 3000:3000 --gpus all embedding-calculator-gpu宿主机需先安装 nvidia-docker2 并重启 dockerLinuxWindows 则需 Docker Desktop WSL2 后端更新的 NVIDIA 驱动。源码层验证模型如何被加载从 insightface.py 的InsightFaceMixin.get_model_file可以看到插件启动时会校验模型文件是否存在不存在即抛ModelImportException并通过model_store.find_params_file定位参数文件_CTX_ID ENV.GPU_IDX决定模型绑定到 CPU 还是 GPU 上下文model.prepare(ctx_idself._CTX_ID)。这解释了为何GPU_IDX是构建期参数而非运行期参数——它被烤进了插件初始化逻辑。七、贡献与问题反馈官方鼓励社区分享自己的构建会以 community build 名义加入清单也鼓励对 custom-builds 报告任何 bug——因为其测试覆盖度低于默认构建。若构建过程中遇到问题embedding-calculator 的 Troubleshooting 章节列出了两个常见坑Windows 下 CRLF 行尾导致的构建报错dos2unix修复与 uWSGI 在 Windows 本地环境不可安装。八、总结场景推荐构建无 AVX2 的老 CPU、通用部署FaceNet (default)纯 CPU 追求速度MobilenetGPU 实时识别、追求速度Mobilenet-gpu追求最高精度可接受慢SubCenter-ArcFace-r100CPU/ SubCenter-ArcFace-r100-gpuGPU极简部署、单容器体验Single-Docker-File自有模型修改Calculator.ml_models dev 模板 compose 构建参数掌握以上清单、选型规则与构建参数机制后你可以按硬件条件在精度与吞吐之间做出有依据的取舍并能把自有模型通过模型名构建参数平滑接入 CompreFace 的插件体系。赞分享人工智能计算机视觉后端AI 应用【免费下载链接】CompreFaceLeading free and open-source face recognition system项目地址https://gitcode.com/gh_mirrors/co/CompreFace点击查看免费下载相关推荐CompreFace 自定义构建详解按硬件与精度需求选择模型组合的完整指南CompreFace 自定义构建详解按硬件与精度需求选择模型组合的完整指南 CompreFace 在人脸识别精度、系统吞吐量和硬件适配之间始终存在取舍默认发人工智能计算机视觉后端AI 应用Handsontable 自定义构建Custom Builds完全指南Monorepo 构建流程与各包构建命令详解Handsontable 自定义构建Custom Builds完全指南Monorepo 构建流程与各包构建命令详解 Handsontable 的构建流程前端UI组件如何快速构建Apache Airflow自定义Docker镜像完整实战指南如何快速构建Apache Airflow自定义Docker镜像完整实战指南 Apache Airflow作为业界领先的工作流编排平台其Docker镜像构建是后端任务调度工作流自动化数据编排批处理数据工程流程编排上一篇5分钟上手VSCodium代码片段让你的开发效率提升300%的秘密武器下一篇FreeTube 完整指南无广告、零追踪的开源视频客户端怎么用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

CompreFace 自定义构建（Custom Builds）实战指南：按硬件选择人脸模型、运行 GPU 构建与自构镜像

相关推荐

WPScan 插件版本指纹实战：从 Media Credit 的 CHANGELOG.md 看动态查找器如何识别插件版本

可信AI赋能芯片签核：从黑盒预测到可验证决策

MySQL常用函数实战指南：从字符串到窗口函数的避坑手册

更多资讯

MindSpeed LLM流式推理实战：分布式在线生成完全指南

react-native-fast-image 中移除内置 AppGlideModule：解决 Glide 单例冲突的 excludeAppGlideModule 实践

揭秘源师兄Python IDE隐藏的游戏化玩法：做任务、绑邀请码领积分，学Python更有动力

迁移 MySQL 扩展：从 mysql_* 到 mysqli 与 PDO 的升级指南（php-the-right-way）

DETR目标检测实战：从二分图匹配到端到端训练全解析

从.wasm到ESP32完整应用：运行时、固件与实操指南

今日更新

AI元人文：从工具使用到思维重构的深度探索

Python+CNN车牌识别实战：从数据预处理到模型训练与部署

Vim基础操作全攻略：保存退出、模式切换与高频命令实战

本周精选

深入解析Transformer多头注意力机制与工程优化

OpenClaw 的 Skills 跑学习任务，模型通道改到 TaoToken 通道行不行？

ChatGPT报错Oops, an error occurred! 全链路排查指南

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？