| # 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` | |
| |
