• 安装相关
• 运行问题
• 功能使用
• 性能优化
• 错误处理
• 其他问题

问题描述：运行 install.cmd 时出现依赖安装失败。

解决方案：

1. 检查网络连接
2. 使用国内镜像源：

   pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 检查Python版本是否符合要求（3.7+）

问题描述：首次运行时模型文件自动下载失败。

解决方案：

1. 手动下载模型文件（参考 models/README.md）
2. 检查网络连接和代理设置
3. 确保有足够的磁盘空间（约需2GB）

问题描述：提示CUDA相关错误或无法使用GPU加速。

解决方案：

1. 安装正确版本的NVIDIA驱动
2. 安装对应版本的CUDA Toolkit
3. 确认是否安装cuDNN
4. 检查环境变量配置

问题描述：运行 face.py 时报错或无响应。

解决方案：

1. 检查Python环境：

   python --version
   pip list

2. 确认所有依赖已正确安装
3. 检查是否有权限问题
4. 查看错误日志

问题描述：界面元素显示不完整或布局混乱。

解决方案：

1. 检查显示器分辨率设置
2. 更新图形驱动
3. 确认tkinter正确安装：

   # Linux
   sudo apt-get install python3-tk

问题描述：人脸检测失败或准确率低。

解决方案：

1. 确保图片质量良好
2. 尝试不同的检测算法：

   # 示例：切换到RetinaFace
   detector = 'retinaface'

3. 调整检测参数

问题描述：人脸识别结果不准确或置信度低。

解决方案：

1. 增加训练样本数量
2. 使用更好质量的照片
3. 尝试不同的识别模型
4. 调整相似度阈值

问题描述：处理大量图片时速度很慢。

解决方案：

1. 启用GPU加速
2. 使用批处理模式
3. 减小图片分辨率
4. 优化代码配置

最佳实践：

1. 使用GPU加速：

   # 设置GPU使用
   import os
   os.environ['CUDA_VISIBLE_DEVICES'] = '0'

2. 启用批处理
3. 优化图像尺寸
4. 使用缓存机制

优化建议：

1. 及时释放不用的资源
2. 使用生成器处理大数据
3. 控制批处理大小
4. 定期清理缓存

错误代码	描述	解决方案
E001	模型加载失败	检查模型文件完整性
E002	图像格式错误	确认支持的图像格式
E003	内存不足	减少批处理大小
E004	GPU错误	检查CUDA配置

查看日志：

1. 检查 debug.log 文件
2. 使用日志查看器
3. 开启详细日志：

   import logging
   logging.basicConfig(level=logging.DEBUG)

备份建议：

1. 定期备份人脸数据库
2. 导出识别结果
3. 保存配置文件
4. 使用版本控制

更新步骤：

1. 拉取最新代码
2. 更新依赖包
3. 备份原有数据
4. 迁移配置文件

---