Tiger AI Platform 人脸识别功能汇总导读本文汇总平台「人脸识别」能力——业界常用框架与任务模型对比、本项目选型InsightFace、底库与实时 1:N 识别流程、API / 权限以及操作界面说明。文中配图位请按说明截取平台页面放入docs/images/face/后替换占位图。文章目录Tiger AI Platform 人脸识别功能汇总一、功能概览*图 1侧栏「视觉识别 → 人脸识别」入口二、框架与方案对比选型背景2.1 常见框架 / SDK 对比2.2 任务模型对比检测 vs 识别2.3 Buffalo 套件档位对比三、本项目采用的框架与模型3.1 技术选型结论3.2 种子模型模型管理四、系统架构与数据流4.1 模块结构4.2 端到端流程4.3 登记与识别细节五、人脸底库功能5.1 数据模型5.2 底库界面能力5.3 匹配策略说明六、实时识别界面七、API 与权限八、部署与使用步骤简版九、阈值、性能与注意事项十、与平台其他视觉能力的边界十一、配图清单请按序补齐十二、相关代码与文档索引一、功能概览平台在视觉识别菜单下提供独立工作台人脸识别路由/ai/face完成能力说明实时 1:N 识别浏览器摄像头抓帧 → 服务端检测 特征提取 → 与底库余弦匹配 → 画面叠加与结果表人脸底库人员 CRUD、多图登记上传 / 拍照、按模型绑定特征向量模型纳管种子模型 Buffalo-S / Buffalo-L在「模型管理」中拉取 InsightFace 权重权限控制菜单与按钮级权限查询 / 新增 / 修改 / 删除识别流水线本项目图像帧 → SCRFD 人脸检测可选 detThresh → 对齐 → ArcFace 特征512 维L2 归一化 → 与底库矩阵余弦相似度 1:N → score ≥ threshold → 匹配姓名否则 unknown*图 1侧栏「视觉识别 → 人脸识别」入口二、框架与方案对比选型背景人脸相关能力通常拆成检测在哪、识别 / 比对是谁、活体 / 属性可选。工程上可选开源框架或云 API。2.1 常见框架 / SDK 对比方案类型优势局限适合场景InsightFace开源ONNX检测识别一体化buffalo 套件成熟CPU/GPU 均可社区与论文基线强商用需自行评估许可需管权重与底库本平台采用本地部署 1:NDeepFace开源封装多后端VGG-Face、Facenet、ArcFace 等易试用生产性能与依赖链偏重API 偏脚本快速验证、研究对比face_recognition (dlib)开源上手简单、教程多精度与抗干扰弱于现代 ArcFace维护偏旧演示、小样本MediaPipe Face开源实时检测/网格强移动端友好不提供开箱 1:N 身份识别美颜、关键点、活体辅助OpenCV DNN / YuNet开源部署轻、依赖少识别能力弱或需自建比对仅检测、嵌入式FaceNet / 自训 ArcFace自研管线可控、可定制数据集工程成本高训练、对齐、底库、服务大规模定制云 APIFace、腾讯云、阿里云等商业 SaaS精度与运维省心活体/证件等齐全费用、隐私出境/合规、离线不可用ToB 快速上线、强合规云厂商2.2 任务模型对比检测 vs 识别任务代表模型输出本项目人脸检测SCRFD、RetinaFace、YuNet、MTCNN框 / 关键点 / 检测分SCRFDInsightFace buffalo 内置人脸识别特征ArcFace、CosFace、SphereFace、MobileFaceNet固定维 embeddingArcFace 系SMobileFaceLResNet50比对策略余弦 / 欧氏距离 阈值是否同一人余弦相似度默认阈值0.4识别模式1:1 核验 / 1:N 检索比对两人 / 搜底库1:N 底库检索2.3 Buffalo 套件档位对比InsightFace 官方 buffalo 套件将检测与识别 ONNX 打包发布本平台种子了两档档位识别骨干相对精度速度 / 资源建议buffalo_sMobileFacew600k_mbf.onnx中高CPU 友好默认开发与演示buffalo_lResNet50w600k_r50.onnx更高更吃算力建议 GPU CUDA EP底库较大或要求更高召回不同 pack /model_key的特征空间不互通更换识别模型后必须重新登记人脸。三、本项目采用的框架与模型3.1 技术选型结论项本项目选择推理框架libraryinsightface任务类型taskface-recognition运行时ONNX Runtime优先 CUDA EP否则 CPU检测SCRFDdet_size(640, 640)默认detThresh0.5特征ArcFace 512 维入库与比对前L2 归一化匹配内存底库矩阵 × 查询向量余弦阈值默认0.4依赖见backend/requirements.txtinsightface0.7.3 onnxruntime1.17.0 # GPU 环境可换装匹配的 onnxruntime-gpu3.2 种子模型模型管理model_key显示名versionpack权重来源insightface-buffalo-sInsightFace Buffalo-Sbuffalo_sInsightFace v0.7buffalo_s.zipinsightface-buffalo-lInsightFace Buffalo-Lbuffalo_lInsightFace v0.7buffalo_l.zip分类人脸识别状态启用后出现在人脸页「识别模型」下拉框。权重目录backend/uploads/insightface/models/pack/拉取方式模型管理 →拉取权重或python scripts/poc_insightface.py buffalo_s*图 2模型管理中筛选 libraryinsightface / taskface-recognition并展示 Buffalo-S/L 与「拉取权重」四、系统架构与数据流4.1 模块结构层级路径职责ORMbackend/models/face.pyFacePerson、FaceEmbedding底库服务backend/services/face_gallery.py打包/解包向量、缓存、余弦匹配、多图平均推理backend/inference.pyFaceAnalysis 缓存、抽特征、识别绘图APIbackend/routes/face.py/api/ai/face/*前端frontend/src/views/ai/face/index.vue实时识别 底库 UI客户端frontend/src/api/ai.js→faceApi封装 HTTP4.2 端到端流程数据库InsightFace GalleryFlask /api/ai/face前端 /ai/face实时识别 Tab人脸底库 TabPOST .../enrollPOST /recognize人员 CRUDFaceAnalysis SCRFDArcFace按 model_key 缓存底库矩阵face_personface_embedding4.3 登记与识别细节新增人员只写face_person姓名、工号、备注、启停此时尚无特征。登记enroll上传 15 张图 → 每张取检测分最高的人脸 embedding →平均后 L2→ 按model_key覆盖写入face_embedding→ 清底库缓存可选保存登记图到uploads/faces/person_id/。识别recognize抽全图人脸 → 对每个 embedding 做 1:N → 返回 bbox / name / score / matched。实时页优化抓帧宽约 640隔帧默认 2降低 CPU 压力客户端IoU0.3短时跟踪减少标签闪烁。五、人脸底库功能5.1 数据模型人员face_person字段说明name姓名必填employee_no工号 / 编号可选remark备注status0启用 /1停用停用后不参与匹配特征face_embedding字段说明person_id外键级联删除model_key与AiModel.model_key绑定dim默认 512vectorfloat32 二进制source_path登记图相对路径可选同一人员、同一model_key仅保留一条主特征再次登记会覆盖。5.2 底库界面能力功能说明查询按姓名搜索列表新增 / 编辑 / 删除人员信息维护删除级联特征登记人脸选择 InsightFace 模型本地上传与/或摄像头拍照合计最多5张特征数展示列表显示embeddingCount启停停用人员不进入匹配矩阵图 3人脸底库列表含姓名、工号、特征数、状态、操作列图 4登记人脸对话框模型选择 上传/拍照预览15 张5.3 匹配策略说明仅加载status启用且对应model_key的特征。查询向量与底库矩阵做点积等价于余弦因已 L2。score threshold判定匹配否则姓名为unknown。建议在真实底库上标定阈值区间0.350.45默认 0.4。六、实时识别界面控件默认 / 范围作用识别模型Buffalo-S/L已拉取权重决定 pack 与底库model_key摄像头系统设备列表getUserMedia相似度阈值0.40.20.8匹配门槛隔帧205CPU 建议 23GPU 可调 0开始 / 停止—启停识别循环画面 HUDFPS、人脸数、已识别数右侧表格姓名、相似度百分比、匹配/未知。图 5实时识别页左侧摄像头叠加框 右侧识别结果表建议含至少一人已匹配七、API 与权限前缀/api/ai/face需 JWT。方法路径权限说明GET/personsai:face:list底库列表可按 name 过滤GET/persons/:idai:face:list详情含 embeddingsPOST/personsai:face:add新增人员PUT/persons/:idai:face:edit编辑DELETE/persons/:idai:face:remove删除POST/persons/:id/enrollai:face:add登记modelIdfilesPOST/recognizeai:face:list识别file/imagemodelIdthreshold等菜单种子ai:face:list|query|add|edit|remove见backend/seed.py。八、部署与使用步骤简版安装依赖insightface、onnxruntime或 GPU 版。启动后端种子后打开模型管理对 Buffalo-S或 L执行拉取权重。打开人脸识别 → 人脸底库新增人员 → 登记 15 张正脸照。切到实时识别选同一模型、调阈值与隔帧 → 开始识别。可选 PoCcd backend python scripts/poc_insightface.py buffalo_s图 6模型管理中对 InsightFace 模型点击「拉取权重」成功后的状态filePath / 大小九、阈值、性能与注意事项项建议余弦阈值默认 0.4误识多则调高拒识多则调低检测阈值后端默认 0.5前端暂未暴露CPU抓帧宽 640 隔帧 23GPU安装 CUDA 对应onnxruntime-gpu后可将隔帧调低换模型必须重新 enroll合规人脸属敏感个人信息须授权、限用途与留存InsightFace 许可见官方仓库页面顶部已有合规提示条对外演示勿将底库暴露至公网。图 7人脸识别页顶部合规提示含 InsightFace 许可与隐私说明十、与平台其他视觉能力的边界模块关系摄像头检测/ai/camera通用目标检测YOLO 等不是人脸底库 1:N视频 / 图片检测物体检测与告警不走face_embedding人脸识别/ai/face唯一完整的 InsightFace 底库登记与实时识别工作台十一、配图清单请按序补齐将截图保存到docs/images/face/文件名与上文占位一致文件名建议内容01-menu-face.png菜单进入人脸识别02-model-manage-insightface.png模型管理中的 InsightFace 模型03-gallery-list.png人脸底库列表04-enroll-dialog.png登记人脸对话框05-live-recognize.png实时识别运行中06-fetch-weights.png拉取权重成功07-compliance-banner.png合规提示条若暂无截图Markdown 预览中图片会显示为裂图补齐文件后无需改文案路径。十二、相关代码与文档索引说明路径开发速查API / 阈值face-recognition.mdORMbackend/models/face.py底库匹配backend/services/face_gallery.py推理backend/inference.pyInsightFace 段路由backend/routes/face.py前端页frontend/src/views/ai/face/index.vue种子模型与菜单backend/seed.pyPoCbackend/scripts/poc_insightface.py文档版本与平台人脸模块实现同步整理框架对比表供选型说明实际能力以仓库代码与种子数据为准。