12 KiB

Raw Blame History

人脸识别管理系统使用指南

🎯 系统简介

这是一个完整的人脸识别管理系统,支持:

✅ Web后台注册: 通过Web管理后台注册用户
✅ 后端存储: SQLite数据库集中存储用户特征
✅ Android识别: Android设备直接调用后端识别API
✅ 统一管理: 所有设备共享同一个用户库

📦 系统架构

┌─────────────────────────┐
│   Web管理后台           │
│   http://IP:8000/admin  │
│   - 注册用户            │
│   - 查看用户列表        │
│   - 删除用户            │
│   - 查看统计            │
└───────────┬─────────────┘
            │
            ↓
┌─────────────────────────┐
│   FastAPI后端服务       │
│   - 用户管理API         │
│   - 人脸识别API         │
│   - SQLite数据库        │
│   - 特征提取引擎        │
└───────────┬─────────────┘
            │
            ↓
    ┌───────┴────────┐
    ↓                ↓
┌─────────┐    ┌─────────┐
│Android1 │    │Android2 │
│ 识别    │    │ 识别    │
└─────────┘    └─────────┘

🚀 快速开始

步骤1: 安装后端依赖

cd E:\face\FaceFeatureExtractorAPI
pip install -r requirements.txt

步骤2: 启动后端服务

python app.py

预期输出:

🚀 启动服务: http://0.0.0.0:8000
📚 API文档: http://0.0.0.0:8000/docs
🎛️ 管理后台: http://0.0.0.0:8000/admin
INFO:     Uvicorn running on http://0.0.0.0:8000
✅ 数据库初始化完成

步骤3: 打开Web管理后台

在浏览器中访问: http://192.168.0.148:8000/admin

你会看到一个美观的管理界面:

统计面板(用户数、识别次数等)
用户注册表单
用户列表

步骤4: 注册用户

在Web管理后台:

输入姓名(必填)
输入年龄(可选)
上传人脸照片
点击"注册用户"

提示:

照片必须包含清晰的人脸
支持jpg/png格式
建议正面照,光线充足

步骤5: Android端识别

Android应用无需修改,保持原有功能:

活体检测在本地完成
识别时调用后端 /api/recognize 接口
后端在数据库中查找匹配用户
返回识别结果

🔧 API接口文档

1. 用户注册

POST /api/users/register

请求(multipart/form-data):

name: 张三 (必填)
age: 25 (可选)
image: [人脸照片文件] (必填)

响应:

{
  "success": true,
  "message": "用户 '张三' 注册成功",
  "user_id": 1,
  "user": {
    "id": 1,
    "name": "张三",
    "age": 25,
    "feature_dim": 1024,
    "photo_filename": "张三_20251020_143022.jpg",
    "created_at": "2025-10-20T14:30:22",
    "is_active": true
  }
}

2. 获取用户列表

GET /api/users/list?skip=0&limit=100&active_only=true

响应:

{
  "success": true,
  "message": "查询成功",
  "total": 10,
  "users": [
    {
      "id": 1,
      "name": "张三",
      "age": 25,
      "feature_dim": 1024,
      "photo_filename": "张三_20251020_143022.jpg",
      "created_at": "2025-10-20T14:30:22",
      "is_active": true
    }
  ]
}

3. 人脸识别 (核心接口)

POST /api/recognize

请求(multipart/form-data):

image: [待识别的人脸照片] (必填)
device_id: android_001 (可选)
threshold: 0.7 (可选,默认0.7)

响应(识别成功):

{
  "success": true,
  "message": "识别成功: 张三",
  "recognized": true,
  "user_id": 1,
  "user_name": "张三",
  "similarity": 0.8543,
  "threshold": 0.7,
  "processing_time": 0.52
}

响应(未识别):

{
  "success": true,
  "message": "未识别到注册用户 (最高相似度: 0.62)",
  "recognized": false,
  "similarity": 0.62,
  "threshold": 0.7,
  "processing_time": 0.48
}

