尧图网站建设 
InsightFace Server自托管人脸识别服务的 Docker 部署、INT8 高速搜索与 REST API 实战【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface本文以 InsightFace 仓库server/子项目的官方文档为主体系统讲解 InsightFace Server 这个自托管人脸识别服务器的定位、Docker 快速启动CPU / CUDA 12 双运行时、从源码构建、检测与检索核心语义以及 REST API 和 Python SDK 的使用方法。读完本文你可以独立完成模型安装、容器启动、认证配置与集合Collection注册/搜索的全流程并理解其 INT8 向量量化搜索的精度与容量特性。一、InsightFace Server 是什么InsightFace Server 是一个自托管self-hosted人脸识别服务器在一个容器内同时提供 Web UI、REST API、SQLite 持久化与本地 CPU 或 NVIDIA GPU 推理。其工作流一句话概括图片上传 - 检测、比较、注册、搜索它的核心价值主张是单块 GPU 承载 5000 万 人脸向量借助 INT8 特征量化实现高速检索且几乎不损失精度。与云厂商的托管人脸识别服务相比它是一个更简单、更注重隐私的替代方案图片、Embedding、模型、索引全部保留在自己的网络内。需要明确的是它不是 AWS 兼容产品——不实现 SigV4、IAM、Region 与 AWS 资源语义。关键版本与平台信息当前发布版本0.2.0平台限定Linux x86_64。运行时镜像RuntimeImageCPUghcr.io/deepinsight/insightface-server:0.2.0-cpuNVIDIA GPUghcr.io/deepinsight/insightface-server:0.2.0-cuda12移动标签cpu与cuda12分别指向对应运行时的最新稳定版项目不提供含义模糊的latest标签。发布策略可参阅 Maintainer Guide。模型许可警告公开的 InsightFace 训练模型通常仅限非商用研究用途商用需要单独获取授权。这一许可独立于 Server 源代码本身的 MIT 许可详见 LICENSING.md。二、核心功能一览官方文档列出的功能集合如下也是该 Server 的能力边界检测与特征SCRFD 检测、5 点关键点、对齐alignment、ArcFace Embedding、L2 归一化、原始 cosine similarity、严格的 1:N Person 搜索。多分辨率检测融合多个输入分辨率的候选框合并后执行单次 NMS单脸选择支持largest与center_largest两种策略。数据模型Collection - Person - FaceSample三层结构Collection 固定绑定某个模型支持多张图注册、部分成功、metadata、明确的拒绝理由。注册审查注册review_mode支持off、standard、strict支持external_trusted模式即由可信上游提供的预计算 Embedding服务端仍执行图像检测与质量审查但不再重新抽取特征也不回退到其他特征。GPU 严格检索支持 FP32、FP16、BF16、INT8 四种向量存储格式。Web UI多语言界面包含 Dashboard、Collections、People、Detect、Compare、Search、RTSP Monitor、System、Help。API 面/v1下有 29 个 snake_case REST 操作含受保护的/v1/embeddings端点与轻量 Python SDK。RTSP Monitor服务端常驻监控有界内存事件队列、支持多客户端、可选preview.mjpeg浏览器关闭后监控不停止。存储与可靠性SQLite 为持久正本内存中是可重建的精确索引/models只读挂载、/data持久卷、schema migration、health checkCUDA 模式做“不容许 CPU 回退”的启动验证。图像格式支持 JPEG、PNG、WebP默认不保留原始上传图片。2.1 RTX 5090 GPU 搜索性能在单块 NVIDIA GeForce RTX 509032,607 MiB 显存上原生 CUDA exact-flat 索引在 INT8 模式下可容纳5890 万个 512 维图像向量GPU 数据类型最大图像向量数10M Top-5 p50 延迟10M 串行 QPSFP3215.8M12.84 ms77.85FP1630.7M6.83 ms146.32BF1630.7M6.83 ms146.33INT858.9M3.84 ms260.81官方给出的测量前提与限制INT8 相对 FP32实测容量约3.73 倍10M Top-5 吞吐约3.35 倍数值来自同一块 RTX 5090Driver 580.105.08、CUDA 12.9的 GPU 侧测量容量上限针对不含 ONNX 模型与 Server 负载的独立原生索引速度测试严格使用 10M 个图像向量GPU 常驻 Top-5 全量精确扫描单 query 并发10 次 warm-up 100 次测量索引在其存储表示内部是精确的但量化会导致 score 与 FP32 略有差异生产环境需要为模型、请求、并发、索引重建和 allocator 预留 VRAM。从源码结构看这一量化契约在 native/search/README.md 中有明确定义INT8 采用按索引的 scale推荐x736另有兼容的x1000量化公式为q clamp(round_half_away_from_zero(x * S), -128, 127)内部得分为int32_dot(q_database, q_query) / (S * S)再 clamp 到 cosine 区间两种 INT8 scale 是相互独立的每索引契约可共存于同一进程且旧的 x1000 Collection 绝不会被静默重解释为 x736。2.2 ICCV21-MFR 多人种 MR-ALL 精度验证为了证明“量化不伤精度”官方在 ICCV21-MFR 挑战赛的多人种MR测试集上做了对照实验全部 profile 使用 Server API 一次性抽取并 L2 归一化的同一份 512 维buffalo_lembedding只改变向量的存储格式与检索计算表示。协议为 MR-ALL 全组合 1:1FAR1e-6检索 profileFAR 1e-6 下 MR-ALL 准确率Cosine 阈值与 FP32 的差FP3291.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%且同时保有 3.73 倍容量与 3.35 倍吞吐优势。注意这评估的是“向量存储与检索”精度不是 INT8 模型推理的评估。支持的检索 profile 在 config.py 中声明为fp32_v1、fp16_v1、bf16_v1、int8_x736_v1、int8_x1000_v1与原生库的能力一致FP16 仅 CUDA 支持BF16 需要 AmpereSM80及以上架构Turing 仍支持 FP32、FP16 与 INT8不支持的 profile 与 CUDA 故障一律 fail-closed原生库内部没有 dtype 或 CPU 回退。三、Docker 快速启动3.1 前置条件Linux x86_64装有 Docker Engine 与 Docker ComposeCUDA 版本另需对应 NVIDIA GPU、NVIDIA Driver 与 NVIDIA Container Toolkit宿主机不需要安装 Python、OpenCV、ONNX Runtime、CUDA Toolkit 或 cuDNN公开镜像中不包含模型、客户数据、API Key 或生产配置。3.2 安装模型在 InsightFace 仓库完整 checkout 下模型安装到server/.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校验。从源码结构看models是一个 compose profile 工具服务入口为 models_cli.py其许可证默认模板与 Ed25519 公钥存放在 licensing/ 目录。模型的许可条件独立于 Server 源代码的许可。3.3 启动 CPU 或 CUDA 12 服务启动 CPU 版docker compose -f server/deploy/compose.cpu.yml up -d curl -fsS http://127.0.0.1:18097/v1/health或启动 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/health随后在浏览器打开 CPU 的http://SERVER:18097/或 CUDA 的http://SERVER:18098/创建 Collection向 Person 注册至少一张图片再用另一张图片执行搜索。需要保留数据时用不带-v的docker compose ... down/data是具名卷down后依然保留。3.4 启用认证随附的 Compose 文件为隔离评估场景默认关闭认证。在暴露给其他用户或网络之前必须设置export INSIGHTFACE_AUTH_ENABLEDtrue export INSIGHTFACE_API_KEY替换为足够长的随机密钥 docker compose -f server/deploy/compose.cpu.yml up -d两份 Compose 文件compose.cpu.yml 与 compose.cuda12.yml暴露的环境变量及默认值基本一致常用项如下环境变量默认值说明INSIGHTFACE_AUTH_ENABLEDfalse是否启用 API 认证INSIGHTFACE_API_KEY空Bearer 密钥INSIGHTFACE_LOG_LEVELINFO日志级别INSIGHTFACE_SAVE_FACE_CROPSfalse是否保存人脸 crop默认不保存INSIGHTFACE_DEFAULT_THRESHOLD0.4默认 cosine 阈值INSIGHTFACE_COLLECTION_DEFAULT_SEARCH_PROFILEfp32_v1新 Collection 默认检索 profileINSIGHTFACE_COLLECTION_DEFAULT_CAPACITY_ROWS100000Collection 默认容量INSIGHTFACE_COLLECTION_MAX_CAPACITY_ROWS10000000Collection 容量硬上限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索引构建批大小两份 Compose 还做了容器安全加固read_only根文件系统、非 root 用户10001:10001、cap_drop: [ALL]、no-new-privileges、pids 限制与 tmpfs 限额CUDA 版额外设置INSIGHTFACE_STRICT_CUDA1与gpus: all并在启动时做不允许 CPU 回退的 CUDA 校验。CPU 版固定INSIGHTFACE_EXECUTION_PROVIDER: CPUExecutionProviderCUDA 版固定CUDAExecutionProvider。完整的初学者上手步骤见 用户指南日语版。四、从源码构建由于 Dockerfile 需要复制server/与python-package/insightface/的选定推理模块整个仓库都是 build context。构建目标定义在 Makefile 中镜像 tag 固定为0.2.0系列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确保使用本地构建的镜像。构建阶段使用固定的 base image 与依赖模型则在models install阶段按许可单独下载。五、核心行为与关键语义这些“默认语义”直接决定业务代码的正确写法Similarity 是原始 cosine 值不是概率。阈值范围0.0..1.0默认0.4。Collection 与模型和 embedding contract 绑定。模型不匹配时 Collection 仍可查看但注册/搜索会返回collection_model_mismatch错误。检测 Profile 的复制语义启动时的系统级 Detection Profile 在新建 Collection 时被复制此后每个 Collection 的 Profile 可独立修改且从下一个请求开始生效。人脸 crop可选保存的是 112x112 的 bounding-box JPEG 裁剪图不是原图也不是用于识别的对齐输入默认关闭。持久化模型SQLite commit 是正本注册/删除的成功响应返回前内存索引先完成同步重启后从 SQLite 重建索引。可观测性与分页响应带x-request-id列表 API 使用不透明的签名 cursor 分页。检索后端的选择逻辑在 search/factory.py 中search_backendauto默认时mock 推理映射到 NumPyreference后端CUDAExecutionProvider映射到native_cuda否则使用native_cpu原生后端加载libifs_search_cuda.so/libifs_search_cpu.so后会执行一次分组 Top-K 自检结果异常则启动失败。精确的字段、默认值、生命周期与失败行为以 REST API 指南 和 用户指南 为权威文档。5.1 检测参数配置系统级检测参数在 server/config/server.toml 中配置进程启动时一次性加载修改后需重启容器配置项默认值说明inference.max_concurrencyautoCPU 4 / CUDA 8上限 256全进程共享的推理并发预算API 调用、注册与 RTSP 帧共用detection.input_sizes[[96, 96], [512, 512]]动态 SCRFD 在每个分辨率上推理候选框映射回原图坐标后做单次全局 NMSdetection.threshold0.50检测器置信度下限在合并 NMS 之前生效detection.nms_threshold0.40单次全局 NMS 的 IoU 阈值detection.single_face_selectionlargest单脸操作的选择策略可选center_largest最大化面积 - 2.0 * 人脸框中心到图像中心的平方距离detection.max_detected_faces100部署级安全上限请求只能要求更少web.disabledfalsetrue时进入纯 API 模式仅保留/v1与/openapi.json从 config.py 的校验逻辑看input_sizes有更严格的约束每项必须是 32 的倍数对齐 SCRFD 最大特征图 stride每边取值 32..2048最多 4 个分辨率不可重复且总像素不超过 4M越界配置会在启动阶段被直接拒绝而不是运行时才暴露。六、REST API 与 Python SDKAPI 按以下分组组织System/v1/health、/v1/system、/v1/models无状态人脸/v1/detect、/v1/compare、/v1/embeddingsCollection、Person、FaceSample的 CRUDCollection 内 Person 搜索RTSP Monitor的配置、状态、事件、预览。全部参数、响应、错误与示例以 REST API 使用指南 为准交互式 OpenAPI 文档保留在服务器的/docs路径。官方随附轻量 Python SDK基于httpx不含推理运行时接受图片路径、bytes 或二进制文件对象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 安装与用法python -m pip install ./server/sdk/pythonSDK 的输入形式、方法与完整流程见 用户指南客户端实现见 client.py其中SearchProfile字面量类型与后端一致的五个 profile 对应fp32_v1、fp16_v1、bf16_v1、int8_x736_v1、int8_x1000_v1。SDK 还支持可信上游提取器场景传external_embeddings加 Collection 的embedding_contract_id即可选择external_trusted模式RTSP 监控可通过create_monitor、update_monitor、monitor_state与 cursor 式monitor_events管理预览默认关闭。默认请求等待上限 65 秒略长于服务端 60 秒请求时限可用timeout参数调整。七、安全基线人脸图像与 Embedding 属于生物特征信息。文档给出的安全要求网络暴露前必须启用认证INSIGHTFACE_AUTH_ENABLEDtrue 强随机 API Key用可信的反向代理终结 HTTPS限制 Docker 与卷的访问权限保持宽泛 CORS 关闭定义备份、保留策略、删除流程、同意consent与事件响应流程不要把图像、Embedding、RTSP 凭据、API Key 写进日志。边界同样要说清楚Server不内置TLS、用户账号、RBAC、云 IAM 或合规层。运维与安全的完整建议见 用户指南。八、Phase 1 的范围边界以下能力当前明确不实现规划集成时应避开AWS/CompreFace 兼容层、CUDA 11、Jetson、ARM64、Windows Container、TensorRT、Kubernetes、分布式 Worker、Monitor 事件持久化、录像/NVR、活体检测liveness、deepfake 检测、属性分析。九、文档索引与许可用户指南 — 安装、配置、模型、Web UI、SDK、GPU、安全、备份、故障排查REST API 使用指南 — 全部公开 Endpoint、字段、行为、结果、错误、分页与示例Maintainer Guide — 架构、搜索内部实现、测试、贡献、容器发布。GitHub 上的文档与 Web UI Help 加载的是同一份本地化 Markdown只是展示形式不同。许可唯一权威入口是 LICENSING.md。Server 源代码与 Python SDK 采用 MIT 许可但该声明不覆盖模型文件、模型权重、数据集与第三方组件。公开 InsightFace 训练模型在无单独授权时通常仅限非商用研究用途商用许可需向 InsightFace 官方申请。【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 InsightFace Server：自托管人脸识别服务的 Docker 部署、INT8 高速搜索与 REST API 实战
InsightFace Server自托管人脸识别服务的 Docker 部署、INT8 高速搜索与 REST API 实战【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface本文以 InsightFace 仓库server/子项目的官方文档为主体系统讲解 InsightFace Server 这个自托管人脸识别服务器的定位、Docker 快速启动CPU / CUDA 12 双运行时、从源码构建、检测与检索核心语义以及 REST API 和 Python SDK 的使用方法。读完本文你可以独立完成模型安装、容器启动、认证配置与集合Collection注册/搜索的全流程并理解其 INT8 向量量化搜索的精度与容量特性。一、InsightFace Server 是什么InsightFace Server 是一个自托管self-hosted人脸识别服务器在一个容器内同时提供 Web UI、REST API、SQLite 持久化与本地 CPU 或 NVIDIA GPU 推理。其工作流一句话概括图片上传 - 检测、比较、注册、搜索它的核心价值主张是单块 GPU 承载 5000 万 人脸向量借助 INT8 特征量化实现高速检索且几乎不损失精度。与云厂商的托管人脸识别服务相比它是一个更简单、更注重隐私的替代方案图片、Embedding、模型、索引全部保留在自己的网络内。需要明确的是它不是 AWS 兼容产品——不实现 SigV4、IAM、Region 与 AWS 资源语义。关键版本与平台信息当前发布版本0.2.0平台限定Linux x86_64。运行时镜像RuntimeImageCPUghcr.io/deepinsight/insightface-server:0.2.0-cpuNVIDIA GPUghcr.io/deepinsight/insightface-server:0.2.0-cuda12移动标签cpu与cuda12分别指向对应运行时的最新稳定版项目不提供含义模糊的latest标签。发布策略可参阅 Maintainer Guide。模型许可警告公开的 InsightFace 训练模型通常仅限非商用研究用途商用需要单独获取授权。这一许可独立于 Server 源代码本身的 MIT 许可详见 LICENSING.md。二、核心功能一览官方文档列出的功能集合如下也是该 Server 的能力边界检测与特征SCRFD 检测、5 点关键点、对齐alignment、ArcFace Embedding、L2 归一化、原始 cosine similarity、严格的 1:N Person 搜索。多分辨率检测融合多个输入分辨率的候选框合并后执行单次 NMS单脸选择支持largest与center_largest两种策略。数据模型Collection - Person - FaceSample三层结构Collection 固定绑定某个模型支持多张图注册、部分成功、metadata、明确的拒绝理由。注册审查注册review_mode支持off、standard、strict支持external_trusted模式即由可信上游提供的预计算 Embedding服务端仍执行图像检测与质量审查但不再重新抽取特征也不回退到其他特征。GPU 严格检索支持 FP32、FP16、BF16、INT8 四种向量存储格式。Web UI多语言界面包含 Dashboard、Collections、People、Detect、Compare、Search、RTSP Monitor、System、Help。API 面/v1下有 29 个 snake_case REST 操作含受保护的/v1/embeddings端点与轻量 Python SDK。RTSP Monitor服务端常驻监控有界内存事件队列、支持多客户端、可选preview.mjpeg浏览器关闭后监控不停止。存储与可靠性SQLite 为持久正本内存中是可重建的精确索引/models只读挂载、/data持久卷、schema migration、health checkCUDA 模式做“不容许 CPU 回退”的启动验证。图像格式支持 JPEG、PNG、WebP默认不保留原始上传图片。2.1 RTX 5090 GPU 搜索性能在单块 NVIDIA GeForce RTX 509032,607 MiB 显存上原生 CUDA exact-flat 索引在 INT8 模式下可容纳5890 万个 512 维图像向量GPU 数据类型最大图像向量数10M Top-5 p50 延迟10M 串行 QPSFP3215.8M12.84 ms77.85FP1630.7M6.83 ms146.32BF1630.7M6.83 ms146.33INT858.9M3.84 ms260.81官方给出的测量前提与限制INT8 相对 FP32实测容量约3.73 倍10M Top-5 吞吐约3.35 倍数值来自同一块 RTX 5090Driver 580.105.08、CUDA 12.9的 GPU 侧测量容量上限针对不含 ONNX 模型与 Server 负载的独立原生索引速度测试严格使用 10M 个图像向量GPU 常驻 Top-5 全量精确扫描单 query 并发10 次 warm-up 100 次测量索引在其存储表示内部是精确的但量化会导致 score 与 FP32 略有差异生产环境需要为模型、请求、并发、索引重建和 allocator 预留 VRAM。从源码结构看这一量化契约在 native/search/README.md 中有明确定义INT8 采用按索引的 scale推荐x736另有兼容的x1000量化公式为q clamp(round_half_away_from_zero(x * S), -128, 127)内部得分为int32_dot(q_database, q_query) / (S * S)再 clamp 到 cosine 区间两种 INT8 scale 是相互独立的每索引契约可共存于同一进程且旧的 x1000 Collection 绝不会被静默重解释为 x736。2.2 ICCV21-MFR 多人种 MR-ALL 精度验证为了证明“量化不伤精度”官方在 ICCV21-MFR 挑战赛的多人种MR测试集上做了对照实验全部 profile 使用 Server API 一次性抽取并 L2 归一化的同一份 512 维buffalo_lembedding只改变向量的存储格式与检索计算表示。协议为 MR-ALL 全组合 1:1FAR1e-6检索 profileFAR 1e-6 下 MR-ALL 准确率Cosine 阈值与 FP32 的差FP3291.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%且同时保有 3.73 倍容量与 3.35 倍吞吐优势。注意这评估的是“向量存储与检索”精度不是 INT8 模型推理的评估。支持的检索 profile 在 config.py 中声明为fp32_v1、fp16_v1、bf16_v1、int8_x736_v1、int8_x1000_v1与原生库的能力一致FP16 仅 CUDA 支持BF16 需要 AmpereSM80及以上架构Turing 仍支持 FP32、FP16 与 INT8不支持的 profile 与 CUDA 故障一律 fail-closed原生库内部没有 dtype 或 CPU 回退。三、Docker 快速启动3.1 前置条件Linux x86_64装有 Docker Engine 与 Docker ComposeCUDA 版本另需对应 NVIDIA GPU、NVIDIA Driver 与 NVIDIA Container Toolkit宿主机不需要安装 Python、OpenCV、ONNX Runtime、CUDA Toolkit 或 cuDNN公开镜像中不包含模型、客户数据、API Key 或生产配置。3.2 安装模型在 InsightFace 仓库完整 checkout 下模型安装到server/.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校验。从源码结构看models是一个 compose profile 工具服务入口为 models_cli.py其许可证默认模板与 Ed25519 公钥存放在 licensing/ 目录。模型的许可条件独立于 Server 源代码的许可。3.3 启动 CPU 或 CUDA 12 服务启动 CPU 版docker compose -f server/deploy/compose.cpu.yml up -d curl -fsS http://127.0.0.1:18097/v1/health或启动 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/health随后在浏览器打开 CPU 的http://SERVER:18097/或 CUDA 的http://SERVER:18098/创建 Collection向 Person 注册至少一张图片再用另一张图片执行搜索。需要保留数据时用不带-v的docker compose ... down/data是具名卷down后依然保留。3.4 启用认证随附的 Compose 文件为隔离评估场景默认关闭认证。在暴露给其他用户或网络之前必须设置export INSIGHTFACE_AUTH_ENABLEDtrue export INSIGHTFACE_API_KEY替换为足够长的随机密钥 docker compose -f server/deploy/compose.cpu.yml up -d两份 Compose 文件compose.cpu.yml 与 compose.cuda12.yml暴露的环境变量及默认值基本一致常用项如下环境变量默认值说明INSIGHTFACE_AUTH_ENABLEDfalse是否启用 API 认证INSIGHTFACE_API_KEY空Bearer 密钥INSIGHTFACE_LOG_LEVELINFO日志级别INSIGHTFACE_SAVE_FACE_CROPSfalse是否保存人脸 crop默认不保存INSIGHTFACE_DEFAULT_THRESHOLD0.4默认 cosine 阈值INSIGHTFACE_COLLECTION_DEFAULT_SEARCH_PROFILEfp32_v1新 Collection 默认检索 profileINSIGHTFACE_COLLECTION_DEFAULT_CAPACITY_ROWS100000Collection 默认容量INSIGHTFACE_COLLECTION_MAX_CAPACITY_ROWS10000000Collection 容量硬上限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索引构建批大小两份 Compose 还做了容器安全加固read_only根文件系统、非 root 用户10001:10001、cap_drop: [ALL]、no-new-privileges、pids 限制与 tmpfs 限额CUDA 版额外设置INSIGHTFACE_STRICT_CUDA1与gpus: all并在启动时做不允许 CPU 回退的 CUDA 校验。CPU 版固定INSIGHTFACE_EXECUTION_PROVIDER: CPUExecutionProviderCUDA 版固定CUDAExecutionProvider。完整的初学者上手步骤见 用户指南日语版。四、从源码构建由于 Dockerfile 需要复制server/与python-package/insightface/的选定推理模块整个仓库都是 build context。构建目标定义在 Makefile 中镜像 tag 固定为0.2.0系列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确保使用本地构建的镜像。构建阶段使用固定的 base image 与依赖模型则在models install阶段按许可单独下载。五、核心行为与关键语义这些“默认语义”直接决定业务代码的正确写法Similarity 是原始 cosine 值不是概率。阈值范围0.0..1.0默认0.4。Collection 与模型和 embedding contract 绑定。模型不匹配时 Collection 仍可查看但注册/搜索会返回collection_model_mismatch错误。检测 Profile 的复制语义启动时的系统级 Detection Profile 在新建 Collection 时被复制此后每个 Collection 的 Profile 可独立修改且从下一个请求开始生效。人脸 crop可选保存的是 112x112 的 bounding-box JPEG 裁剪图不是原图也不是用于识别的对齐输入默认关闭。持久化模型SQLite commit 是正本注册/删除的成功响应返回前内存索引先完成同步重启后从 SQLite 重建索引。可观测性与分页响应带x-request-id列表 API 使用不透明的签名 cursor 分页。检索后端的选择逻辑在 search/factory.py 中search_backendauto默认时mock 推理映射到 NumPyreference后端CUDAExecutionProvider映射到native_cuda否则使用native_cpu原生后端加载libifs_search_cuda.so/libifs_search_cpu.so后会执行一次分组 Top-K 自检结果异常则启动失败。精确的字段、默认值、生命周期与失败行为以 REST API 指南 和 用户指南 为权威文档。5.1 检测参数配置系统级检测参数在 server/config/server.toml 中配置进程启动时一次性加载修改后需重启容器配置项默认值说明inference.max_concurrencyautoCPU 4 / CUDA 8上限 256全进程共享的推理并发预算API 调用、注册与 RTSP 帧共用detection.input_sizes[[96, 96], [512, 512]]动态 SCRFD 在每个分辨率上推理候选框映射回原图坐标后做单次全局 NMSdetection.threshold0.50检测器置信度下限在合并 NMS 之前生效detection.nms_threshold0.40单次全局 NMS 的 IoU 阈值detection.single_face_selectionlargest单脸操作的选择策略可选center_largest最大化面积 - 2.0 * 人脸框中心到图像中心的平方距离detection.max_detected_faces100部署级安全上限请求只能要求更少web.disabledfalsetrue时进入纯 API 模式仅保留/v1与/openapi.json从 config.py 的校验逻辑看input_sizes有更严格的约束每项必须是 32 的倍数对齐 SCRFD 最大特征图 stride每边取值 32..2048最多 4 个分辨率不可重复且总像素不超过 4M越界配置会在启动阶段被直接拒绝而不是运行时才暴露。六、REST API 与 Python SDKAPI 按以下分组组织System/v1/health、/v1/system、/v1/models无状态人脸/v1/detect、/v1/compare、/v1/embeddingsCollection、Person、FaceSample的 CRUDCollection 内 Person 搜索RTSP Monitor的配置、状态、事件、预览。全部参数、响应、错误与示例以 REST API 使用指南 为准交互式 OpenAPI 文档保留在服务器的/docs路径。官方随附轻量 Python SDK基于httpx不含推理运行时接受图片路径、bytes 或二进制文件对象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 安装与用法python -m pip install ./server/sdk/pythonSDK 的输入形式、方法与完整流程见 用户指南客户端实现见 client.py其中SearchProfile字面量类型与后端一致的五个 profile 对应fp32_v1、fp16_v1、bf16_v1、int8_x736_v1、int8_x1000_v1。SDK 还支持可信上游提取器场景传external_embeddings加 Collection 的embedding_contract_id即可选择external_trusted模式RTSP 监控可通过create_monitor、update_monitor、monitor_state与 cursor 式monitor_events管理预览默认关闭。默认请求等待上限 65 秒略长于服务端 60 秒请求时限可用timeout参数调整。七、安全基线人脸图像与 Embedding 属于生物特征信息。文档给出的安全要求网络暴露前必须启用认证INSIGHTFACE_AUTH_ENABLEDtrue 强随机 API Key用可信的反向代理终结 HTTPS限制 Docker 与卷的访问权限保持宽泛 CORS 关闭定义备份、保留策略、删除流程、同意consent与事件响应流程不要把图像、Embedding、RTSP 凭据、API Key 写进日志。边界同样要说清楚Server不内置TLS、用户账号、RBAC、云 IAM 或合规层。运维与安全的完整建议见 用户指南。八、Phase 1 的范围边界以下能力当前明确不实现规划集成时应避开AWS/CompreFace 兼容层、CUDA 11、Jetson、ARM64、Windows Container、TensorRT、Kubernetes、分布式 Worker、Monitor 事件持久化、录像/NVR、活体检测liveness、deepfake 检测、属性分析。九、文档索引与许可用户指南 — 安装、配置、模型、Web UI、SDK、GPU、安全、备份、故障排查REST API 使用指南 — 全部公开 Endpoint、字段、行为、结果、错误、分页与示例Maintainer Guide — 架构、搜索内部实现、测试、贡献、容器发布。GitHub 上的文档与 Web UI Help 加载的是同一份本地化 Markdown只是展示形式不同。许可唯一权威入口是 LICENSING.md。Server 源代码与 Python SDK 采用 MIT 许可但该声明不覆盖模型文件、模型权重、数据集与第三方组件。公开 InsightFace 训练模型在无单独授权时通常仅限非商用研究用途商用许可需向 InsightFace 官方申请。【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考