Skip to content
S0ra-aiPublic

About

基于深度学习的人脸识别与管理系统

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

FaceReg

基于 InsightFace + YOLOv8 + FastAPI + Vue 的人脸识别系统,当前版本重点整理了:

  • 模型目录驱动的统一管理
  • 多格式模型解析与校验
  • Windows + uv + 预装 torch 的可落地启动流程
  • 模型、环境、Git flow 的可视化检查

环境要求

  • Python 3.11
  • uv
  • Node.js 20+
  • Windows / Linux 均可,当前文档以 Windows + PowerShell 为主

Docker 部署

当前仓库已经提供完整 Docker 打包方案,默认特征如下:

  • 单容器部署:FastAPI 后端 + Vue 构建产物同镜像
  • GPU 运行:默认使用 CUDA 12.8 的 PyTorch Runtime 基础镜像
  • 资产内置:镜像会打包当前仓库里的 models/、data/、db/、thumbnails/、temp/
  • 宿主持久化:compose.yaml 默认把以上目录和 settings.docker.yaml 绑定回当前仓库
  • Docker 默认增强后端切到 gfpgan,直接使用现有 models/gfpgan/GFPGANv1.4.onnx

前提:

  • Docker Desktop / Docker Engine 已安装
  • 需要使用 GPU 时,宿主机已安装 NVIDIA 驱动和 NVIDIA Container Toolkit

1. 使用 Docker Compose

docker compose build facereg
docker compose up -d facereg

启动后访问:

  • 前端:http://localhost:8000/
  • API 文档:http://localhost:8000/docs

查看日志:

docker compose logs -f facereg

停止服务:

docker compose down

说明:

  • compose.yaml 默认挂载当前仓库的 ./models、./data、./db、./thumbnails、./temp
  • 容器内运行时对数据库、缩略图、临时文件和设置的改动会保留在宿主机
  • 容器启动时读取的是根目录的 settings.docker.yaml

2. 直接运行镜像

如果你希望不挂载宿主目录,直接使用镜像内打包好的模型和数据库:

docker build -t facereg:gpu .
docker run --rm --gpus all -p 8000:8000 facereg:gpu

这种方式会直接使用镜像内置的 models/、data/、db/ 资产,适合做离线演示或单机分发。

快速启动

Windows 一键补环境

如果你已经准备好本机 CUDA 对应的 torch / torchvision wheel,可以直接:

.\scripts\bootstrap.ps1 `
  -TorchWheel D:\path\to\torch-*.whl `
  -TorchVisionWheel D:\path\to\torchvision-*.whl `
  -InstallFrontend

后续所有 CLI 命令统一走:

.\scripts\run.ps1 doctor
.\scripts\run.ps1 serve --reload

1. 创建并同步环境

uv venv -p 3.11
.venv\Scripts\activate
uv sync

如果你已经先手动安装了本机 CUDA 对应的 torch / torchvision wheel,例如:

uv pip install D:\path\to\torch-*.whl
uv pip install D:\path\to\torchvision-*.whl

那么补齐项目依赖时,优先直接执行:

uv pip install -e .

说明:

  • 这条命令会保留你已经装好的本地 torch / torchvision,再把项目缺失依赖补齐
  • 默认 uv sync 只同步项目依赖和 dev 组,不会自动安装 cuda 组
  • 如果你希望完全交给 uv 管理 torch / torchvision,再显式执行 uv sync --group cuda
  • Windows 下 insightface wheel 与 numpy 2.x 不兼容,项目会固定到 numpy < 2.0
  • 手动安装本地 wheel 的场景,运行命令优先使用 .\scripts\run.ps1 ... 或 uv run --no-sync ...
  • 项目默认增强后端是 GFPGAN
  • Windows + Python 3.11 下的 insightface 默认走固定 wheel 源,避免本地编译依赖 MSVC
  • CodeFormer 保留为可选后端,但其上游包源不稳定,不再作为默认依赖

2. 安装前端依赖

cd frontend
npm install
cd ..

3. 先做环境检查

uv run python main.py doctor

这个命令会输出:

  • Python / uv / 虚拟环境状态
  • torch / onnxruntime / insightface 等关键依赖
  • 当前 Git 分支、工作区是否干净、是否适合切分支

4. 启动后端

uv run python main.py serve

开发模式热重载:

uv run python main.py serve --reload

5. 启动前端开发服务器

cd frontend
npm run dev

首次使用流程

推荐按下面顺序操作:

  1. 启动后端和前端
  2. 进入“模型管理”页
  3. 点击“一键安装缺失模型”
  4. 等待模型自动下载、安装、校验完成
  5. 把待入库的人脸图片放到 data
  6. 执行数据库构建
  7. 进入识别页或监控页验证效果

数据库构建命令:

uv run python main.py build

如果你想一键执行“模型检查 + 清理旧数据 + 重建数据库”,可以用:

uv run python main.py init

模型管理

现在模型配置由根目录的 model_catalog.yaml 驱动。

当前特性:

  • 支持 onnx / pt / pth / ckpt / safetensors / zip
  • 支持 GitHub Release、Google Drive、自定义 URL 下载
  • 支持自动安装后校验
  • 支持扫描本地未登记模型
  • 只允许被目录声明为 switchable 的模型参与热切换

如果你要追加自己的模型,不建议直接改业务代码,优先新建 model_catalog.local.yaml 覆盖或补充条目。

当前默认模型策略

  • 主识别模型:antelopev2 / buffalo_l / buffalo_s / buffalo_sc
  • 增强模型:默认 gfpgan
  • 活体模型:支持一键安装兼容 ONNX 版本
  • YOLO:支持 yolov8n/s/m/l/x

注意:

  • AdaFace、ElasticFace 当前已纳入目录与下载/校验归档
  • 这两类模型默认不参与主模型热切换,因为当前运行时主链还是 InsightFace bundle

常用命令

uv run python main.py doctor
uv run python main.py serve
uv run python main.py serve --reload
uv run python main.py build
uv run python main.py init
uv run python main.py info
uv run python main.py recognize path\to\image.jpg

目录说明

Git Flow

推荐分支流:

  • develop: 集成分支
  • master: 发布分支
  • feat/* / fix/* / docs/* / refactor/*: 常规开发分支
  • codex/*: 自动化或临时工程分支

Windows 下可直接用脚本检查和切分支:

.\scripts\git-flow.ps1 -Action status
.\scripts\git-flow.ps1 -Action start -Prefix feat -Name model-hub
.\scripts\git-flow.ps1 -Action switch -Name develop

常见问题

uv sync 后 torch 被替换了

优先使用:

uv pip install -e .

运行命令时不要直接用裸 uv run python .\main.py,它会再次按锁文件同步环境。优先使用:

.\scripts\run.ps1 doctor
uv run --no-sync python .\main.py doctor

如果你希望后续改成由 uv 自己安装和维护 CUDA 版 torch,再执行:

uv sync --group cuda

insightface 在 Windows 上编译失败

当前项目默认已经把 Windows 依赖切到 wheel 源;如果仍然失败,先确认:

  • Python 版本是 3.11
  • 不是手动切到了其他索引
  • 没有旧锁文件和当前 pyproject.toml 不一致

模型明明在本地,但页面不能热切换

说明该模型只被扫描到了,但还没有在 model_catalog.yaml / model_catalog.local.yaml 中声明为 switchable。

开发协作

协作规范见 CONTRIBUTING.md。

About

基于深度学习的人脸识别与管理系统

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages