InsightFace Python 库 1.0.1 实战指南从 FaceAnalysis 快速推理到 Evaluation Studio 桌面评测【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightfaceInsightFace Python 库是 insightface 项目面向应用开发者的一站式人脸分析工具包它以 ONNX Runtime 为推理后端覆盖人脸检测SCRFD、识别ArcFace 系列、关键点、属性性别/年龄、人脸交换与桌面级评测 GUI。本文以 python-package/README.md 为主线结合仓库源码讲解安装配置、快速推理、模型仓库使用、自有模型接入以及 InsightFace Evaluation Studio 桌面应用的完整工作流读完即可上手完成 1:1 比对、1:N 检索、相册聚类与企业评测报告导出。许可证与使用边界InsightFace Python 库的代码以 MIT License 发布学术与商业使用均无限制但库随附的预训练模型无论是自动下载还是手动下载仅限非商业研究用途。使用前请确认你的应用场景符合模型授权约束商业部署需要单独获取模型授权详见 python-package/docs/commercial_evaluation.md。安装与后端选择推理后端从 MXNet 到 ONNX Runtimeinsightface0.1.5使用 MXNet 作为推理后端从insightface0.2起统一改用 onnxruntime这也是当前仓库代码的实际状态——python-package/insightface/init.py 在导入时直接import onnxruntime并在缺失时报Unable to import dependency onnxruntime。安装 ONNX Runtime 时按需选择仅 CPU 推理安装onnxruntimeGPU 推理需手动安装onnxruntime-gpu同时 CUDA 环境需就绪库的基础依赖见 python-package/setup.py包括numpy、onnx、onnxruntime、opencv-python、tqdm、requests、scipy、scikit-image。1.0.1 版本已移除easydict、prettytable等不再使用的基础依赖并将Pillow、scikit-learn移入 GUI extra、matplotlib移入可选的face3dextra。安装 InsightFace Evaluation Studio GUIInsightFace 1.0.1 内置本地桌面 GUI——InsightFace Evaluation Studio。PyPI 用户直接安装pip install insightface[gui] insightface-gui从仓库源码进行开发安装cd python-package pip install -e .[gui] insightface-guiGUI extra 会额外安装PySide6-Essentials6.5、Pillow、reportlab、scikit-learn用于 DBSCAN 聚类见 python-package/setup.py。等价的启动命令在 setup.py 的entry_points中注册insightface-eval-studio insightface-desktop python -m insightface.gui三个命令与insightface-gui指向同一个入口 python-package/insightface/gui/main.py。可选 face3d 构建InsightFace 1.0.1默认不再构建可选的face3dCython/C 扩展以保持默认安装轻量、避免本地编译器依赖。需要旧版 mask renderer / face3d 路径的用户可以显式启用pip install -e .[face3d] --no-build-isolation --config-settings editable_modecompat python setup.py build_ext --inplace --with-face3d等价方式环境变量版INSIGHTFACE_WITH_FACE3D1 python setup.py build_ext --inplace从 setup.py 源码可见--with-face3d与INSIGHTFACE_WITH_FACE3D1都会置位build_face3d从而将insightface.thirdparty.face3d.mesh.cython包纳入打包并cythonizemesh_core_cython.pyx。在 macOS 上构建脚本还会自动检测 Homebrew LLVM/OpenMP 并设置CC/CXX编译器环境。更多细节参见python-package/docs/gui.mdpython-package/docs/commercial_evaluation.mdpython-package/docs/gui_packaging.md快速上手FaceAnalysis 人脸分析应用仓库 README 提供了开箱即用的示例核心是FaceAnalysis应用类import cv2 import numpy as np import insightface from insightface.app import FaceAnalysis from insightface.data import get_image as ins_get_image app FaceAnalysis(providers[CUDAExecutionProvider, CPUExecutionProvider]) app.prepare(ctx_id0) # Auto detection size: 128x128 640x640 img ins_get_image(t1) faces app.get(img) rimg app.draw_on(img, faces) cv2.imwrite(./t1_output.jpg, rimg)该示例从t1.jpg内置测试图由 python-package/insightface/data/image.py 的get_image加载检测人脸并绘制结果到t1_output.jpg。FaceAnalysis 内部调用链从源码看 python-package/insightface/app/face_analysis.py构造阶段FaceAnalysis(nameDEFAULT_MP_NAME, root~/.insightface, allowed_modulesNone)会通过ensure_available定位模型目录扫描其中全部*.onnx文件并用model_zoo.get_model()逐个识别任务类型taskname。默认模型名为buffalo_lDEFAULT_MP_NAME。allowed_modules[detection]可只加载检测模型。prepare(ctx_id, det_thresh0.5, det_sizeNone)检测阈值默认0.5det_sizeNone时判定为 Auto使用DEFAULT_DET_SIZES [(128, 128), (640, 640)]face_analysis.py即先跑 128x128 与 640x640 两次 SCRFD 检测再做统一 NMS 合并。检测模型调用model.prepare(ctx_id, input_sizedet_size, det_threshdet_thresh)其余任务模型识别、关键点、属性调用model.prepare(ctx_id)。get(img, max_num0, det_metricdefault)先由检测模型输出bboxes, kpss再为每个Face对象依次执行识别/关键点/属性等模型的model.get(img, face)把特征与属性回填到Face定义于 python-package/insightface/app/common.py。draw_on(img, faces)用 OpenCV 绘制检测框、关键点并在存在性别/年龄时叠加性别,年龄文本。SCRFD 多尺度检测原理检测模型默认走 python-package/insightface/model_zoo/scrfd.py 的SCRFD类tasknamedetection。其关键行为nms_thresh默认0.4det_thresh默认0.5动态输入模型static_input_size is None默认使用DEFAULT_DET_SIZES双尺度prepare(input_size...)时通过_normalize_input_sizes归一化输入尺寸列表detect()对每个输入尺寸做候选检测合并所有尺度的候选框后按分数降序排序、统一 NMSmax_num0时按面积减去中心偏移惩罚选取靠中心的大脸metricmax时只看面积。模型仓库Model Zoo最新版 insightface 提供以下模型包。加粗的是默认模型包Auto列为Y表示可通过 Python 库直接自动下载。手动下载 zip 模型包时需先解压到~/.insightface/models/再调用程序。NameDetection ModelRecognition ModelAlignmentAttributesModel-SizeAutoantelopev2SCRFD-10GFResNet100Glint360K2d106 3d68GenderAge407MBNbuffalo_lSCRFD-10GFResNet50WebFace600K2d106 3d68GenderAge326MBYbuffalo_mSCRFD-2.5GFResNet50WebFace600K2d106 3d68GenderAge313MBNbuffalo_sSCRFD-500MFMBFWebFace600K2d106 3d68GenderAge159MBNbuffalo_scSCRFD-500MFMBFWebFace600K--16MBN识别准确率官方发布数据NameMR-ALLAfricanCaucasianSouth AsianEast AsianLFWCFP-FPAgeDB-30IJB-C(E4)buffalo_l91.2590.2994.7093.1674.9699.8399.3398.2397.25buffalo_s71.8769.4580.4573.3951.0399.7098.0096.5895.02buffalo_m与buffalo_l准确率相同buffalo_sc与buffalo_s准确率相同。再次提醒这些模型仅限非商业研究用途。模型的自动与手动下载insightface0.3.3初始化app FaceAnalysis()时即自动下载默认模型包insightface0.3.2需先手动执行 CLI 下载命令insightface-cli model.download buffalo_lCLI 入口定义在 python-package/insightface/commands/insightface_cli.py其中model.download由 python-package/insightface/commands/model_download.py 实现下载与解压逻辑封装在 python-package/insightface/utils/storage.py 的download/ensure_available/download_onnx中。使用自有模型只需在~/.insightface/models/下新建一个模型目录放入你自己的 ONNX 模型然后通过名称加载app FaceAnalysis(nameyour_model_zoo)FaceAnalysis.__init__会扫描该目录下所有.onnx文件并按任务类型自动路由face_analysis.py。调用检测与识别模型最新版 insightface仅支持 ONNX 模型。用 PyTorch、MXNet 等框架训练的检测/识别模型可先转换为 ONNX 格式再接入转换工具参考仓库内的 torch2onnx.py、mxnet_to_onnx.py 等。调用检测模型import cv2 import numpy as np import insightface from insightface.app import FaceAnalysis from insightface.data import get_image as ins_get_image # Method-1, use FaceAnalysis app FaceAnalysis(allowed_modules[detection]) # enable detection model only app.prepare(ctx_id0) # Auto detection size: 128x128 640x640 # Method-2, load model directly detector insightface.model_zoo.get_model(your_detection_model.onnx) detector.prepare(ctx_id0) # SCRFD defaults to Auto: 128x128 640x640调用识别模型import cv2 import numpy as np import insightface from insightface.app import FaceAnalysis from insightface.data import get_image as ins_get_image handler insightface.model_zoo.get_model(your_recognition_model.onnx) handler.prepare(ctx_id0)模型自动路由原理model_zoo.get_model()的底层路由逻辑位于 python-package/insightface/model_zoo/model_zoo.py 的ModelRouter它依据 ONNX 图的输入/输出形状自动判定任务类型输出数量5→SCRFD检测模型输入为192x192→Landmark关键点模型输入为96x96→Attribute属性模型双输入且128x128→INSwapper人脸交换模型正方形输入且边长112、为 16 的倍数 →ArcFaceONNX识别模型。其中ArcFaceONNXpython-package/insightface/model_zoo/arcface_onnx.py会扫描计算图前 8 个节点若存在Sub/_minus与Mul/_mul则判定为 MXNet 风格模型input_mean0, input_std1否则使用input_mean127.5, input_std127.5。默认 providers 为[CUDAExecutionProvider, CPUExecutionProvider]model_zoo.py与快速示例一致当ctx_id0时 SCRFD 会强制切换到CPUExecutionProvider。InsightFace Evaluation Studio桌面评测工作台GUI 是 1.0.1 的核心新特性完整操作手册见 python-package/docs/gui.md。数据工作区与本地隐私默认数据保存在~/.insightface/gui含 SQLite 数据库、裁剪图、导出、报告、日志。图像、视频、嵌入向量、数据库与报告默认全部本地存储不会自动上传。可用--workspace覆盖insightface-gui --workspace /path/to/workspace所有页面的图片/视频预览框即上传目标点击Click to upload or drag a file here或拖拽文件到预览框悬停与拖入时预览框变色反馈加载后可点小×删除或拖入新文件替换。模式化导航Workflows左侧常驻Workflows导航栏包含四种模式每个模式内都显示本地处理提示所有处理均在本地完成图像、嵌入与报告不会被自动上传。Face Recognition单个 Query Gallery 工作区。单张 Gallery 图执行 1:1 比对多张图或文件夹执行 1:N 检索按相似度排序并报告相似度、阈值、判定与检测分数。Album ManagementAlbum 工作区支持本地文件夹导入、刷新、DBSCAN 人脸聚类与原始照片缩略图复核。Face SwapSource Target Result 工作区Target 可为图片或视频。Enterprise Evaluation本地 1:1 / 1:N 评测工作区支持身份文件夹导入、Auto Split、指标与报告导出。顶部栏与Tools菜单提供全局工具SettingsUI 主题与语言、Models运行时设置、模型下载、自定义模型目录、License许可中心。支持语言英语、中文、日语、韩语、西班牙语、法语、德语、葡萄牙语、俄语默认跟随操作系统不支持时回退英语主题System、Precision Light、Studio Dark、Graphite Pro、Azure Lab、Emerald Focus、Crimson Audit工作区路径在首次启动时选定设置对话框中不可更改。模型管理打开顶部Models或Tools Models模型包buffalo_l、buffalo_s、antelopev2或自定义模型文件夹providerAuto / CPU / CUDA仅当CUDAExecutionProvider可用时可选检测尺寸Auto、128x128、320x320、640x640、1024x1024Auto 为默认联合 128x128 与 640x640 检测并合并重复框人脸交换模型与 GFPGAN 后处理模型需已下载GFPGANv1.4.onnx。GUI不会自动下载模型。需在Models Downloads点击Refresh Download URLs拉取最新 Release 资源地址再显式下载所选包URL 缓存于~/.insightface/gui/cache/model_download_urls.json。下载的 zip 缓存于~/.insightface/gui/cache/models解压到~/.insightface/models/model_name/例如~/.insightface/models/buffalo_l/、~/.insightface/models/antelopev2/。Downloads 页同时列出第三方修复模型 GFPGANv1.4下载后在Models Runtime开启GFPGAN post-processing人脸交换后执行 512x512 的 GFPGAN 修复。交换模型仅从已下载列表中选取Face Swap 工作区只在真正运行时加载配置的交换模型。即使模型缺失GUI 也能正常打开对应页面会提示Model is not loaded. Please open Models.相册聚类DBSCANAlbum Management Album可添加一个或多个相册目录点击Import / Refresh扫描新图片、检测人脸、保存本地裁剪并聚类。默认余弦相似度阈值0.48值越大聚类越严格DBSCAN 内部使用1 - 余弦阈值作为距离。聚类 ID 避免与既有 People Library ID 重复当簇与既有身份在默认重复距离阈值0.28内匹配时复用该身份 ID否则分配下一个相册身份 ID。簇缩略图取距簇中心最近的人脸选中簇可查看全部原始照片缩略图双击可打开原图。相册目录与聚类结果保存在本地 SQLite 中下次启动自动恢复。Clear仅清除所选相册目录并保留当前聚类结果Rebuild All需确认后从零重跑所有所选目录并替换保存的聚类结果若未选择任何目录Rebuild All会清空已保存的聚类结果。企业评测Enterprise Evaluation进入Enterprise Evaluation可进行无代码本地评测1:1 Verification身份文件夹每个子文件夹为一个身份。开启Auto Split时包含gallery的文件或排序后的第一张图作为该身份 gallery其余为 probe跨身份执行 probe-vs-gallery 匹配不开启则全部作为 probe执行全量两两比对。1:N Identification身份文件夹开启 Auto Split 时选择包含identities/身份文件夹的数据集或直接选择身份文件夹gallery 选取规则同 1:1不开启时使用gallery/identity、probe/identity及可选unknown/目录。评测前需选定Multi-face handling策略并点击Validate Dataset验证校验文件夹布局、Auto Split 规则、gallery/probe 可用性、1:1 正负样本对生成、1:N gallery 覆盖以及多脸策略Require exactly one face默认任一张评测图检出多于一张人脸即验证失败Use largest face多脸图告警评测使用最大人脸Use largest centered face多脸图告警评测使用面积减中心偏移得分最高的人脸Mark as skip多脸图跳过若必需 gallery 被跳过则验证失败。Run Evaluation仅在验证通过后可用。1:1 报告包含最佳余弦阈值准确率、该工作点阈值及1e-6/1e-5/1e-4/1e-3的 TARFAR1:N 报告包含 Top1 及1e-5/1e-4/1e-3/1e-2的 TARFAR 与对应阈值。报告导出至~/.insightface/gui/reports支持 Markdown、HTML、PDF需安装 GUI extra。人脸交换与故障排查Face Swap 的 Source 必须为图片Target 可为图片或视频按文件类型自动选择图像/视频交换视频交换输出.mp4到 exports 目录并展示预览帧。模型缺失时提示Face swap model not found. Please download and choose a swap model in Models.人脸交换可能因用途与模型许可需要单独商业授权请仅在拥有相应权利与同意的前提下使用。故障排查相关命令# 本次启动不自动加载模型不写入 config.json仅用于排查模型/provider 问题 insightface-gui --safe-mode # 强制 CPU insightface-gui --provider cpu日志位于~/.insightface/gui/logs/app.log。代码与模型文件可能适用不同许可证商业部署需获得相应模型授权且使用者需自行负责同意、隐私、留存与生物识别法规合规。版本演进要点Change Log 摘要1.0.12026-05-23移除 PyPI 包元数据 license classifier保留 README 许可指引Pillow/scikit-learn移入 GUI extra、matplotlib移入 face3d extra移除easydict、prettytable依赖。1.02026-05-23新增 InsightFace Evaluation Studio 桌面 GUI新增insightface-gui/insightface-eval-studio/insightface-desktop/python -m insightface.gui启动方式FaceAnalysis.prepare()默认检测尺寸改为 AutoSCRFD 128x128 640x640 联合检测再统一 NMSmodel_zoo.get_model()加载的检测模型默认路由到 SCRFDface3d 扩展默认不再构建。0.7.12022-12-14模型下载源切换到 cloudfront。0.72022-11-28新增人脸交换模型与示例默认 ORT provider 设为 CUDA 与 CPU。0.62022-01-29face-analysis 应用新增姿态估计自动下载地址切换到 ucloud。小结InsightFace Python 库以ONNX 模型 自动路由 FaceAnalysis 一站式应用的设计把检测、识别、关键点、属性、交换等任务收敛为极简 API1.0.1 又通过 Evaluation Studio GUI 补齐了无代码评测链路。无论你是想用几行代码跑通人脸识别流程、接入自有 ONNX 模型还是需要本地化的 1:1/1:N 评测报告都可以在此基础上直接落地。【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考