# ai-facerec

**Repository Path**: ifredom/ai-facerec

## Basic Information

- **Project Name**: ai-facerec
- **Description**: Real-time exit intent detection system in Rust. YOLO11 + ByteTrack + ArcFace on CoreML, with automatic door unlock via UniFi Access.
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-28
- **Last Updated**: 2026-08-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# facerec —— 智能人脸识别进出场管理系统

基于 **InsightFace（buffalo_s）** 的人脸识别 / 进出场检测 Web 系统：检测人脸、追踪轨迹、判定进场/离场、去重、白名单，并通过 Web 看板实时展示六大类日志。

## 仓库结构（两个版本，一条主线）

```
facerec/
├── README.md        # 本文件：仓库总览
├── CLAUDE.md        # AI 助手项目上下文（改动代码前必读）
├── CHANGELOG.md     # 变更记录
├── legacy/          # 单体版 + GPU 变体（源系统，算法权威基线）
│   ├── intfacetest.py        # Flask 单体服务（CPU，端口 5001）
│   ├── intfacetest_gpu.py    # GPU 启动器（monkey-patch provider→CUDA，不改原文件）
│   ├── run_gpu_bench.py      # GPU 部署配置测试/基准
│   ├── profile_video.py      # 视频处理热循环分阶段计时剖析
│   ├── gen_synth_video.py    # 生成带多人脸的测试视频
│   ├── requirements*.txt     # CPU / GPU 依赖清单
│   ├── tech_readme.md        # 单体版环境与启动说明
│   ├── ENV_SETUP_GUIDE.md    # GPU 版环境创建说明
│   ├── DEPLOY_CONFIG_GUIDE.md# 部署配置调研（CUDA/onnxruntime-gpu 版本矩阵）
│   └── bench_assets/         # 基准测试素材（sample.jpg / synth_test.mp4）
└── decoupled/       # 解耦版（FastAPI 后端 + 原生前端，端口 8010，当前主力形态）
    ├── README.md    # 解耦版启动与复现唯一入口
    ├── docs/        # 01需求 / 02技术方案 / 03API设计 / 04部署 / 05模块映射
    ├── backend/     # FastAPI 应用（app/ 分层：api / core / services）
    └── frontend/    # 原生 HTML/CSS/JS（零构建）
```

> 虚拟环境 `.bench_venv/`、`.gpu_venv/` 位于根目录（gitignore 已排除），供 `legacy/` 的 GPU 工具使用。

## 快速导航

| 想做什么 | 看这里 |
|----------|--------|
| AI 助手理解项目 | `CLAUDE.md` |
| 启动解耦版（当前主力） | `decoupled/README.md`（`cd decoupled/backend && run.bat`） |
| 启动单体版 / GPU 版 | `legacy/tech_readme.md`、`legacy/ENV_SETUP_GUIDE.md` |
| 查看接口契约 | `decoupled/docs/03_API设计.md` |
| 单体 → 解耦版映射 | `decoupled/docs/05_模块映射.md` |

## 行为等价约束

`legacy/intfacetest.py`（单体）与 `decoupled/`（解耦版）的算法必须**行为等价**：检测、ByteTracker 三阶段匹配、余弦阈值（0.84/0.40/0.5/0.5）、MIN_FACE_HEIGHT=70、去重上限 15 全部一致。改动算法时两版需同步。