Face Family Classifier

基于人脸识别的本地家庭照片分类与展示工具。它会扫描本机照片目录，提取人脸特征，把可能属于同一家庭或同一组人物关系的照片聚合，并通过 Flask 网页界面展示结果。

适合个人照片整理、活动照片归组、家庭相册初步分类。所有照片和特征缓存默认保存在本机。

功能

• 本地扫描 photos/ 目录中的照片。
• 使用 InsightFace 提取人脸特征。
• 使用 DBSCAN 聚类同一人物，并按共同出现关系聚合家庭。
• 自动增量处理新增照片和已删除照片。
• Web 页面展示家庭分组、成员照片和好评照片。
• 管理页可设置照片目录、好评照片目录和局域网展示用 WiFi 信息。

项目结构

.
├── main.py                    # 主入口：扫描线程 + Web 服务
├── web_app.py                 # Flask 应用和 API
├── family_classifier_core.py  # 增量分类核心逻辑
├── face_family_classifier.py  # 人脸分析与批处理工具
├── admin_config.py            # 本地管理配置读写
├── templates/                 # Web 页面模板
├── admin_config.example.json  # 示例配置，不包含真实隐私信息
├── requirements.txt           # Python 依赖
└── test_admin_config.py       # 轻量配置测试

运行时会生成或使用以下本地目录，这些目录已加入 .gitignore：

• photos/：待处理照片。
• output/：分类结果、缓存和导出文件。
• favorite_photos/：好评照片。
• admin_config.json：本机管理配置。

快速开始

建议使用 Python 3.10 或更高版本。

python -m venv .venv
.\.venv\Scripts\activate
pip install -r requirements.txt
python main.py

启动后打开：

http://127.0.0.1:5000

默认只监听本机 127.0.0.1。如需局域网设备访问，可显式指定：

python main.py --web-host 0.0.0.0

仅建议在可信局域网中这样做，因为管理页会访问本机目录配置和 WiFi 展示信息。

常用参数

python main.py --photos-dir photos --output-dir output
python main.py --provider cpu
python main.py --provider cuda
python main.py --provider directml
python main.py --eps 0.4
python main.py --scan-interval 3
python main.py --web-port 8080

参数说明：

• --photos-dir：照片输入目录，默认 photos。
• --output-dir：分类结果目录，默认 output。
• --provider：推理后端，可选 auto、cpu、directml、rocm、cuda。
• --eps：人脸聚类阈值，数值越小越严格。
• --scan-interval：扫描间隔秒数。
• --web-host / --web-port：Web 服务监听地址和端口。

配置

复制示例配置后按需修改：

copy admin_config.example.json admin_config.json

请不要把 admin_config.json 提交到公开仓库。它可能包含本机路径、WiFi 名称或 WiFi 密码。

隐私与安全

• 照片、人脸特征和分类结果默认只保存在本机。
• 应用本身不主动上传照片或特征向量。
• 首次使用时，相关依赖可能会下载 InsightFace/ONNX 模型。
• 默认 Web 服务只监听 127.0.0.1。
• 公开 issue、截图或日志前，请移除真实照片、WiFi 信息、个人路径和局域网地址。

更多说明见 PRIVACY.md 和 SECURITY.md。

开发检查

python -m py_compile admin_config.py check_env.py face_family_classifier.py family_classifier_core.py main.py web_app.py
python test_admin_config.py

许可证

MIT License. See LICENSE.