InsightFace Server 0.2.0 实战指南单容器自托管人脸识别服务与 INT8 GPU 精确搜索【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightfaceInsightFace Server 是 InsightFace 仓库server/目录下的一个自托管人脸识别服务端单容器内集成 Web UI、REST API、SQLite 持久化与本地 CPU / NVIDIA GPU 推理主打隐私可控图像、特征、模型、索引全部留在内网与高性能单卡 INT8 精确检索可达 5000 万级人脸向量。读完本篇你可以按官方 Compose 文件在 CPU 或 CUDA 12 环境完成部署、安装模型包、启用 API Key 认证并理解其检索后端、配置参数与安全边界的源码级实现。一、项目定位与当前版本InsightFace Server 面向「在自己的基础设施上运行典型人脸识别场景」的定位官方将其描述为 AWS Rekognition 一类服务在隐私优先场景下的更简单、更自持的替代方案图像、embeddings、模型和索引都可以留在你的网络内。需要特别明确它的边界——它不是AWS 兼容替代品SigV4 签名、IAM、Region 与 AWS 资源语义均未实现。当前版本为0.2.0运行平台限定Linux x86_64通过官方容器镜像分发环境镜像CPUghcr.io/deepinsight/insightface-server:0.2.0-cpuNVIDIA GPUghcr.io/deepinsight/insightface-server:0.2.0-cuda12镜像的cpu与cuda12是各自的浮动标签始终指向同一条「家族」的最新稳定版官方刻意不发布语义模糊的latest标签。发布规则详见 维护者指南。模型许可证提示InsightFace 公开预训练模型通常仅授权非商业研究用途商业使用需要单独获得许可通过 InsightFace 官方渠道。二、核心能力全景官方 READMEserver/README.ru.md 及各语言版本列出的能力清单如下检测走 SCRFD输出 5 点 landmarks对齐后提取 ArcFace embedding 并做 L2 归一化相似度采用原始 cosine similarityPerson 1:N 检索是精确exact搜索多尺度检测同一 NMS 全局合并候选框单脸选择策略支持largest或center_largest数据模型为Collection - Person - FaceSample三级结构Collection 绑定模型支持一次提交多张照片的部分成功注册并附带 metadata 与明确的失败原因注册审核模式review_mode三档off/standard/strict另支持预计算的external_trustedembedding可信上游提取器直接提交向量GPU 精确检索支持 FP32、FP16、BF16、INT8 四种向量存储表示多语言 Web UIDashboard、Collections、People、Detect、Compare、Search、RTSP 监控、System、Help 页面/v1下共 29 个 snake_case REST 操作含受保护端点/v1/embeddings并配套轻量级类型化 Python SDK服务端 RTSP Monitor事件仅保存在内存、支持多客户端消费可选preview.mjpeg预览关闭浏览器不会停止监控SQLite 作为持久化事实来源内存中的精确索引可随时重建/models只读挂载、/data持久化卷内置迁移migrations、health check以及严格的 CUDA 校验——不做隐藏的 CPU 回退支持 JPEG / PNG / WebP 输入原始上传图默认不落盘。数据与检索架构从 Compose 文件看部署形态从 server/deploy/compose.cpu.yml 的声明可以看出容器的安全与数据布局设计容器以非 root 用户10001:10001运行read_only: true只读根文件系统cap_drop: [ALL]、no-new-privilegespids_limit与shm_size均有限额/tmp使用 128m tmpfs三类挂载各司其职server/config/server.toml只读绑定到/etc/insightface/server.toml配置命名卷data持久化到/dataSQLite 等状态server/.models只读绑定到/models模型包CPU 与 CUDA 镜像的差异集中在推理环境变量CPU 用INSIGHTFACE_EXECUTION_PROVIDER: CPUExecutionProviderCUDA 用CUDAExecutionProvider并额外设置INSIGHTFACE_STRICT_CUDA: 1对应「严格 CUDA 校验、无 CPU 回退」的承诺、NVIDIA_VISIBLE_DEVICES: all与gpus: all端口约定CPU 映射18097:8080CUDA 映射18098:8080即容器内统一为 8080。Compose 文件里暴露的全部环境变量默认值也值得记住它们是调参的第一入口INSIGHTFACE_DEFAULT_THRESHOLD默认 0.4、INSIGHTFACE_COLLECTION_DEFAULT_SEARCH_PROFILE默认fp32_v1、INSIGHTFACE_COLLECTION_DEFAULT_CAPACITY_ROWS默认 100000上限MAX默认 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、INSIGHTFACE_SAVE_FACE_CROPS默认 false。推理配置详解server/config/server.toml这份 TOML 在进程启动时加载一次修改后需要重启容器。关键配置项及其源码注释语义如下[inference] max_concurrency autoauto解析为 CPU 4 路、CUDA 8 路并发模型管线正整数可覆盖。API 请求、注册流程与 RTSP 帧共享这一个进程级并发预算[detection] input_sizes [[96, 96], [512, 512]]每个条目是[宽, 高]。动态 SCRFD 模型会对每个配置分辨率各跑一遍把所有候选框映射回源图坐标再对合并后的候选集执行一次全局 NMS[detection] threshold 0.50检测器最低置信度在 SCRFD 候选生成阶段、NMS 之前生效[detection] nms_threshold 0.40单次全局 NMS 的 IoU 阈值[detection] single_face_selection largest单脸操作如 compare的选脸策略可选largest或center_largest后者最大化score × area - 2.0 × 人脸框中心到图像中心的距离平方这个像素空间得分[detection] max_detected_faces 100部署级安全上限单个请求只能要求更少、不能更多[web] disabled falsetrue时进入纯 API 模式——保留/v1与/openapi.json但不注册 UI 路由。三、GPU 检索性能与 INT8 精度RTX 5090 上的 GPU 精确检索容量与速度官方基准测试在单张 NVIDIA GeForce RTX 509032 607 MiB 显存Driver 580.105.08CUDA 12.9上进行使用原生 CUDA flat 精确索引GPU 数据类型最大图像向量容量10M Top-5 p50 延迟10M 串行 QPSFP3215.8M12.84 ms77.85FP1630.7M6.83 ms146.32BF1630.7M6.83 ms146.33INT858.9M3.84 ms260.81相对 FP32INT8 提供了3.73 倍的实测容量与3.35 倍的 10M Top-5 吞吐。官方同时给出了严格的测量前提引用时不要脱离容量是「隔离极限」——未加载 ONNX 模型、不叠加 Server 负载下原生索引能容纳的 512 维向量上限速度是在恰好 10M 图像向量上、以完整 GPU-resident 精确 Top-5 扫描方式测得单并发、10 次预热 100 次取均值每个存储表示内部检索都是精确的但量化会使 score 相对 FP32 产生偏移生产环境必须为模型加载、在途请求、并发、索引重建与显存 allocator 预留 VRAM。ICCV21-MFR 多族裔基准上的 MR-ALL 精度官方用 ICCV21-MFR 的多族裔MR测试集按 MR-ALL 1:1 协议、在 FAR1e-6下评估了各检索精度。所有配置共用同一批 512 维 L2 归一化buffalo_lembedding经 Server API 一次性提取唯一变化是向量存储表示与检索计算方式检索配置FAR 1e-6 下 MR-ALLcosine 阈值相对 FP32 差值FP3291.249107 %0.407787—FP1691.249197 %0.4077870.000090 个百分点BF1691.248502 %0.407787-0.000605 个百分点INT891.248005 %0.407739-0.001102 个百分点结论INT8 在本基准上没有可观测的显著精度损失——按 challenge 惯例保留两位小数时FP32 与 INT8 同为91.25% MR-ALL未取整差值仅 0.0011 个百分点同时保留了 3.73 倍容量与 3.35 倍吞吐优势。注意该对比针对的是「向量存储与检索」的精度不是 INT8 模型推理量化推理是另一件事。从源码结构看检索后端由 server/backend/insightface_server/search/ 下的factory/manager/native/reference等模块组织原生 CUDA/C 实现位于 server/native/search/且 server/Makefile 提供了test-native-cpu目标CMake ctest 构建并运行原生检索测试另有test-cpu、test-cuda12、test-consistency等目标用于跨配置一致性验证。四、快速开始前置要求Linux x86_64装有 Docker Engine 与 Docker Compose使用 CUDA 时另需兼容的 NVIDIA GPU、NVIDIA 驱动与 NVIDIA Container Toolkit。宿主机不需要Python、OpenCV、ONNX Runtime、CUDA Toolkit 或 cuDNN——全部封装在容器内。官方镜像不含模型、客户数据、API Key 或生产配置。第一步安装模型包在完整 checkout 的 InsightFace 仓库中把模型装到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_l、buffalo_m、buffalo_sc与antelopev2。安装过程会生成manifest.json与签名的MODEL.LICENSEmodels verify可校验包完整性——模型条款与 Server 源码许可证是分离管理的。从 compose 文件 可见models是一个profiles: [tools]的工具服务入口为python -m insightface_server.models_cli支持代理环境变量HTTP_PROXY等并以INSIGHTFACE_MODELS_UID/GID控制写入属主。第二步启动 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://服务器:18097/或 CUDA 的http://服务器:18098/创建 Collection用一张或多张照片注册 Person再用另一张照片检索。docker compose ... down不带-v会保留数据卷。官方建议的第一条完整使用路径含设置、模型管理、Web UI、备份与诊断见 用户指南。启用 API Key 认证官方 Compose 文件默认关闭认证仅适合隔离环境评估。在开放给其他用户或网络之前务必启用export INSIGHTFACE_AUTH_ENABLEDtrue export INSIGHTFACE_API_KEY换成一个足够长的随机密钥 docker compose -f server/deploy/compose.cpu.yml up -d认证开启后所有/v1请求需携带该 KeySDK 中通过api_key参数传入。五、从源码构建镜像官方 Dockerfile 会拷贝server/与python-package/insightface/中选定推理模块因此构建上下文是整个仓库根目录需要在 checkout 根目录执行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保证运行阶段使用本地刚构建的镜像不会意外拉取 ghcr 上的 0.2.0 发布版构建本身仍会拉取锁定的基础镜像与依赖而models install是另一个显式接受的模型包下载动作。对照 server/Makefile 可知build-cpu/build-cuda12即以仓库根目录..为上下文执行docker build镜像标签与SERVER_VERSION ? 0.2.0一致该文件同时提供lint、test、test-api、test-sdk、test-frontend、smoke-test、release-preflight等开发入口。六、数据模型与关键运行规则理解以下规则能避免大部分「API 报错」困惑Similarity 是原始 cosine 值不是概率。threshold 取值范围0.0..1.0默认0.4对应环境变量INSIGHTFACE_DEFAULT_THRESHOLDCollection 固定了模型与 embedding contract。模型不匹配时 Collection 仍可见但注册/检索会返回collection_model_mismatch错误Detection Profile 的继承语义系统级检测 profile 只在启动时生效创建 Collection 时会将其复制过去此后 Collection 的 profile 可独立调整用于后续请求人脸裁剪的可选保存开启后保存的是 bounding-box 框出的 JPEG 裁剪并缩放到 112x112——既不是原图、也不是对齐后的识别输入默认关闭INSIGHTFACE_SAVE_FACE_CROPSfalseSQLite 是事实来源内存索引在任何注册/删除成功响应之前就已同步重启后从 SQLite 重建响应规范所有响应携带x-request-id列表接口使用不透明的签名 cursor 分页。七、REST API 与 Python SDK/v1下的操作分组系统类/v1/health、/v1/system、/v1/models无状态操作/v1/detect、/v1/compare、/v1/embeddings受保护Collection / Person / FaceSample 的 CRUDPerson 在指定 Collection 内的检索RTSP Monitor 的配置、状态、事件与 preview。全部端点、字段、行为、错误码与分页规则收录在 REST API 指南交互式 OpenAPI 文档直接部署在容器内/docs路径。SDK 用法示例官方 README 片段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 基于httpx、不含推理运行时安装方式为python -m pip install ./server/sdk/python在仓库根目录执行接受图像路径、bytes 或二进制文件对象。更多细节见 SDK 说明无状态的 Detect / Compare / Embeddings 调用可传collection复用该 Collection 的检测 profile可信上游提取器可提交external_embeddings 图像 embedding_contract_id走external_trusted通道服务端仍做检测与质量审核但不重新提取、也不回退到别的特征RTSP 监控可通过create_monitor/update_monitor/monitor_state/monitor_events管理客户端默认等待 65 秒略长于服务端 60 秒请求时限可用timeout调整。八、安全实践与一期边界人脸图像与 embedding 属于生物特征数据。官方给出的安全基线网络暴露前必须启用认证API Key并在受信反向代理上终结 HTTPS收紧 Docker 与 volume 权限不要开启宽泛 CORS明确备份、保留期、删除、知情同意与事件响应流程日志中不得写入图像、embedding、RTSP 凭据或 API Key。Server 本身不提供TLS、用户账号体系、RBAC、云 IAM 或法律合规层——这些由部署方在容器外部承担。一期明确未实现的能力AWS / CompreFace 兼容、CUDA 11、Jetson、ARM64、Windows 容器、TensorRT、Kubernetes、分布式 Worker、Monitor 事件持久化、录像 / NVR、活体检测、deepfake 检测与人口统计属性。九、许可许可条款的唯一入口是 LICENSING.mdServer 代码与 Python SDK 采用 MIT License该声明不覆盖模型文件与权重、数据集及第三方组件。InsightFace 公开模型通常限于非商业研究用途商业授权需另行获取。参考文档用户指南安装、配置、模型、Web UI、SDK、GPU、安全、备份与诊断REST API 指南全部端点、字段、行为、结果、错误、分页与示例维护者指南架构、内部检索、测试、贡献与容器发布示例与多语言 READMEGitHub 与 Web UI 帮助页读取同一份本地化 Markdown仅渲染方式不同。【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
InsightFace Server 0.2.0 实战指南：单容器自托管人脸识别服务与 INT8 GPU 精确搜索
InsightFace Server 0.2.0 实战指南单容器自托管人脸识别服务与 INT8 GPU 精确搜索【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightfaceInsightFace Server 是 InsightFace 仓库server/目录下的一个自托管人脸识别服务端单容器内集成 Web UI、REST API、SQLite 持久化与本地 CPU / NVIDIA GPU 推理主打隐私可控图像、特征、模型、索引全部留在内网与高性能单卡 INT8 精确检索可达 5000 万级人脸向量。读完本篇你可以按官方 Compose 文件在 CPU 或 CUDA 12 环境完成部署、安装模型包、启用 API Key 认证并理解其检索后端、配置参数与安全边界的源码级实现。一、项目定位与当前版本InsightFace Server 面向「在自己的基础设施上运行典型人脸识别场景」的定位官方将其描述为 AWS Rekognition 一类服务在隐私优先场景下的更简单、更自持的替代方案图像、embeddings、模型和索引都可以留在你的网络内。需要特别明确它的边界——它不是AWS 兼容替代品SigV4 签名、IAM、Region 与 AWS 资源语义均未实现。当前版本为0.2.0运行平台限定Linux x86_64通过官方容器镜像分发环境镜像CPUghcr.io/deepinsight/insightface-server:0.2.0-cpuNVIDIA GPUghcr.io/deepinsight/insightface-server:0.2.0-cuda12镜像的cpu与cuda12是各自的浮动标签始终指向同一条「家族」的最新稳定版官方刻意不发布语义模糊的latest标签。发布规则详见 维护者指南。模型许可证提示InsightFace 公开预训练模型通常仅授权非商业研究用途商业使用需要单独获得许可通过 InsightFace 官方渠道。二、核心能力全景官方 READMEserver/README.ru.md 及各语言版本列出的能力清单如下检测走 SCRFD输出 5 点 landmarks对齐后提取 ArcFace embedding 并做 L2 归一化相似度采用原始 cosine similarityPerson 1:N 检索是精确exact搜索多尺度检测同一 NMS 全局合并候选框单脸选择策略支持largest或center_largest数据模型为Collection - Person - FaceSample三级结构Collection 绑定模型支持一次提交多张照片的部分成功注册并附带 metadata 与明确的失败原因注册审核模式review_mode三档off/standard/strict另支持预计算的external_trustedembedding可信上游提取器直接提交向量GPU 精确检索支持 FP32、FP16、BF16、INT8 四种向量存储表示多语言 Web UIDashboard、Collections、People、Detect、Compare、Search、RTSP 监控、System、Help 页面/v1下共 29 个 snake_case REST 操作含受保护端点/v1/embeddings并配套轻量级类型化 Python SDK服务端 RTSP Monitor事件仅保存在内存、支持多客户端消费可选preview.mjpeg预览关闭浏览器不会停止监控SQLite 作为持久化事实来源内存中的精确索引可随时重建/models只读挂载、/data持久化卷内置迁移migrations、health check以及严格的 CUDA 校验——不做隐藏的 CPU 回退支持 JPEG / PNG / WebP 输入原始上传图默认不落盘。数据与检索架构从 Compose 文件看部署形态从 server/deploy/compose.cpu.yml 的声明可以看出容器的安全与数据布局设计容器以非 root 用户10001:10001运行read_only: true只读根文件系统cap_drop: [ALL]、no-new-privilegespids_limit与shm_size均有限额/tmp使用 128m tmpfs三类挂载各司其职server/config/server.toml只读绑定到/etc/insightface/server.toml配置命名卷data持久化到/dataSQLite 等状态server/.models只读绑定到/models模型包CPU 与 CUDA 镜像的差异集中在推理环境变量CPU 用INSIGHTFACE_EXECUTION_PROVIDER: CPUExecutionProviderCUDA 用CUDAExecutionProvider并额外设置INSIGHTFACE_STRICT_CUDA: 1对应「严格 CUDA 校验、无 CPU 回退」的承诺、NVIDIA_VISIBLE_DEVICES: all与gpus: all端口约定CPU 映射18097:8080CUDA 映射18098:8080即容器内统一为 8080。Compose 文件里暴露的全部环境变量默认值也值得记住它们是调参的第一入口INSIGHTFACE_DEFAULT_THRESHOLD默认 0.4、INSIGHTFACE_COLLECTION_DEFAULT_SEARCH_PROFILE默认fp32_v1、INSIGHTFACE_COLLECTION_DEFAULT_CAPACITY_ROWS默认 100000上限MAX默认 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、INSIGHTFACE_SAVE_FACE_CROPS默认 false。推理配置详解server/config/server.toml这份 TOML 在进程启动时加载一次修改后需要重启容器。关键配置项及其源码注释语义如下[inference] max_concurrency autoauto解析为 CPU 4 路、CUDA 8 路并发模型管线正整数可覆盖。API 请求、注册流程与 RTSP 帧共享这一个进程级并发预算[detection] input_sizes [[96, 96], [512, 512]]每个条目是[宽, 高]。动态 SCRFD 模型会对每个配置分辨率各跑一遍把所有候选框映射回源图坐标再对合并后的候选集执行一次全局 NMS[detection] threshold 0.50检测器最低置信度在 SCRFD 候选生成阶段、NMS 之前生效[detection] nms_threshold 0.40单次全局 NMS 的 IoU 阈值[detection] single_face_selection largest单脸操作如 compare的选脸策略可选largest或center_largest后者最大化score × area - 2.0 × 人脸框中心到图像中心的距离平方这个像素空间得分[detection] max_detected_faces 100部署级安全上限单个请求只能要求更少、不能更多[web] disabled falsetrue时进入纯 API 模式——保留/v1与/openapi.json但不注册 UI 路由。三、GPU 检索性能与 INT8 精度RTX 5090 上的 GPU 精确检索容量与速度官方基准测试在单张 NVIDIA GeForce RTX 509032 607 MiB 显存Driver 580.105.08CUDA 12.9上进行使用原生 CUDA flat 精确索引GPU 数据类型最大图像向量容量10M Top-5 p50 延迟10M 串行 QPSFP3215.8M12.84 ms77.85FP1630.7M6.83 ms146.32BF1630.7M6.83 ms146.33INT858.9M3.84 ms260.81相对 FP32INT8 提供了3.73 倍的实测容量与3.35 倍的 10M Top-5 吞吐。官方同时给出了严格的测量前提引用时不要脱离容量是「隔离极限」——未加载 ONNX 模型、不叠加 Server 负载下原生索引能容纳的 512 维向量上限速度是在恰好 10M 图像向量上、以完整 GPU-resident 精确 Top-5 扫描方式测得单并发、10 次预热 100 次取均值每个存储表示内部检索都是精确的但量化会使 score 相对 FP32 产生偏移生产环境必须为模型加载、在途请求、并发、索引重建与显存 allocator 预留 VRAM。ICCV21-MFR 多族裔基准上的 MR-ALL 精度官方用 ICCV21-MFR 的多族裔MR测试集按 MR-ALL 1:1 协议、在 FAR1e-6下评估了各检索精度。所有配置共用同一批 512 维 L2 归一化buffalo_lembedding经 Server API 一次性提取唯一变化是向量存储表示与检索计算方式检索配置FAR 1e-6 下 MR-ALLcosine 阈值相对 FP32 差值FP3291.249107 %0.407787—FP1691.249197 %0.4077870.000090 个百分点BF1691.248502 %0.407787-0.000605 个百分点INT891.248005 %0.407739-0.001102 个百分点结论INT8 在本基准上没有可观测的显著精度损失——按 challenge 惯例保留两位小数时FP32 与 INT8 同为91.25% MR-ALL未取整差值仅 0.0011 个百分点同时保留了 3.73 倍容量与 3.35 倍吞吐优势。注意该对比针对的是「向量存储与检索」的精度不是 INT8 模型推理量化推理是另一件事。从源码结构看检索后端由 server/backend/insightface_server/search/ 下的factory/manager/native/reference等模块组织原生 CUDA/C 实现位于 server/native/search/且 server/Makefile 提供了test-native-cpu目标CMake ctest 构建并运行原生检索测试另有test-cpu、test-cuda12、test-consistency等目标用于跨配置一致性验证。四、快速开始前置要求Linux x86_64装有 Docker Engine 与 Docker Compose使用 CUDA 时另需兼容的 NVIDIA GPU、NVIDIA 驱动与 NVIDIA Container Toolkit。宿主机不需要Python、OpenCV、ONNX Runtime、CUDA Toolkit 或 cuDNN——全部封装在容器内。官方镜像不含模型、客户数据、API Key 或生产配置。第一步安装模型包在完整 checkout 的 InsightFace 仓库中把模型装到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_l、buffalo_m、buffalo_sc与antelopev2。安装过程会生成manifest.json与签名的MODEL.LICENSEmodels verify可校验包完整性——模型条款与 Server 源码许可证是分离管理的。从 compose 文件 可见models是一个profiles: [tools]的工具服务入口为python -m insightface_server.models_cli支持代理环境变量HTTP_PROXY等并以INSIGHTFACE_MODELS_UID/GID控制写入属主。第二步启动 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://服务器:18097/或 CUDA 的http://服务器:18098/创建 Collection用一张或多张照片注册 Person再用另一张照片检索。docker compose ... down不带-v会保留数据卷。官方建议的第一条完整使用路径含设置、模型管理、Web UI、备份与诊断见 用户指南。启用 API Key 认证官方 Compose 文件默认关闭认证仅适合隔离环境评估。在开放给其他用户或网络之前务必启用export INSIGHTFACE_AUTH_ENABLEDtrue export INSIGHTFACE_API_KEY换成一个足够长的随机密钥 docker compose -f server/deploy/compose.cpu.yml up -d认证开启后所有/v1请求需携带该 KeySDK 中通过api_key参数传入。五、从源码构建镜像官方 Dockerfile 会拷贝server/与python-package/insightface/中选定推理模块因此构建上下文是整个仓库根目录需要在 checkout 根目录执行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保证运行阶段使用本地刚构建的镜像不会意外拉取 ghcr 上的 0.2.0 发布版构建本身仍会拉取锁定的基础镜像与依赖而models install是另一个显式接受的模型包下载动作。对照 server/Makefile 可知build-cpu/build-cuda12即以仓库根目录..为上下文执行docker build镜像标签与SERVER_VERSION ? 0.2.0一致该文件同时提供lint、test、test-api、test-sdk、test-frontend、smoke-test、release-preflight等开发入口。六、数据模型与关键运行规则理解以下规则能避免大部分「API 报错」困惑Similarity 是原始 cosine 值不是概率。threshold 取值范围0.0..1.0默认0.4对应环境变量INSIGHTFACE_DEFAULT_THRESHOLDCollection 固定了模型与 embedding contract。模型不匹配时 Collection 仍可见但注册/检索会返回collection_model_mismatch错误Detection Profile 的继承语义系统级检测 profile 只在启动时生效创建 Collection 时会将其复制过去此后 Collection 的 profile 可独立调整用于后续请求人脸裁剪的可选保存开启后保存的是 bounding-box 框出的 JPEG 裁剪并缩放到 112x112——既不是原图、也不是对齐后的识别输入默认关闭INSIGHTFACE_SAVE_FACE_CROPSfalseSQLite 是事实来源内存索引在任何注册/删除成功响应之前就已同步重启后从 SQLite 重建响应规范所有响应携带x-request-id列表接口使用不透明的签名 cursor 分页。七、REST API 与 Python SDK/v1下的操作分组系统类/v1/health、/v1/system、/v1/models无状态操作/v1/detect、/v1/compare、/v1/embeddings受保护Collection / Person / FaceSample 的 CRUDPerson 在指定 Collection 内的检索RTSP Monitor 的配置、状态、事件与 preview。全部端点、字段、行为、错误码与分页规则收录在 REST API 指南交互式 OpenAPI 文档直接部署在容器内/docs路径。SDK 用法示例官方 README 片段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 基于httpx、不含推理运行时安装方式为python -m pip install ./server/sdk/python在仓库根目录执行接受图像路径、bytes 或二进制文件对象。更多细节见 SDK 说明无状态的 Detect / Compare / Embeddings 调用可传collection复用该 Collection 的检测 profile可信上游提取器可提交external_embeddings 图像 embedding_contract_id走external_trusted通道服务端仍做检测与质量审核但不重新提取、也不回退到别的特征RTSP 监控可通过create_monitor/update_monitor/monitor_state/monitor_events管理客户端默认等待 65 秒略长于服务端 60 秒请求时限可用timeout调整。八、安全实践与一期边界人脸图像与 embedding 属于生物特征数据。官方给出的安全基线网络暴露前必须启用认证API Key并在受信反向代理上终结 HTTPS收紧 Docker 与 volume 权限不要开启宽泛 CORS明确备份、保留期、删除、知情同意与事件响应流程日志中不得写入图像、embedding、RTSP 凭据或 API Key。Server 本身不提供TLS、用户账号体系、RBAC、云 IAM 或法律合规层——这些由部署方在容器外部承担。一期明确未实现的能力AWS / CompreFace 兼容、CUDA 11、Jetson、ARM64、Windows 容器、TensorRT、Kubernetes、分布式 Worker、Monitor 事件持久化、录像 / NVR、活体检测、deepfake 检测与人口统计属性。九、许可许可条款的唯一入口是 LICENSING.mdServer 代码与 Python SDK 采用 MIT License该声明不覆盖模型文件与权重、数据集及第三方组件。InsightFace 公开模型通常限于非商业研究用途商业授权需另行获取。参考文档用户指南安装、配置、模型、Web UI、SDK、GPU、安全、备份与诊断REST API 指南全部端点、字段、行为、结果、错误、分页与示例维护者指南架构、内部检索、测试、贡献与容器发布示例与多语言 READMEGitHub 与 Web UI 帮助页读取同一份本地化 Markdown仅渲染方式不同。【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
