PicPocket 后端项目核心指南 (GEMINI.md)
1. 项目定位
本项目是一个为微信小程序提供支撑的高性能图像处理后台，核心业务围绕“人脸评分”、“老照片修复”、“AI 抠图”和“智能图库”展开。
2. 核心技术栈
- Web 框架: FastAPI (Python 3.10+)
- 异步处理:
asyncio+ThreadPoolExecutor(用于隔离 CV 推理等 CPU 密集型任务) - 图像处理: OpenCV, NumPy, PIL
- AI 推理引擎:
- 人脸分析: DeepFace (ArcFace), 自研 EnhancedFaceAnalyzer (YOLO + 颜值模型)
- 画质增强: GFPGAN (修复), Real-ESRGAN (超清)
- 自动上色: DDColor
- 智能抠图: Rembg (通用), RVM (人像视频/图片)
- 风格化: AnimeStylizer
- 向量检索: CLIP (cn_clip) + Vector Store
- 数据持久化: MySQL (aiomysql 异步驱动)
- 云端集成: 百度云 BOS (对象存储), 微信内容安全接口
3. API 路由规范 (api_routes.py)
所有的 API 统一挂载在 /facescore 前缀下：
| 接口路径 | 功能描述 | 核心逻辑/模型 |
|---|---|---|
/analyze |
核心人脸分析接口 | YOLO 检测 + 颜值评分 + 年龄性别 (Hybrid 模式) |
/app/analyze |
App 专用分析接口 | 在 /analyze 基础上增加设备信息记录 |
/upload_file |
文件上传 | 支持 idphoto 类型自动修复 |
/check_image_security |
安全检测 | 微信内容安全检测 |
/detect_faces |
纯人脸检测 | 快速返回 YOLO 检测框 |
/image_search |
以图搜图 | CLIP 向量相似度搜索 |
/outputs |
历史记录/搜索 | 支持分页、分类过滤及向量关键词检索 |
/daily_category_stats |
业务统计 | 统计当日各项功能的使用频率 |
4. 关键开发守则 (必须遵守)
- 禁止阻塞主线程: 严禁在
async def中直接进行耗时计算（如cv2.imread,model.predict）。必须使用process_cpu_intensive_task。 - 内存与会话清理: DeepFace 报错时应调用
_recover_deepface_model；频繁推理需注意显存释放。 - 数据记录一致性: 任何生成新文件的接口都必须通过
_record_output_file异步记入数据库。 - 安全性: 优先执行
check_image_security；处理上传文件需确保 UUID 命名以防冲突。 - 类型提示: 所有新函数必须包含完整的 Typing 类型注解。
5. 目录结构
api_routes.py: 所有 API 的定义与入口。face_analyzer.py: 人脸检测与评分的核心逻辑实现。database.py: 数据库异步操作封装。config.py: 项目全局配置与模型开关。utils.py: 图像保存、BOS 上传、单位转换等工具函数。*_processor.py: 各 AI 功能模块的独立处理器。
6. 语言约束 (必须遵守)
- 所有回答必须使用中文: 无论任何问题或对话内容，必须使用中文回答，禁止使用英文回复用户。