# facereg-python

**Repository Path**: warom-org/facereg-python

## Basic Information

- **Project Name**: facereg-python
- **Description**: 人脸识别算法服务
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-05
- **Last Updated**: 2026-05-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 人脸识别API服务

基于 Python + FastAPI + insightface + FAISS 的高性能人脸识别后台服务

## 功能特性

- ✅ 人脸添加（注册）
- ✅ 人脸比对（1:1相似度比对）
- ✅ 人脸识别（1:N人脸库搜索）
- ✅ 人脸检测（检测位置和关键点）
- ✅ 人脸删除和管理
- ✅ 高性能向量检索（FAISS）
- ✅ RESTful API接口
- ✅ 自动API文档（Swagger）

## 技术栈

| 技术 | 说明 |
|------|------|
| FastAPI | 高性能Web框架 |
| insightface | SOTA人脸识别算法 |
| FAISS | 高效向量检索 |
| MySQL | 数据库 |
| SQLAlchemy | ORM框架 |
| OpenCV | 图像处理 |

## 项目结构

```
facereg-python/
├── api/                    # API层
├── services/              # Service层
├── repositories/          # Repository层
├── database/              # 数据库
├── models/                # 业务模型
├── schemas/               # API Schema
├── utils/                 # 工具类
├── config/                # 配置
├── scripts/               # 脚本
├── main.py               # 应用入口
└── requirements.txt      # 依赖
```

## 快速开始

### 1. 环境要求

- Python 3.8+
- MySQL 8.0+

### 2. 安装依赖

```bash
pip install -r requirements.txt
```

### 3. 配置环境

复制示例配置文件并修改：

```bash
cp env_example.py env_local.py
```

编辑 `env_local.py`，配置数据库等信息：

```python
# 数据库配置
DB_HOST = "localhost"
DB_PORT = 3306
DB_USER = "root"
DB_PASSWORD = "your_password"  # 修改为你的密码
DB_NAME = "facereg_db"
```

### 4. 初始化数据库

```bash
python scripts/init_db.py
```

### 5. 启动服务

```bash
python main.py
```

服务将在 `http://localhost:8000` 启动

### 6. 访问API文档

打开浏览器访问：`http://localhost:8000/docs`

## API接口说明

### 1. 人脸添加

```http
POST /api/v1/face/add
Content-Type: application/json

{
  "personId": "person_001",
  "personName": "张三",
  "image": "base64_encoded_image"
}
```

### 2. 人脸比对

```http
POST /api/v1/face/compare
Content-Type: application/json

{
  "imageA": "base64_encoded_image_a",
  "imageB": "base64_encoded_image_b"
}
```

### 3. 人脸识别

```http
POST /api/v1/face/search
Content-Type: application/json

{
  "image": "base64_encoded_image",
  "topK": 5,
  "threshold": 0.7
}
```

### 4. 人脸检测

```http
POST /api/v1/face/detect
Content-Type: application/json

{
  "image": "base64_encoded_image"
}
```

## 性能指标

- 单次识别速度: < 500ms
- 支持人脸库规模: 10万+
- 识别准确率: > 95%

## 部署

### Docker部署（推荐）

```bash
# 构建镜像
docker build -t facereg-api .

# 运行容器
docker run -d -p 8000:8000 --name facereg facereg-api
```

### 生产环境

使用 Gunicorn + Uvicorn 部署：

```bash
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000
```

## 开发规范

本项目遵循严格的三层架构和开发规范，详见项目文档。

## 文档列表

| 文档 | 说明 |
|------|------|
| [CLAUDE.md](CLAUDE.md) | Claude.ai/code 项目指南（核心文档） |
| [.cursor/rules/develop.mdc](.cursor/rules/develop.mdc) | Cursor AI 开发规则（自动应用） |
| [文档维护指南](docs/文档维护指南.md) | **重要：核心文档同步维护说明** |
| [Python通用开发规范](docs/Python通用开发规范.md) | 详细开发规范 |
| [API文档](docs/API文档.md) | 接口说明文档 |
| [配置说明](docs/配置说明.md) | 环境配置详解 |
| [部署指南](docs/部署指南.md) | 部署说明 |

> **⚠️ 重要提示**：修改 `CLAUDE.md` 或 `develop.mdc` 时，必须同步更新另一个文件！  
> 详见 [文档维护指南](docs/文档维护指南.md)

## License

MIT License