InsightFace Server 实战指南单卡 GPU 承载 50M 人脸向量的自托管人脸识别服务【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightfaceInsightFace Server 是 InsightFace 仓库中面向生产环境的自托管人脸识别服务当前版本 0.2.0Linux x86_64一个容器同时提供 Web UI、REST API、SQLite 持久化与本地 CPU 或 NVIDIA GPU 推理核心能力是 SCRFD 检测 ArcFace 特征 基于 INT8 特征量化的精确 1:N Person 搜索。读完本文你将掌握它的部署方式Compose 一键启动与源码构建、关键配置参数检测 Profile、检索 profile、容量与并发、API/SDK 调用方式以及底层原生精确检索的实现契约。定位与数据流Server 面向“上传图片 - 检测、比对、注册或搜索”这一最常用的人脸识别闭环是注重数据隐私的自托管方案图片、特征、模型和索引都可以留在自己的网络内。需要明确它的边界——它不是AWS Rekognition 兼容替代品不实现 SigV4、IAM、Region 或 AWS 资源语义也不内置 TLS、用户账户、RBAC、云 IAM 或法律合规层。模型许可注意InsightFace 公开预训练模型通常仅限非商业研究用途商业使用需要前往 InsightFace 官网单独获取授权该声明独立于 Server 源码的 MIT License许可细节见 server/LICENSING.md。功能概览识别管线SCRFD 人脸检测、五点关键点、对齐、ArcFace 512 维特征、L2 normalization、原始 cosine similarity、精确 1:N Person 搜索多分辨率检测动态 SCRFD 模型在每组配置的分辨率上分别推理将所有候选映射回源图坐标后做一次全局 NMS单脸策略支持largest和center_largest数据模型Collection - Person - FaceSample三级结构Collection 绑定模型多图片注册支持部分成功、metadata 与明确的拒绝原因审核模式注册review_mode支持off、standard、strict也支持external_trusted外部可信特征量化检索GPU 精确检索支持 FP32、FP16、BF16 和 INT8 向量存储Web UI多语言界面覆盖仪表盘、人员库、人员、人脸检测、比对、搜索、RTSP 监控、系统诊断和帮助API 与 SDK/v1下提供 29 个 snake_case REST 接口包括受保护的/v1/embeddings附带轻量 Python SDKRTSP Monitor服务端独立运行、保存有限的内存事件、支持多客户端可选preview.mjpeg关闭浏览器不会停止监控持久化与运维SQLite 是持久化事实来源内存精确索引可重建/models只读、/data持久化提供 migration、健康检查与禁止静默 CPU 回退的严格 CUDA 启动验证图片格式支持 JPEG、PNG、WebP默认不保留原始上传图片。RTX 5090 上的 GPU 检索性能在单张 NVIDIA GeForce RTX 509032,607 MiB上原生 CUDA 精确全量扫描索引使用 INT8 时实测最多可保存58.9M 个 512 维图片特征向量GPU 数据类型最大图片向量数10M Top-5 p5010M 串行 QPSFP3215.8M12.84 ms77.85FP1630.7M6.83 ms146.32BF1630.7M6.83 ms146.33INT858.9M3.84 ms260.81与 FP32 相比INT8 的实测容量为 3.73 倍10M Top-5 吞吐为 3.35 倍。以上仅为同一张 RTX 5090、Driver 580.105.08、CUDA 12.9 上的 GPU 实测。容量是未加载 ONNX 模型和 Server 工作负载时的独立原生索引极限速度测试固定为 10M 个图片特征向量执行 GPU 驻留的 Top-5 全量精确扫描单请求串行预热 10 次后测量 100 次。索引在各自存储表示内是精确搜索但量化仍可能使分数相对 FP32 发生变化生产部署还必须为模型、请求、并发、索引重建和显存分配器预留空间。ICCV21-MFR 多人种 MR-ALL 精度INT8 的精度代价仓库在 challenges/iccv21-mfr/ 的多人种MR测试集上按照 MR-ALL 全组队 1:1 协议、FAR1e-6测试了原生检索 profile。所有 profile 复用同一批由 Server API 一次性提取并完成 L2 normalization 的 512 维buffalo_l特征仅改变向量存储和检索计算表示检索 profileFAR 1e-6 下的 MR-ALLCosine 阈值相对 FP32FP3291.249107%0.407787—FP1691.249197%0.4077870.000090 个百分点BF1691.248502%0.407787-0.000605 个百分点INT891.248005%0.407739-0.001102 个百分点结论INT8 在该测评中没有实质精度损失。按挑战常用的两位小数展示FP32 和 INT8 的 MR-ALL 均为91.25%未四舍五入的差异也只有 0.0011 个百分点同时保留了上文 3.73 倍实测容量与 3.35 倍 10M Top-5 吞吐优势。这里对比的是向量存储与检索精度并非 INT8 模型推理。量化分数契约源码级佐证上述“量化后仍精确”的承诺来自原生检索库的显式分数契约。server/native/search/README.md 定义了 C ABI v2固定 512 维输入必须是有限、FP32 且 L2-normalized所有返回分数使用原始 cosine 语义q clamp(round_half_away_from_zero(x * S), -128, 127) score_internal int32_dot(q_database, q_query) / (S * S) similarity clamp(score_internal, -1, 1)INT8 支持两种比例系数 profileINT8_X736_V1推荐与INT8_X1000_V1遗留兼容。两者是相互独立的按索引契约可在同一进程共存已有的 x1000 Collection 永远不会被静默重解释为 x736。CPU、CUDA 与 NumPy 参考实现刻意采用相同的 FP32 语义做乘法与“远离零的一半”舍入内部未缩放 INT32 累加器不对外暴露保证排序精确、返回分数落在 [-1, 1]。Profile 支持矩阵同一文档确认ProfileCPUCUDAFP32_V1支持支持FP16_V1不支持返回IFS_SEARCH_UNSUPPORTED支持BF16_V1支持仅 Ampere/SM80 及以上Turing 支持 FP32/FP16/INT8INT8_X736_V1支持支持INT8_X1000_V1支持支持不支持的 profile 与 CUDA 失败一律 fail-closed两个原生库内部没有任何 dtype 降级或 CPU 回退——这与 Server 层面“禁止静默 CPU 回退”的严格 CUDA 启动验证Compose 中的INSIGHTFACE_STRICT_CUDA1相互呼应。快速开始环境要求安装 Docker Engine 和 Docker Compose 的 Linux x86_64CUDA 版本还需要受支持的 NVIDIA GPU、NVIDIA Driver 和 NVIDIA Container Toolkit。宿主机不需要安装 Python、OpenCV、ONNX Runtime、CUDA Toolkit 或 cuDNN。公开镜像不包含模型、客户数据、API Key 或生产配置。运行环境与镜像运行环境镜像CPUghcr.io/deepinsight/insightface-server:0.2.0-cpuNVIDIA GPUghcr.io/deepinsight/insightface-server:0.2.0-cuda12滚动标签cpu和cuda12分别指向对应运行环境的最新稳定版本不提供含义模糊的latest。发布规则见维护者指南仅英文。1. 安装模型在完整 InsightFace 仓库中将模型安装到server/.modelsCompose 文件通过 YAML 锚点把该路径绑定为容器内只读的/modelsmkdir -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模型工具还支持buffalo_m、buffalo_sc和antelopev2。安装会生成manifest.json和签名的MODEL.LICENSE可以用models verify核验。2. 启动 CPU 服务docker compose -f server/deploy/compose.cpu.yml up -d curl -fsS http://127.0.0.1:18097/v1/health3. 启动 CUDA 12 服务docker compose -f server/deploy/compose.cuda12.yml pull docker compose -f server/deploy/compose.cuda12.yml \ run --rm models install buffalo_l --accept-license docker compose -f server/deploy/compose.cuda12.yml up -d curl -fsS http://127.0.0.1:18098/v1/healthCPU 打开http://服务器地址:18097/CUDA 打开http://服务器地址:18098/对应两个 Compose 文件中的端口映射18097:8080与18098:8080。创建 Collection、为 Person 上传一张或多张注册照再用另一张照片搜索。停止时使用不带-v的docker compose ... down即可保留数据库卷。4. 开放网络前必须开启认证项目提供的 Compose 配置在隔离评估环境中默认关闭认证。对其他用户或网络开放前export INSIGHTFACE_AUTH_ENABLEDtrue export INSIGHTFACE_API_KEY请替换为足够长的随机密钥 docker compose -f server/deploy/compose.cpu.yml up -d完整的首次使用流程参见新手用户指南。Compose 配置要点对照仓库文件server/deploy/compose.cpu.yml 与 server/deploy/compose.cuda12.yml 结构一致值得注意的工程细节安全加固read_only: true根文件系统、非特权用户10001:10001、cap_drop: [ALL]、no-new-privileges:true、pids_limit、受限 tmpfs三卷分离/etc/insightface/server.toml只读绑定 server/config/server.toml、/data命名卷SQLite 与持久数据、/models只读绑定server/.models关键环境变量及默认值两个文件相同环境变量默认值作用INSIGHTFACE_DEFAULT_THRESHOLD0.4默认 cosine 阈值INSIGHTFACE_COLLECTION_DEFAULT_SEARCH_PROFILEfp32_v1新 Collection 默认检索 profileINSIGHTFACE_COLLECTION_DEFAULT_CAPACITY_ROWS100000新 Collection 默认索引容量INSIGHTFACE_COLLECTION_MAX_CAPACITY_ROWS10000000容量上限INSIGHTFACE_COLLECTION_DEFAULT_MAX_FACES_PER_PERSON20每 Person 最大 FaceSample 数INSIGHTFACE_COLLECTION_DEFAULT_LOAD_POLICYlazy索引加载策略INSIGHTFACE_SEARCH_DEVICE_ID0检索使用的 GPU 编号INSIGHTFACE_SEARCH_TOPK_MODEautoPerson Top-K 模式INSIGHTFACE_SEARCH_BUILD_BATCH_ROWS4096索引重建批量INSIGHTFACE_SAVE_FACE_CROPSfalse是否保存人脸 cropCUDA 文件额外设置INSIGHTFACE_STRICT_CUDA1、CUDA_MODULE_LOADINGLAZY与NVIDIA_*容器环境变量实现“严格 CUDA 启动验证”启动时校验 GPU 可用拒绝静默回退 CPU。从源码构建Dockerfile 会复制server/和python-package/insightface/中选定的推理模块所以必须使用完整仓库作为构建上下文Makefile 中的docker build ... ..即以仓库根目录为上下文。CPUmake -C server build-cpu docker compose -f server/deploy/compose.cpu.yml \ run --rm --pull never models install buffalo_l --accept-license docker compose -f server/deploy/compose.cpu.yml \ up -d --no-build --pull neverCUDA 12make -C server build-cuda12 docker compose -f server/deploy/compose.cuda12.yml \ run --rm --pull never models install buffalo_l --accept-license docker compose -f server/deploy/compose.cuda12.yml \ up -d --no-build --pull never--pull never确保 Compose 使用本地构建的镜像。构建过程仍会下载锁定的基础镜像和依赖模型安装会单独下载已接受许可的模型包。server/Makefile 中还提供了test、test-api、test-sdk、test-frontend、test-native-cpuCMake CTest 构建并测试原生检索库、smoke-test、release-preflight等目标可用于本地验证。核心行为部署与调参必读Similarity 是原始 cosine 值不是概率阈值使用0.0..1.0默认0.4。Collection 固定绑定模型和 embedding contract模型不匹配时仍可查看但注册和搜索返回collection_model_mismatch。检测 Profile 的继承与独立启动时的检测 Profile 会复制给新 Collection之后 Collection Profile 可以独立修改并从下一次请求生效。可选人脸保存保存内容是缩放为 112x112 的 bounding-box JPEG crop不是原始上传图片也不是识别模型使用的对齐输入默认关闭INSIGHTFACE_SAVE_FACE_CROPSfalse。SQLite 提交是事实来源注册或删除成功返回前会同步索引重启后索引从 SQLite 重建。响应可追踪响应包含x-request-id列表接口使用不透明的签名 cursor 分页。这些行为的对应配置项集中在 server/config/server.toml[inference] # auto resolves to 4 concurrent model pipelines on CPU and 8 on CUDA. # A positive integer overrides the provider-specific default. max_concurrency auto [detection] # 每个条目为 [width, height]所有分辨率分别推理 # 候选映射回源图坐标后做一次全局 NMS。 input_sizes [[96, 96], [512, 512]] threshold 0.50 # SCRFD 候选生成阶段的最低置信度在合并 NMS 之前生效 nms_threshold 0.40 # 全局 NMS 的 IoU 阈值 single_face_selection largest # 或 center_largest max_detected_faces 100 # 部署级安全上限请求只能要求更少 [web] disabled false # true 时进入 API-only 模式仅保留 /v1 与 /openapi.json其中center_largest策略最大化像素空间得分area - 2.0 * squared_distance(face_box_center, image_center)适合“画面中心的那张脸”场景。API 与 SDK主要 API 分组共 29 个接口交互式 OpenAPI 保留在/docs系统/v1/health、/v1/system、/v1/models无状态人脸接口/v1/detect、/v1/compare、/v1/embeddings受保护Collection / Person / FaceSample CRUDCollection Person 搜索RTSP Monitor配置、状态、事件和预览。所有参数、响应、错误和示例见完整 REST API 使用指南。配套 Python SDK 的最小用法from insightface_server import Client with Client(http://localhost:18097, api_keyNone) as client: faces client.detect(photo.jpg) matches client.search(employees, unknown.jpg, limit5)SDK 源码位于 server/sdk/python/SDK 安装、图片输入、方法和完整流程见用户指南。检索后端选择机制源码级佐证Server 的内存精确索引由 server/backend/insightface_server/search/factory.py 中的create_search_backend选择后端。从源码结构看search_backendauto时的决策链是推理模式为mock时使用 NumPy 参考实现ReferenceSearchBackend执行提供方为CUDAExecutionProvider时加载libifs_search_cuda.sonative_cuda否则加载libifs_search_cpu.sonative_cpu。原生后端加载后还会执行一次分组 Top-K 自检添加/搜索/删除各一条记录并校验分数失败即启动失败——这是“fail-closed、无静默降级”设计在 Python 层的落点。库的默认路径为/opt/insightface/server/native/lib也可通过search_library_path覆盖原生路径强制维度为 512与 ABI v2 契约一致。CUDA 端 Person Top-K 的实现细节来自 server/native/search/README.md行到组的元数据驻留设备端两遍 GPU 归约先求每个 Person 的最高分再确定其确定性最优 FaceSample同分时取最小 vector ID最终只有前 K至多 100条(group_id, vector_id, score)记录跨 PCIeCUDA 删除采用 tombstone因此physical_rows在删除/重加循环中持续增长Server 需要在 tombstone 耗尽容量前重建 Collection 代际——这也是“SQLite 为事实来源、索引可重建”设计的原因之一。安全提示人脸图片和 embedding 属于生物特征数据。网络部署时应开启认证、通过可信反向代理终止 HTTPS、限制 Docker 和数据卷访问、保持宽泛 CORS 关闭、制定备份/留存/删除/同意和安全事件处理策略日志中不得记录图片、embedding、RTSP 凭据或 API Key。部署和安全操作细节见用户指南。第一阶段范围明确不做的事当前版本不实现AWS/CompreFace 兼容、CUDA 11、Jetson、ARM64、Windows Container、TensorRT、Kubernetes、分布式 Worker、持久化 Monitor 事件或录像/NVR也不实现活体检测、Deepfake Detection 和人口属性分析。延伸阅读用户指南完整覆盖安装、配置、模型、Web UI、SDK、GPU、安全、备份和故障定位REST API 使用指南覆盖每个公开接口、字段、行为、结果、错误、分页规则和示例维护者指南仅英文架构、检索内部实现、测试、贡献规则和容器发布server/LICENSING.md许可入口——Server 源码与 Python SDK 采用 MIT License该声明不覆盖模型文件、模型权重、数据集或第三方组件。GitHub 文档与 Web UI 帮助页读取完全相同的本地化 User Guide 和 API Guide Markdown区别只在渲染方式——这意味着 UI 内查看的文档始终与仓库内容一致。【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 InsightFace Server 实战指南：单卡 GPU 承载 50M+ 人脸向量的自托管人脸识别服务
InsightFace Server 实战指南单卡 GPU 承载 50M 人脸向量的自托管人脸识别服务【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightfaceInsightFace Server 是 InsightFace 仓库中面向生产环境的自托管人脸识别服务当前版本 0.2.0Linux x86_64一个容器同时提供 Web UI、REST API、SQLite 持久化与本地 CPU 或 NVIDIA GPU 推理核心能力是 SCRFD 检测 ArcFace 特征 基于 INT8 特征量化的精确 1:N Person 搜索。读完本文你将掌握它的部署方式Compose 一键启动与源码构建、关键配置参数检测 Profile、检索 profile、容量与并发、API/SDK 调用方式以及底层原生精确检索的实现契约。定位与数据流Server 面向“上传图片 - 检测、比对、注册或搜索”这一最常用的人脸识别闭环是注重数据隐私的自托管方案图片、特征、模型和索引都可以留在自己的网络内。需要明确它的边界——它不是AWS Rekognition 兼容替代品不实现 SigV4、IAM、Region 或 AWS 资源语义也不内置 TLS、用户账户、RBAC、云 IAM 或法律合规层。模型许可注意InsightFace 公开预训练模型通常仅限非商业研究用途商业使用需要前往 InsightFace 官网单独获取授权该声明独立于 Server 源码的 MIT License许可细节见 server/LICENSING.md。功能概览识别管线SCRFD 人脸检测、五点关键点、对齐、ArcFace 512 维特征、L2 normalization、原始 cosine similarity、精确 1:N Person 搜索多分辨率检测动态 SCRFD 模型在每组配置的分辨率上分别推理将所有候选映射回源图坐标后做一次全局 NMS单脸策略支持largest和center_largest数据模型Collection - Person - FaceSample三级结构Collection 绑定模型多图片注册支持部分成功、metadata 与明确的拒绝原因审核模式注册review_mode支持off、standard、strict也支持external_trusted外部可信特征量化检索GPU 精确检索支持 FP32、FP16、BF16 和 INT8 向量存储Web UI多语言界面覆盖仪表盘、人员库、人员、人脸检测、比对、搜索、RTSP 监控、系统诊断和帮助API 与 SDK/v1下提供 29 个 snake_case REST 接口包括受保护的/v1/embeddings附带轻量 Python SDKRTSP Monitor服务端独立运行、保存有限的内存事件、支持多客户端可选preview.mjpeg关闭浏览器不会停止监控持久化与运维SQLite 是持久化事实来源内存精确索引可重建/models只读、/data持久化提供 migration、健康检查与禁止静默 CPU 回退的严格 CUDA 启动验证图片格式支持 JPEG、PNG、WebP默认不保留原始上传图片。RTX 5090 上的 GPU 检索性能在单张 NVIDIA GeForce RTX 509032,607 MiB上原生 CUDA 精确全量扫描索引使用 INT8 时实测最多可保存58.9M 个 512 维图片特征向量GPU 数据类型最大图片向量数10M Top-5 p5010M 串行 QPSFP3215.8M12.84 ms77.85FP1630.7M6.83 ms146.32BF1630.7M6.83 ms146.33INT858.9M3.84 ms260.81与 FP32 相比INT8 的实测容量为 3.73 倍10M Top-5 吞吐为 3.35 倍。以上仅为同一张 RTX 5090、Driver 580.105.08、CUDA 12.9 上的 GPU 实测。容量是未加载 ONNX 模型和 Server 工作负载时的独立原生索引极限速度测试固定为 10M 个图片特征向量执行 GPU 驻留的 Top-5 全量精确扫描单请求串行预热 10 次后测量 100 次。索引在各自存储表示内是精确搜索但量化仍可能使分数相对 FP32 发生变化生产部署还必须为模型、请求、并发、索引重建和显存分配器预留空间。ICCV21-MFR 多人种 MR-ALL 精度INT8 的精度代价仓库在 challenges/iccv21-mfr/ 的多人种MR测试集上按照 MR-ALL 全组队 1:1 协议、FAR1e-6测试了原生检索 profile。所有 profile 复用同一批由 Server API 一次性提取并完成 L2 normalization 的 512 维buffalo_l特征仅改变向量存储和检索计算表示检索 profileFAR 1e-6 下的 MR-ALLCosine 阈值相对 FP32FP3291.249107%0.407787—FP1691.249197%0.4077870.000090 个百分点BF1691.248502%0.407787-0.000605 个百分点INT891.248005%0.407739-0.001102 个百分点结论INT8 在该测评中没有实质精度损失。按挑战常用的两位小数展示FP32 和 INT8 的 MR-ALL 均为91.25%未四舍五入的差异也只有 0.0011 个百分点同时保留了上文 3.73 倍实测容量与 3.35 倍 10M Top-5 吞吐优势。这里对比的是向量存储与检索精度并非 INT8 模型推理。量化分数契约源码级佐证上述“量化后仍精确”的承诺来自原生检索库的显式分数契约。server/native/search/README.md 定义了 C ABI v2固定 512 维输入必须是有限、FP32 且 L2-normalized所有返回分数使用原始 cosine 语义q clamp(round_half_away_from_zero(x * S), -128, 127) score_internal int32_dot(q_database, q_query) / (S * S) similarity clamp(score_internal, -1, 1)INT8 支持两种比例系数 profileINT8_X736_V1推荐与INT8_X1000_V1遗留兼容。两者是相互独立的按索引契约可在同一进程共存已有的 x1000 Collection 永远不会被静默重解释为 x736。CPU、CUDA 与 NumPy 参考实现刻意采用相同的 FP32 语义做乘法与“远离零的一半”舍入内部未缩放 INT32 累加器不对外暴露保证排序精确、返回分数落在 [-1, 1]。Profile 支持矩阵同一文档确认ProfileCPUCUDAFP32_V1支持支持FP16_V1不支持返回IFS_SEARCH_UNSUPPORTED支持BF16_V1支持仅 Ampere/SM80 及以上Turing 支持 FP32/FP16/INT8INT8_X736_V1支持支持INT8_X1000_V1支持支持不支持的 profile 与 CUDA 失败一律 fail-closed两个原生库内部没有任何 dtype 降级或 CPU 回退——这与 Server 层面“禁止静默 CPU 回退”的严格 CUDA 启动验证Compose 中的INSIGHTFACE_STRICT_CUDA1相互呼应。快速开始环境要求安装 Docker Engine 和 Docker Compose 的 Linux x86_64CUDA 版本还需要受支持的 NVIDIA GPU、NVIDIA Driver 和 NVIDIA Container Toolkit。宿主机不需要安装 Python、OpenCV、ONNX Runtime、CUDA Toolkit 或 cuDNN。公开镜像不包含模型、客户数据、API Key 或生产配置。运行环境与镜像运行环境镜像CPUghcr.io/deepinsight/insightface-server:0.2.0-cpuNVIDIA GPUghcr.io/deepinsight/insightface-server:0.2.0-cuda12滚动标签cpu和cuda12分别指向对应运行环境的最新稳定版本不提供含义模糊的latest。发布规则见维护者指南仅英文。1. 安装模型在完整 InsightFace 仓库中将模型安装到server/.modelsCompose 文件通过 YAML 锚点把该路径绑定为容器内只读的/modelsmkdir -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模型工具还支持buffalo_m、buffalo_sc和antelopev2。安装会生成manifest.json和签名的MODEL.LICENSE可以用models verify核验。2. 启动 CPU 服务docker compose -f server/deploy/compose.cpu.yml up -d curl -fsS http://127.0.0.1:18097/v1/health3. 启动 CUDA 12 服务docker compose -f server/deploy/compose.cuda12.yml pull docker compose -f server/deploy/compose.cuda12.yml \ run --rm models install buffalo_l --accept-license docker compose -f server/deploy/compose.cuda12.yml up -d curl -fsS http://127.0.0.1:18098/v1/healthCPU 打开http://服务器地址:18097/CUDA 打开http://服务器地址:18098/对应两个 Compose 文件中的端口映射18097:8080与18098:8080。创建 Collection、为 Person 上传一张或多张注册照再用另一张照片搜索。停止时使用不带-v的docker compose ... down即可保留数据库卷。4. 开放网络前必须开启认证项目提供的 Compose 配置在隔离评估环境中默认关闭认证。对其他用户或网络开放前export INSIGHTFACE_AUTH_ENABLEDtrue export INSIGHTFACE_API_KEY请替换为足够长的随机密钥 docker compose -f server/deploy/compose.cpu.yml up -d完整的首次使用流程参见新手用户指南。Compose 配置要点对照仓库文件server/deploy/compose.cpu.yml 与 server/deploy/compose.cuda12.yml 结构一致值得注意的工程细节安全加固read_only: true根文件系统、非特权用户10001:10001、cap_drop: [ALL]、no-new-privileges:true、pids_limit、受限 tmpfs三卷分离/etc/insightface/server.toml只读绑定 server/config/server.toml、/data命名卷SQLite 与持久数据、/models只读绑定server/.models关键环境变量及默认值两个文件相同环境变量默认值作用INSIGHTFACE_DEFAULT_THRESHOLD0.4默认 cosine 阈值INSIGHTFACE_COLLECTION_DEFAULT_SEARCH_PROFILEfp32_v1新 Collection 默认检索 profileINSIGHTFACE_COLLECTION_DEFAULT_CAPACITY_ROWS100000新 Collection 默认索引容量INSIGHTFACE_COLLECTION_MAX_CAPACITY_ROWS10000000容量上限INSIGHTFACE_COLLECTION_DEFAULT_MAX_FACES_PER_PERSON20每 Person 最大 FaceSample 数INSIGHTFACE_COLLECTION_DEFAULT_LOAD_POLICYlazy索引加载策略INSIGHTFACE_SEARCH_DEVICE_ID0检索使用的 GPU 编号INSIGHTFACE_SEARCH_TOPK_MODEautoPerson Top-K 模式INSIGHTFACE_SEARCH_BUILD_BATCH_ROWS4096索引重建批量INSIGHTFACE_SAVE_FACE_CROPSfalse是否保存人脸 cropCUDA 文件额外设置INSIGHTFACE_STRICT_CUDA1、CUDA_MODULE_LOADINGLAZY与NVIDIA_*容器环境变量实现“严格 CUDA 启动验证”启动时校验 GPU 可用拒绝静默回退 CPU。从源码构建Dockerfile 会复制server/和python-package/insightface/中选定的推理模块所以必须使用完整仓库作为构建上下文Makefile 中的docker build ... ..即以仓库根目录为上下文。CPUmake -C server build-cpu docker compose -f server/deploy/compose.cpu.yml \ run --rm --pull never models install buffalo_l --accept-license docker compose -f server/deploy/compose.cpu.yml \ up -d --no-build --pull neverCUDA 12make -C server build-cuda12 docker compose -f server/deploy/compose.cuda12.yml \ run --rm --pull never models install buffalo_l --accept-license docker compose -f server/deploy/compose.cuda12.yml \ up -d --no-build --pull never--pull never确保 Compose 使用本地构建的镜像。构建过程仍会下载锁定的基础镜像和依赖模型安装会单独下载已接受许可的模型包。server/Makefile 中还提供了test、test-api、test-sdk、test-frontend、test-native-cpuCMake CTest 构建并测试原生检索库、smoke-test、release-preflight等目标可用于本地验证。核心行为部署与调参必读Similarity 是原始 cosine 值不是概率阈值使用0.0..1.0默认0.4。Collection 固定绑定模型和 embedding contract模型不匹配时仍可查看但注册和搜索返回collection_model_mismatch。检测 Profile 的继承与独立启动时的检测 Profile 会复制给新 Collection之后 Collection Profile 可以独立修改并从下一次请求生效。可选人脸保存保存内容是缩放为 112x112 的 bounding-box JPEG crop不是原始上传图片也不是识别模型使用的对齐输入默认关闭INSIGHTFACE_SAVE_FACE_CROPSfalse。SQLite 提交是事实来源注册或删除成功返回前会同步索引重启后索引从 SQLite 重建。响应可追踪响应包含x-request-id列表接口使用不透明的签名 cursor 分页。这些行为的对应配置项集中在 server/config/server.toml[inference] # auto resolves to 4 concurrent model pipelines on CPU and 8 on CUDA. # A positive integer overrides the provider-specific default. max_concurrency auto [detection] # 每个条目为 [width, height]所有分辨率分别推理 # 候选映射回源图坐标后做一次全局 NMS。 input_sizes [[96, 96], [512, 512]] threshold 0.50 # SCRFD 候选生成阶段的最低置信度在合并 NMS 之前生效 nms_threshold 0.40 # 全局 NMS 的 IoU 阈值 single_face_selection largest # 或 center_largest max_detected_faces 100 # 部署级安全上限请求只能要求更少 [web] disabled false # true 时进入 API-only 模式仅保留 /v1 与 /openapi.json其中center_largest策略最大化像素空间得分area - 2.0 * squared_distance(face_box_center, image_center)适合“画面中心的那张脸”场景。API 与 SDK主要 API 分组共 29 个接口交互式 OpenAPI 保留在/docs系统/v1/health、/v1/system、/v1/models无状态人脸接口/v1/detect、/v1/compare、/v1/embeddings受保护Collection / Person / FaceSample CRUDCollection Person 搜索RTSP Monitor配置、状态、事件和预览。所有参数、响应、错误和示例见完整 REST API 使用指南。配套 Python SDK 的最小用法from insightface_server import Client with Client(http://localhost:18097, api_keyNone) as client: faces client.detect(photo.jpg) matches client.search(employees, unknown.jpg, limit5)SDK 源码位于 server/sdk/python/SDK 安装、图片输入、方法和完整流程见用户指南。检索后端选择机制源码级佐证Server 的内存精确索引由 server/backend/insightface_server/search/factory.py 中的create_search_backend选择后端。从源码结构看search_backendauto时的决策链是推理模式为mock时使用 NumPy 参考实现ReferenceSearchBackend执行提供方为CUDAExecutionProvider时加载libifs_search_cuda.sonative_cuda否则加载libifs_search_cpu.sonative_cpu。原生后端加载后还会执行一次分组 Top-K 自检添加/搜索/删除各一条记录并校验分数失败即启动失败——这是“fail-closed、无静默降级”设计在 Python 层的落点。库的默认路径为/opt/insightface/server/native/lib也可通过search_library_path覆盖原生路径强制维度为 512与 ABI v2 契约一致。CUDA 端 Person Top-K 的实现细节来自 server/native/search/README.md行到组的元数据驻留设备端两遍 GPU 归约先求每个 Person 的最高分再确定其确定性最优 FaceSample同分时取最小 vector ID最终只有前 K至多 100条(group_id, vector_id, score)记录跨 PCIeCUDA 删除采用 tombstone因此physical_rows在删除/重加循环中持续增长Server 需要在 tombstone 耗尽容量前重建 Collection 代际——这也是“SQLite 为事实来源、索引可重建”设计的原因之一。安全提示人脸图片和 embedding 属于生物特征数据。网络部署时应开启认证、通过可信反向代理终止 HTTPS、限制 Docker 和数据卷访问、保持宽泛 CORS 关闭、制定备份/留存/删除/同意和安全事件处理策略日志中不得记录图片、embedding、RTSP 凭据或 API Key。部署和安全操作细节见用户指南。第一阶段范围明确不做的事当前版本不实现AWS/CompreFace 兼容、CUDA 11、Jetson、ARM64、Windows Container、TensorRT、Kubernetes、分布式 Worker、持久化 Monitor 事件或录像/NVR也不实现活体检测、Deepfake Detection 和人口属性分析。延伸阅读用户指南完整覆盖安装、配置、模型、Web UI、SDK、GPU、安全、备份和故障定位REST API 使用指南覆盖每个公开接口、字段、行为、结果、错误、分页规则和示例维护者指南仅英文架构、检索内部实现、测试、贡献规则和容器发布server/LICENSING.md许可入口——Server 源码与 Python SDK 采用 MIT License该声明不覆盖模型文件、模型权重、数据集或第三方组件。GitHub 文档与 Web UI 帮助页读取完全相同的本地化 User Guide 和 API Guide Markdown区别只在渲染方式——这意味着 UI 内查看的文档始终与仓库内容一致。【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考