AG Face Attendance Machine

人脸识别考勤机 Demo：

摄像头采集
  -> OpenCV 本地检测人脸
  -> 百度智能云人脸库注册 / 1:N 搜索
  -> SQLite 本地保存考勤记录
  -> DeepSeek 生成考勤分析总结

说明：本项目核心流程 “OpenCV + 百度智能云人脸识别 + DeepSeek 分析”。

功能

• OpenCV 摄像头采集
• OpenCV Haar Cascade 本地人脸检测
• 百度智能云人脸库：创建用户组、注册人脸、列出用户
• 百度智能云人脸 1:N 搜索打卡
• SQLite 本地考勤记录
• CSV 导出
• DeepSeek 自动生成考勤分析报告
• 中文 Tkinter 图形界面
• .env 本地保存密钥，默认不会提交到 GitHub

隐私与密钥

不要提交密钥、数据库、人脸抓拍图。

.gitignore 已忽略：

• .env
• data/*.db
• data/captures/
• data/exports/
• data/reports/
• data/cache/

仓库只提交 .env.example。

安装

cd "D:\AG-face-attendance-machine"
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip setuptools wheel
pip install -e .

也可以双击：

install_env.bat

配置 .env

复制模板：

Copy-Item .env.example .env
notepad .env

填写：

BAIDU_API_KEY=你的百度人脸识别应用API Key
BAIDU_SECRET_KEY=你的百度人脸识别应用Secret Key
BAIDU_GROUP_ID=attendance
BAIDU_MATCH_THRESHOLD=80

DEEPSEEK_API_KEY=你的DeepSeek API Key
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-chat

百度智能云具体怎么开

一定要创建“人脸识别”应用，不要用 OCR 应用，也不要用离线 SDK 页面。

百度官方流程大致是：

1. 进入百度 AI 开放平台 / 百度智能云控制台。
2. 进入 人脸识别 产品。
3. 打开 应用列表，创建应用。
4. 在应用权限里确认包含这些接口：
   • face/v3/detect：人脸检测
   • face/v3/faceset/group/add：创建用户组
   • face/v3/faceset/user/add：人脸注册
   • face/v3/search：人脸 1:N 搜索
5. 创建成功后复制这个“人脸识别应用”的 API Key 和 Secret Key 到 .env。

如果你的 access_token 的 scope 里大量是 ocr，基本说明拿到的是 OCR 应用权限，不是本项目需要的人脸库权限。

如果控制台明确提示某接口需要企业认证，那需要按百度要求完成认证；代码和 SDK 不能绕过接口权限。

图形界面

启动中文 GUI：

ag-attendance gui

或双击：

run_gui.bat

GUI 推荐顺序：

1. 点 环境诊断
2. 点 百度检查
3. 点 初始化数据库
4. 点 检测摄像头
5. 点 创建人脸组
6. 填 用户ID 和 姓名
7. 点 摄像头注册，出现绿色框后按 Space
8. 点 识别打卡
9. 点 查看记录 / 导出CSV / DeepSeek分析

命令行用法

诊断环境

ag-attendance diagnose

初始化数据库

ag-attendance init-db

检测摄像头

ag-attendance camera-check --max 5

检查百度配置

只检查 token：

ag-attendance baidu-check

同时探测人脸库接口权限：

ag-attendance baidu-check --probe-face-api

打印 token scope，排查是否拿错 OCR 应用：

ag-attendance baidu-check --show-scope

创建百度人脸组

使用 .env 里的 BAIDU_GROUP_ID：

ag-attendance baidu-init-group

查看人脸组：

ag-attendance baidu-groups

查看某个人脸组里的用户：

ag-attendance baidu-users

摄像头注册人脸

ag-attendance register-camera --user-id AG --name AG --camera 0

弹出 OpenCV 预览窗口后：

1. 正对摄像头。
2. 等绿色人脸框出现。
3. 按 Space 注册。
4. 按 q 或 Esc 取消。

照片注册人脸

ag-attendance register-image --user-id AG --name AG --image "D:\photos\ag.jpg"

识别打卡

ag-attendance punch --camera 0 --threshold 80

绿色结果表示打卡成功；红色结果表示陌生人或分数低于阈值。

查看记录

ag-attendance records
ag-attendance records --date 2026-07-07

导出 CSV

ag-attendance records --date 2026-07-07 --export data\exports\records_2026-07-07.csv

DeepSeek 分析

ag-attendance analyze --date 2026-07-07

报告默认保存到：

data\reports\

百度接口对应关系

本项目调用的百度 REST API：

• 获取 Token：/oauth/2.0/token
• 创建人脸组：/rest/2.0/face/v3/faceset/group/add
• 注册人脸：/rest/2.0/face/v3/faceset/user/add
• 人脸搜索：/rest/2.0/face/v3/search

BAIDU_GROUP_ID=attendance 表示百度人脸库里的用户组名。

register-camera / register-image 会把人脸注册到这个组里；punch 会在这个组里做 1:N 搜索。

常见问题

error_code 6: No permission to access data

含义：密钥能获取 token，但当前百度应用没有目标接口权限。

处理：

1. 确认用的是“人脸识别”应用，不是 OCR 应用。
2. 在应用详情里确认开通：
   • faceset/group/add
   • faceset/user/add
   • search
3. 如果控制台提示企业认证，先完成认证或换有权限的账号/应用。
4. 更新本地 .env 后重新运行：

ag-attendance baidu-check --probe-face-api
ag-attendance baidu-init-group

Registration cancelled

注册不是自动完成。打开预览窗口后，必须等绿色框出现再按 Space。

No face detected

改善光线、正对摄像头、离摄像头近一点，或者换成 register-camera 的交互预览模式。

项目结构

D:\AG-face-attendance-machine
|-- src/ag_attendance/
|   |-- baidu_face.py      # 百度人脸 API 客户端
|   |-- attendance.py      # 注册与打卡流程
|   |-- database.py        # SQLite 记录
|   |-- deepseek.py        # DeepSeek 分析
|   |-- detector.py        # OpenCV 人脸检测
|   |-- gui.py             # 中文 GUI
|   `-- cli.py             # 命令行入口
|-- data/                  # 本地运行数据，基本被 git 忽略
|-- .env.example
|-- requirements.txt
|-- pyproject.toml
`-- README.md

参考

• 百度人脸库管理系列接口
• 百度 Access Token 获取
• 百度创建应用说明
• 百度人脸 1:N 搜索
• DeepSeek API 文档
• OpenCV 文档

License

MIT