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）
构建与运行
本地开发
安装依赖：
./install.sh # 或手动安装： pip install -r requirements.txt设置环境变量：创建
.env文件，填写必需的配置（MySQL、BOS、微信等）启动服务：
./start_local.sh # 或直接运行： uvicorn app:app --host 0.0.0.0 --port 7860
Docker 部署
docker build -t picpocket:latest .
docker run -p 7860:7860 --env-file .env picpocket:latest
Dockerfile 已配置为兼容 HuggingFace Spaces 部署（见 README.md 元数据）。
生产环境（Gunicorn + Uvicorn）
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/ 目录。运行方式：
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 |