企业官网建设流程全解析

• 人工智能
• 计算机视觉
• 后端
• AI 应用

本文以 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。清单内容如下（精度数据来自该清单文档）：

对应目录结构一目了然，每个构建就是一个自包含的 compose 项目：

• custom-builds/FaceNet/docker-compose.yml
• custom-builds/Mobilenet/docker-compose.yml
• custom-builds/Mobilenet-gpu/docker-compose.yml
• custom-builds/SubCenter-ArcFace-r100/docker-compose.yml
• custom-builds/SubCenter-ArcFace-r100-gpu/docker-compose.yml
• custom-builds/Single-Docker-File/：单容器一体化构建（见第五节）

源码佐证：模型即"可插拔配置"

清单中的模型名并非随意标注。以 InsightFace 后端的识别插件为例，insightface.py 中Calculator类的ml_models元组注册了全部可选模型（模型名、Google Drive 文件 ID、距离阈值参数、batch size）：

class 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-msfdrop75"（SubCenter-ArcFace 系列，LFW 99.80%）与 "MobileFaceNet"（99.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。

三、如何选择合适的构建

官方文档给出的选型规则直接可用，核心思想是"精度差异不大，但硬件资源需求差异巨大"：

1. 实时人脸识别→ 选择支持 GPU 的构建（Mobilenet-gpu 或 SubCenter-ArcFace-r100-gpu）；
2. 老旧或低性能系统→ 选择为移动设备设计的模型（Mobilenet / MobileFaceNet 系列，InsightFace 后端）；
3. 不要盲目追求最准的模型：各模型间精度差异并不显著，但所需硬件资源可能天差地别。例如 SubCenter-ArcFace-r100 在纯 CPU 上是"最准也最慢"的组合，而 Mobilenet 是纯 CPU 模型中最快的组合。

四、运行 Custom Builds：命令与三个关键注意点

运行流程与默认构建几乎一致——进入对应构建目录，执行docker-compose up -d即可。例如使用 GPU 版 SubCenter-ArcFace：

cd custom-builds/SubCenter-ArcFace-r100-gpu docker-compose up -d

但文档特别强调了三点，实际部署时务必注意：

1. 数据卷是全新的。从 custom-build 目录启动会创建新的 docker volume，你之前保存的人脸数据不会出现在新实例里。若想带着旧数据跑 custom-build，需要把原构建目录中的文件复制到 custom-build 目录（并覆盖原文件），保证 compose 配置与既有卷定义兼容。
2. 模型通常不可互换。不同构建使用的人脸识别模型算出的 embedding 不通用：在旧构建中保存的示例/人脸，在新构建上无法直接识别。可选的迁移方案见 人脸数据迁移文档。
3. 不要不改端口就跑两个实例。若同一台机器要同时运行多个 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_PORT=3000 - 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-core（ML 端口 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:latest（BASE_IMAGE构建参数）为底座，默认UWSGI_PROCESSES=2、UWSGI_THREADS=1；
• 安装 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.py
• InsightFace 后端：embedding-calculator/src/services/facescan/plugins/insightface/insightface.py

例如 InsightFace 元组的每个元素形如('模型名', 'Google Drive 文件 ID', (阈值参数1, 阈值参数2), batch_size)，其中阈值参数对应 ArcFace 的余弦距离 margin/threshold 校准值，batch_size 控制 embedding 计算批大小（如 mobilefacenet 用 200，r100 用 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_PORT=3000

第 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_PLUGIN=insightface.FaceDetector@retinaface_r50_v1 - CALCULATION_PLUGIN=insightface.Calculator@arcface_r100_v1 - EXTRA_PLUGINS=insightface.LandmarksDetector,insightface.GenderDetector,insightface.AgeDetector,insightface.facemask.MaskDetector,insightface.PoseEstimator - BASE_IMAGE=compreface-core-base:base-cuda100-py37 - GPU_IDX=0 environment: - ML_PORT=3000

参数语义详解（均来自 embedding-calculator/README.md）：

可选插件矩阵（README 插件表）：

预训练模型清单（用插件名@模型名指定）：

• facenet.Calculator：20180402-114759（默认）、20180408-102900；
• insightface.FaceDetector：retinaface_r50_v1（默认）、retinaface_mnet025_v1、retinaface_mnet025_v2；
• insightface.Calculator：arcface_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.Dockerfile）：

docker build . -t embedding-calculator-cuda -f gpu.Dockerfile docker build . -t embedding-calculator-gpu --build-arg GPU_IDX=0 --build-arg BASE_IMAGE=embedding-calculator-cuda docker run -p 3000:3000 --gpus all embedding-calculator-gpu

宿主机需先安装 nvidia-docker2 并重启 docker（Linux）；Windows 则需 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_id=self._CTX_ID)）。这解释了为何GPU_IDX是构建期参数而非运行期参数——它被"烤"进了插件初始化逻辑。

七、贡献与问题反馈

官方鼓励社区分享自己的构建（会以 community build 名义加入清单），也鼓励对 custom-builds 报告任何 bug——因为其测试覆盖度低于默认构建。若构建过程中遇到问题，embedding-calculator 的 Troubleshooting 章节列出了两个常见坑：Windows 下 CRLF 行尾导致的构建报错（dos2unix修复）与 uWSGI 在 Windows 本地环境不可安装。

八、总结

掌握以上清单、选型规则与构建参数机制后，你可以按硬件条件在精度与吞吐之间做出有依据的取舍，并能把自有模型通过@模型名构建参数平滑接入 CompreFace 的插件体系。

• 人工智能
• 计算机视觉
• 后端
• AI 应用