4. 同步用户数据

GET /api/users/sync

返回所有用户的完整数据(包含特征向量),供Android端下载到本地

响应:

{
  "success": true,
  "message": "同步成功",
  "total": 10,
  "users": [
    {
      "id": 1,
      "name": "张三",
      "age": 25,
      "feature_dim": 1024,
      "feature": [0.123, 0.456, ..., 0.789],  // 1024维特征向量
      "photo_filename": "张三_20251020_143022.jpg",
      "created_at": "2025-10-20T14:30:22",
      "is_active": true
    }
  ]
}

5. 删除用户

DELETE /api/users/{user_id}

响应:

{
  "success": true,
  "message": "用户 '张三' 已删除"
}

注意:这是软删除,用户数据仍保留在数据库中,但is_active设置为false

6. 统计信息

GET /api/stats

响应:

{
  "success": true,
  "stats": {
    "total_users": 10,
    "total_recognitions": 100,
    "successful_recognitions": 85,
    "recognition_rate": 85.0
  }
}

📱 Android端修改(可选)

目前Android端已经兼容后端识别,无需修改。如果需要从Android端注册用户到后端,可以添加以下功能:

选项1: 保持当前模式(推荐)

Web后台注册 → 后端数据库
Android识别 → 调用后端 /api/recognize

选项2: Android也支持注册到后端

修改RegisterActivity.java,在注册成功后调用后端注册API:

// 在extractAndRegister方法的onSuccess中添加
NetworkManager.getInstance().registerUserToBackend(
    bitmap,
    name,
    1,  // age
    new NetworkManager.ApiCallback<>() {
        @Override
        public void onSuccess(RegisterResponse result) {
            Toast.makeText(RegisterActivity.this,
                "用户已同步到后端", Toast.LENGTH_SHORT).show();
        }

        @Override
        public void onFailure(String error) {
            Log.w(TAG, "后端同步失败: " + error);
        }
    }
);

🗂️ 数据库结构

users表

CREATE TABLE users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name VARCHAR(100) NOT NULL UNIQUE,  -- 姓名
    age INTEGER,                         -- 年龄
    feature_vector BLOB NOT NULL,        -- 1024维特征(二进制)
    feature_dim INTEGER DEFAULT 1024,    -- 特征维度
    photo_filename VARCHAR(255),         -- 照片文件名
    created_at TIMESTAMP,                -- 创建时间
    updated_at TIMESTAMP,                -- 更新时间
    is_active BOOLEAN DEFAULT TRUE       -- 是否激活
);

recognition_logs表

CREATE TABLE recognition_logs (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id INTEGER,                  -- 识别到的用户ID
    user_name VARCHAR(100),           -- 识别到的用户姓名
    device_id VARCHAR(100),           -- 设备ID
    similarity FLOAT,                 -- 相似度
    threshold FLOAT DEFAULT 0.7,      -- 阈值
    is_recognized BOOLEAN DEFAULT FALSE,  -- 是否识别成功
    recognized_at TIMESTAMP,          -- 识别时间
    photo_filename VARCHAR(255)       -- 识别时的照片
);

📂 目录结构

FaceFeatureExtractorAPI/
├── app.py                          # 主应用(V2.0)
├── database.py                     # 数据库模型
├── face_feature_extractor.py      # 特征提取器
├── admin.html                      # Web管理后台
├── requirements.txt                # Python依赖
├── face_recognition.db             # SQLite数据库(自动生成)
└── uploads/                        # 上传文件目录(自动生成)
    ├── photos/                     # 用户照片
    └── logs/                       # 识别记录照片

🧪 测试流程

1. 测试后端健康检查

curl http://192.168.0.148:8000/health

预期:

{
  "status": "healthy",
  "extractor_loaded": true,
  "database_connected": true,
  "total_users": 0
}

2. 测试Web注册

