人脸识别相似度比对 Skill
工作流程概览
输入: 图片A + 图片B
↓
① 人脸检测 (YuNet 或 Haar Cascade)
↓
② 人脸区域裁剪 + 对齐
↓
③ 特征提取 (SFace ONNX 或 HOG+Patch)
↓
④ 余弦相似度计算
↓
输出: 相似度分数 (0~1) + 判断结论
第一步：确认图片输入
用户上传的图片位于 /mnt/user-data/uploads/ 下，使用 view 工具列出可用文件：
ls /mnt/user-data/uploads/
将两张图片路径记为 IMAGE_A 和 IMAGE_B。
第二步：选择算法方案
根据环境自动选择最优方案：
| 方案 | 检测器 | 特征提取器 | 精度 | 条件 |
|---|---|---|---|---|
| 方案A（推荐） | YuNet ONNX | SFace ONNX | ★★★★★ | 需要 .onnx 模型文件 |
| 方案B（通用） | Haar Cascade | HOG + Patch Histogram | ★★★☆☆ | 仅需 OpenCV 内置 |
如何判断用哪个方案：运行脚本时自动检测，优先使用方案A，若模型文件不存在则自动降级为方案B。
方案A 模型下载（可选，推荐）：
https://github.com/opencv/opencv_zoo/raw/main/models/face_detection_yunet/face_detection_yunet_2023mar.onnx
https://github.com/opencv/opencv_zoo/raw/main/models/face_recognition_sface/face_recognition_sface_2021dec.onnx
将两个 .onnx 文件放在工作目录或 /tmp/ 下。
第三步：执行识别脚本
使用以下脚本（也可直接调用 scripts/face_compare.py）：
python3 /home/claude/face-recognition/scripts/face_compare.py \
--img1 IMAGE_A \
--img2 IMAGE_B \
--output /tmp/face_result.jpg
脚本会自动：
- 检测两张图片中的人脸区域
- 裁剪并标注人脸框
- 提取人脸特征向量
- 计算余弦相似度
- 输出带标注的对比图 + 相似度分数
第四步：解读结果并向用户汇报
相似度分数判读表
| 相似度分数 | 判断结论 |
|---|---|
| 0.90 ~ 1.00 | ✅ 极高概率为同一人（强烈匹配） |
| 0.75 ~ 0.90 | ✅ 很可能为同一人（高置信度） |
| 0.60 ~ 0.75 | ⚠️ 可能为同一人（中等置信度，建议人工核验） |
| 0.40 ~ 0.60 | ❓ 不确定（低置信度） |
| 0.00 ~ 0.40 | ❌ 很可能不是同一人 |
注意：以上阈值基于方案B（HOG特征）。若使用方案A（SFace），推荐阈值为 >0.593（余弦距离）。
向用户展示的格式示例
📊 人脸识别结果
━━━━━━━━━━━━━━━━━━━━
图片A：检测到 1 张人脸 ✓
图片B：检测到 1 张人脸 ✓
相似度分数：0.847
判断结论：✅ 很可能为同一人（高置信度）
使用算法：SFace (OpenCV FaceRecognizerSF)
━━━━━━━━━━━━━━━━━━━━
异常处理
| 问题 | 原因 | 处理方式 |
|---|---|---|
| 未检测到人脸 | 图片质量差/无正脸 | 告知用户并建议换图 |
| 检测到多张人脸 | 图中有多人 | 取最大人脸（面积最大）处理，提示用户 |
| 图片无法读取 | 格式不支持 | 提示支持 JPG/PNG/BMP/WEBP |
| 相似度结果异常 | 光线/角度差异大 | 在结果中加注"受光照/角度影响，结果仅供参考" |
详细实现参考
→ 查看 scripts/face_compare.py 获取完整可执行代码
→ 查看 references/algorithm_notes.md 了解算法原理说明