尧图网站建设 
InsightFace Server 用户指南从 Docker 部署到人脸库构建、检索与 RTSP 监控的完整实操【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface本文是 InsightFace Server 的逐步操作指南面向首次使用者从一份空仓库开始完成容器部署、模型安装、Collection人脸库创建、Person 注册并最终通过 Web UI、/v1REST API 与 Python SDK 三种途径拿到搜索结果。读完本文你将掌握 CPU/CUDA 双环境部署、认证开启、检测配置、精确向量检索、RTSP 摄像头监控以及数据备份与故障排查的全套实战能力。从这里开始从零到一台可用的 ServerInsightFace Server 需要一台 Linux x86_64 主机并预装 Docker Engine 与 Docker Compose。若使用 CUDA 部署主机还需安装受支持的 NVIDIA 驱动与 NVIDIA Container Toolkit。不要在宿主机上安装 CUDA、cuDNN、ONNX Runtime、Python 或 OpenCV——运行时依赖全部封装在镜像内。CPU 示例一条命令走完拉取镜像、安装模型、启动服务、健康检查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/healthNVIDIA GPU 部署只需把compose.cpu.yml换成 server/deploy/compose.cuda12.yml端口相应变为18098。模型安装器会在下载前展示模型许可licenseInsightFace 官方预训练模型默认仅限非商业研究用途商业使用需单独获取商业许可。两个 Compose 文件默认以auth_enabledfalse启动便于隔离环境评估该模式下 API 调用无需携带 key 字段Web UI 也会隐藏密钥输入控件。在把服务暴露给其他用户或网络之前务必先在启动前开启认证export INSIGHTFACE_AUTH_ENABLEDtrue export INSIGHTFACE_API_KEYreplace-with-a-long-random-secret docker compose -f server/deploy/compose.cpu.yml up -d随后打开http://SERVER:18097/CPU或http://SERVER:18098/CUDA 12开始使用。首次工作流的推荐顺序先看 Dashboard → 创建 Collection → 注册至少含一张清晰图片的 Person → 用该 Person 的另一张不同图片执行 Search。注意一次查无此人的成功结果是空列表而不是服务器故障。停止服务用docker compose ... down不要加-v一旦加上-v命名的数据卷将被永久删除。从 Compose 文件可以看到该部署的安全基线服务以只读根文件系统read_only: true、非 root 用户user: 10001:10001、丢弃全部 Linux capabilitiescap_drop: [ALL]、禁止权限提升no-new-privileges以及 512 的进程数上限运行/data是命名数据卷/models与 server/config/server.toml 均以只读方式挂载进容器。1. 登录与就绪检查打开对应端口CPU18097/ CUDA 1218098。若已开启认证选择Configure API key粘贴运维提供的密钥并选择Use for this tab——浏览器仅将该密钥保存在内存中刷新或关闭标签页即被清除。注册数据之前先检查Dashboard或System页面服务、数据库、模型与推理提供方provider必须全部就绪。CUDA 部署必须显示CUDAExecutionProviderServer绝不会静默回退到 CPU详见第 14 节 fail-fast 校验。2. 创建 Collection打开Collections选择New collection需要设置以下内容一个稳定的 ID例如employees显示名称与可选元数据默认余弦阈值初始值0.4当前主机支持的搜索 profile详见第 13 节容量上限与每个 Person 的最大 FaceSample 数检测器输入尺寸、检测/NMS 阈值与单脸选择策略可选的 112×112bounding-box cropJPEG 存储——注意这是未对齐的检测框裁剪图不是对齐后的识别输入默认关闭。Collection 与模型身份强绑定它固定于当前激活模型的 identity、digest、嵌入维度与预处理版本。其检测 profile 在创建时拷贝系统 profile之后可独立修改每次修改只影响下一次请求并递增detection_revision不会重新处理已有的 FaceSample。单脸策略中largest按面积优先center_largest最大化area - 2.0 × 人脸框中心到图像中心的像素距离的平方检测置信度不参与该打分。3. 注册 Person打开People选择 Collection然后Register person。可提供可选的稳定 person ID、姓名、外部 ID 与 JSON 元数据上传一张或多张 JPEG、PNG 或 WebP 图片。注册审查enrollment review模式有三种off直接采用 Collection 的单脸策略允许多人脸standard要求恰好一张可用人脸并执行尺寸、检测、清晰度、亮度与姿态检查strict在 standard 检查之上还要求该样本的组内最高相似度必须超过组外最高相似度。批量注册支持部分成功。重试前请逐一查看被拒图片及其原因服务端不会保留被拒绝的原始图片。开启 crop 存储时只保存缩放至 112×112 的bounding-box crop——既不保存原始上传也不保存对齐后的识别输入。受信任的系统还可以用external_trusted方式提交预先计算好的、L2 归一化的嵌入向量图片仍用于检测与质量审查但服务端不再重新提取特征。嵌入契约必须与 Collection 完全一致维度、预处理版本等源码层面这一约束体现在 embedding_contract.py 的契约校验逻辑中。4. 检测与比对Detect上传一张图片查看检测框、五个关键点、置信度与启发式质量评分。检测不到人脸同样是成功结果——返回空列表。Compare上传源图与目标图选择系统或某个 Collection 的检测 profile该 profile 的单脸策略会分别在每张图中挑选一张可用人脸。结果包含原始余弦similarity、选用的threshold与matched。相似度不是概率其取值范围是[-1.0, 1.0]匹配判定为similarity threshold阈值闭区间。若任一张图没有可用人脸API 返回422 face_not_found。质量评分体系详见 api.md 的 Common behavior 部分detection_score是检测器置信度quality.score、sharpness、brightness、pose是本地定义的启发式质量信号并非 AWS 指标。检测框同时返回像素坐标与归一化坐标两种形式EXIF 方向信息会在推理前自动矫正。默认限制压缩图 10 MiB、解码后 4000 万像素、单请求 64 MiB。5. 搜索 Collection打开Search选择 Collection上传查询图片设置结果数量上限并可选择覆盖阈值。Collection 的检测 profile 负责挑选查询人脸。结果按相似度降序排列Person 的得分取该 Person 所有 FaceSample 中的最高分。查无匹配是成功的空列表。一致性保证新接受的 FaceSample 会先提交到 SQLite再写入内存索引最后才返回成功响应删除操作同时更新两个存储。服务重启时从 SQLite 重建内存索引——SQLite 始终是权威数据源。6. RTSP 摄像头监控打开Camera monitoring选择New Monitor。为任务设置 ID 与名称填写rtsp://或rtsps://流地址选择 Collection并配置推理频率与可选匹配阈值。事件设置控制连续多少次观测才确认一张人脸、缺席多久触发离开事件、重复事件的冷却时间以及内存中保留最近多少个事件。Web 视频预览默认关闭。仅在运维人员需要目视检查时才开启识别与事件推送不依赖预览。开启后服务端发送原始 JPEG 帧Web UI 根据/state结果绘制绿色框已注册人员与琥珀色框检测到但未注册的人脸。Monitor 独立于浏览器在服务端运行关闭页面不会停止监控已启用的 Monitor 在 Server 重启后自动恢复。Start/Stop切换enabledEdit轮换 RTSP 源或微调设置Delete删除任务。解码器只保留最新帧若处理速度超过请求间隔过期帧会被丢弃而不是排队避免延迟累积。监控配置存储在 SQLite 中RTSP 凭据在/data内加密保存永远不会通过 API 返回。视频帧不会落盘。最近的进入/离开/错误/恢复事件只存在于有界的内存环形缓冲区中重启即丢失。跨不可信网络使用 UI/API 时应启用 HTTPS并将 Monitor 管理权限限制给受信任的运维人员。7. 更新与删除数据Collection 与 Person 均可从其列表中直接编辑。删除 FaceSample 会同时移除其嵌入向量与可选 crop删除非空 Collection 需要显式的强制确认。进行批量或破坏性维护之前请先备份/data。8. API 与 Python SDK开发者可以在/docs打开 OpenAPI 交互式 schema 浏览器同源完整 HTTP 契约见 API 使用指南。每个 API 响应都携带x-request-id反馈问题时应附上该 ID。Python SDK 是面向自托管 Server REST API 的轻量客户端基于httpx不含推理运行时接受图片路径、bytes 或二进制文件类对象。安装与使用python -m pip install ./server/sdk/pythonfrom insightface_server import Client client Client(http://localhost:18097, api_keyyour-key) client.create_collection(collection_idemployees, nameEmployees, threshold0.4) client.add_person(employees, person_idalice, images[alice-1.jpg, alice-2.jpg]) matches client.search(employees, query.jpg, limit5)SDK 使用要点见 server/sdk/python/README.md系统检测 profile 是启动时配置Collection 在创建时拷贝它并可覆盖输入尺寸、检测/NMS 阈值与单脸策略无状态 Detect/Compare/Embeddings 调用可传collection以使用该 Collection 的 profile。受信任的上游提取器可传external_embeddings与必需的图片及 Collection 的embedding_contract_id从而走external_trusted路径。持久化 RTSP 监控通过create_monitor、update_monitor、monitor_state与基于游标的monitor_events提供。SDK 客户端默认等待 65 秒略长于服务端 60 秒的请求期限需要不同快速失败策略时可传timeout。同时提供 curl 形态的一等公民调用方式认证关闭时省略Authorization 头不要发送空的认证头BASE_URLhttp://127.0.0.1:18097 AUTH_HEADERAuthorization: Bearer ${INSIGHTFACE_API_KEY} curl -fsS ${BASE_URL}/v1/health curl -sS ${BASE_URL}/v1/collections -H ${AUTH_HEADER} \ -H Content-Type: application/json \ -d {id:employees,name:Employees,threshold:0.4} curl -sS ${BASE_URL}/v1/collections/employees/persons -H ${AUTH_HEADER} \ -F idalice -F nameAlice -F review_modeoff \ -F imagesalice-enroll.jpg curl -sS ${BASE_URL}/v1/collections/employees/search -H ${AUTH_HEADER} \ -F imagealice-query.jpg -F limit5客户端重试安全规则api.md 明确约定客户端超时应长于服务端请求超时将x-request-id作为关联 ID 记录日志但不得记录图片、嵌入向量、RTSP 凭据与 API keynext_cursor只能复用于相同的端点、Collection、Person 与过滤条件组合不要解析或自行构造GET 可安全重试DELETE 需先检查当前状态再重试Person/FaceSample 创建在网络失败后不要自动重试先查询客户端提供的资源 ID429与瞬时503可用带抖动的指数退避重试校验类4xx必须修改请求。9. 数据、备份与安全持久化/data以只读方式挂载/models在停止写入的前提下或使用 SQLite 安全的快照方式同时备份 SQLite 数据库与已配置的 crop 存储API key 以哈希形式存储后续启动时提供不同的INSIGHTFACE_API_KEY会有意轮换该数据卷的当前活动 key不要记录图片、嵌入向量或密钥除非确有需要保持 CORS 关闭镜像内不包含模型文件。InsightFace 官方开源预训练模型含buffalo_l仅限非商业研究用途商业使用需单独许可见 https://www.insightface.aiSystem页面会展示同样的声明。10. 故障排查错误含义与处置401 unauthorized当前标签页没有有效 key或 key 已被轮换重新配置 API key409 collection_model_mismatchCollection 是用不同的模型契约创建的与当前模型不匹配422 face_not_found没有选出可用人脸检查图片质量或检测阈值CUDA 启动失败属于有意为之——驱动、GPU、模型会话、provider 或预热校验任一环节失败即中止检查 System 页、容器日志与响应中的request_id11. 模型与模型许可镜像不含模型。一次性models服务把模型包安装到server/.models而正常 Server 启动保持离线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支持的开源公共包对应 packages.py 中的PACKAGES目录:包名检测模型识别模型buffalo_ldet_10g.onnxw600k_r50.onnxbuffalo_mdet_2.5g.onnxw600k_r50.onnxbuffalo_scdet_500m.onnxw600k_mbf.onnxantelopev2scrfd_10g_bnkps.onnxglintr100.onnx安装流程models_cli.py 定义了list/install/verify/info四个子命令下载归档 → 校验归档 SHA-256 → 校验每个模型文件的 SHA-256 → 写入manifest.json与签名文件MODEL.LICENSE。所有公开包的归档与文件级校验和在packages.py中硬编码例如buffalo_l归档 SHA-256 为80ffe37d…、det_10g.onnx为5838f7fe…。不带--accept-license时工具只打印许可条款并退出不会下载——非交互环境下stdin 非 TTY会直接报错并提示添加该参数。models verify校验包身份、签名许可、有效期与当前授权状态输出 Issuer、License ID、Model ID、Grant、有效期与 Commercial use: PERMITTED / NOT PERMITTED。私有模型可使用同样的 manifest 与离线签名许可格式。许可绑定的是逻辑model_id——它是合规凭证既不是 DRM也不是模型文件的校验和因此客户可以使用转换后的 FP16、INT8、优化 ONNX 或 TensorRT 产物见packages.py模块文档注释。12. 仅启动时可配置项Startup-only configuration通用启动配置文件是 server/config/server.tomlCompose 以只读方式挂载到容器内/etc/insightface/server.toml。配置只在进程启动时读取一次没有运行时配置 API修改后必须重启容器。默认值[inference] max_concurrency auto # CPU 4, CUDA 8 [detection] input_sizes [[96, 96], [512, 512]] threshold 0.50 nms_threshold 0.40 single_face_selection largest max_detected_faces 100 [web] disabled false从 config.py 的load_server_config与Settings.from_env可以看到这些配置的底层约束与语义[inference].max_concurrencyauto按 provider 解析为 CPU 4、CUDA 8default_inference_max_concurrency或显式指定 1..256 的整数API 调用、注册与 RTSP 帧共享这一个进程级推理预算[detection].input_sizes动态 SCRFD 会运行每个配置的分辨率把候选框映射回原图坐标合并后做一次全局 NMS。每个尺寸必须是 32 的倍数SCRFD 最大特征图步长为 32、边长 32..2048、总像素不超过 4M、最多 4 个尺寸且不允许重复——这些校验在normalize_detector_input_sizes中实现用于在耗尽 CPU 内存或 GPU 显存之前拦截错误配置[detection].threshold生成 SCRFD 候选时应用的检测置信度下限在合并 NMS 之前取值范围0.0..1.0[detection].nms_threshold全局 NMS 的 IoU 阈值[detection].single_face_selection仅largest与center_largest两个取值[detection].max_detected_faces部署级安全上限取值 1..100请求可以要求更少的结果但永远不能超过该值[web].disabled设为true即纯 API 模式——/v1与/openapi.json仍然可用但/、/docs、指南页面与前端静态资源不再注册。配置分层TOML 文件之外的部署级参数通过环境变量注入Compose 的environment段全部带${VAR:-default}形式例如INSIGHTFACE_SAVE_FACE_CROPS、INSIGHTFACE_DEFAULT_THRESHOLD默认0.4、INSIGHTFACE_COLLECTION_DEFAULT_SEARCH_PROFILE默认fp32_v1、INSIGHTFACE_COLLECTION_DEFAULT_CAPACITY_ROWS默认100000、INSIGHTFACE_COLLECTION_MAX_CAPACITY_ROWS默认10000000、INSIGHTFACE_COLLECTION_DEFAULT_MAX_FACES_PER_PERSON默认20、INSIGHTFACE_COLLECTION_DEFAULT_LOAD_POLICY默认lazy、INSIGHTFACE_SEARCH_DEVICE_ID默认0、INSIGHTFACE_SEARCH_TOPK_MODE默认auto、INSIGHTFACE_SEARCH_BUILD_BATCH_ROWS默认4096等。环境变量优先级高于 TOML例如显式设置INSIGHTFACE_INFERENCE_MAX_CONCURRENCY会覆盖文件中的max_concurrency见Settings.from_env中 env 与 file_config 的合并顺序。检测 profile 的作用范围config.py的Settings.detection_profile与此对应无状态 Detect 与 Embeddings 使用系统 profileCompare 可用系统 profile 或选定的 Collection注册与搜索使用各自 Collection 的 profile。新 Collection 拷贝系统检测 profile 后即可独立更新影响下一次请求。13. 精确搜索 profile 与容量System 响应只会通告当前 CPU/GPU 上实际可用的 profile。Collection 在创建时固定一个 profile后续搜索请求无法更改。可用 profile 定义于 config.py 的SUPPORTED_SEARCH_PROFILES并与 native.py 的_PROFILE_CODES一一对应Profile存储表示典型可用性fp32_v1FP32CPU 与 CUDAfp16_v1FP16CUDAbf16_v1BF16受支持的 CPU 或 SM80 CUDAint8_x736_v1INT8scale 736CPU 与 CUDA推荐的 INT8 方案int8_x1000_v1INT8scale 1000兼容性 profile所有 profile 都是对每个活跃 FaceSample 的扁平穷举搜索低精度 profile 只是对 FP32 分数的近似不是 ANN 索引。INT8 点积累加到 INT32对外暴露的相似度与阈值始终是原始余弦值。容量模型capacity_rows为 Collection 预留最大活跃行数避免常规增长停顿。512 维向量的近似存储开销为每 FP32 行 2,048 字节、每 FP16/BF16 行 1,024 字节、每 INT8 行 512 字节未计 ID 与工作区。请按实际内存预算设置容量默认100000部署护栏上限10000000。max_faces_per_person默认20它限制的是每个 Person 的样本数量而不是人数上限。原生索引层native.py通过ifs_search_grouped_topk执行分组 Person Top-K精确检索并校验查询与库内向量均为 L2 归一化容差2e-4确保余弦相似度的计算前提成立。14. CUDA 支持与 fail-fast 验证CUDA 镜像内含 CUDA Runtime 12.9.1、cuDNN 9.24.0、Python 3.11 与onnxruntime-gpu1.27.0。宿主机只需 Driver、Docker Engine、NVIDIA Container Toolkit 与兼容 GPUTuring、Ampere、Ada、HopperDriver R535 或更新Blackwell 与 RTX 50 系列Driver 570.26 或更新新部署建议优先使用稳定的 R580 或更新驱动。架构兼容性不构成对每个 GPU SKU 的正式认证声明。每次 CUDA 启动时 Server 都会检查GPU 型号、Compute Capability、Driver、实际 CUDA/cuDNN/ORT 版本、CUDAExecutionProvider是否存在、真实的检测与识别 Session 是否建立以及真实的预热推理是否成功。它审计 provider 放置情况一旦异常即终止进程而非静默回退 CPUCompose 中通过INSIGHTFACE_STRICT_CUDA1强化此行为。使用前请在System页确认校验结果。15. 构建、升级、备份与恢复用户可以从完整仓库检出构建两个镜像server/Makefilemake -C server build-cpu make -C server build-cuda12之后在 Compose 的模型安装与up命令中追加--pull never以使用本地镜像。构建使用固定的基础镜像与锁定依赖但需要网络访问获取这些输入。公共镜像标签为0.2.0-cpu/0.2.0-cuda12滚动的cpu/cuda12标签指向最新的稳定变体刻意不设latest标签。升级前停止写入对/data加 crop 存储做 SQLite 安全的快照保留/models及其许可文件。先基于副本启动新容器检查迁移与/v1/health再验证模型契约与一次已知搜索。收尾用docker compose down不加-vdocker compose down -v会删除命名数据卷。对外暴露时在可信反向代理处终结 HTTPS只放行必要的来源而非宽泛 CORS施加边缘限速/请求体/超时限制并将数据卷与备份作为生物识别数据保护。需要明确的是Server 第一阶段只提供单一无差别 API key不是多租户授权系统请据此设计访问控制边界。延伸阅读API 使用指南完整 HTTP 契约与全部端点Python SDK 客户端说明启动配置 server.tomlCPU Compose 部署文件 与 CUDA 12 Compose 部署文件服务端配置与校验实现、模型包目录与校验和、模型安装 CLI、原生精确搜索实现【免费下载链接】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/insightface本文是 InsightFace Server 的逐步操作指南面向首次使用者从一份空仓库开始完成容器部署、模型安装、Collection人脸库创建、Person 注册并最终通过 Web UI、/v1REST API 与 Python SDK 三种途径拿到搜索结果。读完本文你将掌握 CPU/CUDA 双环境部署、认证开启、检测配置、精确向量检索、RTSP 摄像头监控以及数据备份与故障排查的全套实战能力。从这里开始从零到一台可用的 ServerInsightFace Server 需要一台 Linux x86_64 主机并预装 Docker Engine 与 Docker Compose。若使用 CUDA 部署主机还需安装受支持的 NVIDIA 驱动与 NVIDIA Container Toolkit。不要在宿主机上安装 CUDA、cuDNN、ONNX Runtime、Python 或 OpenCV——运行时依赖全部封装在镜像内。CPU 示例一条命令走完拉取镜像、安装模型、启动服务、健康检查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/healthNVIDIA GPU 部署只需把compose.cpu.yml换成 server/deploy/compose.cuda12.yml端口相应变为18098。模型安装器会在下载前展示模型许可licenseInsightFace 官方预训练模型默认仅限非商业研究用途商业使用需单独获取商业许可。两个 Compose 文件默认以auth_enabledfalse启动便于隔离环境评估该模式下 API 调用无需携带 key 字段Web UI 也会隐藏密钥输入控件。在把服务暴露给其他用户或网络之前务必先在启动前开启认证export INSIGHTFACE_AUTH_ENABLEDtrue export INSIGHTFACE_API_KEYreplace-with-a-long-random-secret docker compose -f server/deploy/compose.cpu.yml up -d随后打开http://SERVER:18097/CPU或http://SERVER:18098/CUDA 12开始使用。首次工作流的推荐顺序先看 Dashboard → 创建 Collection → 注册至少含一张清晰图片的 Person → 用该 Person 的另一张不同图片执行 Search。注意一次查无此人的成功结果是空列表而不是服务器故障。停止服务用docker compose ... down不要加-v一旦加上-v命名的数据卷将被永久删除。从 Compose 文件可以看到该部署的安全基线服务以只读根文件系统read_only: true、非 root 用户user: 10001:10001、丢弃全部 Linux capabilitiescap_drop: [ALL]、禁止权限提升no-new-privileges以及 512 的进程数上限运行/data是命名数据卷/models与 server/config/server.toml 均以只读方式挂载进容器。1. 登录与就绪检查打开对应端口CPU18097/ CUDA 1218098。若已开启认证选择Configure API key粘贴运维提供的密钥并选择Use for this tab——浏览器仅将该密钥保存在内存中刷新或关闭标签页即被清除。注册数据之前先检查Dashboard或System页面服务、数据库、模型与推理提供方provider必须全部就绪。CUDA 部署必须显示CUDAExecutionProviderServer绝不会静默回退到 CPU详见第 14 节 fail-fast 校验。2. 创建 Collection打开Collections选择New collection需要设置以下内容一个稳定的 ID例如employees显示名称与可选元数据默认余弦阈值初始值0.4当前主机支持的搜索 profile详见第 13 节容量上限与每个 Person 的最大 FaceSample 数检测器输入尺寸、检测/NMS 阈值与单脸选择策略可选的 112×112bounding-box cropJPEG 存储——注意这是未对齐的检测框裁剪图不是对齐后的识别输入默认关闭。Collection 与模型身份强绑定它固定于当前激活模型的 identity、digest、嵌入维度与预处理版本。其检测 profile 在创建时拷贝系统 profile之后可独立修改每次修改只影响下一次请求并递增detection_revision不会重新处理已有的 FaceSample。单脸策略中largest按面积优先center_largest最大化area - 2.0 × 人脸框中心到图像中心的像素距离的平方检测置信度不参与该打分。3. 注册 Person打开People选择 Collection然后Register person。可提供可选的稳定 person ID、姓名、外部 ID 与 JSON 元数据上传一张或多张 JPEG、PNG 或 WebP 图片。注册审查enrollment review模式有三种off直接采用 Collection 的单脸策略允许多人脸standard要求恰好一张可用人脸并执行尺寸、检测、清晰度、亮度与姿态检查strict在 standard 检查之上还要求该样本的组内最高相似度必须超过组外最高相似度。批量注册支持部分成功。重试前请逐一查看被拒图片及其原因服务端不会保留被拒绝的原始图片。开启 crop 存储时只保存缩放至 112×112 的bounding-box crop——既不保存原始上传也不保存对齐后的识别输入。受信任的系统还可以用external_trusted方式提交预先计算好的、L2 归一化的嵌入向量图片仍用于检测与质量审查但服务端不再重新提取特征。嵌入契约必须与 Collection 完全一致维度、预处理版本等源码层面这一约束体现在 embedding_contract.py 的契约校验逻辑中。4. 检测与比对Detect上传一张图片查看检测框、五个关键点、置信度与启发式质量评分。检测不到人脸同样是成功结果——返回空列表。Compare上传源图与目标图选择系统或某个 Collection 的检测 profile该 profile 的单脸策略会分别在每张图中挑选一张可用人脸。结果包含原始余弦similarity、选用的threshold与matched。相似度不是概率其取值范围是[-1.0, 1.0]匹配判定为similarity threshold阈值闭区间。若任一张图没有可用人脸API 返回422 face_not_found。质量评分体系详见 api.md 的 Common behavior 部分detection_score是检测器置信度quality.score、sharpness、brightness、pose是本地定义的启发式质量信号并非 AWS 指标。检测框同时返回像素坐标与归一化坐标两种形式EXIF 方向信息会在推理前自动矫正。默认限制压缩图 10 MiB、解码后 4000 万像素、单请求 64 MiB。5. 搜索 Collection打开Search选择 Collection上传查询图片设置结果数量上限并可选择覆盖阈值。Collection 的检测 profile 负责挑选查询人脸。结果按相似度降序排列Person 的得分取该 Person 所有 FaceSample 中的最高分。查无匹配是成功的空列表。一致性保证新接受的 FaceSample 会先提交到 SQLite再写入内存索引最后才返回成功响应删除操作同时更新两个存储。服务重启时从 SQLite 重建内存索引——SQLite 始终是权威数据源。6. RTSP 摄像头监控打开Camera monitoring选择New Monitor。为任务设置 ID 与名称填写rtsp://或rtsps://流地址选择 Collection并配置推理频率与可选匹配阈值。事件设置控制连续多少次观测才确认一张人脸、缺席多久触发离开事件、重复事件的冷却时间以及内存中保留最近多少个事件。Web 视频预览默认关闭。仅在运维人员需要目视检查时才开启识别与事件推送不依赖预览。开启后服务端发送原始 JPEG 帧Web UI 根据/state结果绘制绿色框已注册人员与琥珀色框检测到但未注册的人脸。Monitor 独立于浏览器在服务端运行关闭页面不会停止监控已启用的 Monitor 在 Server 重启后自动恢复。Start/Stop切换enabledEdit轮换 RTSP 源或微调设置Delete删除任务。解码器只保留最新帧若处理速度超过请求间隔过期帧会被丢弃而不是排队避免延迟累积。监控配置存储在 SQLite 中RTSP 凭据在/data内加密保存永远不会通过 API 返回。视频帧不会落盘。最近的进入/离开/错误/恢复事件只存在于有界的内存环形缓冲区中重启即丢失。跨不可信网络使用 UI/API 时应启用 HTTPS并将 Monitor 管理权限限制给受信任的运维人员。7. 更新与删除数据Collection 与 Person 均可从其列表中直接编辑。删除 FaceSample 会同时移除其嵌入向量与可选 crop删除非空 Collection 需要显式的强制确认。进行批量或破坏性维护之前请先备份/data。8. API 与 Python SDK开发者可以在/docs打开 OpenAPI 交互式 schema 浏览器同源完整 HTTP 契约见 API 使用指南。每个 API 响应都携带x-request-id反馈问题时应附上该 ID。Python SDK 是面向自托管 Server REST API 的轻量客户端基于httpx不含推理运行时接受图片路径、bytes 或二进制文件类对象。安装与使用python -m pip install ./server/sdk/pythonfrom insightface_server import Client client Client(http://localhost:18097, api_keyyour-key) client.create_collection(collection_idemployees, nameEmployees, threshold0.4) client.add_person(employees, person_idalice, images[alice-1.jpg, alice-2.jpg]) matches client.search(employees, query.jpg, limit5)SDK 使用要点见 server/sdk/python/README.md系统检测 profile 是启动时配置Collection 在创建时拷贝它并可覆盖输入尺寸、检测/NMS 阈值与单脸策略无状态 Detect/Compare/Embeddings 调用可传collection以使用该 Collection 的 profile。受信任的上游提取器可传external_embeddings与必需的图片及 Collection 的embedding_contract_id从而走external_trusted路径。持久化 RTSP 监控通过create_monitor、update_monitor、monitor_state与基于游标的monitor_events提供。SDK 客户端默认等待 65 秒略长于服务端 60 秒的请求期限需要不同快速失败策略时可传timeout。同时提供 curl 形态的一等公民调用方式认证关闭时省略Authorization 头不要发送空的认证头BASE_URLhttp://127.0.0.1:18097 AUTH_HEADERAuthorization: Bearer ${INSIGHTFACE_API_KEY} curl -fsS ${BASE_URL}/v1/health curl -sS ${BASE_URL}/v1/collections -H ${AUTH_HEADER} \ -H Content-Type: application/json \ -d {id:employees,name:Employees,threshold:0.4} curl -sS ${BASE_URL}/v1/collections/employees/persons -H ${AUTH_HEADER} \ -F idalice -F nameAlice -F review_modeoff \ -F imagesalice-enroll.jpg curl -sS ${BASE_URL}/v1/collections/employees/search -H ${AUTH_HEADER} \ -F imagealice-query.jpg -F limit5客户端重试安全规则api.md 明确约定客户端超时应长于服务端请求超时将x-request-id作为关联 ID 记录日志但不得记录图片、嵌入向量、RTSP 凭据与 API keynext_cursor只能复用于相同的端点、Collection、Person 与过滤条件组合不要解析或自行构造GET 可安全重试DELETE 需先检查当前状态再重试Person/FaceSample 创建在网络失败后不要自动重试先查询客户端提供的资源 ID429与瞬时503可用带抖动的指数退避重试校验类4xx必须修改请求。9. 数据、备份与安全持久化/data以只读方式挂载/models在停止写入的前提下或使用 SQLite 安全的快照方式同时备份 SQLite 数据库与已配置的 crop 存储API key 以哈希形式存储后续启动时提供不同的INSIGHTFACE_API_KEY会有意轮换该数据卷的当前活动 key不要记录图片、嵌入向量或密钥除非确有需要保持 CORS 关闭镜像内不包含模型文件。InsightFace 官方开源预训练模型含buffalo_l仅限非商业研究用途商业使用需单独许可见 https://www.insightface.aiSystem页面会展示同样的声明。10. 故障排查错误含义与处置401 unauthorized当前标签页没有有效 key或 key 已被轮换重新配置 API key409 collection_model_mismatchCollection 是用不同的模型契约创建的与当前模型不匹配422 face_not_found没有选出可用人脸检查图片质量或检测阈值CUDA 启动失败属于有意为之——驱动、GPU、模型会话、provider 或预热校验任一环节失败即中止检查 System 页、容器日志与响应中的request_id11. 模型与模型许可镜像不含模型。一次性models服务把模型包安装到server/.models而正常 Server 启动保持离线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支持的开源公共包对应 packages.py 中的PACKAGES目录:包名检测模型识别模型buffalo_ldet_10g.onnxw600k_r50.onnxbuffalo_mdet_2.5g.onnxw600k_r50.onnxbuffalo_scdet_500m.onnxw600k_mbf.onnxantelopev2scrfd_10g_bnkps.onnxglintr100.onnx安装流程models_cli.py 定义了list/install/verify/info四个子命令下载归档 → 校验归档 SHA-256 → 校验每个模型文件的 SHA-256 → 写入manifest.json与签名文件MODEL.LICENSE。所有公开包的归档与文件级校验和在packages.py中硬编码例如buffalo_l归档 SHA-256 为80ffe37d…、det_10g.onnx为5838f7fe…。不带--accept-license时工具只打印许可条款并退出不会下载——非交互环境下stdin 非 TTY会直接报错并提示添加该参数。models verify校验包身份、签名许可、有效期与当前授权状态输出 Issuer、License ID、Model ID、Grant、有效期与 Commercial use: PERMITTED / NOT PERMITTED。私有模型可使用同样的 manifest 与离线签名许可格式。许可绑定的是逻辑model_id——它是合规凭证既不是 DRM也不是模型文件的校验和因此客户可以使用转换后的 FP16、INT8、优化 ONNX 或 TensorRT 产物见packages.py模块文档注释。12. 仅启动时可配置项Startup-only configuration通用启动配置文件是 server/config/server.tomlCompose 以只读方式挂载到容器内/etc/insightface/server.toml。配置只在进程启动时读取一次没有运行时配置 API修改后必须重启容器。默认值[inference] max_concurrency auto # CPU 4, CUDA 8 [detection] input_sizes [[96, 96], [512, 512]] threshold 0.50 nms_threshold 0.40 single_face_selection largest max_detected_faces 100 [web] disabled false从 config.py 的load_server_config与Settings.from_env可以看到这些配置的底层约束与语义[inference].max_concurrencyauto按 provider 解析为 CPU 4、CUDA 8default_inference_max_concurrency或显式指定 1..256 的整数API 调用、注册与 RTSP 帧共享这一个进程级推理预算[detection].input_sizes动态 SCRFD 会运行每个配置的分辨率把候选框映射回原图坐标合并后做一次全局 NMS。每个尺寸必须是 32 的倍数SCRFD 最大特征图步长为 32、边长 32..2048、总像素不超过 4M、最多 4 个尺寸且不允许重复——这些校验在normalize_detector_input_sizes中实现用于在耗尽 CPU 内存或 GPU 显存之前拦截错误配置[detection].threshold生成 SCRFD 候选时应用的检测置信度下限在合并 NMS 之前取值范围0.0..1.0[detection].nms_threshold全局 NMS 的 IoU 阈值[detection].single_face_selection仅largest与center_largest两个取值[detection].max_detected_faces部署级安全上限取值 1..100请求可以要求更少的结果但永远不能超过该值[web].disabled设为true即纯 API 模式——/v1与/openapi.json仍然可用但/、/docs、指南页面与前端静态资源不再注册。配置分层TOML 文件之外的部署级参数通过环境变量注入Compose 的environment段全部带${VAR:-default}形式例如INSIGHTFACE_SAVE_FACE_CROPS、INSIGHTFACE_DEFAULT_THRESHOLD默认0.4、INSIGHTFACE_COLLECTION_DEFAULT_SEARCH_PROFILE默认fp32_v1、INSIGHTFACE_COLLECTION_DEFAULT_CAPACITY_ROWS默认100000、INSIGHTFACE_COLLECTION_MAX_CAPACITY_ROWS默认10000000、INSIGHTFACE_COLLECTION_DEFAULT_MAX_FACES_PER_PERSON默认20、INSIGHTFACE_COLLECTION_DEFAULT_LOAD_POLICY默认lazy、INSIGHTFACE_SEARCH_DEVICE_ID默认0、INSIGHTFACE_SEARCH_TOPK_MODE默认auto、INSIGHTFACE_SEARCH_BUILD_BATCH_ROWS默认4096等。环境变量优先级高于 TOML例如显式设置INSIGHTFACE_INFERENCE_MAX_CONCURRENCY会覆盖文件中的max_concurrency见Settings.from_env中 env 与 file_config 的合并顺序。检测 profile 的作用范围config.py的Settings.detection_profile与此对应无状态 Detect 与 Embeddings 使用系统 profileCompare 可用系统 profile 或选定的 Collection注册与搜索使用各自 Collection 的 profile。新 Collection 拷贝系统检测 profile 后即可独立更新影响下一次请求。13. 精确搜索 profile 与容量System 响应只会通告当前 CPU/GPU 上实际可用的 profile。Collection 在创建时固定一个 profile后续搜索请求无法更改。可用 profile 定义于 config.py 的SUPPORTED_SEARCH_PROFILES并与 native.py 的_PROFILE_CODES一一对应Profile存储表示典型可用性fp32_v1FP32CPU 与 CUDAfp16_v1FP16CUDAbf16_v1BF16受支持的 CPU 或 SM80 CUDAint8_x736_v1INT8scale 736CPU 与 CUDA推荐的 INT8 方案int8_x1000_v1INT8scale 1000兼容性 profile所有 profile 都是对每个活跃 FaceSample 的扁平穷举搜索低精度 profile 只是对 FP32 分数的近似不是 ANN 索引。INT8 点积累加到 INT32对外暴露的相似度与阈值始终是原始余弦值。容量模型capacity_rows为 Collection 预留最大活跃行数避免常规增长停顿。512 维向量的近似存储开销为每 FP32 行 2,048 字节、每 FP16/BF16 行 1,024 字节、每 INT8 行 512 字节未计 ID 与工作区。请按实际内存预算设置容量默认100000部署护栏上限10000000。max_faces_per_person默认20它限制的是每个 Person 的样本数量而不是人数上限。原生索引层native.py通过ifs_search_grouped_topk执行分组 Person Top-K精确检索并校验查询与库内向量均为 L2 归一化容差2e-4确保余弦相似度的计算前提成立。14. CUDA 支持与 fail-fast 验证CUDA 镜像内含 CUDA Runtime 12.9.1、cuDNN 9.24.0、Python 3.11 与onnxruntime-gpu1.27.0。宿主机只需 Driver、Docker Engine、NVIDIA Container Toolkit 与兼容 GPUTuring、Ampere、Ada、HopperDriver R535 或更新Blackwell 与 RTX 50 系列Driver 570.26 或更新新部署建议优先使用稳定的 R580 或更新驱动。架构兼容性不构成对每个 GPU SKU 的正式认证声明。每次 CUDA 启动时 Server 都会检查GPU 型号、Compute Capability、Driver、实际 CUDA/cuDNN/ORT 版本、CUDAExecutionProvider是否存在、真实的检测与识别 Session 是否建立以及真实的预热推理是否成功。它审计 provider 放置情况一旦异常即终止进程而非静默回退 CPUCompose 中通过INSIGHTFACE_STRICT_CUDA1强化此行为。使用前请在System页确认校验结果。15. 构建、升级、备份与恢复用户可以从完整仓库检出构建两个镜像server/Makefilemake -C server build-cpu make -C server build-cuda12之后在 Compose 的模型安装与up命令中追加--pull never以使用本地镜像。构建使用固定的基础镜像与锁定依赖但需要网络访问获取这些输入。公共镜像标签为0.2.0-cpu/0.2.0-cuda12滚动的cpu/cuda12标签指向最新的稳定变体刻意不设latest标签。升级前停止写入对/data加 crop 存储做 SQLite 安全的快照保留/models及其许可文件。先基于副本启动新容器检查迁移与/v1/health再验证模型契约与一次已知搜索。收尾用docker compose down不加-vdocker compose down -v会删除命名数据卷。对外暴露时在可信反向代理处终结 HTTPS只放行必要的来源而非宽泛 CORS施加边缘限速/请求体/超时限制并将数据卷与备份作为生物识别数据保护。需要明确的是Server 第一阶段只提供单一无差别 API key不是多租户授权系统请据此设计访问控制边界。延伸阅读API 使用指南完整 HTTP 契约与全部端点Python SDK 客户端说明启动配置 server.tomlCPU Compose 部署文件 与 CUDA 12 Compose 部署文件服务端配置与校验实现、模型包目录与校验和、模型安装 CLI、原生精确搜索实现【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考