# ai-facerecognition

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

## Basic Information

- **Project Name**: ai-facerecognition
- **Description**: 入场，出场，人流建库，人脸识别MVP
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 团体访客人脸闭环核验系统

监狱货运区团体访客闭环核验系统：

入场多人检测 -> 无感采集 -> 建立临时访客库 -> 出场再次识别 -> 闭环核验 -> 人数统计 -> 异常报警

需求详见 `团体访客人脸闭环核验系统_PRD_MVP.md`。

## 当前技术路线

本项目当前确认的主方案是：

`YOLO + ByteTrack/DeepSORT + InsightFace + FAISS`

其中：

- `YOLO`：检测人员、做人流统计、区域判断
- `ByteTrack/DeepSORT`：持续跟踪同一人
- `InsightFace`：做人脸检测、特征提取、身份识别
- `FAISS`：做临时访客库向量检索

## 当前仓库状态

当前仓库里已经落地的是一个基线 POC，而不是完整主方案。

已实现版本为：

`InsightFace + embedding 相似度比对`

当前已具备：

- 入场视频建临时访客库
- 狱警白名单过滤
- 出场视频核验
- 未离场 / 陌生人员统计
- FAISS top-k 检索 + exact best-pair 精排
- 报表输出

当前尚未实现：

- YOLO 人体检测层
- ByteTrack / DeepSORT 跟踪层
- 真正基于多人 track 的闭环匹配

因此，当前代码的定位是：

`基线版本 / 对照 POC`

而后续目标版本是：

`YOLO + 跟踪 + InsightFace + FAISS`

## V2 复刻引擎（stream，2026-08-28 落地）

intfacetest.py（单文件 Flask 看板）的算法核心已复刻进 `facevideo/` 模块化架构，
作为 `--engine stream` 新引擎（与旧 batch 流程并存）：

```
uv run python -m facevideo.cli --engine stream --out output_stream
```

融合了 intfacetest 的 4 点核心策略：

1. **进出场非对称检测阈值**（进场 0.45 / 出场 0.40，见参数校准说明）
2. **多角度记忆库 ByteTracker**：阶段一 IoU+特征联合匈牙利匹配 → 阶段二低分/侧脸
   特征找回 → 阶段三新建；轨迹滚动保存 15 帧特征
3. **per-person 特征滚动追加**：人员特征窗口 15，重复命中只追加不新建
4. **人工闭环**：`facevideo/web_app.py` Flask 看板（逗留弹窗 → 工作人员确认 → 白名单）

关键实现：

- `facevideo/stream.py`：`StreamProcessor` 增量处理引擎 + `StreamParams` 参数集
- `facevideo/tracker.py`：新增 `ByteTracker`/`STrack`（intfacetest 移植，事件式日志）
- `facevideo/web_app.py` + `facevideo/web_index.html`：实时看板（SSE 流式视频处理、
  摄像头刷脸、6 大算法看板、逗留告警、白名单管理），启动 `uv run python -m facevideo.web_app`
- **跨机位聚合匹配**：出场匹配用 track 多角度记忆库 × 人员多帧 best-pair 聚合距离
  （PLAN §8：单帧 embedding 跨机位相似度中位数仅 0.28，必须聚合）

### stream 引擎参数校准说明（2026-08-28，测试视频真值 43 人）

intfacetest.py 原参数（buffalo_s + det_size 640 + 进场阈值 0.84）在测试视频
（`1-入场-角度1-人员完整.mp4` 竖屏 1080×1920 / `2-出场-人员完整.mov`）上实测
**0 建库**：det_size 640 检测率仅 ~10%，且本视频 det_score max=0.675 < 0.84。
校准后默认参数（CLI 默认值，无需显式传）：

```
--det-size 1280 --enter-det-thresh 0.45 --exit-det-thresh 0.40
--enter-threshold 0.50 --leave-threshold 0.60
--min-face-height 60 --min-face-height-exit 40
--min-track-obs 2 --sample-frac 0.2
```

实测结果：**入场建库 42/43（98%，真值 43）、出场匹配 42/42（100% 完整闭环）**；
出场匹配 = 流式实时匹配（0.60）+ 结束全局最优补齐（0.70，解决流式先到先得劣化）。
**视频方向自动校正**：`1-进场排队.mp4` 画面横躺，引擎自动检测并逆时针旋转 90° 后
处理，落盘快照正立（实测两眼角度 p50=2.5°，41/42 正立）。详见
`.claude/plans/v2-intfacetest-fusion.plan.md` §6.9。

