# Picpocket（FaceScore 服务）

## 项目概述

Picpocket（又称 FaceScore）是一个基于 **Python、FastAPI 和多种深度学习模型**构建的 **AI 人脸识别与图像处理 REST API 服务**。它提供全面的人脸分析、图像增强和明星匹配等功能。

### 核心功能

- **人脸分析**：颜值评分、年龄估算、性别识别、情绪识别（使用 DeepFace、YOLO、MediaPipe）
- **图像增强**：照片修复（GFPGAN）、超分辨率（Real-ESRGAN）、图像上色（DDColor）、动漫风格化
- **背景移除**：rembg 和 RVM（鲁棒视频抠图）用于证件照处理
- **明星匹配**：与中国明星数据集进行人脸相似度比对
- **CLIP 搜索**：基于 cn_clip 的图文搜索和图图搜索
- **微信小程序集成**：访问令牌管理和 API 端点
- **定时清理**：通过 APScheduler 自动清理临时图片
- **多源存储**：支持本地文件系统和 BOS（百度对象存储 / Cloudflare R2）

### 主要技术栈

| 类别 | 技术 |
|------|------|
| **框架** | FastAPI、Uvicorn、Gunicorn |
| **ML/DL** | PyTorch、TensorFlow/tf-keras、DeepFace、YOLO、MediaPipe、GFPGAN、Real-ESRGAN、DDColor、cn_clip |
| **数据库** | MySQL（aiomysql 异步连接池） |
| **存储** | BOS/S3（boto3）、本地文件系统 |
| **调度** | APScheduler |
| **容器化** | Docker（兼容 HuggingFace Spaces） |

## 项目结构

```
picpocket/
├── app.py                    # FastAPI 应用入口，生命周期管理
├── api_routes.py             # 所有 API 端点（5000+ 行），主要业务逻辑
├── config.py                 # 配置、环境变量、兼容性补丁
├── models.py                 # Pydantic 请求/响应模型
├── database.py               # MySQL 异步连接池和 CRUD 操作
├── utils.py                  # 工具函数（图像处理、BOS 上传等）
├── face_analyzer.py          # EnhancedFaceAnalyzer - 核心人脸分析编排
├── facial_analyzer.py        # FacialFeatureAnalyzer - 详细面部特征评分
├── clip_utils.py             # CLIP 编码用于文本/图像搜索
├── vector_store.py           # FAISS 向量存储用于 CLIP 嵌入
├── gfpgan_restorer.py        # GFPGAN 照片修复封装
├── ddcolor_colorizer.py      # DDColor 图像上色封装
├── realesrgan_upscaler.py    # Real-ESRGAN 超分辨率封装
├── rembg_processor.py        # rembg 背景移除封装
├── rvm_processor.py          # RVM（鲁棒视频抠图）封装
├── anime_stylizer.py         # 动漫风格迁移封装
├── cleanup_scheduler.py      # APScheduler 图像清理定时任务
├── star_scraper.py           # 明星数据网络爬虫
├── region_code_utils.py      # 地区/国家代码工具
├── wx_access_token.py        # 微信访问令牌管理
├── requirements.txt          # Python 依赖
├── Dockerfile                # Docker 镜像定义（兼容 HF Spaces）
├── build.sh                  # 构建脚本（编译 Python、移动产物）
├── install.sh                # 本地开发安装脚本（使用清华镜像源）
├── start_local.sh            # 本地启动脚本（Gunicorn）
├── sql/                      # 数据库 schema 文件
├── test/                     # 测试文件
└── facelist-web/             # 前端 Web UI（可选，挂载于 /facelist）
```

## 构建与运行

### 本地开发

1. **安装依赖：**
   ```bash
   ./install.sh
   # 或手动安装：
   pip install -r requirements.txt
   ```

2. **设置环境变量**：创建 `.env` 文件，填写必需的配置（MySQL、BOS、微信等）

3. **启动服务：**
   ```bash
   ./start_local.sh
   # 或直接运行：
   uvicorn app:app --host 0.0.0.0 --port 7860
   ```

