把人脸识别部署在自己的网络里。
一个 Linux 容器即可提供完整的人脸识别后端：检测、比对、注册、精确 1:N 搜索和 RTSP/RTSPS 摄像头监控，并内置 Web UI、REST API 与 Python SDK。
选择适合您的模型方案
从技术验证走向生产，无需重新集成。
随着模型权利和识别精度要求提升，始终沿用同一套自托管 Server。
从验证到生产，无需重写集成
Server 与 Python SDK 采用 MIT License。生产环境可申请公开模型商业授权，或评估面向百万、千万级 1:N 底库的高精度私有模型，同时沿用现有 Server 集成。
申请商业授权一个自托管服务
架构保障私有，设计兼顾实用。
图片、特征、模型和索引都可以留在您掌控的基础设施内。多语言控制台调用的公共 API 与您的应用完全相同，且不使用 CDN、分析服务、远程字体或第三方 JavaScript。
检测
为 JPEG、PNG 和 WebP 图片返回边界框、五点关键点、检测置信度和本地质量信号。
比对
从两张图片各选取一张人脸，使用明确阈值和原始 cosine 相似度进行比对；该数值不是概率。
注册
以 Collection、Person 和 FaceSample 组织身份，支持多图片注册、审查模式和明确的拒绝原因。
搜索
执行精确全量 1:N 人员搜索。每个 Person 按高于 Collection 阈值的最强 FaceSample 匹配排序。
监控
运行持久化 RTSP 识别任务，查看最近的进入、离开、错误与恢复事件，并可选开启操作员预览。
集成
使用 Web UI、29 个 REST 接口、交互式 OpenAPI 参考文档或轻量类型化 Python 客户端。
快速开始
从拉取仓库到第一次精确搜索。
选择 CPU 或 CUDA，安装模型包并确认服务就绪，再通过 Python SDK 创建 Collection、注册人员并完成搜索。
git clone https://github.com/deepinsight/insightface.git
cd insightface
mkdir -p server/.models
export INSIGHTFACE_MODELS_UID="$(id -u)"
export INSIGHTFACE_MODELS_GID="$(id -g)"
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 \
run --rm models verify buffalo_l
docker compose -f server/deploy/compose.cpu.yml \
up -d --wait --wait-timeout 180
curl -fsS http://127.0.0.1:18097/v1/health拉取仓库并安装模型
获取 InsightFace 代码，并在 Server 镜像之外单独安装模型包。
启动一种运行环境
技术验证可选择 CPU，需要 GPU 检索和推理时选择 CUDA 12。
确认全部就绪
检查 /v1/health，并确认数据库、模型和执行 Provider 已就绪。
完成第一次搜索
创建 Collection，注册一名人员，再通过另一张图片执行 Python 搜索。
CPU
需要配备 Docker Engine 和 Docker Compose 的 Linux x86_64。适合评估和中等工作负载。
NVIDIA CUDA 12
另需支持的 NVIDIA GPU、驱动和 NVIDIA Container Toolkit。启动失败时会直接报错，不会无提示回退到 CPU。
部署边界
识别流水线
从图片到排序后的匹配结果。
控制台、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 Top-5 吞吐倍数。
| 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 |
INT8 特征量化
已发布的 MR-ALL 基准测试中，INT8 检索精度基本无损。
数据在单张 NVIDIA GeForce RTX 5090 上测得。容量是未加载 ONNX 模型或 Server 工作负载时的独立原生索引上限。速度测试使用恰好 10M 个 512 维图片向量、GPU 驻留的全量 Top-5 搜索、一个进行中查询、10 次预热和 100 次测量查询。生产部署必须为模型、请求、并发、索引重建及内存分配器预留显存。搜索在各自存储表示内是精确的，但低精度存储相较 FP32 仍可能改变分数和排序。
持久化 RTSP Monitor
不依赖浏览器的摄像头监控。
为 RTSP 或 RTSPS 视频源创建服务端 Monitor，调整推理频率与事件确认策略，然后让不同客户端轮询当前状态和近期事件。关闭控制台不会停止识别，已启用的 Monitor 会在 Server 重启后恢复。帧永不录制；近期事件容量有限且不持久化，预览默认关闭。
请将识别结果作为操作员的辅助信息，而非高影响决策的唯一依据。为每项部署明确同意、留存、删除、复核和安全事件响应策略。
运维与安全
边界清晰，便于加固。
Server 会公开私有部署运维所需的状态，同时确保密钥、图片、特征和凭据不会进入诊断信息。
InsightFace Server 已内置
就绪状态与诊断
检查服务、数据库、模型、Provider、容量和近期安全错误摘要。
CUDA 快速失败
启动时验证实际 Provider、Session、库、GPU 兼容性和预热推理。
持久化数据边界
模型保持只读，/data 持久化，并从 SQLite 重建可丢弃的精确索引。
受保护的凭据
对 API Key 进行哈希处理，在 /data 中加密 RTSP 凭据，并从响应中脱敏数据源。
仅 API 模式
关闭控制台和指南，同时为私有服务保留 /v1 与 /openapi.json。
补齐生产环境边界
随附的 Compose 配置面向隔离环境中的技术验证。对外提供生产服务前，请按网络架构与治理要求补齐部署控制。
实施指南
从首个容器到可用集成。
先通过精简的快速开始完成首次私有部署；准备连接应用后，再进入 API 与 Python SDK 工作流。
常见问题
规划您的部署与模型授权。
从技术验证走向生产前，团队最常关心的问题。
InsightFace Server 可以免费使用吗？+
Server 源代码和 Python SDK 采用 MIT License。模型文件具有独立条款，因此代码可用并不代表自动获得模型商业使用权。
Server 容器是否包含识别模型？+
不包含。模型包需要单独安装和验证，从而明确记录模型身份、版本与授权状态。
InsightFace 公开预训练模型可以商用吗？+
公开预训练模型包通常仅限非商业学术研究；商业使用需要 InsightFace 单独授予商业许可。
使用私有模型或商业授权模型需要重新开发吗？+
不需要。已授权模型继续使用同一套 Server、Web UI、REST API、Python SDK、manifest 和安装流程。
InsightFace Server 可以离线运行吗？+
可以。容器镜像和模型包安装完成后，Server 的正常启动与运行可以保持在您的离线基础设施内。
58.9M 容量代表什么？+
它是单张 RTX 5090 上 512 维 INT8 图片向量的原生索引实测上限，不代表 5890 万人，也不代表完整 API 的端到端容量。
1:N 搜索是精确搜索还是近似搜索？+
在所选存储表示内执行全量精确平面搜索，不使用近似最近邻索引。
支持哪些部署硬件？+
随附部署面向 Linux x86_64，可使用本地 CPU 推理，或通过 CUDA 12 运行在受支持的 NVIDIA GPU 上。