打开 http://192.168.0.148:8000/admin
填写姓名"测试用户"
上传一张人脸照片
点击"注册用户"
查看用户列表是否显示新用户

3. 测试API注册(使用Postman或curl)

curl -X POST http://192.168.0.148:8000/api/users/register \
  -F "name=测试用户" \
  -F "age=25" \
  -F "image=@/path/to/face.jpg"

4. 测试识别API

curl -X POST http://192.168.0.148:8000/api/recognize \
  -F "image=@/path/to/face.jpg" \
  -F "device_id=test_device" \
  -F "threshold=0.7"

5. 测试Android端

确保Android设备和电脑在同一WiFi
打开Android应用
点击"人脸识别"
对准摄像头
活体检测通过后自动识别
查看是否显示注册的用户姓名

⚙️ 配置选项

修改识别阈值

在 app.py 中搜索 threshold,修改默认值:

threshold: float = Form(0.7, description="识别阈值"),

或者在调用 /api/recognize 时传递自定义阈值:

threshold=0.75

修改数据库路径

在 database.py 中修改:

DATABASE_URL = "sqlite:///./face_recognition.db"

修改照片存储路径

在 app.py 中修改:

UPLOAD_DIR = Path("uploads")
PHOTOS_DIR = UPLOAD_DIR / "photos"

🔒 生产环境建议

使用HTTPS: 配置SSL证书,保护数据传输
使用PostgreSQL: 替换SQLite,提高并发性能
添加身份验证: API添加Token验证
数据备份: 定期备份数据库和照片
日志监控: 记录所有API请求和识别记录
限流保护: 防止恶意请求

🐛 故障排除

问题1: 数据库初始化失败

现象: 启动时报错 ImportError: cannot import name 'User' from 'database'

解决:

# 确保database.py存在且无语法错误
python -c "from database import User, init_database; init_database()"

问题2: 识别总是失败

检查:

后端是否有注册用户: 访问 /api/users/list
识别阈值是否过高: 尝试降低到 0.6
照片质量是否合格: 确保光线充足,人脸清晰

问题3: Android无法连接后端

检查:

电脑防火墙是否开放8000端口
Android和电脑是否在同一WiFi
IP地址是否正确配置
Web API是否正在运行

📊 性能优化

数据库优化

-- 为常用查询添加索引
CREATE INDEX idx_users_name ON users(name);
CREATE INDEX idx_users_active ON users(is_active);
CREATE INDEX idx_logs_recognized_at ON recognition_logs(recognized_at);

特征向量缓存

# 在app.py中添加缓存(可选)
from functools import lru_cache

@lru_cache(maxsize=100)
def get_user_features_cached(user_id):
    # 缓存用户特征向量
    pass

📝 更新日志

V2.0.0 (2025-10-20)

✅ 添加SQLite数据库支持
✅ 实现用户注册API
✅ 实现后端识别API
✅ 创建Web管理后台
✅ 添加识别日志记录
✅ 支持统计功能
✅ 支持用户同步

V1.0.0

✅ 基础特征提取API
✅ 特征对比API
✅ 无状态服务

🆘 获取帮助

如果遇到问题:

查看后端日志: 终端输出
查看API文档: http://192.168.0.148:8000/docs
检查数据库: 使用SQLite浏览器打开 face_recognition.db
查看识别记录: 查询 recognition_logs 表

🎉 快速测试命令

# 1. 安装依赖
cd E:\face\FaceFeatureExtractorAPI
pip install -r requirements.txt

# 2. 启动服务
python app.py

# 3. 在浏览器打开管理后台
start http://192.168.0.148:8000/admin

# 4. 测试健康检查
curl http://192.168.0.148:8000/health

# 5. 查看用户列表
curl http://192.168.0.148:8000/api/users/list

# 6. 查看统计
curl http://192.168.0.148:8000/api/stats

现在可以开始使用了! 🚀

12 KiB Raw Blame History