跳到正文

故障排查

修复 SnapByFace 的启动与性能问题：模型文件缺失、FAISS 缺失时的 NumPy 回退、macOS Gatekeeper、Windows SmartScreen，以及索引变慢。

先看日志文件 —— 大多数问题在里面就能看到：

# macOS
open ~/.snapbyface/logs/snapbyface.log

# Windows（PowerShell）
notepad "$env:USERPROFILE\.snapbyface\logs\snapbyface.log"

开始扫描时报「模型文件缺失」

现象：应用能打开，但一启动分析就报模型路径错误。

  1. 安装不完整。 安装包约 300 MB，因为 det_10g.onnx 与 w600k_r50.onnx 就打包在里面。请重新下载并安装。
  2. 运行位置不对（macOS）。 把应用拖到「应用程序」里，不要直接从 .dmg 里运行。
  3. 杀毒软件隔离。 有些终端防护工具会把应用目录里的大文件直接删掉 —— 加白名单后重装。

::::note SnapByFace 在运行时从不下载模型。模型缺失时的解决办法永远是重装安装包。 ::::

匹配很慢：FAISS 回落到了 NumPy

SnapByFace 用 FAISS 做特征检索。如果这个构建版本里没有 FAISS，它会回退到 NumPy 暴力检索。

  • 结果完全一致。 差别只在速度，不在质量。
  • 索引到几万张人脸时差别最明显。
  • 重装当前版本即可恢复 FAISS。

::::tip 暂时没法重装的话，就减少工作量：一次只索引一个目录，或者调阈值 —— 改阈值只重新匹配已有特征，永远不重新分析素材。参见 阈值调优。 ::::

macOS：「SnapByFace 已损坏，无法打开」

这是 Gatekeeper 拦的，不是下载坏了。SnapByFace 是一个人做的，还没有做 Apple 公证 —— 公证需要价格不低的开发者证书。可以先核对下载页上的 SHA-256 校验值确认文件是原版，然后清除隔离属性：

xattr -cr /Applications/SnapByFace.app
  1. 如果仍然打不开，确认应用放在 /Applications 里，且下载的是与你芯片匹配的版本。

Windows：SmartScreen「Windows 已保护你的电脑」

  1. 在对话框里选择「更多信息」。
  2. 选择「仍要运行」。SnapByFace 是一个人做的，还没有已验证的发布者证书 —— 这就是 SmartScreen 标记它的原因。可以核对下载页上的 SHA-256 校验值确认文件是原版。
  3. 如果公司策略禁止，请让 IT 放行该发布者。

性能：索引太慢

按顺序排查：

  1. 检查视频抽帧间隔。 默认 1 秒；面对数小时素材，先用 2–5 秒跑第一遍更合理。
  2. 改阈值而不是重建索引。 阈值改动只重新匹配已有特征，不会重新分析素材。
  3. 把素材挪到本地固态硬盘。 网络共享与 USB 硬盘通常才是真正的瓶颈。
  4. 让它在后台跑，需要时用暂停/继续；进度会保留。
  5. 索引过程中避免复制或编辑素材 —— 变化的文件会被重新排队。
  6. 关掉其他吃 CPU 的应用，把算力留给 SnapByFace。

崩溃或重启后有未完成的任务

启动时 SnapByFace 会询问是否继续未完成的任务。继续会从上次保存的进度往下做；不继续也会保留已经索引好的文件。

如果同一个文件每次都失败，从日志里取出它的路径，用别的播放器试着打开 —— 文件损坏或编码特殊会反复失败，把这个目录排除掉比反复重试更快。

结果看起来不对

  • 错误人脸太多： 调高阈值。参见 阈值调优。
  • 漏掉太多： 调低阈值，然后确认那些人脸真的能被检出（尺寸、光线、模糊）。
  • 某个人从不匹配： 换一张正面、单人、光线均匀的参照照片。
  • 视频命中的边界模糊： 正常 —— 区间由抽帧结果拼出，精度大约在一个抽帧间隔左右。

重置应用状态

万不得已时，关掉 SnapByFace 并删除它的工作目录：

# macOS
rm -rf ~/.snapbyface

# Windows（PowerShell）
Remove-Item -Recurse -Force "$env:USERPROFILE\.snapbyface"

::::caution 这会删除索引、你的设置与激活状态。你的原始照片和视频不受影响。之后你需要重新添加素材目录、重新跑分析，并重新输入授权码。 ::::

下一步