尧图网页设计 
InsightFace Server 用户指南从 Docker Compose 零启动到人脸库检索实战【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightfaceInsightFace Server 是 insightface 项目中面向服务化部署的人脸分析后端提供 Web UI、/v1REST API 与 Python SDK 三种使用方式。本文以 server/docs/user-guide.ko.md 为骨架结合仓库内 Compose 编排、TOML 配置与后端源码完整讲解从空目录启动服务、创建人员库Collection、注册人员Person到完成首次人脸检索的完整链路并深入 RTSP 摄像头监控、模型许可、精确检索 Profile、CUDA 严格启动检查与备份恢复等运维主题。读完本文你将掌握一套可离线部署、可扩展、具备合规模型授权的生产级人脸检索服务搭建方案。从零启动Compose 拉起服务并完成首次搜索环境前置条件CPU 版需要 Linux x86_64、Docker Engine 与 Docker Compose。CUDA 版在此基础上还需要兼容的 NVIDIA Driver 与 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/health执行顺序的含义mkdir -p server/.models创建模型挂载目录对应 server/deploy/compose.cpu.yml 中x-models-path: models-path ../.modelspull拉取镜像镜像标签为ghcr.io/deepinsight/insightface-server:0.2.0-cpurun --rm models install buffalo_l通过一次性models服务下载并校验模型包写入server/.models详见下文模型安装与许可章节up -d后台启动主服务将容器内8080端口映射到宿主机18097curl健康检查。/v1/health返回成功即代表服务可用。GPU 版把compose.cpu.yml换成compose.cuda12.yml健康检查端口改为18098。从 server/deploy/compose.cuda12.yml 可以看到 GPU 版额外设置INSIGHTFACE_EXECUTION_PROVIDERCUDAExecutionProvider、INSIGHTFACE_STRICT_CUDA1并声明gpus: all。认证默认关闭与上线前必做配置随项目提供的 Compose 在隔离评估环境中默认INSIGHTFACE_AUTH_ENABLEDfalse此时 API 无需认证字段Web UI 也会隐藏 API Key 输入。对外网开放前必须显式开启认证export INSIGHTFACE_AUTH_ENABLEDtrue export INSIGHTFACE_API_KEYreplace-with-a-long-random-secret docker compose -f server/deploy/compose.cpu.yml up -d注意INSIGHTFACE_AUTH_ENABLED、INSIGHTFACE_API_KEY等环境变量在 server/deploy/compose.cpu.yml 中以${VAR:-default}形式透传因此可直接作用于容器。认证的实现见 server/backend/insightface_server/api/auth.pyinitialize()在启动时把INSIGHTFACE_API_KEY同步进存储仅保存 hashrequire()校验Authorization: Bearer key请求头Key 不匹配时返回401 unauthorized。第一次操作按以下顺序完成确认仪表盘全部就绪 → 创建 Collection → 用至少一张清晰图片注册 Person → 用该人员的另一张图片执行 Search。没有匹配时返回空列表是正常的成功结果说明搜索链路已跑通。停止服务使用docker compose ... down且不要加-v-v会永久删除命名数据卷insightface-simple-cpu-data。登录与就绪状态检查CPU 打开http://服务器地址:18097/CUDA 12 打开http://服务器地址:18098/。若启用了认证点击配置 API Key粘贴管理员提供的 Key 并选择在此标签页使用。Key 只保留在当前标签页内存中刷新或关闭页面即清除——这是避免 Key 落入浏览器持久化存储的安全设计。注册数据前请查看仪表盘或系统页服务、数据库、模型和 Provider 均应显示就绪。CUDA 部署必须显示CUDAExecutionProvider且不会静默回退到 CPU详见CUDA 支持与严格启动检查章节。创建 Collection人员库打开人员库选择新建人员库需要设置稳定 ID例如employees后续 API 调用均以该 ID 定位 Collection展示名称、描述和可选 metadata默认 cosine 阈值初始建议0.4当前主机支持的 search profile精确检索 Profile 详见后文容量capacity_rows和每个 Person 最多 FaceSample 数检测输入尺寸、检测/NMS 阈值以及单脸挑选策略是否保存缩放为 112×112 的bounding-box cropJPEG。注意它不是识别模型使用的对齐输入默认关闭。关键约束Collection 会固定绑定模型 ID、版本、digest、特征维度和预处理版本。即使更换模型旧 Collection 依然可见但若模型契约不一致注册与检索会被显式拒绝对应错误码409 collection_model_mismatch。检测配置在创建时复制系统默认值之后可以单独修改修改从下一次请求生效并递增detection_revision但不会重新处理已有 FaceSample。单脸挑选策略single_face_selection有两个取值源码定义见 server/backend/insightface_server/config.py 的SUPPORTED_SINGLE_FACE_SELECTIONSlargest优先选择面积最大的人脸center_largest最大化人脸面积 - 2.0 × 人脸框中心到图像中心的像素距离平方即兼顾面积与居中程度检测置信度不参与该分数。注册 Person打开人员选择 Collection点击注册人员。可填写稳定的 Person ID、姓名、外部 ID 和 JSON metadata然后拖入一张或多张 JPEG、PNG 或 WebP 图片。图片大小上限为 10 MiB、像素上限 4000 万、单次最多 20 张对应 server/backend/insightface_server/config.py 中INSIGHTFACE_MAX_IMAGE_BYTES、INSIGHTFACE_MAX_IMAGE_PIXELS、INSIGHTFACE_MAX_REGISTRATION_IMAGES的默认值。入库审查模式review_modeoff使用 Collection 的单脸挑选策略允许图片中存在多张脸standard要求一张可用脸并检查尺寸、检测分数、清晰度、亮度和姿态strict在 standard 基础上要求样本的最佳类内相似度高于最佳类外相似度即与库内已有样本的相似度必须显著区分于其他人员。批量注册支持部分成功——每张图片独立返回注册结果系统会给出各失败图片的具体原因且不保存被拒绝的原图。启用人脸图保存时只保存缩放为 112×112 的bounding-box crop不保存原始上传图片。可信系统可以使用external_trusted模式提交预先抽取并 L2 归一化的 embedding仍需同时提供图片完成检测与质量审查但服务不会再次抽取特征embedding 契约必须与 Collection 完全一致。SDK 侧对应的类型定义见 server/sdk/python/src/insightface_server/client.pyReviewMode、EmbeddingMode等字面量类型。检测、比对与搜索检测上传单图可查看人脸框、五点关键点、检测分数和启发式质量信息。无人脸是成功的空列表。比对分别上传 source 和 target可选择系统或 Collection 检测配置。配置中的策略从两张图各挑选一张可用脸返回原始 cosinesimilarity、threshold和matched。Similarity 不是概率任一图片没有可用脸时返回422 face_not_found。搜索选择 Collection 与查询图片设置返回数量可临时覆盖阈值。系统按 Collection 检测配置挑选查询脸按相似度降序返回。Person 得分取其所有 FaceSample 的最高相似度无匹配是成功的空列表。写入一致性是这套服务的核心设计新 FaceSample 先提交到 SQLite再加入内存索引然后才返回成功删除操作同时更新两处。重启时从 SQLite 重建内存索引SQLite 始终是权威数据源。检索后端协议定义在 server/backend/insightface_server/search/base.pyMutableSearchIndex协议规定了add_batch、remove_batch、search_persons、stats等操作确保写入路径与查询路径严格同步。RTSP 摄像头监控打开摄像头监控点击新建监控任务填写任务 ID 和名称输入rtsp://或rtsps://地址选择 Collection并设置每秒推理次数和可选匹配阈值。事件策略可以设置连续多少帧后确认目标、离开超时、重复事件冷却时间以及内存中保留的最近事件数量。Monitor 的完整选项定义见 server/backend/insightface_server/services/rtsp.py 的MonitorOptions含confirm_frames、event_buffer_size等字段。关键特性Web 视频预览默认关闭但不开预览也会持续识别和生成事件开启后服务器传输原始 JPEG 帧Web UI 依据/state结果绘制标注绿色框表示已入库人员橙色框表示检测到但未入库的人脸Monitor 独立运行在服务器端关闭浏览器不会停止处于启用状态的任务会在 Server 重启后自动恢复使用启动/停止修改enabled使用编辑更换 RTSP 源或调整参数使用删除永久移除任务解码器只保留最新帧推理耗时超过设定周期时直接跳过过时帧不会排队补跑——这是保证实时性的重要策略Monitor 配置保存在 SQLite 中RTSP 凭据加密保存在/data且 API 不会回传视频帧不保存进入、离开、错误和恢复事件只保留在有上限的内存环形缓冲区进程重启后丢失。数据、备份与安全持久化挂载/data/models只读挂载见 server/deploy/compose.cpu.yml 的 volumes 定义停止写入后备份 SQLite 和裁剪图目录或使用 SQLite 安全快照方式API Key 只以 hash 保存见 server/backend/insightface_server/api/auth.py 的sync_api_key/verify_api_key后续启动同一数据卷时传入不同INSIGHTFACE_API_KEY会主动轮换当前 Key不要记录图片、embedding 或 Key除非确有需要不要开启宽泛 CORS公开镜像不包含模型。InsightFace 提供的开源预训练模型包括buffalo_l仅限非商业研究使用商业使用需要单独许可系统页面也会显示相同提示。模型安装与许可镜像本身不包含模型。正常 Server 启动是离线的模型通过一次性的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_lmodels服务的入口是python -m insightface_server.models_cliCLI 实现见 server/backend/insightface_server/models_cli.py支持list、install、verify、info四个子命令。支持的公开模型包定义在 server/backend/insightface_server/models/packages.py 的PACKAGES包名检测模型识别模型buffalo_ldet_10g.onnxw600k_r50.onnxbuffalo_mdet_2.5g.onnxw600k_r50.onnxbuffalo_scdet_500m.onnxw600k_mbf.onnxantelopev2scrfd_10g_bnkps.onnxglintr100.onnx安装流程具备完整的供应链校验download_archive逐块下载并比对归档 SHA-256extract_required_models对每个解压出的模型文件逐一校验 SHA-256安装成功后会生成manifest.json与签名许可文件MODEL.LICENSE。不带--accept-license时工具只显示许可并退出不会下载非交互环境下会直接报错提示添加该参数。models verify会核验包身份、签名、有效期和当前授权状态。许可按model_id表达授权是合规凭证不是 DRM也不要求模型文件 SHA-256 保持不变——因此用户可以将模型转换为 FP16、INT8 或 TensorRT 产物而不会破坏授权。启动时配置 server.toml 详解通用配置文件为 server/config/server.tomlCompose 将其只读挂载到容器内/etc/insightface/server.toml。该文件只在进程启动时读取一次修改后必须重启容器。完整默认配置如下[inference] max_concurrency auto # CPU为4CUDA为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各参数的含义与底层约束源码见 server/backend/insightface_server/config.py[inference].max_concurrencyauto时 CPU 解析为 4、CUDA 解析为 8default_inference_max_concurrency也支持正整数覆盖范围 1~256MAX_INFERENCE_MAX_CONCURRENCY。API 调用、注册与 RTSP 帧共享这一个进程级预算[detection].input_sizes每个条目为[宽, 高]。动态 SCRFD 模型会分别运行所有配置的分辨率把所有候选框映射回原图坐标后合并再对合并后的候选集执行一次全局 NMS。校验规则最多 4 个尺寸、每条边 32~2048 且必须是 32 的倍数SCRFD 最大特征图步长为 32、总像素不超过 4M防止配置错误耗尽内存[detection].threshold检测器最低置信度在 SCRFD 候选生成阶段、合并 NMS 之前生效[detection].nms_threshold全局 NMS 的 IoU 阈值[detection].single_face_selectionlargest或center_largest[detection].max_detected_faces部署级安全上限范围 1~100请求只能要求更少结果不能更多[web].disabledtrue时进入 API-only 模式/v1与/openapi.json仍可用但不注册/、/docs、帮助文档和前端静态资源。系统配置只在启动时读取不提供运行时修改 API。新 Collection 会复制系统检测配置之后可独立修改并从下一次请求生效。无状态 Detect 和 Embeddings 使用系统配置Compare 可使用系统配置或指定 Collection注册与 Search 始终使用 Collection 配置。精确检索 Profile 与容量系统接口只公布当前 CPU/GPU 真正可用的 Profile。Collection 在创建时固定 Profile不能在单次 Search 请求中临时切换。Profile存储类型常见可用环境fp32_v1FP32CPU 与 CUDAfp16_v1FP16CUDAbf16_v1BF16支持的 CPU 或 SM80 CUDAint8_x736_v1INT8scale 736CPU 与 CUDA推荐 INT8int8_x1000_v1INT8scale 1000兼容已有 Collection这些实现都会遍历全部有效 FaceSample属于 Flat 精确全量搜索不是 ANN 索引SEARCH_PROFILES定义于 server/backend/insightface_server/search/base.py。低精度 Profile 会近似 FP32 分数INT8 点积使用 INT32 累加。对外相似度和阈值始终是原始 cosine。容量与占用估算capacity_rows预留该 Collection 的最大有效行数避免常规扩容停顿。512 维向量的大致纯特征占用为FP32 每行 2,048 字节FP16/BF16 每行 1,024 字节INT8 每行 512 字节还需额外计算 ID 与工作区。默认容量100000部署级上限默认10000000对应 Compose 中INSIGHTFACE_COLLECTION_DEFAULT_CAPACITY_ROWS与INSIGHTFACE_COLLECTION_MAX_CAPACITY_ROWS。max_faces_per_person默认20限制单人样本数不限制 Person 数量。CUDA 支持与严格启动检查CUDA 镜像包含 CUDA Runtime 12.9.1、cuDNN 9.24.0、Python 3.11 和onnxruntime-gpu1.27.0。宿主机只需 Driver、Docker Engine、NVIDIA Container Toolkit 和兼容 GPU。Driver 版本要求Turing、Ampere、Ada、HopperDriver R535 或更高Blackwell 与 RTX 50 系列Driver 570.26 或更高新部署建议使用稳定的 R580 或更高版本。架构兼容不等于所有 GPU 型号都已经正式认证。每次 CUDA 启动都会核验 GPU 型号、Compute Capability、Driver、实际 CUDA/cuDNN/ORT 版本、CUDAExecutionProvider、真实检测与识别 Session 以及真实 warm-up 推理并审计 Provider 分配。任何关键检查失败都会终止启动不会静默回退 CPUCompose 中由INSIGHTFACE_STRICT_CUDA1强化该行为。使用前请在系统页面确认结果。Python SDK 快速上手面向开发者的 OpenAPI Schema 浏览器位于/docs每个响应都带x-request-id报告问题时请一并提供。SDK 代码位于 server/sdk/python/src/insightface_server/同步客户端Client封装了 Collections、Person、Search、Detect、Compare、Monitors 等全套操作图片输入支持路径、bytes、file-like 对象等多种形式ImageInput联合类型。from insightface_server import Client client Client(http://localhost:18097, api_keyyour-key) client.create_collection(collection_idemployees, name员工库, threshold0.4) client.add_person(employees, person_idalice, images[alice-1.jpg, alice-2.jpg]) matches client.search(employees, query.jpg, limit5)该示例中的三个方法分别对应创建 Collection、注册 Person 与执行 Search与 Web UI 中的操作路径一一对应。构建、升级、备份与恢复用户可从完整仓库自行构建镜像make -C server build-cpu make -C server build-cuda12随后在 Compose 的模型安装与up命令中加入--pull never即可使用本地镜像。构建使用固定基础镜像和锁定依赖但仍需联网获取这些输入。公开版本 Tag 为0.2.0-cpu和0.2.0-cuda12移动 Tagcpu/cuda12分别指向最新稳定版本明确不发布含义模糊的latest。升级前停止写入使用 SQLite 安全方式备份/data以及可选裁剪图并保留/models和许可文件。先用数据副本启动新镜像检查 migration、/v1/health、模型契约和一条已知 Search再切换正式数据。停止使用docker compose down且不要带-v。故障定位与错误码401 unauthorized当前标签页未配置 Key 或 Key 已轮换认证逻辑见 server/backend/insightface_server/api/auth.py409 collection_model_mismatchCollection 与当前模型契约不同模型 ID/版本/digest/维度/预处理不匹配422 face_not_found没有选出可用脸检查图片质量与检测阈值CUDA 模式在 Driver、GPU、模型 Session、Provider 或 warm-up 检查失败时会主动终止启动。排查时请结合系统页、容器日志以及响应中的request_id。跨网络使用时应在可信反向代理终止 HTTPS只开放必要的 CORS origin并在边缘限制速率、请求体和超时。数据卷及备份应按生物识别数据保护。第一阶段只有一个不区分权限的 API Key不应把它当作多租户授权系统对外公开前务必启用INSIGHTFACE_AUTH_ENABLEDtrue并设置足够长的随机INSIGHTFACE_API_KEY。完整的 HTTP 字段与响应说明请查阅 server/docs/api.ko.mdAPI 使用手册。【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 InsightFace Server 用户指南：从 Docker Compose 零启动到人脸库检索实战
InsightFace Server 用户指南从 Docker Compose 零启动到人脸库检索实战【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightfaceInsightFace Server 是 insightface 项目中面向服务化部署的人脸分析后端提供 Web UI、/v1REST API 与 Python SDK 三种使用方式。本文以 server/docs/user-guide.ko.md 为骨架结合仓库内 Compose 编排、TOML 配置与后端源码完整讲解从空目录启动服务、创建人员库Collection、注册人员Person到完成首次人脸检索的完整链路并深入 RTSP 摄像头监控、模型许可、精确检索 Profile、CUDA 严格启动检查与备份恢复等运维主题。读完本文你将掌握一套可离线部署、可扩展、具备合规模型授权的生产级人脸检索服务搭建方案。从零启动Compose 拉起服务并完成首次搜索环境前置条件CPU 版需要 Linux x86_64、Docker Engine 与 Docker Compose。CUDA 版在此基础上还需要兼容的 NVIDIA Driver 与 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/health执行顺序的含义mkdir -p server/.models创建模型挂载目录对应 server/deploy/compose.cpu.yml 中x-models-path: models-path ../.modelspull拉取镜像镜像标签为ghcr.io/deepinsight/insightface-server:0.2.0-cpurun --rm models install buffalo_l通过一次性models服务下载并校验模型包写入server/.models详见下文模型安装与许可章节up -d后台启动主服务将容器内8080端口映射到宿主机18097curl健康检查。/v1/health返回成功即代表服务可用。GPU 版把compose.cpu.yml换成compose.cuda12.yml健康检查端口改为18098。从 server/deploy/compose.cuda12.yml 可以看到 GPU 版额外设置INSIGHTFACE_EXECUTION_PROVIDERCUDAExecutionProvider、INSIGHTFACE_STRICT_CUDA1并声明gpus: all。认证默认关闭与上线前必做配置随项目提供的 Compose 在隔离评估环境中默认INSIGHTFACE_AUTH_ENABLEDfalse此时 API 无需认证字段Web UI 也会隐藏 API Key 输入。对外网开放前必须显式开启认证export INSIGHTFACE_AUTH_ENABLEDtrue export INSIGHTFACE_API_KEYreplace-with-a-long-random-secret docker compose -f server/deploy/compose.cpu.yml up -d注意INSIGHTFACE_AUTH_ENABLED、INSIGHTFACE_API_KEY等环境变量在 server/deploy/compose.cpu.yml 中以${VAR:-default}形式透传因此可直接作用于容器。认证的实现见 server/backend/insightface_server/api/auth.pyinitialize()在启动时把INSIGHTFACE_API_KEY同步进存储仅保存 hashrequire()校验Authorization: Bearer key请求头Key 不匹配时返回401 unauthorized。第一次操作按以下顺序完成确认仪表盘全部就绪 → 创建 Collection → 用至少一张清晰图片注册 Person → 用该人员的另一张图片执行 Search。没有匹配时返回空列表是正常的成功结果说明搜索链路已跑通。停止服务使用docker compose ... down且不要加-v-v会永久删除命名数据卷insightface-simple-cpu-data。登录与就绪状态检查CPU 打开http://服务器地址:18097/CUDA 12 打开http://服务器地址:18098/。若启用了认证点击配置 API Key粘贴管理员提供的 Key 并选择在此标签页使用。Key 只保留在当前标签页内存中刷新或关闭页面即清除——这是避免 Key 落入浏览器持久化存储的安全设计。注册数据前请查看仪表盘或系统页服务、数据库、模型和 Provider 均应显示就绪。CUDA 部署必须显示CUDAExecutionProvider且不会静默回退到 CPU详见CUDA 支持与严格启动检查章节。创建 Collection人员库打开人员库选择新建人员库需要设置稳定 ID例如employees后续 API 调用均以该 ID 定位 Collection展示名称、描述和可选 metadata默认 cosine 阈值初始建议0.4当前主机支持的 search profile精确检索 Profile 详见后文容量capacity_rows和每个 Person 最多 FaceSample 数检测输入尺寸、检测/NMS 阈值以及单脸挑选策略是否保存缩放为 112×112 的bounding-box cropJPEG。注意它不是识别模型使用的对齐输入默认关闭。关键约束Collection 会固定绑定模型 ID、版本、digest、特征维度和预处理版本。即使更换模型旧 Collection 依然可见但若模型契约不一致注册与检索会被显式拒绝对应错误码409 collection_model_mismatch。检测配置在创建时复制系统默认值之后可以单独修改修改从下一次请求生效并递增detection_revision但不会重新处理已有 FaceSample。单脸挑选策略single_face_selection有两个取值源码定义见 server/backend/insightface_server/config.py 的SUPPORTED_SINGLE_FACE_SELECTIONSlargest优先选择面积最大的人脸center_largest最大化人脸面积 - 2.0 × 人脸框中心到图像中心的像素距离平方即兼顾面积与居中程度检测置信度不参与该分数。注册 Person打开人员选择 Collection点击注册人员。可填写稳定的 Person ID、姓名、外部 ID 和 JSON metadata然后拖入一张或多张 JPEG、PNG 或 WebP 图片。图片大小上限为 10 MiB、像素上限 4000 万、单次最多 20 张对应 server/backend/insightface_server/config.py 中INSIGHTFACE_MAX_IMAGE_BYTES、INSIGHTFACE_MAX_IMAGE_PIXELS、INSIGHTFACE_MAX_REGISTRATION_IMAGES的默认值。入库审查模式review_modeoff使用 Collection 的单脸挑选策略允许图片中存在多张脸standard要求一张可用脸并检查尺寸、检测分数、清晰度、亮度和姿态strict在 standard 基础上要求样本的最佳类内相似度高于最佳类外相似度即与库内已有样本的相似度必须显著区分于其他人员。批量注册支持部分成功——每张图片独立返回注册结果系统会给出各失败图片的具体原因且不保存被拒绝的原图。启用人脸图保存时只保存缩放为 112×112 的bounding-box crop不保存原始上传图片。可信系统可以使用external_trusted模式提交预先抽取并 L2 归一化的 embedding仍需同时提供图片完成检测与质量审查但服务不会再次抽取特征embedding 契约必须与 Collection 完全一致。SDK 侧对应的类型定义见 server/sdk/python/src/insightface_server/client.pyReviewMode、EmbeddingMode等字面量类型。检测、比对与搜索检测上传单图可查看人脸框、五点关键点、检测分数和启发式质量信息。无人脸是成功的空列表。比对分别上传 source 和 target可选择系统或 Collection 检测配置。配置中的策略从两张图各挑选一张可用脸返回原始 cosinesimilarity、threshold和matched。Similarity 不是概率任一图片没有可用脸时返回422 face_not_found。搜索选择 Collection 与查询图片设置返回数量可临时覆盖阈值。系统按 Collection 检测配置挑选查询脸按相似度降序返回。Person 得分取其所有 FaceSample 的最高相似度无匹配是成功的空列表。写入一致性是这套服务的核心设计新 FaceSample 先提交到 SQLite再加入内存索引然后才返回成功删除操作同时更新两处。重启时从 SQLite 重建内存索引SQLite 始终是权威数据源。检索后端协议定义在 server/backend/insightface_server/search/base.pyMutableSearchIndex协议规定了add_batch、remove_batch、search_persons、stats等操作确保写入路径与查询路径严格同步。RTSP 摄像头监控打开摄像头监控点击新建监控任务填写任务 ID 和名称输入rtsp://或rtsps://地址选择 Collection并设置每秒推理次数和可选匹配阈值。事件策略可以设置连续多少帧后确认目标、离开超时、重复事件冷却时间以及内存中保留的最近事件数量。Monitor 的完整选项定义见 server/backend/insightface_server/services/rtsp.py 的MonitorOptions含confirm_frames、event_buffer_size等字段。关键特性Web 视频预览默认关闭但不开预览也会持续识别和生成事件开启后服务器传输原始 JPEG 帧Web UI 依据/state结果绘制标注绿色框表示已入库人员橙色框表示检测到但未入库的人脸Monitor 独立运行在服务器端关闭浏览器不会停止处于启用状态的任务会在 Server 重启后自动恢复使用启动/停止修改enabled使用编辑更换 RTSP 源或调整参数使用删除永久移除任务解码器只保留最新帧推理耗时超过设定周期时直接跳过过时帧不会排队补跑——这是保证实时性的重要策略Monitor 配置保存在 SQLite 中RTSP 凭据加密保存在/data且 API 不会回传视频帧不保存进入、离开、错误和恢复事件只保留在有上限的内存环形缓冲区进程重启后丢失。数据、备份与安全持久化挂载/data/models只读挂载见 server/deploy/compose.cpu.yml 的 volumes 定义停止写入后备份 SQLite 和裁剪图目录或使用 SQLite 安全快照方式API Key 只以 hash 保存见 server/backend/insightface_server/api/auth.py 的sync_api_key/verify_api_key后续启动同一数据卷时传入不同INSIGHTFACE_API_KEY会主动轮换当前 Key不要记录图片、embedding 或 Key除非确有需要不要开启宽泛 CORS公开镜像不包含模型。InsightFace 提供的开源预训练模型包括buffalo_l仅限非商业研究使用商业使用需要单独许可系统页面也会显示相同提示。模型安装与许可镜像本身不包含模型。正常 Server 启动是离线的模型通过一次性的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_lmodels服务的入口是python -m insightface_server.models_cliCLI 实现见 server/backend/insightface_server/models_cli.py支持list、install、verify、info四个子命令。支持的公开模型包定义在 server/backend/insightface_server/models/packages.py 的PACKAGES包名检测模型识别模型buffalo_ldet_10g.onnxw600k_r50.onnxbuffalo_mdet_2.5g.onnxw600k_r50.onnxbuffalo_scdet_500m.onnxw600k_mbf.onnxantelopev2scrfd_10g_bnkps.onnxglintr100.onnx安装流程具备完整的供应链校验download_archive逐块下载并比对归档 SHA-256extract_required_models对每个解压出的模型文件逐一校验 SHA-256安装成功后会生成manifest.json与签名许可文件MODEL.LICENSE。不带--accept-license时工具只显示许可并退出不会下载非交互环境下会直接报错提示添加该参数。models verify会核验包身份、签名、有效期和当前授权状态。许可按model_id表达授权是合规凭证不是 DRM也不要求模型文件 SHA-256 保持不变——因此用户可以将模型转换为 FP16、INT8 或 TensorRT 产物而不会破坏授权。启动时配置 server.toml 详解通用配置文件为 server/config/server.tomlCompose 将其只读挂载到容器内/etc/insightface/server.toml。该文件只在进程启动时读取一次修改后必须重启容器。完整默认配置如下[inference] max_concurrency auto # CPU为4CUDA为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各参数的含义与底层约束源码见 server/backend/insightface_server/config.py[inference].max_concurrencyauto时 CPU 解析为 4、CUDA 解析为 8default_inference_max_concurrency也支持正整数覆盖范围 1~256MAX_INFERENCE_MAX_CONCURRENCY。API 调用、注册与 RTSP 帧共享这一个进程级预算[detection].input_sizes每个条目为[宽, 高]。动态 SCRFD 模型会分别运行所有配置的分辨率把所有候选框映射回原图坐标后合并再对合并后的候选集执行一次全局 NMS。校验规则最多 4 个尺寸、每条边 32~2048 且必须是 32 的倍数SCRFD 最大特征图步长为 32、总像素不超过 4M防止配置错误耗尽内存[detection].threshold检测器最低置信度在 SCRFD 候选生成阶段、合并 NMS 之前生效[detection].nms_threshold全局 NMS 的 IoU 阈值[detection].single_face_selectionlargest或center_largest[detection].max_detected_faces部署级安全上限范围 1~100请求只能要求更少结果不能更多[web].disabledtrue时进入 API-only 模式/v1与/openapi.json仍可用但不注册/、/docs、帮助文档和前端静态资源。系统配置只在启动时读取不提供运行时修改 API。新 Collection 会复制系统检测配置之后可独立修改并从下一次请求生效。无状态 Detect 和 Embeddings 使用系统配置Compare 可使用系统配置或指定 Collection注册与 Search 始终使用 Collection 配置。精确检索 Profile 与容量系统接口只公布当前 CPU/GPU 真正可用的 Profile。Collection 在创建时固定 Profile不能在单次 Search 请求中临时切换。Profile存储类型常见可用环境fp32_v1FP32CPU 与 CUDAfp16_v1FP16CUDAbf16_v1BF16支持的 CPU 或 SM80 CUDAint8_x736_v1INT8scale 736CPU 与 CUDA推荐 INT8int8_x1000_v1INT8scale 1000兼容已有 Collection这些实现都会遍历全部有效 FaceSample属于 Flat 精确全量搜索不是 ANN 索引SEARCH_PROFILES定义于 server/backend/insightface_server/search/base.py。低精度 Profile 会近似 FP32 分数INT8 点积使用 INT32 累加。对外相似度和阈值始终是原始 cosine。容量与占用估算capacity_rows预留该 Collection 的最大有效行数避免常规扩容停顿。512 维向量的大致纯特征占用为FP32 每行 2,048 字节FP16/BF16 每行 1,024 字节INT8 每行 512 字节还需额外计算 ID 与工作区。默认容量100000部署级上限默认10000000对应 Compose 中INSIGHTFACE_COLLECTION_DEFAULT_CAPACITY_ROWS与INSIGHTFACE_COLLECTION_MAX_CAPACITY_ROWS。max_faces_per_person默认20限制单人样本数不限制 Person 数量。CUDA 支持与严格启动检查CUDA 镜像包含 CUDA Runtime 12.9.1、cuDNN 9.24.0、Python 3.11 和onnxruntime-gpu1.27.0。宿主机只需 Driver、Docker Engine、NVIDIA Container Toolkit 和兼容 GPU。Driver 版本要求Turing、Ampere、Ada、HopperDriver R535 或更高Blackwell 与 RTX 50 系列Driver 570.26 或更高新部署建议使用稳定的 R580 或更高版本。架构兼容不等于所有 GPU 型号都已经正式认证。每次 CUDA 启动都会核验 GPU 型号、Compute Capability、Driver、实际 CUDA/cuDNN/ORT 版本、CUDAExecutionProvider、真实检测与识别 Session 以及真实 warm-up 推理并审计 Provider 分配。任何关键检查失败都会终止启动不会静默回退 CPUCompose 中由INSIGHTFACE_STRICT_CUDA1强化该行为。使用前请在系统页面确认结果。Python SDK 快速上手面向开发者的 OpenAPI Schema 浏览器位于/docs每个响应都带x-request-id报告问题时请一并提供。SDK 代码位于 server/sdk/python/src/insightface_server/同步客户端Client封装了 Collections、Person、Search、Detect、Compare、Monitors 等全套操作图片输入支持路径、bytes、file-like 对象等多种形式ImageInput联合类型。from insightface_server import Client client Client(http://localhost:18097, api_keyyour-key) client.create_collection(collection_idemployees, name员工库, threshold0.4) client.add_person(employees, person_idalice, images[alice-1.jpg, alice-2.jpg]) matches client.search(employees, query.jpg, limit5)该示例中的三个方法分别对应创建 Collection、注册 Person 与执行 Search与 Web UI 中的操作路径一一对应。构建、升级、备份与恢复用户可从完整仓库自行构建镜像make -C server build-cpu make -C server build-cuda12随后在 Compose 的模型安装与up命令中加入--pull never即可使用本地镜像。构建使用固定基础镜像和锁定依赖但仍需联网获取这些输入。公开版本 Tag 为0.2.0-cpu和0.2.0-cuda12移动 Tagcpu/cuda12分别指向最新稳定版本明确不发布含义模糊的latest。升级前停止写入使用 SQLite 安全方式备份/data以及可选裁剪图并保留/models和许可文件。先用数据副本启动新镜像检查 migration、/v1/health、模型契约和一条已知 Search再切换正式数据。停止使用docker compose down且不要带-v。故障定位与错误码401 unauthorized当前标签页未配置 Key 或 Key 已轮换认证逻辑见 server/backend/insightface_server/api/auth.py409 collection_model_mismatchCollection 与当前模型契约不同模型 ID/版本/digest/维度/预处理不匹配422 face_not_found没有选出可用脸检查图片质量与检测阈值CUDA 模式在 Driver、GPU、模型 Session、Provider 或 warm-up 检查失败时会主动终止启动。排查时请结合系统页、容器日志以及响应中的request_id。跨网络使用时应在可信反向代理终止 HTTPS只开放必要的 CORS origin并在边缘限制速率、请求体和超时。数据卷及备份应按生物识别数据保护。第一阶段只有一个不区分权限的 API Key不应把它当作多租户授权系统对外公开前务必启用INSIGHTFACE_AUTH_ENABLEDtrue并设置足够长的随机INSIGHTFACE_API_KEY。完整的 HTTP 字段与响应说明请查阅 server/docs/api.ko.mdAPI 使用手册。【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考