家庭照片/视频人脸识别系统 — 本地运行，隐私安全，跨平台
基于 InsightFace + DBSCAN 的本地人脸识别系统，支持照片和视频的自动检测、聚类、命名和浏览。所有数据本地处理，无需云端 API。
| 仪表盘 | 照片画廊 | 人脸聚类 |
|---|---|---|
|
 |
 |
截图中的人脸区域已脱敏处理，实际使用时显示真实人脸缩略图。
- 文件扫描: 自动发现目录下的照片和视频文件，支持增量扫描和文件搬迁追踪
- 人脸检测: InsightFace (buffalo_l) 模型，GPU 加速 (CUDA/DirectML/CoreML/CPU)
- 视频处理: 自适应抽帧策略，同一视频中重复人脸自动去重
- 视频缩略图: 静态封面 + 鼠标悬停 Sprite 动画预览（每个视频仅 ~34KB）
- 人脸聚类: DBSCAN 算法自动将相似人脸归为同一人
- 命名管理: CLI 或 Web 界面为聚类命名，关联到具体人物
- Web 界面: 暗色主题 UI，画廊浏览、聚类管理、时间轴、多人搜索
- 实时进度: SSE 流式进度推送 + 手动取消长时间操作
- 跨平台: Windows / macOS / Linux，自动检测硬件选择最优推理后端
- 多目录支持: 本地目录 + UNC 网络路径，Web 端管理
- HEIC 支持: 全链路支持 HEIC/HEIF 格式（读取→检测→缩略图→Web预览）
- 导出功能: JSON 导出 + mklink 符号链接按人分类
| 平台 | 硬件条件 | 推理后端 | onnxruntime 包 |
|---|---|---|---|
| Windows / Linux | NVIDIA GPU | CUDA | onnxruntime-gpu |
| Windows | 任意 GPU (AMD/Intel/NVIDIA) | DirectML | onnxruntime-directml |
| macOS | Apple Silicon (M1/M2/M3/M4) | CoreML | onnxruntime-silicon |
| macOS | Intel CPU | CPU | onnxruntime |
| Linux | 无 GPU | CPU | onnxruntime |
硬件自动检测优先级: CUDA → DirectML → CoreML → CPU
- Python 3.10+
- GPU（可选）
自动安装（推荐）:
git clone https://github.com/YOUR_USERNAME/famface.git
cd famface
python install.py手动安装:
pip install -r requirements.txt
# 根据平台选择:
pip install -r requirements-cuda.txt # NVIDIA GPU
pip install -r requirements-directml.txt # Windows 任意 GPU
pip install -r requirements-silicon.txt # Apple Silicon
pip install -r requirements-cpu.txt # 纯 CPU首次运行前，设置媒体文件目录：
# 方式1: 环境变量
export MEDIA_DIR=/path/to/your/photos
# 方式2: Web 端添加（启动后在仪表盘页面操作）
# 方式3: CLI 添加
python main.py scan --root-dir /path/to/your/photos可选环境变量：
| 变量 | 说明 | 示例 |
|---|---|---|
MEDIA_DIR |
默认媒体目录 | /path/to/photos |
CUDA_PATH |
CUDA Toolkit 路径 | /usr/local/cuda |
CUDA_BIN_PATH |
CUDA bin 目录 | /usr/local/cuda/bin |
# 查看硬件检测
python main.py hw
# 扫描文件
python main.py scan
# 检测人脸
python main.py detect
# 聚类分析
python main.py cluster
# 启动 Web 界面
python main.py serve
# 查看所有命令
python main.py --help| 命令 | 说明 |
|---|---|
scan |
扫描媒体文件，--type image|video|all 过滤类型 |
detect |
检测人脸，--limit N 限制数量，--type 过滤类型 |
cluster |
聚类分析，--eps 0.45 --min-samples 3 调参 |
name |
命名聚类，--list-unnamed 列出待命名 |
export |
导出数据，--mklink 创建符号链接 |
stats |
显示统计信息 |
serve |
启动 Web UI，--host 0.0.0.0 --port 8765 |
hw |
显示硬件检测结果 |
ignore-dir |
管理忽略目录，--add --remove --list |
extract-dates |
从 EXIF 提取拍摄日期 |
regenerate-thumbs |
重新生成缩略图 |
启动 python main.py serve 后访问 http://localhost:8765
| 页面 | 功能 |
|---|---|
| 仪表盘 | 统计概览 + 快速操作 + 文件夹管理 |
| 照片画廊 | 分页浏览 + 文件夹筛选 + 类型筛选 + 视频悬停预览 |
| 聚类管理 | 查看/命名/修改/忽略聚类，就地操作无需刷新 |
| 时间轴 | 按月份查看文件分布 |
| 多人搜索 | 查找同时包含多人的照片 |
famface/
├── main.py # CLI 入口
├── config.py # 配置 + 跨平台硬件检测
├── database.py # SQLite 数据库操作
├── scanner.py # 文件扫描 + 指纹 + EXIF日期
├── detector.py # 人脸检测 + 视频抽帧 + HEIC支持 + 视频缩略图
├── clusterer.py # DBSCAN 聚类
├── progress.py # 进度报告 (CLI + SSE) + 取消机制
├── install.py # 跨平台自动安装脚本
├── requirements.txt # 基础依赖
├── requirements-cuda.txt # NVIDIA GPU
├── requirements-directml.txt # Windows 任意 GPU
├── requirements-silicon.txt # Apple Silicon
├── requirements-cpu.txt # 纯 CPU
├── docs/ # 截图（已脱敏）
├── tests/ # 测试套件
└── web/
├── app.py # FastAPI 后端
├── static/ # CSS + JS + Favicon
└── templates/ # HTML 模板
- 本地推理: InsightFace + ONNX Runtime，无需云端 API，隐私安全
- 跨平台硬件自检测: CUDA → DirectML → CoreML → CPU 自动回退
- 边扫描边写入: 每个文件立即写入 DB，批量 commit 减少 IO 瓶颈
- 增量检测: "detecting" 状态 + 断点续跑，中断后不丢失进度
- 视频 Sprite 预览: 8帧拼成竖条图 + CSS 动画，每个视频仅 ~34KB
- HEIC 全链路: pillow-heif 读取 → 检测 → 缩略图 → Web 自动转 JPEG
- SSE 实时进度: 流式推送 + 手动取消，长时间操作可感知可控制
- 所有数据（人脸嵌入、缩略图、数据库）仅存储在本地
data/目录 data/目录已加入.gitignore，不会被提交到 Git- 截图中的人脸区域已脱敏处理
- Web 界面默认绑定
localhost，仅本机可访问