stream 引擎输出（`output_stream/`）：`入场人员/` 快照、`manifest.json`、
`report.csv`、`summary.json`、`stream_stats.json`（参数+统计）、`stream_events.json`（事件日志）。

## 环境

```bash
uv venv .venv
uv pip install -r requirements.txt
```

## 配置（`.env`）

```
ENTRY_VIDEO=入场视频路径
EXIT_VIDEO=出场视频路径
GUARD_PHOTOS=狱警白名单照片文件夹（可选）
```

## 运行当前基线版本

```bash
# 读取 .env 的视频路径，输出到 output/
uv run python -m facevideo.cli --out output

# 显式指定视频与狱警白名单
uv run python -m facevideo.cli --entry 入场.mp4 --exit 出场.mp4 --photos 狱警照/ --out output
```

当前可用参数：

```bash
--flow candidates|library  # 闭环架构：candidates=入口候选池+出口身份确认(默认)，library=旧建库匹配
--camera level|overhead45  # 机位适配（默认 level；det-size/min-det 取 profile，见"机位切换"）
--retrieval faiss|brute    # 检索方式：faiss=top-k 召回后精排(默认)，brute=全量对照
--retrieval-topk 8         # FAISS owner shortlist 大小
--entry-tracker iou|bytetrack  # 旧 library 流程的追踪方式
--threshold 0.5    # 匹配相似度阈值
--merge 0.4        # 轨迹合并同人 embedding 阈值
--frame-step 2     # 每 N 帧处理 1 帧
--min-obs 2        # 轨迹最少观测帧
--min-det 0.5      # 检测置信度下限（默认取机位 profile）
--det-size 1280    # 检测输入短边（默认取机位 profile）
--model buffalo_s # insightface 模型
--ctx -1           # -1=CPU, 0=GPU
--qa               # 快照自动 QA（qa_snapshots.csv + qa_review.html）
```

## 机位切换（CameraProfile）⚠️ 换机位必读

**默认机位 = 水平视角（`level`，平视/平行拍摄，即当前测试视频）**，不是 45°。
`overhead45`（4m/45° 俯拍）仅为**预留配置项**，等拿到真实 45° 视频实测后再校准启用。

机位相关策略（朝相机信号 / 阈值 / 检测参数）已解耦到 `facevideo/camera.py` 的 `CameraProfile`。
不同摄像头**只需切换 `--camera`，无需改优化代码**：

```bash
# 水平视角（默认，当前测试视频）
uv run python -m facevideo.cli --out output

# 4m 高度 45° 俯拍（预留，待实测校准；stream 引擎下 det_size 自动取 1600）
uv run python -m facevideo.cli --camera overhead45 --out output
```

- `--det-size` / `--min-det` **默认取 profile**（`level`=1280/0.5，`overhead45`=1600/0.5），仍可用参数显式覆盖。
- profile 贯穿：`pose_quality`（选帧质量）→ 追踪 → 两段式选帧 → QA 阈值 → 出场匹配。
- stream 引擎（`--engine stream`）：默认水平适配；`--camera overhead45` 且未显式 `--det-size` 时检测尺寸取 1600。
- 新增机位：在 `facevideo/camera.py` 的 `PRESETS` 加一个 `CameraProfile` 实例即可。

## 当前输出（`output/`）

- `入场人员/<id>.jpg`：每位访客最佳人脸快照
- `faiss_roster_index.json` / `faiss_candidate_index.json`：阶段五索引元数据（走 `--retrieval faiss` 时输出）
- `出场截图/<id>/`：已匹配离场人员截图归档
- `出场截图/陌生人员/`：陌生人员截图归档
- `report.csv`：每人是否离场、时间、相似度、出现次数
- `summary.json`：总人数、已离场、未离场、陌生人员、狱警统计
- `manifest.json`：访客库清单

## 自检

```bash
uv run python -m facevideo.smoke_test
```

## 目录

- `facevideo/`：当前基线实现
  - `recognizer.py`
  - `roster.py`
  - `processor.py`
  - `cli.py`
  - `smoke_test.py`
- `assets/test/`：冒烟测试人脸照片
- `assets/photos/`：可放狱警白名单照片
- `技术方案台账.md`：技术选型与主方案说明
- `PLAN.md`：实施计划

## 备注

这个项目的核心难点不只是模型选型，还包括：

- 4 米高、45 度俯角机位
- 室外光照
- 无感通行
- 多人排队
- 人脸像素是否足够

所以后续验证必须同时关注：

- 模型效果
- 跟踪聚合效果
- 摄像机安装条件