InsightFace Server 实战指南从 Docker 部署到人脸注册、搜索与 RTSP 监控【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightfaceInsightFace Server 是 InsightFace 项目提供的自托管人脸分析服务围绕检测 → 注册 → 搜索这条主线将 SCRFD 人脸检测、ArcFace 识别模型、SQLite 持久化与向量索引封装成一套可直接运行的服务同一套能力同时暴露在 Web 界面、/v1REST API 与 Python SDK 中。本文以 server/docs/user-guide.fr.md 为骨架结合 server/config/server.toml、server/backend/insightface_server 源码与 server/deploy 部署文件完整讲解从空目录启动服务、创建 Collection、注册 Person、执行检测/比较/搜索、接入 RTSP 摄像头监控到数据安全、模型许可、GPU 运行与故障排查的端到端流程。读完本文你将能够独立部署并运维一个可用于内部评估与非商业研究的人脸搜索服务并理解其底层实现原理。1. 环境要求与从零到第一次搜索1.1 硬件与软件前提根据官方用户指南部署分为 CPU 与 CUDA 两条路径CPU 版需要 Linux x86_64、Docker Engine 与 Docker ComposeCUDA 版在 CPU 基础上额外要求兼容的 NVIDIA 驱动与 NVIDIA Container Toolkit但宿主机上无需安装 CUDA、cuDNN、ONNX Runtime、Python 或 OpenCV——这些全部封装在镜像内部。1.2 五分钟跑通第一个搜索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 docker compose -f server/deploy/compose.cpu.yml up -d curl -fsS http://127.0.0.1:18097/v1/health依次解释每个步骤mkdir -p server/.models准备模型目录。镜像不包含任何模型启动时保持完全离线模型需要显式安装详见第 9 节docker compose ... pull拉取服务镜像。CPU 镜像 tag 为0.2.0-cpurun --rm models install buffalo_l以一次性服务方式运行模型安装器下载并校验buffalo_l模型包up -d以后台模式启动主服务CPU 版将容器内8080端口映射到宿主18097curl .../v1/health健康检查。就绪时返回{status:ready, ...}。GPU 部署只需把 compose 文件换成compose.cuda12.yml端口变为18098。安装器在下载前会展示模型许可证LicenseInsightFace 公开预训练模型仅限非商业研究用途商业使用需要另行获取独立许可。1.3 认证默认关闭的警告提供的 Compose 文件为了便于隔离环境评估默认关闭了认证INSIGHTFACE_AUTH_ENABLED默认false。在将服务暴露到任何网络之前务必设置export INSIGHTFACE_AUTH_ENABLEDtrue export INSIGHTFACE_API_KEY一个足够长的随机字符串 docker compose -f server/deploy/compose.cpu.yml up -d随后在 Web 界面验证 Dashboard、创建 Collection、注册 Person再用另一张图片完成搜索。需要停止服务时使用docker compose ... down不要加-v否则会删除保存数据的 volume。2. 连接、健康检查与运行状态2.1 访问入口CPUhttp://服务器地址:18097/CUDA 12http://服务器地址:18098/若已启用认证浏览器会提示选择Configurer la clé API配置 API 密钥粘贴INSIGHTFACE_API_KEY后应用到当前标签页。该密钥只保存在浏览器内存中刷新或关闭页面即消失不会写入本地存储。2.2 状态检查在Tableau de bord仪表盘或Système系统页面确认四类就绪状态service服务、base数据库、modèles模型、Provider推理后端。CUDA 部署必须显示CUDAExecutionProvider且绝不静默回退到 CPU——这一点在源码中有硬性保证INSIGHTFACE_STRICT_CUDA1环境变量见 compose.cuda12.yml配合启动自检任一环节GPU、驱动、CUDA/cuDNN/ORT 版本、Provider、实际 Session、warm-up不通过即拒绝启动。对应/v1/health接口实现在 app.py就绪返回200 ready进程存活但未就绪返回503 not_ready并附带version与auth_enabled字段。3. 创建 Collection核心概念与配置Collection集合是人脸搜索的逻辑容器相当于一个被搜索的人脸库。3.1 创建参数在Collections→Nouvelle collection新建集合中配置参数说明默认值ID稳定的标识符创建后不可随意变更必填Nom名称展示名称—Seuil cosinus余弦阈值判定匹配的相似度下界0.4Profil检测 profile检测策略见 3.3系统默认Capacité容量Collection 可容纳的 FaceSample 行数100000FaceSamples max / personne每个人最多登记的样本数20其中0.4这一默认阈值来自 compose 中的INSIGHTFACE_DEFAULT_THRESHOLD环境变量见 compose.cpu.yml且阈值由系统或 Collection 决定不允许在请求级覆盖——/v1/detect、/v1/search中的min_score/face_selection等旧参数若被传入会直接返回request_detection_override_not_supported错误见 app.py。JPEG 裁剪保存bounding-box crop缩放为 112×112默认关闭需要说明的是这个裁剪不是识别模型的输入——识别输入是经过人脸对齐landmark 对齐后的标准图像裁剪仅用于人工复核。3.2 Collection 与模型的契约绑定Collection 在创建时被绑定到当前模型的五项契约model_id、model_version、model_digest模型摘要、embedding_dimension向量维度、preprocessing_version预处理版本。这在 core.py 的collection()方法中逐项比对契约一致 → 正常提供服务契约不一致 → 返回409 collection_model_mismatchCollection 仍然可见但拒绝注册与搜索必须重建或迁移。这意味着更换识别模型后旧 Collection 不会悄悄用新模型继续工作从而保证向量语义的一致性。3.3 检测 Profile从系统默认到按 Collection 定制检测 profile 在创建 Collection 时复制系统当前值之后可独立修改输入尺寸input_sizesSCRFD 动态模型会在每个配置的分辨率上分别运行检测检测阈值threshold候选框生成的置信度门槛NMS 阈值nms_threshold合并候选框的 IoU 门槛单脸选择策略single_face_selection需要选一个脸的操作比较、搜索、注册如何挑脸largest优先面积最大的脸center_largest最大化面积 − 2.0 × 人脸框中心到图像中心像素距离的平方这一得分源码常量CENTER_LARGEST_DISTANCE_WEIGHT 2.0见 core.py。检测置信度不参与该得分。4. 启动配置 server.toml 详解server/config/server.toml是唯一的启动配置文件只在进程启动时读取一次任何修改都需要重启容器。完整内容如下# InsightFace Server settings loaded once during process startup. # Restart the container after changing this file. [inference] # auto resolves to 4 concurrent model pipelines on CPU and 8 on CUDA. # A positive integer overrides the provider-specific default. API calls, # enrollment and RTSP frames share this one process-wide budget. max_concurrency auto [detection] # Each entry is [width, height]. Dynamic SCRFD models run every configured # resolution, map all candidates to source-image coordinates, then apply one # global NMS pass to the merged candidate set. input_sizes [[96, 96], [512, 512]] # Minimum detector confidence. It is applied while SCRFD candidates are # generated, before the merged NMS pass. threshold 0.50 # IoU threshold used by the single global NMS pass. nms_threshold 0.40 # Used by operations that require one face. Supported values: # largest and center_largest. The latter maximizes the pixel-space score # area - 2.0 * squared_distance(face_box_center, image_center). single_face_selection largest # Deployment-wide safety limit. A request may ask for fewer results, never more. max_detected_faces 100 [web] # false (default): serve the Web UI, interactive API reference and guides. # true: API-only mode; keep /v1 and /openapi.json, but do not register UI routes. disabled false4.1 各配置项的行为与底层约束结合 config.py 的实现这些参数有严格的校验规则input_sizes最多 4 组[宽, 高]每条边必须在 322048 之间且必须是 32 的倍数SCRFD 最大特征图步长为 32总像素数不超过 4M不允许重复。校验逻辑见normalize_detector_input_sizesconfig.pythreshold/nms_threshold必须是 0.01.0 的有限数值max_detected_faces1100 的整数是全部署的硬性安全上限——请求可以要求更少结果但永远不能超过它max_concurrency取auto时CPU 为 4 路并发、CUDA 为 8 路常量见 config.py也可显式指定 1256 的整数。API 调用、注册和 RTSP 帧共享这一个进程级推理预算[web].disabled true只保留/v1与/openapi.json不再注册 Web UI、交互式 API 文档和指南路由实现见 app.py。4.2 SCRFD 多分辨率检测流程文档明确描述了检测管线SCRFD 在每个配置的分辨率上各执行一次推理把所有候选框重新投影到源图像坐标再对合并后的候选集执行一次全局 NMS。这一多分辨率互补的设计让 96×96 的小分辨率负责快速发现小脸、512×512 负责高精度召回最后统一去重。4.3 Compose 环境变量总览compose.cpu.yml 与 compose.cuda12.yml 中暴露的全部可调环境变量均带默认值环境变量默认值含义INSIGHTFACE_AUTH_ENABLEDfalse是否启用 API 密钥认证INSIGHTFACE_CONFIG_FILE/etc/insightface/server.toml启动配置文件路径INSIGHTFACE_API_KEY空启动密钥哈希后存储INSIGHTFACE_CORS_ORIGINS空允许的跨域来源逗号分隔INSIGHTFACE_LOG_LEVELINFO日志级别INSIGHTFACE_SAVE_FACE_CROPSfalse是否保存 112×112 人脸裁剪INSIGHTFACE_DEFAULT_THRESHOLD0.4默认相似度阈值INSIGHTFACE_COLLECTION_DEFAULT_SEARCH_PROFILEfp32_v1新建 Collection 的默认搜索 profileINSIGHTFACE_COLLECTION_DEFAULT_CAPACITY_ROWS100000默认容量INSIGHTFACE_COLLECTION_MAX_CAPACITY_ROWS10000000容量安全阀INSIGHTFACE_COLLECTION_DEFAULT_MAX_FACES_PER_PERSON20每人默认最大样本数INSIGHTFACE_COLLECTION_DEFAULT_LOAD_POLICYlazy索引加载策略eager/lazyINSIGHTFACE_SEARCH_DEVICE_ID0搜索使用的 GPU 设备号INSIGHTFACE_SEARCH_TOPK_MODEautotop-k 计算位置auto/host/deviceINSIGHTFACE_SEARCH_BUILD_BATCH_ROWS4096索引构建批量行数INSIGHTFACE_INFERENCE_MODEonnx推理模式onnx/mockINSIGHTFACE_EXECUTION_PROVIDERCPU 版CPUExecutionProviderCUDA 版CUDAExecutionProvider推理后端CUDA 版额外设置INSIGHTFACE_STRICT_CUDA1、NVIDIA_VISIBLE_DEVICESall、NVIDIA_DRIVER_CAPABILITIEScompute,utility与CUDA_MODULE_LOADINGLAZY。此外 config.py 还支持一批未在 compose 中暴露的变量如INSIGHTFACE_MAX_IMAGE_BYTES10MB、INSIGHTFACE_MAX_IMAGE_PIXELS4000万、INSIGHTFACE_MAX_REGISTRATION_IMAGES20、INSIGHTFACE_REQUEST_TIMEOUT_SECONDS60、INSIGHTFACE_RTSP_MAX_STREAMS4等可按需自行注入。5. 注册 Person三种审核模式与外部可信向量在Personnes人员页面选择 Collection 后可Inscrire une personne注册人员填写可选的 ID、姓名、外部 IDexternal_id、JSON metadata并上传一张或多张JPEG、PNG 或 WebP图片。5.1 review_mode 三种模式模式行为off使用 Collection 的单脸选择策略允许多张脸的场景下按策略选脸不做额外质量控制standard强制要求一个可用的脸并检查尺寸、检测置信度、清晰度、亮度与姿态strict在 standard 基础上进一步要求类内最佳相似度 类外最佳相似度防撞脸注册standard的具体判定标准在源码_registration_reasoncore.py中可见人脸短边 registration_min_face_size默认 40 像素→face_too_small检测置信度 registration_min_score默认 0.6→low_detection_scoreyaw/pitch/roll 任一绝对值 45° →extreme_pose质量分 registration_min_quality默认 0.35→low_quality。strict的类内/类外比较在_strict_registration_reviewcore.py中实现对每个新样本计算与同人已有样本的最高相似度类内再通过索引查询其他 Person 的最佳相似度类外若类内 ≤ 类外则拒绝并返回identity_similarity_conflict附带两侧相似度与命中的other_person_id。整个判定在 Collection 写锁内完成防止并发注册改变类外最大值。5.2 批量注册与数据存储批次允许部分成功每个被拒绝的图片都会返回index、filename、reason及附加细节原始上传图像不存储只保存派生出的向量、边界框、五点 landmarks、质量分等每人的 FaceSample 上限由max_faces_per_person控制超出返回409 person_face_limit_exceededCollection 容量超限返回409 collection_capacity_exceeded。5.3 external_trusted接受外部可信向量embedding_modeexternal_trusted允许调用方直接提交已由外部系统计算的向量向量必须是已做 L2 归一化的、维度与 Collection 契约一致默认 512 维的有限浮点数组源码通过_trusted_embeddingcore.py校验并重新归一化图片仍然必须上传因为检测器、landmarks 与质量检查仍会运行但识别器不会再次提取向量必须同时提供embedding_contract_id且与 Collection 绑定的契约一致否则返回409 embedding_contract_mismatch。6. 检测、比较与搜索6.1 Detect检测/v1/detect返回边界框bounding box、五点 landmarks、检测得分与质量分。没有检测到人脸时返回合法的空列表而不是报错。6.2 Compare比较/v1/compare使用系统或 Collection 的检测 profile 为每张图片各选一个脸返回三个关键字段app.pysimilarity余弦相似度实现为clip(dot(a, b), -1, 1)见 core.pythreshold生效阈值请求显式传入否则取系统/Collection 默认matchedsimilarity threshold的布尔结果。相似度不是概率它没有校准到 01 的概率语义只是一个余弦得分matched完全由阈值决定。6.3 Search搜索在Rechercher搜索中选择 Collection 与图片一个Person 的得分 其所有 FaceSample 中的最佳相似度结果按相似度降序排列无命中时返回空列表每次搜索先对查询图选脸、提取向量再执行索引查询见FaceService.searchcore.py。6.4 写入与索引的一致性保障写入路径遵循先 SQLite 后索引的顺序每个 FaceSample 先在 SQLite 中提交再追加到搜索索引最后才返回响应。因此请求返回成功即意味着数据已持久化若索引构建失败服务返回503 search_index_unavailable并在后台重建SearchMutationCommittedError会明确告知写入已提交、索引追赶失败见 search/manager.py。重启后索引完全从 SQLite 重建SQLite 是唯一事实来源。6.5 搜索 Profile精确扫描而非 ANNCollection 创建时固定 search profile不可按请求选择。/v1/system只公布当前部署实际可用的 profileSUPPORTED_SEARCH_PROFILES见 config.pyProfile说明fp32_v1CPU/CUDA 标准 FP32fp16_v1CUDA 半精度bf16_v1兼容 CPU 或 CUDA SM80int8_x736_v1INT8 量化推荐用于 CPU/CUDAINT32 累加int8_x1000_v1为既有 Collection 提供兼容性的早期量化所有 profile 都会逐条遍历每个 FaceSample 做精确比较不是 ANN 近似索引公开得分保持为 raw cosine。INT8 的量化在 search/reference.py 中定义int8_x1000_v1的 scale 为 1000、int8_x736_v1为 736向量先乘 scale 再四舍五入到[-128, 127]比较时在 INT32 域内累加quantize_int8见 reference.py。存储体积估算512 维每行FP32 约2048 字节、FP16/BF16 约1024 字节、INT8 约512 字节。索引生命周期由状态机管理UNLOADED → BUILDING → READY → DIRTY → REBUILDING ...见 search/manager.py。7. RTSP 摄像头监控Surveillance caméra摄像头监控允许把一路 RTSP 视频流接入系统做持续人脸识别。7.1 配置项创建持久化的Monitor配置source RTSP视频流地址Collection要搜索的人脸库fréquence推理频率inference_fps即每秒推理次数seuil阈值可选覆盖 Collection 默认阈值politique dévénements事件策略包括确认帧数confirm_frames、缺席超时absence_timeout_seconds、冷却时间cooldown_seconds、是否上报陌生人emit_unknown等完整字段见 rtsp.py。7.2 预览与 /state预览默认关闭关闭时识别与事件照常运行只是不产生预览画面预览开启后Web UI 通过/state接口在原始帧上叠加标记绿色 已注册人员橙色 陌生人实时预览走preview.mjpegMotion JPEG 流见 app.py。7.3 运行模型与数据边界Monitor独立于浏览器运行即使没有任何客户端连接识别照常执行服务重启后自动恢复活跃任务Monitor 配置保存在SQLite中RTSP 凭据在/data下加密存储——具体由SecretCodec用 32 字节随机密钥、AES-GCM 算法加 scope 关联数据加密见 secrets.py图像与事件不落盘事件只保留在有界的内存缓冲区中解码器只保留最新一帧旧帧直接丢弃而不是排队堆积next_inference_time也明确绝不调度追赶性推理见 rtsp.pyRTSP 源在展示/日志中会被脱敏redacted_rtsp_source只保留 scheme、主机、端口与路径剥离凭据与查询参数rtsp.py。监控的搜索路径复用search_all_facescore.py单帧检测一次、逐脸查询、每张脸取limit1的最佳匹配且流状态中不暴露向量。8. 数据持久化与安全最佳实践8.1 卷与备份持久化/dataSQLite 数据库、游标密钥、监控凭据密钥都在其中/models只读挂载模型目录不允许被运行时进程写入备份SQLite 与裁剪图crops必须一起备份因为两者互相关联大规模操作前务必先备份。8.2 密钥管理API 密钥以哈希形式存储使用同一数据卷但更换INSIGHTFACE_API_KEY重启后活动密钥自动轮换旧密钥失效新密钥生效绝不记录图像、向量embeddings与密钥都不允许写入日志。8.3 传输与错误处理每次响应都带x-request-id中间件为每个请求生成 UUID见 app.py排查问题时务必携带该 ID所有响应统一附加安全头X-Content-Type-Options: nosniff、X-Frame-Options: DENY、Referrer-Policy: no-referrer、Permissions-Policy禁用摄像头/麦克风/定位以及严格的Content-Security-Policy常见错误码401API 密钥无效或缺失409 collection_model_mismatch请求的 Collection 与当前模型契约不符422 face_not_found图片中没有可用的人脸。开发者可访问/docs查看 OpenAPI schema 浏览器仅当[web].disabledfalse时注册面向任务流的 API 说明见 api.fr.md。9. 模型包与许可证9.1 模型安装器镜像不内置模型正常启动保持离线。通过一次性models服务安装到server/.modelsdocker 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安装器还支持list列出支持包与安装状态与info显示包来源、哈希与许可命令解析见 models_cli.py。9.2 支持的模型包包名检测模型识别模型buffalo_ldet_10g.onnxw600k_r50.onnx512 维buffalo_mdet_2.5g.onnxw600k_r50.onnxbuffalo_scdet_500m.onnxw600k_mbf.onnxantelopev2scrfd_10g_bnkps.onnxglintr100.onnx完整目录含每个文件的 SHA-256、输入尺寸、预处理版本、embedding 维度定义在 models/packages.py。9.3 校验与许可证机制安装流程下载 →校验压缩包 SHA-256archive_sha256→ 解压时逐文件校验 SHA-256→ 生成manifest.json与签名文件MODEL.LICENSE不传--accept-license时交互式终端会提示确认非交互环境直接中止报错提示必须加--accept-licensemodels_cli.pyverify子命令会验证模型文件、manifest 与签名许可证输出许可证 ID、授权范围Grant、有效期与Commercial use: PERMITTED/NOT PERMITTED结论InsightFace 公开预训练模型保留为非商业研究用途商业使用需要单独的许可。10. Python SDK、镜像构建与版本管理10.1 Python SDKSDK 接受路径、bytes 与文件对象三种输入提供类型化方法覆盖 Detect、Compare、Collections、人员注册、Search 与 Monitors 全流程。HTTP 契约细节以 api.fr.md 为准SDK 源码位于 server/sdk/python。10.2 从源码构建镜像任何用户都可以从完整仓库构建make -C server build-cpu make -C server build-cuda12对应 Makefile 目标server/Makefile分别以--platform linux/amd64构建 CPU 与 CUDA 12 镜像。构建后如需使用本地镜像而非拉取远端给 Compose 命令加--pull never。10.3 版本与升级不可变 tag0.2.0-cpu与0.2.0-cuda12指向固定版本浮动 tagcpu与cuda12跟随最新稳定版不发布latest升级前停止写入 → 用对 SQLite 安全的方式备份/data与裁剪图严禁docker compose down -v它会删除数据 volume。11. GPU 运行、网络暴露与故障排查11.1 CUDA 镜像技术栈与驱动要求CUDA 12 镜像包含CUDA Runtime 12.9.1、cuDNN 9.24.0、onnxruntime-gpu1.27.0。驱动版本要求按 GPU 架构Turing / Ampere / Ada / HopperR535 或更高Blackwell / RTX 50 系列570.26 或更高推荐稳定版 R580 或更新。启动时自检覆盖GPU 可见性、Compute Capability、驱动版本、CUDA/cuDNN/ORT 版本、Execution Provider、实际创建的 Session 数量与 warm-up 结果——任何一步失败都拒绝启动绝不静默回退 CPU。11.2 网络暴露清单将服务暴露到外网前用可靠的反向代理终结 HTTPS限制CORSINSIGHTFACE_CORS_ORIGINS、速率、请求体大小与超时max_request_bytes默认 64MB、request_timeout_seconds默认 60s将/data与备份按生物识别数据标准保护日志中永不出现图像、向量或密钥。11.3 能力边界Phase 1当前阶段Phase 1只支持单一 API Key无角色role体系不是多租户授权系统。若需要多租户隔离与细粒度权限需要在其上自行实现授权层。12. 常见问题速查现象排查方向/v1/health返回 503服务仍在启动中模型加载/索引构建稍后重试401API 密钥缺失或不匹配确认INSIGHTFACE_AUTH_ENABLEDtrue且 Key 与卷内哈希一致409 collection_model_mismatch更换过模型包旧 Collection 契约不匹配需重建或迁移422 face_not_found图片无人脸或人脸不满足质量/尺寸/姿态门槛standard/strict模式413 request_too_large请求体超过max_request_bytes503 request_timeout超过request_timeout_seconds留意推理并发是否被打满重启后搜索变慢索引从 SQLite 重建中lazy策略下按需加载CUDA 版意外走 CPU检查启动日志自检项与INSIGHTFACE_STRICT_CUDA1更详细的运维口径可继续阅读 maintainer-guide.md。结合本文的部署命令、配置项与源码依据你可以把 InsightFace Server 作为内部评估、原型验证与非商业研究的基础设施并依据第 8 节与第 11 节的安全清单把它可靠地接入你的网络环境。【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
InsightFace Server 实战指南：从 Docker 部署到人脸注册、搜索与 RTSP 监控
InsightFace Server 实战指南从 Docker 部署到人脸注册、搜索与 RTSP 监控【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightfaceInsightFace Server 是 InsightFace 项目提供的自托管人脸分析服务围绕检测 → 注册 → 搜索这条主线将 SCRFD 人脸检测、ArcFace 识别模型、SQLite 持久化与向量索引封装成一套可直接运行的服务同一套能力同时暴露在 Web 界面、/v1REST API 与 Python SDK 中。本文以 server/docs/user-guide.fr.md 为骨架结合 server/config/server.toml、server/backend/insightface_server 源码与 server/deploy 部署文件完整讲解从空目录启动服务、创建 Collection、注册 Person、执行检测/比较/搜索、接入 RTSP 摄像头监控到数据安全、模型许可、GPU 运行与故障排查的端到端流程。读完本文你将能够独立部署并运维一个可用于内部评估与非商业研究的人脸搜索服务并理解其底层实现原理。1. 环境要求与从零到第一次搜索1.1 硬件与软件前提根据官方用户指南部署分为 CPU 与 CUDA 两条路径CPU 版需要 Linux x86_64、Docker Engine 与 Docker ComposeCUDA 版在 CPU 基础上额外要求兼容的 NVIDIA 驱动与 NVIDIA Container Toolkit但宿主机上无需安装 CUDA、cuDNN、ONNX Runtime、Python 或 OpenCV——这些全部封装在镜像内部。1.2 五分钟跑通第一个搜索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 docker compose -f server/deploy/compose.cpu.yml up -d curl -fsS http://127.0.0.1:18097/v1/health依次解释每个步骤mkdir -p server/.models准备模型目录。镜像不包含任何模型启动时保持完全离线模型需要显式安装详见第 9 节docker compose ... pull拉取服务镜像。CPU 镜像 tag 为0.2.0-cpurun --rm models install buffalo_l以一次性服务方式运行模型安装器下载并校验buffalo_l模型包up -d以后台模式启动主服务CPU 版将容器内8080端口映射到宿主18097curl .../v1/health健康检查。就绪时返回{status:ready, ...}。GPU 部署只需把 compose 文件换成compose.cuda12.yml端口变为18098。安装器在下载前会展示模型许可证LicenseInsightFace 公开预训练模型仅限非商业研究用途商业使用需要另行获取独立许可。1.3 认证默认关闭的警告提供的 Compose 文件为了便于隔离环境评估默认关闭了认证INSIGHTFACE_AUTH_ENABLED默认false。在将服务暴露到任何网络之前务必设置export INSIGHTFACE_AUTH_ENABLEDtrue export INSIGHTFACE_API_KEY一个足够长的随机字符串 docker compose -f server/deploy/compose.cpu.yml up -d随后在 Web 界面验证 Dashboard、创建 Collection、注册 Person再用另一张图片完成搜索。需要停止服务时使用docker compose ... down不要加-v否则会删除保存数据的 volume。2. 连接、健康检查与运行状态2.1 访问入口CPUhttp://服务器地址:18097/CUDA 12http://服务器地址:18098/若已启用认证浏览器会提示选择Configurer la clé API配置 API 密钥粘贴INSIGHTFACE_API_KEY后应用到当前标签页。该密钥只保存在浏览器内存中刷新或关闭页面即消失不会写入本地存储。2.2 状态检查在Tableau de bord仪表盘或Système系统页面确认四类就绪状态service服务、base数据库、modèles模型、Provider推理后端。CUDA 部署必须显示CUDAExecutionProvider且绝不静默回退到 CPU——这一点在源码中有硬性保证INSIGHTFACE_STRICT_CUDA1环境变量见 compose.cuda12.yml配合启动自检任一环节GPU、驱动、CUDA/cuDNN/ORT 版本、Provider、实际 Session、warm-up不通过即拒绝启动。对应/v1/health接口实现在 app.py就绪返回200 ready进程存活但未就绪返回503 not_ready并附带version与auth_enabled字段。3. 创建 Collection核心概念与配置Collection集合是人脸搜索的逻辑容器相当于一个被搜索的人脸库。3.1 创建参数在Collections→Nouvelle collection新建集合中配置参数说明默认值ID稳定的标识符创建后不可随意变更必填Nom名称展示名称—Seuil cosinus余弦阈值判定匹配的相似度下界0.4Profil检测 profile检测策略见 3.3系统默认Capacité容量Collection 可容纳的 FaceSample 行数100000FaceSamples max / personne每个人最多登记的样本数20其中0.4这一默认阈值来自 compose 中的INSIGHTFACE_DEFAULT_THRESHOLD环境变量见 compose.cpu.yml且阈值由系统或 Collection 决定不允许在请求级覆盖——/v1/detect、/v1/search中的min_score/face_selection等旧参数若被传入会直接返回request_detection_override_not_supported错误见 app.py。JPEG 裁剪保存bounding-box crop缩放为 112×112默认关闭需要说明的是这个裁剪不是识别模型的输入——识别输入是经过人脸对齐landmark 对齐后的标准图像裁剪仅用于人工复核。3.2 Collection 与模型的契约绑定Collection 在创建时被绑定到当前模型的五项契约model_id、model_version、model_digest模型摘要、embedding_dimension向量维度、preprocessing_version预处理版本。这在 core.py 的collection()方法中逐项比对契约一致 → 正常提供服务契约不一致 → 返回409 collection_model_mismatchCollection 仍然可见但拒绝注册与搜索必须重建或迁移。这意味着更换识别模型后旧 Collection 不会悄悄用新模型继续工作从而保证向量语义的一致性。3.3 检测 Profile从系统默认到按 Collection 定制检测 profile 在创建 Collection 时复制系统当前值之后可独立修改输入尺寸input_sizesSCRFD 动态模型会在每个配置的分辨率上分别运行检测检测阈值threshold候选框生成的置信度门槛NMS 阈值nms_threshold合并候选框的 IoU 门槛单脸选择策略single_face_selection需要选一个脸的操作比较、搜索、注册如何挑脸largest优先面积最大的脸center_largest最大化面积 − 2.0 × 人脸框中心到图像中心像素距离的平方这一得分源码常量CENTER_LARGEST_DISTANCE_WEIGHT 2.0见 core.py。检测置信度不参与该得分。4. 启动配置 server.toml 详解server/config/server.toml是唯一的启动配置文件只在进程启动时读取一次任何修改都需要重启容器。完整内容如下# InsightFace Server settings loaded once during process startup. # Restart the container after changing this file. [inference] # auto resolves to 4 concurrent model pipelines on CPU and 8 on CUDA. # A positive integer overrides the provider-specific default. API calls, # enrollment and RTSP frames share this one process-wide budget. max_concurrency auto [detection] # Each entry is [width, height]. Dynamic SCRFD models run every configured # resolution, map all candidates to source-image coordinates, then apply one # global NMS pass to the merged candidate set. input_sizes [[96, 96], [512, 512]] # Minimum detector confidence. It is applied while SCRFD candidates are # generated, before the merged NMS pass. threshold 0.50 # IoU threshold used by the single global NMS pass. nms_threshold 0.40 # Used by operations that require one face. Supported values: # largest and center_largest. The latter maximizes the pixel-space score # area - 2.0 * squared_distance(face_box_center, image_center). single_face_selection largest # Deployment-wide safety limit. A request may ask for fewer results, never more. max_detected_faces 100 [web] # false (default): serve the Web UI, interactive API reference and guides. # true: API-only mode; keep /v1 and /openapi.json, but do not register UI routes. disabled false4.1 各配置项的行为与底层约束结合 config.py 的实现这些参数有严格的校验规则input_sizes最多 4 组[宽, 高]每条边必须在 322048 之间且必须是 32 的倍数SCRFD 最大特征图步长为 32总像素数不超过 4M不允许重复。校验逻辑见normalize_detector_input_sizesconfig.pythreshold/nms_threshold必须是 0.01.0 的有限数值max_detected_faces1100 的整数是全部署的硬性安全上限——请求可以要求更少结果但永远不能超过它max_concurrency取auto时CPU 为 4 路并发、CUDA 为 8 路常量见 config.py也可显式指定 1256 的整数。API 调用、注册和 RTSP 帧共享这一个进程级推理预算[web].disabled true只保留/v1与/openapi.json不再注册 Web UI、交互式 API 文档和指南路由实现见 app.py。4.2 SCRFD 多分辨率检测流程文档明确描述了检测管线SCRFD 在每个配置的分辨率上各执行一次推理把所有候选框重新投影到源图像坐标再对合并后的候选集执行一次全局 NMS。这一多分辨率互补的设计让 96×96 的小分辨率负责快速发现小脸、512×512 负责高精度召回最后统一去重。4.3 Compose 环境变量总览compose.cpu.yml 与 compose.cuda12.yml 中暴露的全部可调环境变量均带默认值环境变量默认值含义INSIGHTFACE_AUTH_ENABLEDfalse是否启用 API 密钥认证INSIGHTFACE_CONFIG_FILE/etc/insightface/server.toml启动配置文件路径INSIGHTFACE_API_KEY空启动密钥哈希后存储INSIGHTFACE_CORS_ORIGINS空允许的跨域来源逗号分隔INSIGHTFACE_LOG_LEVELINFO日志级别INSIGHTFACE_SAVE_FACE_CROPSfalse是否保存 112×112 人脸裁剪INSIGHTFACE_DEFAULT_THRESHOLD0.4默认相似度阈值INSIGHTFACE_COLLECTION_DEFAULT_SEARCH_PROFILEfp32_v1新建 Collection 的默认搜索 profileINSIGHTFACE_COLLECTION_DEFAULT_CAPACITY_ROWS100000默认容量INSIGHTFACE_COLLECTION_MAX_CAPACITY_ROWS10000000容量安全阀INSIGHTFACE_COLLECTION_DEFAULT_MAX_FACES_PER_PERSON20每人默认最大样本数INSIGHTFACE_COLLECTION_DEFAULT_LOAD_POLICYlazy索引加载策略eager/lazyINSIGHTFACE_SEARCH_DEVICE_ID0搜索使用的 GPU 设备号INSIGHTFACE_SEARCH_TOPK_MODEautotop-k 计算位置auto/host/deviceINSIGHTFACE_SEARCH_BUILD_BATCH_ROWS4096索引构建批量行数INSIGHTFACE_INFERENCE_MODEonnx推理模式onnx/mockINSIGHTFACE_EXECUTION_PROVIDERCPU 版CPUExecutionProviderCUDA 版CUDAExecutionProvider推理后端CUDA 版额外设置INSIGHTFACE_STRICT_CUDA1、NVIDIA_VISIBLE_DEVICESall、NVIDIA_DRIVER_CAPABILITIEScompute,utility与CUDA_MODULE_LOADINGLAZY。此外 config.py 还支持一批未在 compose 中暴露的变量如INSIGHTFACE_MAX_IMAGE_BYTES10MB、INSIGHTFACE_MAX_IMAGE_PIXELS4000万、INSIGHTFACE_MAX_REGISTRATION_IMAGES20、INSIGHTFACE_REQUEST_TIMEOUT_SECONDS60、INSIGHTFACE_RTSP_MAX_STREAMS4等可按需自行注入。5. 注册 Person三种审核模式与外部可信向量在Personnes人员页面选择 Collection 后可Inscrire une personne注册人员填写可选的 ID、姓名、外部 IDexternal_id、JSON metadata并上传一张或多张JPEG、PNG 或 WebP图片。5.1 review_mode 三种模式模式行为off使用 Collection 的单脸选择策略允许多张脸的场景下按策略选脸不做额外质量控制standard强制要求一个可用的脸并检查尺寸、检测置信度、清晰度、亮度与姿态strict在 standard 基础上进一步要求类内最佳相似度 类外最佳相似度防撞脸注册standard的具体判定标准在源码_registration_reasoncore.py中可见人脸短边 registration_min_face_size默认 40 像素→face_too_small检测置信度 registration_min_score默认 0.6→low_detection_scoreyaw/pitch/roll 任一绝对值 45° →extreme_pose质量分 registration_min_quality默认 0.35→low_quality。strict的类内/类外比较在_strict_registration_reviewcore.py中实现对每个新样本计算与同人已有样本的最高相似度类内再通过索引查询其他 Person 的最佳相似度类外若类内 ≤ 类外则拒绝并返回identity_similarity_conflict附带两侧相似度与命中的other_person_id。整个判定在 Collection 写锁内完成防止并发注册改变类外最大值。5.2 批量注册与数据存储批次允许部分成功每个被拒绝的图片都会返回index、filename、reason及附加细节原始上传图像不存储只保存派生出的向量、边界框、五点 landmarks、质量分等每人的 FaceSample 上限由max_faces_per_person控制超出返回409 person_face_limit_exceededCollection 容量超限返回409 collection_capacity_exceeded。5.3 external_trusted接受外部可信向量embedding_modeexternal_trusted允许调用方直接提交已由外部系统计算的向量向量必须是已做 L2 归一化的、维度与 Collection 契约一致默认 512 维的有限浮点数组源码通过_trusted_embeddingcore.py校验并重新归一化图片仍然必须上传因为检测器、landmarks 与质量检查仍会运行但识别器不会再次提取向量必须同时提供embedding_contract_id且与 Collection 绑定的契约一致否则返回409 embedding_contract_mismatch。6. 检测、比较与搜索6.1 Detect检测/v1/detect返回边界框bounding box、五点 landmarks、检测得分与质量分。没有检测到人脸时返回合法的空列表而不是报错。6.2 Compare比较/v1/compare使用系统或 Collection 的检测 profile 为每张图片各选一个脸返回三个关键字段app.pysimilarity余弦相似度实现为clip(dot(a, b), -1, 1)见 core.pythreshold生效阈值请求显式传入否则取系统/Collection 默认matchedsimilarity threshold的布尔结果。相似度不是概率它没有校准到 01 的概率语义只是一个余弦得分matched完全由阈值决定。6.3 Search搜索在Rechercher搜索中选择 Collection 与图片一个Person 的得分 其所有 FaceSample 中的最佳相似度结果按相似度降序排列无命中时返回空列表每次搜索先对查询图选脸、提取向量再执行索引查询见FaceService.searchcore.py。6.4 写入与索引的一致性保障写入路径遵循先 SQLite 后索引的顺序每个 FaceSample 先在 SQLite 中提交再追加到搜索索引最后才返回响应。因此请求返回成功即意味着数据已持久化若索引构建失败服务返回503 search_index_unavailable并在后台重建SearchMutationCommittedError会明确告知写入已提交、索引追赶失败见 search/manager.py。重启后索引完全从 SQLite 重建SQLite 是唯一事实来源。6.5 搜索 Profile精确扫描而非 ANNCollection 创建时固定 search profile不可按请求选择。/v1/system只公布当前部署实际可用的 profileSUPPORTED_SEARCH_PROFILES见 config.pyProfile说明fp32_v1CPU/CUDA 标准 FP32fp16_v1CUDA 半精度bf16_v1兼容 CPU 或 CUDA SM80int8_x736_v1INT8 量化推荐用于 CPU/CUDAINT32 累加int8_x1000_v1为既有 Collection 提供兼容性的早期量化所有 profile 都会逐条遍历每个 FaceSample 做精确比较不是 ANN 近似索引公开得分保持为 raw cosine。INT8 的量化在 search/reference.py 中定义int8_x1000_v1的 scale 为 1000、int8_x736_v1为 736向量先乘 scale 再四舍五入到[-128, 127]比较时在 INT32 域内累加quantize_int8见 reference.py。存储体积估算512 维每行FP32 约2048 字节、FP16/BF16 约1024 字节、INT8 约512 字节。索引生命周期由状态机管理UNLOADED → BUILDING → READY → DIRTY → REBUILDING ...见 search/manager.py。7. RTSP 摄像头监控Surveillance caméra摄像头监控允许把一路 RTSP 视频流接入系统做持续人脸识别。7.1 配置项创建持久化的Monitor配置source RTSP视频流地址Collection要搜索的人脸库fréquence推理频率inference_fps即每秒推理次数seuil阈值可选覆盖 Collection 默认阈值politique dévénements事件策略包括确认帧数confirm_frames、缺席超时absence_timeout_seconds、冷却时间cooldown_seconds、是否上报陌生人emit_unknown等完整字段见 rtsp.py。7.2 预览与 /state预览默认关闭关闭时识别与事件照常运行只是不产生预览画面预览开启后Web UI 通过/state接口在原始帧上叠加标记绿色 已注册人员橙色 陌生人实时预览走preview.mjpegMotion JPEG 流见 app.py。7.3 运行模型与数据边界Monitor独立于浏览器运行即使没有任何客户端连接识别照常执行服务重启后自动恢复活跃任务Monitor 配置保存在SQLite中RTSP 凭据在/data下加密存储——具体由SecretCodec用 32 字节随机密钥、AES-GCM 算法加 scope 关联数据加密见 secrets.py图像与事件不落盘事件只保留在有界的内存缓冲区中解码器只保留最新一帧旧帧直接丢弃而不是排队堆积next_inference_time也明确绝不调度追赶性推理见 rtsp.pyRTSP 源在展示/日志中会被脱敏redacted_rtsp_source只保留 scheme、主机、端口与路径剥离凭据与查询参数rtsp.py。监控的搜索路径复用search_all_facescore.py单帧检测一次、逐脸查询、每张脸取limit1的最佳匹配且流状态中不暴露向量。8. 数据持久化与安全最佳实践8.1 卷与备份持久化/dataSQLite 数据库、游标密钥、监控凭据密钥都在其中/models只读挂载模型目录不允许被运行时进程写入备份SQLite 与裁剪图crops必须一起备份因为两者互相关联大规模操作前务必先备份。8.2 密钥管理API 密钥以哈希形式存储使用同一数据卷但更换INSIGHTFACE_API_KEY重启后活动密钥自动轮换旧密钥失效新密钥生效绝不记录图像、向量embeddings与密钥都不允许写入日志。8.3 传输与错误处理每次响应都带x-request-id中间件为每个请求生成 UUID见 app.py排查问题时务必携带该 ID所有响应统一附加安全头X-Content-Type-Options: nosniff、X-Frame-Options: DENY、Referrer-Policy: no-referrer、Permissions-Policy禁用摄像头/麦克风/定位以及严格的Content-Security-Policy常见错误码401API 密钥无效或缺失409 collection_model_mismatch请求的 Collection 与当前模型契约不符422 face_not_found图片中没有可用的人脸。开发者可访问/docs查看 OpenAPI schema 浏览器仅当[web].disabledfalse时注册面向任务流的 API 说明见 api.fr.md。9. 模型包与许可证9.1 模型安装器镜像不内置模型正常启动保持离线。通过一次性models服务安装到server/.modelsdocker 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安装器还支持list列出支持包与安装状态与info显示包来源、哈希与许可命令解析见 models_cli.py。9.2 支持的模型包包名检测模型识别模型buffalo_ldet_10g.onnxw600k_r50.onnx512 维buffalo_mdet_2.5g.onnxw600k_r50.onnxbuffalo_scdet_500m.onnxw600k_mbf.onnxantelopev2scrfd_10g_bnkps.onnxglintr100.onnx完整目录含每个文件的 SHA-256、输入尺寸、预处理版本、embedding 维度定义在 models/packages.py。9.3 校验与许可证机制安装流程下载 →校验压缩包 SHA-256archive_sha256→ 解压时逐文件校验 SHA-256→ 生成manifest.json与签名文件MODEL.LICENSE不传--accept-license时交互式终端会提示确认非交互环境直接中止报错提示必须加--accept-licensemodels_cli.pyverify子命令会验证模型文件、manifest 与签名许可证输出许可证 ID、授权范围Grant、有效期与Commercial use: PERMITTED/NOT PERMITTED结论InsightFace 公开预训练模型保留为非商业研究用途商业使用需要单独的许可。10. Python SDK、镜像构建与版本管理10.1 Python SDKSDK 接受路径、bytes 与文件对象三种输入提供类型化方法覆盖 Detect、Compare、Collections、人员注册、Search 与 Monitors 全流程。HTTP 契约细节以 api.fr.md 为准SDK 源码位于 server/sdk/python。10.2 从源码构建镜像任何用户都可以从完整仓库构建make -C server build-cpu make -C server build-cuda12对应 Makefile 目标server/Makefile分别以--platform linux/amd64构建 CPU 与 CUDA 12 镜像。构建后如需使用本地镜像而非拉取远端给 Compose 命令加--pull never。10.3 版本与升级不可变 tag0.2.0-cpu与0.2.0-cuda12指向固定版本浮动 tagcpu与cuda12跟随最新稳定版不发布latest升级前停止写入 → 用对 SQLite 安全的方式备份/data与裁剪图严禁docker compose down -v它会删除数据 volume。11. GPU 运行、网络暴露与故障排查11.1 CUDA 镜像技术栈与驱动要求CUDA 12 镜像包含CUDA Runtime 12.9.1、cuDNN 9.24.0、onnxruntime-gpu1.27.0。驱动版本要求按 GPU 架构Turing / Ampere / Ada / HopperR535 或更高Blackwell / RTX 50 系列570.26 或更高推荐稳定版 R580 或更新。启动时自检覆盖GPU 可见性、Compute Capability、驱动版本、CUDA/cuDNN/ORT 版本、Execution Provider、实际创建的 Session 数量与 warm-up 结果——任何一步失败都拒绝启动绝不静默回退 CPU。11.2 网络暴露清单将服务暴露到外网前用可靠的反向代理终结 HTTPS限制CORSINSIGHTFACE_CORS_ORIGINS、速率、请求体大小与超时max_request_bytes默认 64MB、request_timeout_seconds默认 60s将/data与备份按生物识别数据标准保护日志中永不出现图像、向量或密钥。11.3 能力边界Phase 1当前阶段Phase 1只支持单一 API Key无角色role体系不是多租户授权系统。若需要多租户隔离与细粒度权限需要在其上自行实现授权层。12. 常见问题速查现象排查方向/v1/health返回 503服务仍在启动中模型加载/索引构建稍后重试401API 密钥缺失或不匹配确认INSIGHTFACE_AUTH_ENABLEDtrue且 Key 与卷内哈希一致409 collection_model_mismatch更换过模型包旧 Collection 契约不匹配需重建或迁移422 face_not_found图片无人脸或人脸不满足质量/尺寸/姿态门槛standard/strict模式413 request_too_large请求体超过max_request_bytes503 request_timeout超过request_timeout_seconds留意推理并发是否被打满重启后搜索变慢索引从 SQLite 重建中lazy策略下按需加载CUDA 版意外走 CPU检查启动日志自检项与INSIGHTFACE_STRICT_CUDA1更详细的运维口径可继续阅读 maintainer-guide.md。结合本文的部署命令、配置项与源码依据你可以把 InsightFace Server 作为内部评估、原型验证与非商业研究的基础设施并依据第 8 节与第 11 节的安全清单把它可靠地接入你的网络环境。【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考