### Docker 部署

```bash
docker build -t picpocket:latest .
docker run -p 7860:7860 --env-file .env picpocket:latest
```

Dockerfile 已配置为兼容 **HuggingFace Spaces** 部署（见 README.md 元数据）。

### 生产环境（Gunicorn + Uvicorn）

```bash
gunicorn app:app \
  -k uvicorn.workers.UvicornWorker \
  -w 1 \
  -b 0.0.0.0:7860 \
  --timeout 120
```

### API 文档

服务启动后，可通过以下地址访问交互式 API 文档：
- Swagger UI：`http://localhost:7860/cp_docs`
- ReDoc：`http://localhost:7860/cp_redoc`

### 关键环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `IMAGES_DIR` | 图片存储目录 | `/opt/data/images` |
| `MODELS_PATH` | AI 模型目录 | `/opt/data/models` |
| `MYSQL_HOST`, `MYSQL_PORT`, `MYSQL_DB`, `MYSQL_USER`, `MYSQL_PASSWORD` | MySQL 连接配置 | - |
| `BOS_ACCESS_KEY`, `BOS_SECRET_KEY`, `BOS_ENDPOINT`, `BOS_BUCKET_NAME` | BOS/S3 存储配置 | - |
| `WECHAT_APPID`, `WECHAT_SECRET` | 微信小程序凭证 | - |
| `ENABLE_GFPGAN`, `ENABLE_DDCOLOR`, `ENABLE_REALESRGAN` 等 | 功能开关 | `true` |
| `AUTO_INIT_*` | 懒加载 vs 预加载控制 | `false` |
| `HUGGINGFACE_SYNC_ENABLED` | 启动时自动从 HF 同步模型 | `true` |

## 架构说明

### 初始化策略

服务默认使用**懒加载**初始化 AI 模型（`AUTO_INIT_*` = `false`）。模型在首次使用时才加载，以减少启动时间和内存占用。生产环境可通过环境变量覆盖此行为。

### 兼容性补丁

`config.py` 中包含大量兼容性补丁，用于解决：
- **torchvision.functional_tensor**：缺失模块的变通方案
- **PyTorch ONNX/PyTree**：GFPGAN 和 ModelScope 兼容性
- **PyArrow**：扩展类型兼容性
- **TensorFlow/Keras**：DeepFace 中的 SymbolicTensor 处理
- **OpenMP/MKL**：CPU 线程优化

### 数据库 Schema

服务使用 MySQL 配合异步连接池（`aiomysql`）。Schema 定义在 `sql/` 目录中，主要表包括：
- 图片记录（路径、评分、分类）
- 设备追踪（设备 ID、地区、应用版本）
- 明星/名人数据（来自网络爬虫）

### 线程安全

CPU 密集型的人脸分析操作通过 `ThreadPoolExecutor` 卸载，避免阻塞异步事件循环。DeepFace 调用受 `asyncio.Lock` 保护，防止并发模型状态损坏。

## 开发规范

- **日志**：通过 `ENABLE_LOGGING` 和 `LOG_LEVEL` 环境变量可配置
- **类型提示**：使用 Pydantic 模型进行请求/响应验证
- **异步/等待**：FastAPI 和 aiomysql 提供完整的异步支持
- **错误处理**：AI 模型不可用时优雅降级
- **代码风格**：遵循 PEP 8，使用 `ruff` 或 `flake8` 进行 lint（推断）

## 测试

测试文件位于 `test/` 目录。运行方式：
```bash
pytest test/
```

## 常用命令

| 任务 | 命令 |
|------|------|
| 安装依赖 | `./install.sh` 或 `pip install -r requirements.txt` |
| 启动服务（本地） | `./start_local.sh` 或 `uvicorn app:app --reload` |
| 编译 Python 文件 | `./build.sh` 或 `python -m compileall .` |
| 运行测试 | `pytest test/` |
| 构建 Docker 镜像 | `docker build -t picpocket .` |
| 运行 Docker 容器 | `docker run -p 7860:7860 --env-file .env picpocket` |