人脸识别基础设施 始终留在您的网络内。
在一个自托管 Linux 服务中掌控完整的人脸识别技术栈——通过 Web UI、REST API 和 Python SDK 完成人脸检测、比对、注册、精确 1:N 搜索与持久化 RTSP 监控。单张 RTX 5090 的 INT8 实测中，搜索容量可扩展至 5890 万个图片向量，并在 1000 万向量下实现 3.84 ms 的 Top-5 延迟。
一个自托管服务
架构保障私有，设计兼顾实用。
图片、特征、模型和索引都可以留在您掌控的基础设施内。多语言控制台调用的公共 API 与您的应用完全相同，且不使用 CDN、分析服务、远程字体或第三方 JavaScript。
检测
为 JPEG、PNG 和 WebP 图片返回边界框、五点关键点、检测置信度和本地质量信号。
比对
从两张图片各选取一张人脸，使用明确阈值和原始 cosine 相似度进行比对；该数值不是概率。
注册
以 Collection、Person 和 FaceSample 组织身份，支持多图片注册、审查模式和明确的拒绝原因。
搜索
执行精确全量 1:N 人员搜索。每个 Person 按高于 Collection 阈值的最强 FaceSample 匹配排序。
监控
运行持久化 RTSP 识别任务，查看最近的进入、离开、错误与恢复事件，并可选开启操作员预览。
集成
使用 Web UI、29 个 REST 接口、交互式 OpenAPI 参考文档或轻量类型化 Python 客户端。
识别流水线
从图片到排序后的匹配结果。
控制台、REST API、Python SDK 和 RTSP Monitor 均遵循同一套明确的处理契约。
图片或 RTSP 帧
JPEG、PNG、WebP，或实时摄像头的最新一帧。
多分辨率 SCRFD
检测人脸、合并候选结果，并执行一次全局 NMS。
对齐并提取特征
五点对齐、ArcFace 特征提取和 L2 normalization。
绑定模型的 Collection
固定模型、预处理、检测器、阈值和容量。
精确 CPU/GPU 搜索
对所选 profile 中每个有效 FaceSample 进行全量打分。
Person 匹配
返回按原始 cosine 分数排序的人员以及请求 ID。
SQLite 始终是事实来源
持久化数据库是事实来源；内存精确索引只是可重建的投影。注册结果会在成功响应返回前加入索引，删除操作也会同时从两处存储中移除数据。
明确的身份契约
Collection 清晰划分模型、策略与数据边界。
每个 Collection 都固定模型身份、预处理版本、特征维度、检测器策略、搜索 profile、容量和匹配阈值。该契约可防止模型或运行时变化时发生无提示混用。
- 为每个 Person 添加多个 FaceSample，并查看部分注册结果，避免整个批次因个别失败而丢失。
- 选择 off、standard 或 strict 审查模式，执行人脸数量、尺寸、清晰度、亮度、姿态及同一人员一致性检查。
- 通过 Collection 的 embedding contract 连接可信上游特征流水线；图片仍需经过检测与审查。
- 可为每张已接受的人脸选择性保存一张 112×112 边界框裁剪图。原始上传图片和用于识别的对齐输入均不会保留。
实测搜索性能
单 GPU 规模的精确搜索。
原生全量搜索 profile 让您在不切换到近似最近邻索引的情况下，权衡向量精度、容量与吞吐。
单张 RTX 5090 上 512 维向量的实测最大值。
在恰好 10M 个向量、仅一个进行中查询的条件下测得。
10M 个向量下实测的全量 Top-5 搜索吞吐。
同一张 GPU 上实测的 INT8 容量倍数。
| GPU 数据类型 | 最大向量数 | 10M Top-5 p50 | 10M 串行 QPS |
|---|---|---|---|
| FP32 | 15.8M | 12.84 ms | 77.85 |
| FP16 | 30.7M | 6.83 ms | 146.32 |
| BF16 | 30.7M | 6.83 ms | 146.33 |
| INT8 | 58.9M | 3.84 ms | 260.81 |
FP32 与 INT8 均为 91.25%
在 ICCV21-MFR MR-ALL、FAR 1e-6 条件下，两种 profile 精确到小数点后两位均为 91.25%。INT8 相比 FP32 的未取整差异为 −0.001102 个百分点。
数据在单张 NVIDIA GeForce RTX 5090 上测得。容量是未加载 ONNX 模型或 Server 工作负载时的独立原生索引上限。速度测试使用恰好 10M 个 512 维图片向量、GPU 驻留的全量 Top-5 搜索、一个进行中查询、10 次预热和 100 次测量查询。生产部署必须为模型、请求、并发、索引重建及内存分配器预留显存。搜索在各自存储表示内是精确的，但低精度存储相较 FP32 仍可能改变分数和排序。
持久化 RTSP Monitor
不依赖浏览器的摄像头监控。
创建服务端 RTSP Monitor，调整推理频率与事件确认策略，然后让不同客户端轮询当前状态和近期事件。关闭控制台不会停止识别，已启用的 Monitor 会在 Server 重启后恢复。帧永不录制；近期事件容量有限且不持久化，预览默认关闭。
请将识别结果作为操作员的辅助信息，而非高影响决策的唯一依据。为每项部署明确同意、留存、删除、复核和安全事件响应策略。
Docker 部署
选择 CPU 轻松起步，或使用 CUDA 12 扩展规模。
请从完整的 InsightFace 仓库 checkout 运行。宿主机无需安装 Python、OpenCV、ONNX Runtime、CUDA Toolkit 或 cuDNN；容器自带运行时，模型则作为独立的许可安装内容。
mkdir -p server/.models
docker compose -f server/deploy/compose.cpu.yml pull
docker compose -f server/deploy/compose.cpu.yml \
run --rm models install buffalo_l --accept-license
docker compose -f server/deploy/compose.cpu.yml up -d
curl -fsS http://127.0.0.1:18097/v1/healthCPU
需要配备 Docker Engine 和 Docker Compose 的 Linux x86_64。适合评估和中等工作负载。
NVIDIA CUDA 12
另需支持的 NVIDIA GPU、驱动和 NVIDIA Container Toolkit。启动失败时会直接报错，不会无提示回退到 CPU。
部署边界
运维与安全
边界清晰，便于加固。
Server 会公开私有部署运维所需的状态，同时确保密钥、图片、特征和凭据不会进入诊断信息。
就绪状态与诊断
检查服务、数据库、模型、Provider、容量和近期安全错误摘要。
CUDA 快速失败
启动时验证实际 Provider、Session、库、GPU 兼容性和预热推理。
持久化数据边界
模型保持只读，/data 持久化，并从 SQLite 重建可丢弃的精确索引。
受保护的凭据
对 API Key 进行哈希处理，在 /data 中加密 RTSP 凭据，并从响应中脱敏数据源。
仅 API 模式
关闭控制台和指南，同时为私有服务保留 /v1 与 /openapi.json。
接入网络前请先完成安全加固
随附的 Compose 配置为隔离评估而关闭认证。此版本在容器内提供明文 HTTP、单一且不区分权限的 API Key，不内置用户账户、RBAC、IAM、限流器、TLS 或法律合规层；也不提供活体检测、深度伪造检测、人口属性分析、录像/NVR 或分布式 Worker。请启用认证，在可信反向代理终止 HTTPS，限制 CORS 和网络访问，在边缘设置速率、请求体与超时限制，并将数据卷和备份作为生物特征数据加以保护。
实施指南
从首个容器到可用集成。
先通过精简的快速开始完成首次私有部署；准备连接应用后，再进入 API 与 Python SDK 工作流。