基于 InsightFace + YOLOv8 + FastAPI + Vue 的人脸识别系统,当前版本重点整理了:
- 模型目录驱动的统一管理
- 多格式模型解析与校验
- Windows +
uv+ 预装torch的可落地启动流程 - 模型、环境、Git flow 的可视化检查
- Python
3.11 uv- Node.js
20+ - Windows / Linux 均可,当前文档以 Windows + PowerShell 为主
当前仓库已经提供完整 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
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
如果你希望不挂载宿主目录,直接使用镜像内打包好的模型和数据库:
docker build -t facereg:gpu .
docker run --rm --gpus all -p 8000:8000 facereg:gpu这种方式会直接使用镜像内置的 models/、data/、db/ 资产,适合做离线演示或单机分发。
如果你已经准备好本机 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 --reloaduv 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 下
insightfacewheel 与numpy 2.x不兼容,项目会固定到numpy < 2.0 - 手动安装本地 wheel 的场景,运行命令优先使用
.\scripts\run.ps1 ...或uv run --no-sync ... - 项目默认增强后端是
GFPGAN - Windows + Python 3.11 下的
insightface默认走固定 wheel 源,避免本地编译依赖MSVC CodeFormer保留为可选后端,但其上游包源不稳定,不再作为默认依赖
cd frontend
npm install
cd ..uv run python main.py doctor这个命令会输出:
- Python /
uv/ 虚拟环境状态 torch/onnxruntime/insightface等关键依赖- 当前 Git 分支、工作区是否干净、是否适合切分支
uv run python main.py serve开发模式热重载:
uv run python main.py serve --reloadcd frontend
npm run dev推荐按下面顺序操作:
- 启动后端和前端
- 进入“模型管理”页
- 点击“一键安装缺失模型”
- 等待模型自动下载、安装、校验完成
- 把待入库的人脸图片放到 data
- 执行数据库构建
- 进入识别页或监控页验证效果
数据库构建命令:
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- src: 后端代码
- frontend: Vue 前端
- model_catalog.yaml: 模型注册表
- settings.yaml: 运行时设置
- data: 入库图片目录
- models: 模型文件目录
- db: 向量库 / 元数据目录
推荐分支流:
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 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当前项目默认已经把 Windows 依赖切到 wheel 源;如果仍然失败,先确认:
- Python 版本是
3.11 - 不是手动切到了其他索引
- 没有旧锁文件和当前
pyproject.toml不一致
说明该模型只被扫描到了,但还没有在 model_catalog.yaml / model_catalog.local.yaml 中声明为 switchable。
协作规范见 CONTRIBUTING.md。