init

.gitignore

@@ -0,0 +1,66 @@
+HELP.md
+target/
+output/
+!.mvn/wrapper/maven-wrapper.jar
+!**/src/main/**/target/
+!**/src/test/**/target/
+
+.flattened-pom.xml
+
+### STS ###
+.apt_generated
+.classpath
+.factorypath
+.project
+.settings
+.springBeans
+.sts4-cache
+
+### IntelliJ IDEA ###
+.idea
+*.iws
+*.iml
+*.ipr
+
+### NetBeans ###
+/nbproject/private/
+/nbbuild/
+/dist/
+/nbdist/
+/.nb-gradle/
+build/
+!**/src/main/**/build/
+!**/src/test/**/build/
+
+### VS Code ###
+.vscode/
+
+### LOG ###
+logs/
+
+*.class
+
+**/node_modules/
+/*.log
+/output/
+/faiss/
+/web/facelist-web/
+**/._*
+__pycache__/
+.DS_Store
+*.pth
+/data/celebrity_faces/ds_model_arcface_detector_retinaface_aligned_normalization_base_expand_0.pkl
+/data/celebrity_faces/jpeg_6c06eca6.jpeg
+/data/celebrity_faces/jpeg_51e1394b.jpeg
+/data/celebrity_faces/jpeg_66fee390.jpeg
+/data/celebrity_faces/jpeg_70b86102.jpeg
+/data/celebrity_faces/jpeg_406b961a.jpeg
+/data/celebrity_faces/jpeg_1321f87f.jpeg
+/data/celebrity_faces/jpeg_b56ae384.jpeg
+/data/celebrity_faces/jpeg_c07cdb46.jpeg
+/data/celebrity_faces/jpeg_c7353005.jpeg
+/data/celebrity_faces/jpeg_d4cb0602.jpeg
+/data/celebrity_faces/jpeg_dbb64030.jpeg
+/data/celebrity_faces/jpeg_fc652ad4.jpeg
+/data/celebrity_faces/jpeg_fd6b0869.jpeg
+/data/celebrity_embeddings.db

Dockerfile

@@ -0,0 +1,75 @@
+FROM python:3.10-slim
+
+ENV TZ=Asia/Shanghai \
+    OUTPUT_DIR=/opt/output \
+    IMAGES_DIR=/opt/images \
+    MODELS_PATH=/opt/models \
+    DEEPFACE_HOME=/opt/models \
+    FAISS_INDEX_DIR=/opt/faiss \
+    CELEBRITY_SOURCE_DIR=/opt/chinese_celeb_dataset \
+    GENDER_CONFIDENCE=1 \
+    UPSCALE_SIZE=2 \
+    AGE_CONFIDENCE=0.1 \
+    DRAW_SCORE=true \
+    FACE_CONFIDENCE=0.7 \
+    ENABLE_DDCOLOR=false \
+    ENABLE_GFPGAN=false \
+    ENABLE_REALESRGAN=false \
+    ENABLE_ANIME_STYLE=false \
+    ENABLE_RVM=false \
+    ENABLE_REMBG=false \
+    ENABLE_CLIP=false \
+    CLEANUP_INTERVAL_HOURS=1 \
+    CLEANUP_AGE_HOURS=1 \
+    BEAUTY_ADJUST_GAMMA=0.8 \
+    BEAUTY_ADJUST_MIN=1.0 \
+    BEAUTY_ADJUST_MAX=9.0 \
+    ENABLE_ANIME_PRELOAD=false \
+    ENABLE_LOGGING=true \
+    BEAUTY_ADJUST_ENABLED=true \
+    RVM_LOCAL_REPO=/app/RobustVideoMatting \
+    RVM_WEIGHTS_PATH=/opt/models/torch/hub/checkpoints/rvm_resnet50.pth \
+    RVM_MODEL=resnet50 \
+    AUTO_INIT_GFPGAN=false \
+    AUTO_INIT_DDCOLOR=false \
+    AUTO_INIT_REALESRGAN=false \
+    AUTO_INIT_ANIME_STYLE=false \
+    AUTO_INIT_CLIP=false \
+    AUTO_INIT_RVM=false \
+    AUTO_INIT_REMBG=false \
+    ENABLE_WARMUP=true \
+    REALESRGAN_MODEL=realesr-general-x4v3 \
+    CELEBRITY_FIND_THRESHOLD=0.87 \
+    FEMALE_AGE_ADJUSTMENT=4 \
+    HOSTNAME=HG
+
+RUN mkdir -p  /opt/chinese_celeb_dataset /opt/faiss /opt/models /opt/images /opt/output
+WORKDIR /app
+COPY requirements.txt .
+COPY *.py /app/
+
+# 安装必要的系统工具和依赖
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    cmake \
+    git \
+    wget \
+    curl \
+    ca-certificates \
+    libopenblas-dev \
+    liblapack-dev \
+    libx11-dev \
+    libgtk-3-dev \
+    libboost-python-dev \
+    libglib2.0-0 \
+    libsm6 \
+    libxext6 \
+    libxrender-dev \
+    libgomp1 \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN pip install --upgrade pip
+# 安装所有依赖 - 现在可以一次性完成
+RUN pip install --no-cache-dir -r requirements.txt
+EXPOSE 7860
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860","--no-access-log","--log-level","critical"]

anime_stylizer.py

@@ -0,0 +1,427 @@
+import os
+import tempfile
+import time
+
+import cv2
+
+from config import logger
+
+
+class AnimeStylizer:
+    def __init__(self):
+        start_time = time.perf_counter()
+        self.stylizers = {}  # 存储不同风格的模型
+        self.current_style = None
+        self.current_stylizer = None
+
+        # 检查是否启用Anime Style功能
+        from config import ENABLE_ANIME_STYLE
+        if ENABLE_ANIME_STYLE:
+            self._initialize_models()
+        else:
+            logger.info("Anime Style feature is disabled, skipping model initialization")
+        init_time = time.perf_counter() - start_time
+        if hasattr(self, 'model_configs') and len(self.model_configs) > 0:
+            logger.info(f"AnimeStylizer initialized successfully, time: {init_time:.3f}s")
+        else:
+            logger.info(f"AnimeStylizer initialization completed but not available, time: {init_time:.3f}s")
+
+    def _initialize_models(self):
+        """初始化所有Anime Style模型（使用ModelScope）"""
+        try:
+            logger.info("Initializing multiple Anime Style models (using ModelScope)...")
+
+            # 添加torch类型兼容性补丁
+            import torch
+            if not hasattr(torch, 'uint64'):
+                logger.info("Adding torch.uint64 compatibility patch...")
+                torch.uint64 = torch.int64  # 使用int64作为uint64的替代
+            if not hasattr(torch, 'uint32'):
+                logger.info("Adding torch.uint32 compatibility patch...")
+                torch.uint32 = torch.int32  # 使用int32作为uint32的替代
+            if not hasattr(torch, 'uint16'):
+                logger.info("Adding torch.uint16 compatibility patch...")
+                torch.uint16 = torch.int16  # 使用int16作为uint16的替代
+
+            # 导入ModelScope相关模块
+            from modelscope.outputs import OutputKeys
+            from modelscope.pipelines import pipeline
+            from modelscope.utils.constant import Tasks
+
+            self.OutputKeys = OutputKeys
+
+            # 定义所有可用的模型和风格
+            self.model_configs = {
+                "handdrawn": {
+                    "model_id": "iic/cv_unet_person-image-cartoon-handdrawn_compound-models",
+                    "name": "手绘风格",
+                    "description": "手绘动漫风格 - 传统手绘感觉，线条清晰"
+                },
+                "disney": {
+                    "model_id": "iic/cv_unet_person-image-cartoon-3d_compound-models",
+                    "name": "迪士尼风格",
+                    "description": "迪士尼风格 - 立体感强，色彩鲜艳"
+                },
+                "illustration": {
+                    "model_id": "iic/cv_unet_person-image-cartoon-sd-design_compound-models",
+                    "name": "插画风格",
+                    "description": "插画风格 - 现代插画设计感"
+                },
+                "artstyle": {
+                    "model_id": "iic/cv_unet_person-image-cartoon-artstyle_compound-models",
+                    "name": "艺术风格",
+                    "description": "艺术风格 - 独特的艺术表现力"
+                },
+                "anime": {
+                    "model_id": "iic/cv_unet_person-image-cartoon_compound-models",
+                    "name": "二次元风格",
+                    "description": "二次元风格 - 经典动漫角色风格"
+                },
+                "sketch": {
+                    "model_id": "iic/cv_unet_person-image-cartoon-sketch_compound-models",
+                    "name": "素描风格",
+                    "description": "素描风格 - 黑白素描画效果"
+                }
+            }
+
+            logger.info(f"Defined {len(self.model_configs)} anime style model configurations")
+            logger.info("Models will be loaded on-demand when first used to save memory")
+
+            # 检查是否启用预加载
+            try:
+                from config import ENABLE_ANIME_PRELOAD
+                if ENABLE_ANIME_PRELOAD:
+                    logger.info("Enabling anime style model preloading...")
+                    self.preload_models()
+                else:
+                    logger.info("Anime style model preloading is disabled, will be loaded on-demand when first used")
+            except ImportError:
+                logger.info("Anime style model preloading configuration not found, will be loaded on-demand when first used")
+
+        except ImportError as e:
+            logger.error(f"ModelScope module import failed: {e}")
+            self.model_configs = {}
+        except Exception as e:
+            logger.error(f"Anime Style model initialization failed: {e}")
+            self.model_configs = {}
+
+    def _load_model(self, style_type):
+        """按需加载指定风格的模型"""
+        if style_type not in self.model_configs:
+            logger.error(f"Unsupported style type: {style_type}")
+            return False
+
+        if style_type in self.stylizers:
+            logger.info(f"Model {style_type} already loaded, using directly")
+            return True
+
+        try:
+            from modelscope.pipelines import pipeline
+            from modelscope.utils.constant import Tasks
+
+            config = self.model_configs[style_type]
+            logger.info(f"Loading {config['name']} model: {config['model_id']}")
+
+            # 根据模型类型选择合适的任务类型
+            if "stable_diffusion" in config["model_id"]:
+                # Stable Diffusion 系列模型使用文生图任务类型
+                task_type = Tasks.text_to_image_synthesis
+                logger.info(f"Using text_to_image_synthesis task type to load Stable Diffusion model")
+            else:
+                # UNet 系列模型使用人像风格化任务
+                task_type = Tasks.image_portrait_stylization
+                logger.info(f"Using image_portrait_stylization task type to load UNet model")
+
+            stylizer = pipeline(task_type, model=config["model_id"])
+            self.stylizers[style_type] = stylizer
+
+            logger.info(f"{config['name']} model loaded successfully")
+            return True
+
+        except Exception as e:
+            logger.error(f"Failed to load {style_type} model: {e}")
+            return False
+
+    def preload_models(self, style_types=None):
+        """
+        预加载指定的动漫风格模型
+        :param style_types: 要预加载的风格类型列表，如果为None则预加载所有模型
+        """
+        if not self.is_available():
+            logger.warning("Anime Style module is not available, cannot preload models")
+            return
+
+        if style_types is None:
+            style_types = list(self.model_configs.keys())
+        elif isinstance(style_types, str):
+            style_types = [style_types]
+
+        logger.info(f"Starting to preload anime style models: {style_types}")
+
+        successful_loads = []
+        failed_loads = []
+
+        for style_type in style_types:
+            if style_type not in self.model_configs:
+                logger.warning(f"Unknown style type: {style_type}, skipping preload")
+                failed_loads.append(style_type)
+                continue
+
+            try:
+                logger.info(f"Preloading model: {self.model_configs[style_type]['name']} ({style_type})")
+                if self._load_model(style_type):
+                    successful_loads.append(style_type)
+                    logger.info(f"✓ Successfully preloaded: {self.model_configs[style_type]['name']}")
+                else:
+                    failed_loads.append(style_type)
+                    logger.error(f"✗ Preload failed: {self.model_configs[style_type]['name']}")
+            except Exception as e:
+                logger.error(f"✗ Exception occurred while preloading model {style_type}: {e}")
+                failed_loads.append(style_type)
+
+        if successful_loads:
+            logger.info(f"Successfully preloaded models ({len(successful_loads)}): {successful_loads}")
+        if failed_loads:
+            logger.warning(f"Failed to preload models ({len(failed_loads)}): {failed_loads}")
+
+        logger.info(f"Anime style model preloading completed, success: {len(successful_loads)}/{len(style_types)}")
+
+    def get_loaded_models(self):
+        """
+        获取已加载的模型列表
+        :return: 已加载的模型风格类型列表
+        """
+        return list(self.stylizers.keys())
+
+    def is_model_loaded(self, style_type):
+        """
+        检查指定风格的模型是否已加载
+        :param style_type: 风格类型
+        :return: 是否已加载
+        """
+        return style_type in self.stylizers
+
+    def get_preload_status(self):
+        """
+        获取模型预加载状态
+        :return: 包含预加载状态的字典
+        """
+        total_models = len(self.model_configs)
+        loaded_models = len(self.stylizers)
+
+        status = {
+            "total_models": total_models,
+            "loaded_models": loaded_models,
+            "preload_ratio": f"{loaded_models}/{total_models}",
+            "preload_percentage": round((loaded_models / total_models * 100) if total_models > 0 else 0, 1),
+            "available_styles": list(self.model_configs.keys()),
+            "loaded_styles": list(self.stylizers.keys()),
+            "unloaded_styles": [style for style in self.model_configs.keys() if style not in self.stylizers]
+        }
+
+        return status
+
+    def is_available(self):
+        """检查Anime Stylizer是否可用"""
+        return hasattr(self, 'model_configs') and len(self.model_configs) > 0
+
+    def stylize_image(self, image, style_type="disney"):
+        """
+        对图像进行动漫风格化
+        :param image: 输入图像 (numpy array, BGR格式)
+        :param style_type: 动漫风格类型，支持的类型：
+            "handdrawn" - 手绘风格
+            "disney" - 迪士尼风格 (默认)
+            "illustration" - 插画风格
+            "flat" - 扁平风格
+            "clipart" - 剪贴画风格
+            "watercolor" - 水彩风格
+            "artstyle" - 艺术风格
+            "anime" - 二次元风格
+            "sketch" - 素描风格
+        :return: 动漫风格化后的图像 (numpy array, BGR格式)
+        """
+        if not self.is_available():
+            logger.error("Anime Style model not initialized")
+            return image
+
+        # 加载指定风格的模型
+        if not self._load_model(style_type):
+            logger.error(f"Failed to load {style_type} model")
+            return image
+
+        return self._stylize_image_via_file(image, style_type)
+
+    def _stylize_image_via_file(self, image, style_type="disney"):
+        """
+        通过临时文件进行动漫风格化
+        :param image: 输入图像 (numpy array, BGR格式)
+        :param style_type: 动漫风格类型
+        :return: 动漫风格化后的图像 (numpy array, BGR格式)
+        """
+        try:
+            config = self.model_configs.get(style_type, {})
+            style_name = config.get('name', style_type)
+            logger.info(f"Using anime stylization processing, style type: {style_name} ({style_type})")
+
+            # 验证风格类型
+            if style_type not in self.model_configs:
+                logger.warning(f"Invalid style type: {style_type}, using default style disney")
+                style_type = "disney"
+
+            # 使用最高质量设置保存临时图像
+            with tempfile.NamedTemporaryFile(suffix='.webp', delete=False) as tmp_input:
+                # 使用WebP格式，最高质量设置
+                cv2.imwrite(tmp_input.name, image, [cv2.IMWRITE_WEBP_QUALITY, 100])
+                tmp_input_path = tmp_input.name
+
+            try:
+                logger.info(f"Temporary file saved to: {tmp_input_path}")
+
+                # 使用ModelScope进行动漫风格化
+                stylizer = self.stylizers[style_type]
+
+                # 根据模型类型使用不同的调用方式
+                if "stable_diffusion" in config["model_id"]:
+                    # Stable Diffusion模型需要特殊处理
+                    logger.info("Using Stable Diffusion model, text parameter is required")
+                    # 对于Stable Diffusion，必须使用'sks style'格式的提示词
+                    style_prompts = {}
+                    prompt = style_prompts.get(style_type, "sks style, cartoon style artwork")
+                    logger.info(f"Using prompt: {prompt}")
+                    result = stylizer({"text": prompt})
+                else:
+                    # UNet模型直接处理
+                    result = stylizer(tmp_input_path)
+
+                # 获取风格化后的图像
+                # 不同模型的输出键名可能不同，需要适配
+                if "stable_diffusion" in config["model_id"]:
+                    # Stable Diffusion模型通常使用不同的输出键名
+                    logger.info(f"Stable Diffusion model output keys: {list(result.keys())}")
+                    if 'output_imgs' in result:
+                        stylized_image = result['output_imgs'][0]
+                    elif 'output_img' in result:
+                        stylized_image = result['output_img']
+                    elif self.OutputKeys.OUTPUT_IMG in result:
+                        stylized_image = result[self.OutputKeys.OUTPUT_IMG]
+                    else:
+                        # 尝试获取第一个图像输出
+                        for key in result.keys():
+                            if isinstance(result[key], (list, tuple)) and len(result[key]) > 0:
+                                stylized_image = result[key][0]
+                                logger.info(f"Using output key: {key}")
+                                break
+                            elif hasattr(result[key], 'shape'):
+                                stylized_image = result[key]
+                                logger.info(f"Using output key: {key}")
+                                break
+                        else:
+                            raise KeyError(f"未找到有效的图像输出键，可用键: {list(result.keys())}")
+                else:
+                    # UNet模型使用标准输出键
+                    stylized_image = result[self.OutputKeys.OUTPUT_IMG]
+
+                logger.info(f"Anime stylization output: size={stylized_image.shape}, type={stylized_image.dtype}")
+
+                # ModelScope输出的图像已经是BGR格式，不需要转换
+                logger.info("Anime stylization processing completed")
+                return stylized_image
+
+            finally:
+                # 清理临时文件
+                try:
+                    os.unlink(tmp_input_path)
+                except:
+                    pass
+
+        except Exception as e:
+            logger.error(f"Anime stylization processing failed: {e}")
+            logger.info("Returning original image")
+            return image
+
+    def get_available_styles(self):
+        """
+        获取支持的动漫风格类型
+        :return: 字典，包含风格代码和描述
+        """
+        if not hasattr(self, 'model_configs'):
+            return {}
+
+        return {
+            style_type: f"{config['name']} - {config['description'].split(' - ')[1]}"
+            for style_type, config in self.model_configs.items()
+        }
+
+    def save_debug_image(self, image, filename_prefix):
+        """保存调试用的图像"""
+        try:
+            debug_path = f"{filename_prefix}_debug.webp"
+            cv2.imwrite(debug_path, image, [cv2.IMWRITE_WEBP_QUALITY, 95])
+            logger.info(f"Debug image saved: {debug_path}")
+            return debug_path
+        except Exception as e:
+            logger.error(f"Failed to save debug image: {e}")
+            return None
+
+    def test_stylization(self, test_url=None):
+        """
+        测试动漫风格化功能
+        :param test_url: 测试图像URL，默认使用官方示例
+        :return: 测试结果
+        """
+        if not self.is_available():
+            return False, "Anime Style模型未初始化"
+
+        try:
+            test_url = test_url or 'https://modelscope.oss-cn-beijing.aliyuncs.com/test/images/portrait.jpg'
+            logger.info(f"Testing anime stylization feature, using image: {test_url}")
+
+            # 测试默认风格
+            result = self.stylizer(test_url)
+            stylized_img = result[self.OutputKeys.OUTPUT_IMG]
+
+            # 保存测试结果
+            test_output_path = 'anime_style_test_result.webp'
+            cv2.imwrite(test_output_path, stylized_img, [cv2.IMWRITE_WEBP_QUALITY, 95])
+
+            logger.info(f"Anime stylization test successful, result saved to: {test_output_path}")
+            return True, f"测试成功，结果保存到: {test_output_path}"
+
+        except Exception as e:
+            logger.error(f"Anime stylization test failed: {e}")
+            return False, f"测试失败: {e}"
+
+    def test_local_image(self, image_path, style_type="disney"):
+        """
+        测试本地图像动漫风格化
+        :param image_path: 本地图像路径
+        :param style_type: 动漫风格类型
+        :return: 测试结果
+        """
+        if not self.is_available():
+            return False, "Anime Style模型未初始化"
+
+        try:
+            logger.info(f"Testing local image anime stylization: {image_path}, style: {style_type}")
+
+            # 读取本地图像
+            image = cv2.imread(image_path)
+            if image is None:
+                return False, f"Unable to read image: {image_path}"
+
+            # 保存原图用于对比
+            self.save_debug_image(image, "original")
+
+            # 动漫风格化处理
+            stylized_image = self.stylize_image(image, style_type)
+
+            # 保存风格化结果
+            result_path = self.save_debug_image(stylized_image, f"anime_style_{style_type}")
+
+            logger.info(f"Local image anime stylization successful, result saved to: {result_path}")
+            return True, f"本地图像动漫风格化成功，结果保存到: {result_path}"
+
+        except Exception as e:
+            logger.error(f"Local image anime stylization failed: {e}")
+            return False, f"本地图像动漫风格化失败: {e}"

app.py

@@ -0,0 +1,131 @@
+import os
+import time
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from starlette.middleware.cors import CORSMiddleware
+
+from cleanup_scheduler import start_cleanup_scheduler, stop_cleanup_scheduler
+from config import (
+    logger,
+    OUTPUT_DIR,
+    DEEPFACE_AVAILABLE,
+    DLIB_AVAILABLE,
+    MODELS_PATH,
+    IMAGES_DIR,
+    YOLO_AVAILABLE,
+    ENABLE_LOGGING,
+)
+from database import close_mysql_pool, init_mysql_pool
+
+logger.info("Starting to import api_routes module...")
+try:
+    t_start = time.perf_counter()
+    from api_routes import api_router
+    import_time = time.perf_counter() - t_start
+    logger.info(f"api_routes module imported successfully, time: {import_time:.3f}s")
+except Exception as e:
+    import_time = time.perf_counter() - t_start
+    logger.error(f"api_routes module import failed, time: {import_time:.3f}s, error: {e}")
+    raise
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    start_time = time.perf_counter()
+    logger.info("FaceScore service starting...")
+    logger.info(f"Output directory: {OUTPUT_DIR}")
+    logger.info(f"DeepFace available: {DEEPFACE_AVAILABLE}")
+    logger.info(f"YOLO available: {YOLO_AVAILABLE}")
+    logger.info(f"MediaPipe available: {DLIB_AVAILABLE}")
+    logger.debug(f"Archive directory: {IMAGES_DIR}")
+    os.makedirs(OUTPUT_DIR, exist_ok=True)
+
+    # 初始化数据库连接池
+    try:
+      await init_mysql_pool()
+      logger.info("MySQL 连接池初始化完成")
+    except Exception as exc:
+      logger.error(f"初始化 MySQL 连接池失败: {exc}")
+      raise
+
+    # 启动图片清理定时任务
+    logger.info("Starting image cleanup scheduled task...")
+    try:
+        start_cleanup_scheduler()
+        logger.info("Image cleanup scheduled task started successfully")
+    except Exception as e:
+        logger.error(f"Failed to start image cleanup scheduled task: {e}")
+
+    # 记录启动完成时间
+    total_startup_time = time.perf_counter() - start_time
+    logger.info(f"FaceScore service startup completed, total time: {total_startup_time:.3f}s")
+
+    yield
+
+    # 应用关闭时停止定时任务
+    logger.info("Stopping image cleanup scheduled task...")
+    try:
+        stop_cleanup_scheduler()
+        logger.info("Image cleanup scheduled task stopped")
+    except Exception as e:
+        logger.error(f"Failed to stop image cleanup scheduled task: {e}")
+
+    # 关闭数据库连接池
+    try:
+      await close_mysql_pool()
+    except Exception as exc:
+      logger.warning(f"关闭 MySQL 连接池失败: {exc}")
+
+
+# 创建 FastAPI 应用
+app = FastAPI(
+    title="Enhanced FaceScore 服务",
+    description="支持多模型的人脸分析REST API服务，包含五官评分功能。支持混合模式：HowCuteAmI（颜值+性别）+ DeepFace（年龄+情绪）",
+    version="3.0.0",
+    docs_url="/cp_docs",
+    redoc_url="/cp_redoc",
+    lifespan=lifespan,
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# 注册路由
+app.include_router(api_router)
+
+# 添加根路径处理
+@app.get("/")
+async def root():
+    return "UP"
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    if not os.path.exists(MODELS_PATH):
+        logger.critical(
+            "Warning: 'models' directory not found. Please ensure it exists and contains model files."
+        )
+        logger.critical(
+            "Exiting application as FaceAnalyzer cannot be initialized without models."
+        )
+        exit(1)
+
+    # 根据日志开关配置 Uvicorn 日志
+    if ENABLE_LOGGING:
+        uvicorn.run(app, host="0.0.0.0", port=8080, reload=False)
+    else:
+        # 禁用 Uvicorn 的访问日志和错误日志
+        uvicorn.run(
+            app,
+            host="0.0.0.0",
+            port=8080,
+            reload=False,
+            access_log=False,  # 禁用访问日志
+            log_level="critical"  # 只显示严重错误
+        )

cleanup_scheduler.py

@@ -0,0 +1,202 @@
+"""
+定时清理图片文件模块
+每小时检查一次IMAGES_DIR目录，删除1小时以前的图片文件
+"""
+import glob
+import os
+import time
+from datetime import datetime
+
+from apscheduler.schedulers.background import BackgroundScheduler
+
+from config import logger, IMAGES_DIR, CLEANUP_INTERVAL_HOURS, CLEANUP_AGE_HOURS
+
+
+# from utils import delete_file_from_bos  # 暂时注释掉删除BOS文件的功能
+
+
+class ImageCleanupScheduler:
+    """图片清理定时任务类"""
+
+    def __init__(self, images_dir=None, cleanup_hours=None, interval_hours=None):
+        """
+        初始化清理调度器
+
+        Args:
+            images_dir (str): 图片目录路径，默认使用config中的IMAGES_DIR
+            cleanup_hours (float): 清理时间阈值（小时），默认使用环境变量CLEANUP_AGE_HOURS
+            interval_hours (float): 定时任务执行间隔（小时），默认使用环境变量CLEANUP_INTERVAL_HOURS
+        """
+        self.images_dir = images_dir or IMAGES_DIR
+        self.cleanup_hours = cleanup_hours if cleanup_hours is not None else CLEANUP_AGE_HOURS
+        self.interval_hours = interval_hours if interval_hours is not None else CLEANUP_INTERVAL_HOURS
+        self.scheduler = BackgroundScheduler()
+        self.is_running = False
+
+        # 确保目录存在
+        os.makedirs(self.images_dir, exist_ok=True)
+        logger.info(f"Image cleanup scheduler initialized, monitoring directory: {self.images_dir}, cleanup threshold: {self.cleanup_hours} hours, execution interval: {self.interval_hours} hours")
+
+    def cleanup_old_images(self):
+        """
+        清理过期的图片文件
+        删除超过指定时间的图片文件
+        """
+        try:
+            current_time = time.time()
+            cutoff_time = current_time - (self.cleanup_hours * 3600)  # 转换为秒
+            cutoff_datetime = datetime.fromtimestamp(cutoff_time)
+
+            # 支持的图片格式
+            image_extensions = ['*.jpg', '*.jpeg', '*.png', '*.webp', '*.gif', '*.bmp']
+            deleted_files = []
+            total_size_deleted = 0
+
+            logger.info(f"Starting to clean image directory: {self.images_dir}")
+            logger.info(f"Cleanup threshold time: {cutoff_datetime.strftime('%Y-%m-%d %H:%M:%S')}")
+
+            # 遍历所有图片文件
+            for extension in image_extensions:
+                pattern = os.path.join(self.images_dir, extension)
+                for file_path in glob.glob(pattern):
+                    try:
+                        # 获取文件修改时间
+                        file_mtime = os.path.getmtime(file_path)
+
+                        # 如果文件时间早于阈值时间，则删除
+                        if file_mtime < cutoff_time:
+                            file_size = os.path.getsize(file_path)
+                            file_time = datetime.fromtimestamp(file_mtime)
+
+                            # 删除文件
+                            os.remove(file_path)
+                            # delete_file_from_bos(file_path)  # 暂时注释掉删除BOS文件
+                            deleted_files.append(os.path.basename(file_path))
+                            total_size_deleted += file_size
+
+                            logger.debug(f"Deleting expired file: {os.path.basename(file_path)} ")
+
+                    except (OSError, IOError) as e:
+                        logger.error(f"Failed to delete file {os.path.basename(file_path)}: {e}")
+                        continue
+
+                logger.info(f"Cleanup completed! Deleted {len(deleted_files)} files, ")
+                logger.debug(f"Deleted file list: {', '.join(deleted_files[:10])}")
+            else:
+                logger.info("Cleanup completed! No expired files found to clean")
+
+            return {
+                'success': True,
+                'deleted_count': len(deleted_files),
+                'deleted_size': total_size_deleted,
+                'deleted_files': deleted_files,
+                'cutoff_time': cutoff_datetime.isoformat()
+            }
+
+        except Exception as e:
+            error_msg = f"图片清理任务执行失败: {e}"
+            logger.error(error_msg)
+            return {
+                'success': False,
+                'error': str(e),
+                'deleted_count': 0,
+                'deleted_size': 0
+            }
+
+    def _format_size(self, size_bytes):
+        """格式化文件大小显示"""
+        if size_bytes == 0:
+            return "0 B"
+        size_names = ["B", "KB", "MB", "GB"]
+        i = 0
+        while size_bytes >= 1024 and i < len(size_names) - 1:
+            size_bytes /= 1024.0
+            i += 1
+        return f"{size_bytes:.1f} {size_names[i]}"
+
+    def start(self):
+        """启动定时清理任务"""
+        if self.is_running:
+            logger.warning("Image cleanup scheduler is already running")
+            return
+
+        try:
+            # 添加定时任务：使用可配置的��行间隔
+            self.scheduler.add_job(
+                func=self.cleanup_old_images,
+                trigger='interval',
+                hours=self.interval_hours,  # 使用环境变量配置的执行间隔
+                id='image_cleanup',
+                name='image clean tast',
+                replace_existing=True
+            )
+
+            # 启动调度器
+            self.scheduler.start()
+            self.is_running = True
+
+            logger.info(f"Image cleanup scheduler started, will execute cleanup task every {self.interval_hours} hours")
+
+            # 立即执行一次清理（可选）
+            logger.info("Executing image cleanup task immediately...")
+            self.cleanup_old_images()
+
+        except Exception as e:
+            logger.error(f"Failed to start image cleanup scheduler: {e}")
+            raise
+
+    def stop(self):
+        """停止定时清理任务"""
+        if not self.is_running:
+            logger.warning("Image cleanup scheduler is not running")
+            return
+
+        try:
+            self.scheduler.shutdown(wait=False)
+            self.is_running = False
+            logger.info("Image cleanup scheduler stopped")
+        except Exception as e:
+            logger.error(f"Failed to stop image cleanup scheduler: {e}")
+
+    def get_status(self):
+        """获取调度器状态"""
+        return {
+            'running': self.is_running,
+            'images_dir': self.images_dir,
+            'cleanup_hours': self.cleanup_hours,
+            'interval_hours': self.interval_hours,
+            'next_run': self.scheduler.get_jobs()[0].next_run_time.isoformat()
+                       if self.is_running and self.scheduler.get_jobs() else None
+        }
+
+
+# 创建全局调度器实例
+cleanup_scheduler = ImageCleanupScheduler()
+
+
+def start_cleanup_scheduler():
+    """启动图片清理调度器"""
+    cleanup_scheduler.start()
+
+
+def stop_cleanup_scheduler():
+    """停止图片清理调度器"""
+    cleanup_scheduler.stop()
+
+
+def get_cleanup_status():
+    """获取清理调度器状态"""
+    return cleanup_scheduler.get_status()
+
+
+def manual_cleanup():
+    """手动执行一次清理"""
+    return cleanup_scheduler.cleanup_old_images()
+
+
+if __name__ == "__main__":
+    # 测试代码
+    print("测试图片清理功能...")
+    test_scheduler = ImageCleanupScheduler()
+    result = test_scheduler.cleanup_old_images()
+    print(f"清理结果: {result}")

clip_utils.py

@@ -0,0 +1,65 @@
+# clip_utils.py
+import logging
+import os
+from typing import Union, List
+
+import cn_clip.clip as clip
+import torch
+from PIL import Image
+from cn_clip.clip import load_from_name
+
+from config import MODELS_PATH
+
+# 配置日志
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# 环境变量配置
+MODEL_NAME_CN = os.environ.get('MODEL_NAME_CN', 'ViT-B-16')
+
+# 设备配置
+device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+
+# 模型初始化
+model = None
+preprocess = None
+
+def init_clip_model():
+    """初始化CLIP模型"""
+    global model, preprocess
+    try:
+        model, preprocess = load_from_name(MODEL_NAME_CN, device=device, download_root=MODELS_PATH)
+        model.eval()
+        logger.info(f"CLIP model initialized successfully, dimension: {model.visual.output_dim}")
+        return True
+    except Exception as e:
+        logger.error(f"CLIP model initialization failed: {e}")
+        return False
+
+def is_clip_available():
+    """检查CLIP模型是否可用"""
+    return model is not None and preprocess is not None
+
+def encode_image(image_path: str) -> torch.Tensor:
+    """编码图片为向量"""
+    if not is_clip_available():
+        raise RuntimeError("CLIP模型未初始化")
+
+    image = Image.open(image_path).convert("RGB")
+    image_tensor = preprocess(image).unsqueeze(0).to(device)
+    with torch.no_grad():
+        features = model.encode_image(image_tensor)
+        features = features / features.norm(p=2, dim=-1, keepdim=True)
+    return features.cpu()
+
+def encode_text(text: Union[str, List[str]]) -> torch.Tensor:
+    """编码文本为向量"""
+    if not is_clip_available():
+        raise RuntimeError("CLIP模型未初始化")
+
+    texts = [text] if isinstance(text, str) else text
+    text_tokens = clip.tokenize(texts).to(device)
+    with torch.no_grad():
+        features = model.encode_text(text_tokens)
+        features = features / features.norm(p=2, dim=-1, keepdim=True)
+    return features.cpu()

config.py

@@ -0,0 +1,472 @@
+import logging
+import os
+
+# 解决OpenMP库冲突问题
+os.environ["KMP_DUPLICATE_LIB_OK"] = "TRUE"
+# 设置CPU线程数为CPU核心数，提高CPU利用率
+import multiprocessing
+cpu_cores = multiprocessing.cpu_count()
+os.environ["OMP_NUM_THREADS"] = str(min(cpu_cores, 8))  # 最多使用8个线程
+os.environ["MKL_NUM_THREADS"] = str(min(cpu_cores, 8))
+os.environ["NUMEXPR_NUM_THREADS"] = str(min(cpu_cores, 8))
+
+# 修复torchvision兼容性问题
+try:
+    import torchvision.transforms.functional_tensor
+except ImportError:
+    # 为缺失的functional_tensor模块创建兼容性补丁
+    import torchvision.transforms.functional as F
+    import torchvision.transforms as transforms
+    import sys
+    from types import ModuleType
+
+    # 创建functional_tensor模块
+    functional_tensor = ModuleType('torchvision.transforms.functional_tensor')
+
+    # 添加常用的函数映射
+    if hasattr(F, 'rgb_to_grayscale'):
+        functional_tensor.rgb_to_grayscale = F.rgb_to_grayscale
+    if hasattr(F, 'adjust_brightness'):
+        functional_tensor.adjust_brightness = F.adjust_brightness
+    if hasattr(F, 'adjust_contrast'):
+        functional_tensor.adjust_contrast = F.adjust_contrast
+    if hasattr(F, 'adjust_saturation'):
+        functional_tensor.adjust_saturation = F.adjust_saturation
+    if hasattr(F, 'normalize'):
+        functional_tensor.normalize = F.normalize
+    if hasattr(F, 'resize'):
+        functional_tensor.resize = F.resize
+    if hasattr(F, 'crop'):
+        functional_tensor.crop = F.crop
+    if hasattr(F, 'pad'):
+        functional_tensor.pad = F.pad
+
+    # 将模块添加到sys.modules
+    sys.modules['torchvision.transforms.functional_tensor'] = functional_tensor
+    transforms.functional_tensor = functional_tensor
+
+# 环境变量配置 - 禁用TensorFlow优化和GPU
+os.environ["TF_ENABLE_ONEDNN_OPTS"] = "0"
+os.environ["TF_CPP_MIN_LOG_LEVEL"] = "2"
+os.environ["CUDA_VISIBLE_DEVICES"] = "-1"  # 强制使用CPU
+os.environ["TF_FORCE_GPU_ALLOW_GROWTH"] = "false"
+
+# 修复PyTorch兼容性问题
+try:
+    import torch
+    import torch.onnx
+
+    # 修复GFPGAN的ONNX兼容性
+    if not hasattr(torch.onnx._internal.exporter, 'ExportOptions'):
+        from types import SimpleNamespace
+        torch.onnx._internal.exporter.ExportOptions = SimpleNamespace
+
+    # 修复ModelScope的PyTree兼容性 - 更完整的实现
+    import torch.utils
+    if not hasattr(torch.utils, '_pytree'):
+        # 如果_pytree模块不存在，创建一个
+        from types import ModuleType
+        torch.utils._pytree = ModuleType('_pytree')
+
+    pytree = torch.utils._pytree
+
+    if not hasattr(pytree, 'register_pytree_node'):
+        def register_pytree_node(typ, flatten_fn, unflatten_fn, *, flatten_with_keys_fn=None, **kwargs):
+            """兼容性实现：注册PyTree节点类型"""
+            pass  # 简单实现，不做实际操作
+        pytree.register_pytree_node = register_pytree_node
+
+    if not hasattr(pytree, 'tree_flatten'):
+        def tree_flatten(tree, is_leaf=None):
+            """兼容性实现：展平树结构"""
+            if isinstance(tree, (list, tuple)):
+                flat = []
+                spec = []
+                for i, item in enumerate(tree):
+                    if isinstance(item, (list, tuple, dict)):
+                        sub_flat, sub_spec = tree_flatten(item, is_leaf)
+                        flat.extend(sub_flat)
+                        spec.append((i, sub_spec))
+                    else:
+                        flat.append(item)
+                        spec.append((i, None))
+                return flat, (type(tree), spec)
+            elif isinstance(tree, dict):
+                flat = []
+                spec = []
+                for key, value in sorted(tree.items()):
+                    if isinstance(value, (list, tuple, dict)):
+                        sub_flat, sub_spec = tree_flatten(value, is_leaf)
+                        flat.extend(sub_flat)
+                        spec.append((key, sub_spec))
+                    else:
+                        flat.append(value)
+                        spec.append((key, None))
+                return flat, (dict, spec)
+            else:
+                return [tree], None
+        pytree.tree_flatten = tree_flatten
+
+    if not hasattr(pytree, 'tree_unflatten'):
+        def tree_unflatten(values, spec):
+            """兼容性实现：重构树结构"""
+            if spec is None:
+                return values[0] if values else None
+
+            tree_type, tree_spec = spec
+            if tree_type in (list, tuple):
+                result = []
+                value_idx = 0
+                for pos, sub_spec in tree_spec:
+                    if sub_spec is None:
+                        result.append(values[value_idx])
+                        value_idx += 1
+                    else:
+                        # 计算子树需要的值数量
+                        sub_count = _count_tree_values(sub_spec)
+                        sub_values = values[value_idx:value_idx + sub_count]
+                        result.append(tree_unflatten(sub_values, sub_spec))
+                        value_idx += sub_count
+                return tree_type(result)
+            elif tree_type == dict:
+                result = {}
+                value_idx = 0
+                for key, sub_spec in tree_spec:
+                    if sub_spec is None:
+                        result[key] = values[value_idx]
+                        value_idx += 1
+                    else:
+                        sub_count = _count_tree_values(sub_spec)
+                        sub_values = values[value_idx:value_idx + sub_count]
+                        result[key] = tree_unflatten(sub_values, sub_spec)
+                        value_idx += sub_count
+                return result
+            return values[0] if values else None
+        pytree.tree_unflatten = tree_unflatten
+
+    if not hasattr(pytree, 'tree_map'):
+        def tree_map(fn, tree, *other_trees, is_leaf=None):
+            """兼容性实现：树映射"""
+            flat, spec = tree_flatten(tree, is_leaf)
+            if other_trees:
+                other_flats = [tree_flatten(t, is_leaf)[0] for t in other_trees]
+                mapped = [fn(x, *others) for x, *others in zip(flat, *other_flats)]
+            else:
+                mapped = [fn(x) for x in flat]
+            return tree_unflatten(mapped, spec)
+        pytree.tree_map = tree_map
+
+    # 辅助函数
+    def _count_tree_values(spec):
+        """计算树规格中的值数量"""
+        if spec is None:
+            return 1
+        tree_type, tree_spec = spec
+        return sum(_count_tree_values(sub_spec) if sub_spec else 1 for _, sub_spec in tree_spec)
+
+    # 修复pyarrow兼容性问题
+    try:
+        import pyarrow
+        if not hasattr(pyarrow, 'PyExtensionType'):
+            # 为旧版本pyarrow添加PyExtensionType兼容性
+            pyarrow.PyExtensionType = type('PyExtensionType', (), {})
+    except ImportError:
+        pass
+
+except (ImportError, AttributeError) as e:
+    print(f"Warning: PyTorch/PyArrow compatibility patch failed: {e}")
+    pass
+IMAGES_DIR = os.environ.get("IMAGES_DIR", "~/app/data/images")
+OUTPUT_DIR = IMAGES_DIR
+
+# 明星图库目录配置
+CELEBRITY_SOURCE_DIR = os.environ.get(
+    "CELEBRITY_SOURCE_DIR", "~/apps/chinese_celeb_imgs"
+).strip()
+if CELEBRITY_SOURCE_DIR:
+    CELEBRITY_SOURCE_DIR = os.path.expanduser(CELEBRITY_SOURCE_DIR)
+
+CELEBRITY_FIND_THRESHOLD = float(
+    os.environ.get("CELEBRITY_FIND_THRESHOLD", 0.88)
+)
+
+# BOS 对象存储配置（默认存储为Base64编码字符串）
+BOS_ACCESS_KEY = os.environ.get(
+    "BOS_ACCESS_KEY", "YjljNWQxYjZiMDdiNDU5ZGIzNGZmNjdlMzMzY2QxZDE="
+).strip()
+BOS_SECRET_KEY = os.environ.get(
+    "BOS_SECRET_KEY", "MGE4Y2Y1ZTk5MDQ4NGYyMTk4NmVmODM5MjI4Y2U0N2I="
+).strip()
+BOS_ENDPOINT = os.environ.get(
+    "BOS_ENDPOINT", "https://s3.bj.bcebos.com"
+).strip()
+BOS_BUCKET_NAME = os.environ.get("BOS_BUCKET_NAME", "hbgs-travel").strip()
+BOS_IMAGE_DIR = os.environ.get("BOS_IMAGE_DIR", "20220808").strip()
+_bos_enabled_env = os.environ.get("BOS_UPLOAD_ENABLED")
+if _bos_enabled_env is not None:
+    BOS_UPLOAD_ENABLED = _bos_enabled_env.lower() in ("1", "true", "on")
+else:
+    BOS_UPLOAD_ENABLED = all(
+        [
+            BOS_ACCESS_KEY.strip(),
+            BOS_SECRET_KEY.strip(),
+            BOS_ENDPOINT,
+            BOS_BUCKET_NAME,
+        ]
+    )
+APP_SECRET_TOKEN = os.environ.get("APP_SECRET_TOKEN", "Abdc@q1")
+HOSTNAME = os.environ.get("HOSTNAME", "default-hostname")
+MODELS_PATH = os.environ.get("MODELS_PATH", "~/apps/ai/models")
+DEEPFACE_HOME = os.environ.get("DEEPFACE_HOME", "~/apps/ai")
+os.environ["DEEPFACE_HOME"] = DEEPFACE_HOME
+
+# 设置GFPGAN相关模型下载路径
+GFPGAN_MODEL_DIR = "~/apps/ai/models"
+os.makedirs(GFPGAN_MODEL_DIR, exist_ok=True)
+
+# 设置各种模型库的下载目录环境变量
+os.environ["GFPGAN_MODEL_ROOT"] = GFPGAN_MODEL_DIR
+os.environ["FACEXLIB_CACHE_DIR"] = GFPGAN_MODEL_DIR
+os.environ["BASICSR_CACHE_DIR"] = GFPGAN_MODEL_DIR
+os.environ["REALESRGAN_MODEL_ROOT"] = GFPGAN_MODEL_DIR
+os.environ["HUB_CACHE_DIR"] = GFPGAN_MODEL_DIR  # PyTorch Hub缓存
+
+# 设置rembg模型下载路径到统一的AI模型目录
+REMBG_MODEL_DIR = os.path.expanduser(MODELS_PATH.replace("$HOME", "~"))
+os.environ["U2NET_HOME"] = REMBG_MODEL_DIR  # u2net模型缓存目录
+os.environ["REMBG_HOME"] = REMBG_MODEL_DIR  # rembg通用缓存目录
+
+IMG_QUALITY = float(os.environ.get("IMG_QUALITY", 0.5))
+FACE_CONFIDENCE = float(os.environ.get("FACE_CONFIDENCE", 0.7))
+AGE_CONFIDENCE = float(os.environ.get("AGE_CONFIDENCE", 0.99))
+GENDER_CONFIDENCE = float(os.environ.get("GENDER_CONFIDENCE", 1.1))
+UPSCALE_SIZE = int(os.environ.get("UPSCALE_SIZE", 2))
+SAVE_QUALITY = int(os.environ.get("SAVE_QUALITY", 90))
+REALESRGAN_MODEL = os.environ.get("REALESRGAN_MODEL", "realesr-general-x4v3")
+# yolov11n-face.pt / yolov8n-face.pt
+YOLO_MODEL = os.environ.get("YOLO_MODEL", "yolov8n-face.pt")
+# mobilenetv3/resnet50
+RVM_MODEL = os.environ.get("RVM_MODEL", "resnet50")
+RVM_LOCAL_REPO = os.environ.get("RVM_LOCAL_REPO", "").strip()
+RVM_WEIGHTS_PATH = os.environ.get("RVM_WEIGHTS_PATH", "").strip()
+DRAW_SCORE = os.environ.get("DRAW_SCORE", "true").lower() in ("1", "true", "on")
+
+# 颜值评分温和提升配置（默认开启；默认区间与力度：区间=[6.0, 8.0]，gamma=0.3）
+# - BEAUTY_ADJUST_ENABLED: 是否开启提分
+# - BEAUTY_ADJUST_MIN: 提分下限（低于该值不提分）
+# - BEAUTY_ADJUST_MAX: 提分上限（目标上限；仅在 [min, max) 区间内提分）
+# - BEAUTY_ADJUST_THRESHOLD: 兼容旧配置，等价于 BEAUTY_ADJUST_MAX
+# - BEAUTY_ADJUST_GAMMA: 提分力度，(0,1]，越小提升越多
+BEAUTY_ADJUST_ENABLED = os.environ.get("BEAUTY_ADJUST_ENABLED", "true").lower() in ("1", "true", "on")
+BEAUTY_ADJUST_MIN = float(os.environ.get("BEAUTY_ADJUST_MIN", 1.0))
+# 向后兼容：未提供 BEAUTY_ADJUST_MAX 时，使用旧的 BEAUTY_ADJUST_THRESHOLD 或 8.0
+_legacy_thr = os.environ.get("BEAUTY_ADJUST_THRESHOLD")
+BEAUTY_ADJUST_MAX = float(os.environ.get("BEAUTY_ADJUST_MAX", _legacy_thr if _legacy_thr is not None else 8.0))
+BEAUTY_ADJUST_GAMMA = float(os.environ.get("BEAUTY_ADJUST_GAMMA", 0.5))  # 0<gamma<=1，越小提升越多
+
+# 兼容旧引用，保留变量名（不再直接使用于逻辑内部）
+BEAUTY_ADJUST_THRESHOLD = BEAUTY_ADJUST_MAX
+
+# 整体协调性分数温和提升配置（默认开启；默认阈值与力度：T=8.0, gamma=0.5）
+HARMONY_ADJUST_ENABLED = os.environ.get("HARMONY_ADJUST_ENABLED", "true").lower() in ("1", "true", "on")
+HARMONY_ADJUST_THRESHOLD = float(os.environ.get("HARMONY_ADJUST_THRESHOLD", 9.0))
+HARMONY_ADJUST_GAMMA = float(os.environ.get("HARMONY_ADJUST_GAMMA", 0.3))
+
+# 启动优化：是否在启动时自动初始化/预热重型组件
+ENABLE_WARMUP = os.environ.get("ENABLE_WARMUP", "false").lower() in ("1", "true", "on")
+AUTO_INIT_ANALYZER = os.environ.get("AUTO_INIT_ANALYZER", "true").lower() in ("1", "true", "on")
+AUTO_INIT_GFPGAN = os.environ.get("AUTO_INIT_GFPGAN", "false").lower() in ("1", "true", "on")
+AUTO_INIT_DDCOLOR = os.environ.get("AUTO_INIT_DDCOLOR", "false").lower() in ("1", "true", "on")
+AUTO_INIT_REALESRGAN = os.environ.get("AUTO_INIT_REALESRGAN", "false").lower() in ("1", "true", "on")
+AUTO_INIT_REMBG = os.environ.get("AUTO_INIT_REMBG", "false").lower() in ("1", "true", "on")
+AUTO_INIT_ANIME_STYLE = os.environ.get("AUTO_INIT_ANIME_STYLE", "false").lower() in ("1", "true", "on")
+AUTO_INIT_RVM = os.environ.get("AUTO_INIT_RVM", "false").lower() in ("1", "true", "on")
+
+# 定时任务相关配置
+CLEANUP_INTERVAL_HOURS = float(os.environ.get("CLEANUP_INTERVAL_HOURS", 12.0))  # 清理任务执行间隔（小时），默认1小时
+CLEANUP_AGE_HOURS = float(os.environ.get("CLEANUP_AGE_HOURS", 12.0))  # 清理文件的年龄阈值（小时），默认1小时
+
+log_level_str = os.getenv("LOG_LEVEL", "INFO").upper()
+log_level = getattr(logging, log_level_str, logging.INFO)
+
+# 日志开关配置 - 控制是否启用所有日志输出
+ENABLE_LOGGING = os.environ.get("ENABLE_LOGGING", "true").lower() in ("1", "true", "on")
+
+# 功能开关配置
+ENABLE_DDCOLOR = os.environ.get("ENABLE_DDCOLOR", "true").lower() in ("1", "true", "on")
+ENABLE_REALESRGAN = os.environ.get("ENABLE_REALESRGAN", "true").lower() in ("1", "true", "on")
+ENABLE_GFPGAN = os.environ.get("ENABLE_GFPGAN", "true").lower() in ("1", "true", "on")
+ENABLE_ANIME_STYLE = os.environ.get("ENABLE_ANIME_STYLE", "true").lower() in ("1", "true", "on")
+ENABLE_ANIME_PRELOAD = os.environ.get("ENABLE_ANIME_PRELOAD", "false").lower() in ("1", "true", "on")
+ENABLE_RVM = os.environ.get("ENABLE_RVM", "true").lower() in ("1", "true", "on")
+
+# 微信小程序配置（需要替换为你的实际值）
+WECHAT_APPID = "wxe520a15ff9642313"
+WECHAT_SECRET = "9a4ca8b0d9a8c8b7eee338c108bfc11f"
+
+# 颜值评分模块配置
+FACE_SCORE_MAX_IMAGES = int(os.environ.get("FACE_SCORE_MAX_IMAGES", 10))  # 颜值评分最大上传图片数量
+
+# 女性年龄调整配置 - 对于20岁以上的女性，显示的年龄会减去指定岁数
+FEMALE_AGE_ADJUSTMENT = int(os.environ.get("FEMALE_AGE_ADJUSTMENT", 3))  # 默认减3岁
+FEMALE_AGE_ADJUSTMENT_THRESHOLD = int(os.environ.get("FEMALE_AGE_ADJUSTMENT_THRESHOLD", 20))  # 年龄阈值，默认20岁
+
+# 配置日志
+if ENABLE_LOGGING:
+    logging.basicConfig(
+        level=log_level,
+        format="[%(asctime)s] [%(levelname)s] %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+    logger = logging.getLogger(__name__)
+else:
+    # 禁用所有日志输出
+    logging.basicConfig(level=logging.CRITICAL + 10)
+    logger = logging.getLogger(__name__)
+    logger.disabled = True
+
+# 全局变量存储 access_token
+access_token_cache = {"token": None, "expires_at": 0}
+
+# 尝试导入依赖
+try:
+    from deepface import DeepFace
+
+    DEEPFACE_AVAILABLE = True
+except ImportError:
+    print("Warning: DeepFace not installed. Install with: pip install deepface")
+    DEEPFACE_AVAILABLE = False
+
+try:
+    import mediapipe as mp
+
+    MEDIAPIPE_AVAILABLE = True
+except ImportError:
+    print("Warning: mediapipe not installed. Install with: pip install mediapipe")
+    MEDIAPIPE_AVAILABLE = False
+
+# 为了保持向后兼容，保留 DLIB_AVAILABLE 变量名
+DLIB_AVAILABLE = MEDIAPIPE_AVAILABLE
+
+try:
+    from ultralytics import YOLO
+
+    YOLO_AVAILABLE = True
+except ImportError:
+    print("Warning: ultralytics not installed. Install with: pip install ultralytics")
+    YOLO_AVAILABLE = False
+
+# 检查GFPGAN是否启用和可用
+if ENABLE_GFPGAN:
+    try:
+        # 检查GFPGAN相关文件是否存在
+        gfpgan_files_exist = True
+        required_files = [
+            "gfpgan_restorer.py",
+            "gfpgan/weights/detection_Resnet50_Final.pth",
+            "gfpgan/weights/parsing_parsenet.pth"
+        ]
+
+        for file_path in required_files:
+            if not os.path.exists(file_path):
+                print(f"Missing GFPGAN file: {file_path}")
+                gfpgan_files_exist = False
+
+        if gfpgan_files_exist:
+            from gfpgan_restorer import GFPGANRestorer
+            GFPGAN_AVAILABLE = True
+            logger.info("GFPGAN photo restoration feature is enabled and available")
+        else:
+            GFPGAN_AVAILABLE = False
+            print("Warning: GFPGAN files missing, functionality disabled")
+    except ImportError as e:
+        print(f"Warning: GFPGAN enabled but not available: {e}")
+        GFPGAN_AVAILABLE = False
+        logger.warning(f"GFPGAN photo restoration feature is enabled but import failed: {e}")
+else:
+    GFPGAN_AVAILABLE = False
+    logger.info("GFPGAN photo restoration feature is disabled (via ENABLE_GFPGAN environment variable)")
+
+# 检查DDColor是否启用和可用
+if ENABLE_DDCOLOR:
+    try:
+        from ddcolor_colorizer import DDColorColorizer
+        DDCOLOR_AVAILABLE = True
+        logger.info("DDColor feature is enabled and available")
+    except ImportError as e:
+        print(f"Warning: DDColor enabled but not available: {e}")
+        DDCOLOR_AVAILABLE = False
+        logger.warning(f"DDColor feature is enabled but import failed: {e}")
+else:
+    DDCOLOR_AVAILABLE = False
+    logger.info("DDColor feature is disabled (via ENABLE_DDCOLOR environment variable)")
+
+# 只使用GFPGAN修复器
+SIMPLE_RESTORER_AVAILABLE = False
+
+# 检查Real-ESRGAN是否启用和可用
+if ENABLE_REALESRGAN:
+    try:
+        from realesrgan_upscaler import RealESRGANUpscaler
+        REALESRGAN_AVAILABLE = True
+        logger.info("Real-ESRGAN super resolution feature is enabled and available")
+    except ImportError as e:
+        print(f"Warning: Real-ESRGAN enabled but not available: {e}")
+        REALESRGAN_AVAILABLE = False
+        logger.warning(f"Real-ESRGAN super resolution feature is enabled but import failed: {e}")
+else:
+    REALESRGAN_AVAILABLE = False
+    logger.info("Real-ESRGAN super resolution feature is disabled (via ENABLE_REALESRGAN environment variable)")
+
+# rembg功能开关配置
+ENABLE_REMBG = os.environ.get("ENABLE_REMBG", "true").lower() in ("1", "true", "on")
+
+# 检查rembg是否启用和可用
+if ENABLE_REMBG:
+    try:
+        import rembg
+        from rembg import new_session
+        REMBG_AVAILABLE = True
+        logger.info("rembg background removal feature is enabled and available")
+        logger.info(f"rembg model storage path: {REMBG_MODEL_DIR}")
+    except ImportError as e:
+        print(f"Warning: rembg enabled but not available: {e}")
+        REMBG_AVAILABLE = False
+        logger.warning(f"rembg background removal feature is enabled but import failed: {e}")
+else:
+    REMBG_AVAILABLE = False
+    logger.info("rembg background removal feature is disabled (via ENABLE_REMBG environment variable)")
+
+CLIP_AVAILABLE = False
+
+# 检查Anime Style是否启用和可用
+if ENABLE_ANIME_STYLE:
+    try:
+        from anime_stylizer import AnimeStylizer
+        ANIME_STYLE_AVAILABLE = True
+        logger.info("Anime stylization feature is enabled and available")
+    except ImportError as e:
+        print(f"Warning: Anime Style enabled but not available: {e}")
+        ANIME_STYLE_AVAILABLE = False
+        logger.warning(f"Anime stylization feature is enabled but import failed: {e}")
+else:
+    ANIME_STYLE_AVAILABLE = False
+    logger.info("Anime stylization feature is disabled (via ENABLE_ANIME_STYLE environment variable)")
+
+# RVM功能开关配置
+ENABLE_RVM = os.environ.get("ENABLE_RVM", "true").lower() in ("1", "true", "on")
+
+# 检查RVM是否启用和可用
+if ENABLE_RVM:
+    try:
+        import torch
+        # 检查是否可以加载RVM模型
+        RVM_AVAILABLE = True
+        logger.info("RVM background removal feature is enabled and available")
+    except ImportError as e:
+        print(f"Warning: RVM enabled but not available: {e}")
+        RVM_AVAILABLE = False
+        logger.warning(f"RVM background removal feature is enabled but import failed: {e}")
+else:
+    RVM_AVAILABLE = False
+    logger.info("RVM background removal feature is disabled (via ENABLE_RVM environment variable)")

database.py

@@ -0,0 +1,376 @@
+import asyncio
+import json
+import os
+from contextlib import asynccontextmanager
+from datetime import datetime
+from typing import Any, Dict, Iterable, List, Optional, Sequence
+
+import aiomysql
+from aiomysql.cursors import DictCursor
+
+from config import IMAGES_DIR, logger
+
+MYSQL_HOST = os.environ.get(
+    "MYSQL_HOST", "rm-bp1205c91psn350b3lo.mysql.rds.aliyuncs.com"
+)
+MYSQL_PORT = int(os.environ.get("MYSQL_PORT", "3306"))
+MYSQL_DB = os.environ.get("MYSQL_DB", "pexar-service-test")
+MYSQL_USER = os.environ.get("MYSQL_USER", "lexar")
+MYSQL_PASSWORD = os.environ.get("MYSQL_PASSWORD", "lexar20241119*")
+MYSQL_POOL_MIN_SIZE = int(os.environ.get("MYSQL_POOL_MIN_SIZE", "1"))
+MYSQL_POOL_MAX_SIZE = int(os.environ.get("MYSQL_POOL_MAX_SIZE", "10"))
+
+_pool: Optional[aiomysql.Pool] = None
+_pool_lock = asyncio.Lock()
+
+
+async def init_mysql_pool() -> aiomysql.Pool:
+  """初始化 MySQL 连接池"""
+  global _pool
+  if _pool is not None:
+    return _pool
+
+  async with _pool_lock:
+    if _pool is not None:
+      return _pool
+    try:
+      _pool = await aiomysql.create_pool(
+          host=MYSQL_HOST,
+          port=MYSQL_PORT,
+          user=MYSQL_USER,
+          password=MYSQL_PASSWORD,
+          db=MYSQL_DB,
+          minsize=MYSQL_POOL_MIN_SIZE,
+          maxsize=MYSQL_POOL_MAX_SIZE,
+          autocommit=True,
+          charset="utf8mb4",
+          cursorclass=DictCursor,
+      )
+      logger.info(
+          "MySQL 连接池初始化成功，host=%s db=%s",
+          MYSQL_HOST,
+          MYSQL_DB,
+      )
+    except Exception as exc:
+      logger.error(f"初始化 MySQL 连接池失败: {exc}")
+      raise
+  return _pool
+
+
+async def close_mysql_pool() -> None:
+  """关闭 MySQL 连接池"""
+  global _pool
+  if _pool is None:
+    return
+
+  async with _pool_lock:
+    if _pool is None:
+      return
+    _pool.close()
+    await _pool.wait_closed()
+    _pool = None
+    logger.info("MySQL 连接池已关闭")
+
+
+@asynccontextmanager
+async def get_connection():
+  """获取连接池中的连接"""
+  if _pool is None:
+    await init_mysql_pool()
+  assert _pool is not None
+  conn = await _pool.acquire()
+  try:
+    yield conn
+  finally:
+    _pool.release(conn)
+
+
+async def execute(query: str,
+    params: Sequence[Any] | Dict[str, Any] | None = None) -> None:
+  """执行写入类 SQL"""
+  async with get_connection() as conn:
+    async with conn.cursor() as cursor:
+      await cursor.execute(query, params or ())
+
+
+async def fetch_all(
+    query: str, params: Sequence[Any] | Dict[str, Any] | None = None
+) -> List[Dict[str, Any]]:
+  """执行查询并返回全部结果"""
+  async with get_connection() as conn:
+    async with conn.cursor() as cursor:
+      await cursor.execute(query, params or ())
+      rows = await cursor.fetchall()
+      return list(rows)
+
+
+def _serialize_extra(extra: Optional[Dict[str, Any]]) -> Optional[str]:
+  if extra is None:
+    return None
+  try:
+    return json.dumps(extra, ensure_ascii=False)
+  except Exception:
+    logger.warning("无法序列化 extra_metadata，已忽略")
+    return None
+
+
+async def upsert_image_record(
+    *,
+    file_path: str,
+    category: str,
+    nickname: Optional[str],
+    score: float,
+    is_cropped_face: bool,
+    size_bytes: int,
+    last_modified: datetime,
+    bos_uploaded: bool,
+    hostname: Optional[str] = None,
+    extra_metadata: Optional[Dict[str, Any]] = None,
+) -> None:
+  """写入或更新图片记录"""
+  query = """
+        INSERT INTO tpl_app_processed_images (
+            file_path,
+            category,
+            nickname,
+            score,
+            is_cropped_face,
+            size_bytes,
+            last_modified,
+            bos_uploaded,
+            hostname,
+            extra_metadata
+        ) VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s)
+        ON DUPLICATE KEY UPDATE
+            category = VALUES(category),
+            nickname = VALUES(nickname),
+            score = VALUES(score),
+            is_cropped_face = VALUES(is_cropped_face),
+            size_bytes = VALUES(size_bytes),
+            last_modified = VALUES(last_modified),
+            bos_uploaded = VALUES(bos_uploaded),
+            hostname = VALUES(hostname),
+            extra_metadata = VALUES(extra_metadata),
+            updated_at = CURRENT_TIMESTAMP
+    """
+  extra_value = _serialize_extra(extra_metadata)
+  await execute(
+      query,
+      (
+        file_path,
+        category,
+        nickname,
+        score,
+        1 if is_cropped_face else 0,
+        size_bytes,
+        last_modified,
+        1 if bos_uploaded else 0,
+        hostname,
+        extra_value,
+      ),
+  )
+
+
+async def fetch_paged_image_records(
+    *,
+    category: Optional[str],
+    nickname: Optional[str],
+    offset: int,
+    limit: int,
+) -> List[Dict[str, Any]]:
+  """按条件分页查询图片记录"""
+  where_clauses: List[str] = []
+  params: List[Any] = []
+  if category and category != "all":
+    where_clauses.append("category = %s")
+    params.append(category)
+  if nickname:
+    where_clauses.append("nickname = %s")
+    params.append(nickname)
+  where_sql = f"WHERE {' AND '.join(where_clauses)}" if where_clauses else ""
+  query = f"""
+        SELECT
+            file_path,
+            category,
+            nickname,
+            score,
+            is_cropped_face,
+            size_bytes,
+            last_modified,
+            bos_uploaded,
+            hostname
+        FROM tpl_app_processed_images
+        {where_sql}
+        ORDER BY last_modified DESC, id DESC
+        LIMIT %s OFFSET %s
+    """
+  params.extend([limit, offset])
+  return await fetch_all(query, params)
+
+
+async def count_image_records(
+    *, category: Optional[str], nickname: Optional[str]
+) -> int:
+  """按条件统计图片记录数量"""
+  where_clauses: List[str] = []
+  params: List[Any] = []
+  if category and category != "all":
+    where_clauses.append("category = %s")
+    params.append(category)
+  if nickname:
+    where_clauses.append("nickname = %s")
+    params.append(nickname)
+  where_sql = f"WHERE {' AND '.join(where_clauses)}" if where_clauses else ""
+  query = f"SELECT COUNT(*) AS total FROM tpl_app_processed_images {where_sql}"
+  rows = await fetch_all(query, params)
+  if not rows:
+    return 0
+  return int(rows[0].get("total", 0) or 0)
+
+
+async def fetch_today_category_counts() -> List[Dict[str, Any]]:
+  """统计当天按类别分组的数量"""
+  query = """
+        SELECT
+            COALESCE(category, 'unknown') AS category,
+            COUNT(*) AS count
+        FROM tpl_app_processed_images
+        WHERE DATE(last_modified) = CURDATE()
+        GROUP BY COALESCE(category, 'unknown')
+    """
+  rows = await fetch_all(query)
+  return [
+    {
+      "category": str(row.get("category") or "unknown"),
+      "count": int(row.get("count") or 0),
+    }
+    for row in rows
+  ]
+
+
+async def fetch_records_by_paths(file_paths: Iterable[str]) -> Dict[
+  str, Dict[str, Any]]:
+  """根据文件名批量查询图片记录"""
+  paths = list({path for path in file_paths if path})
+  if not paths:
+    return {}
+
+  placeholders = ", ".join(["%s"] * len(paths))
+  query = f"""
+        SELECT
+            file_path,
+            category,
+            nickname,
+            score,
+            is_cropped_face,
+            size_bytes,
+            last_modified,
+            bos_uploaded,
+            hostname
+        FROM tpl_app_processed_images
+        WHERE file_path IN ({placeholders})
+    """
+  rows = await fetch_all(query, paths)
+  return {row["file_path"]: row for row in rows}
+
+
+_IMAGES_DIR_ABS = os.path.abspath(os.path.expanduser(IMAGES_DIR))
+
+
+def _normalize_file_path(file_path: str) -> Optional[str]:
+  """将绝对路径转换为相对 IMAGES_DIR 的文件名"""
+  try:
+    abs_path = os.path.abspath(os.path.expanduser(file_path))
+    if os.path.isdir(abs_path):
+      return None
+    if os.path.commonpath([_IMAGES_DIR_ABS, abs_path]) != _IMAGES_DIR_ABS:
+      return os.path.basename(abs_path)
+    rel_path = os.path.relpath(abs_path, _IMAGES_DIR_ABS)
+    return rel_path.replace("\\", "/")
+  except Exception:
+    return None
+
+
+def infer_category_from_filename(filename: str, default: str = "other") -> str:
+  """根据文件名推断类别"""
+  lower_name = filename.lower()
+  if "_face_" in lower_name:
+    return "face"
+  if lower_name.endswith("_original.webp") or "_original" in lower_name:
+    return "original"
+  if "_restore" in lower_name:
+    return "restore"
+  if "_upcolor" in lower_name:
+    return "upcolor"
+  if "_compress" in lower_name:
+    return "compress"
+  if "_upscale" in lower_name:
+    return "upscale"
+  if "_anime_style_" in lower_name:
+    return "anime_style"
+  if "_grayscale" in lower_name:
+    return "grayscale"
+  if "_id_photo" in lower_name or "_save_id_photo" in lower_name:
+    return "id_photo"
+  if "_grid_" in lower_name:
+    return "grid"
+  if "_rvm_id_photo" in lower_name:
+    return "rvm"
+  if "_celebrity_" in lower_name or "_celebrity" in lower_name:
+    return "celebrity"
+  return default
+
+
+from config import HOSTNAME
+
+async def record_image_creation(
+    *,
+    file_path: str,
+    nickname: Optional[str],
+    score: float = 0.0,
+    category: Optional[str] = None,
+    bos_uploaded: bool = False,
+    extra_metadata: Optional[Dict[str, Any]] = None,
+) -> None:
+  """
+  记录图片元数据到数据库，如果数据库不可用则静默忽略。
+  :param file_path: 绝对或相对文件路径
+  :param nickname: 用户昵称
+  :param score: 关联得分
+  :param category: 文件类别，未提供时自动根据文件名推断
+  :param bos_uploaded: 是否已上传至 BOS
+  :param extra_metadata: 额外信息
+  """
+  normalized = _normalize_file_path(file_path)
+  if normalized is None:
+    logger.info("record_image_creation: 无法计算文件名，路径=%s", file_path)
+    return
+
+  abs_path = os.path.join(_IMAGES_DIR_ABS, normalized)
+  if not os.path.isfile(abs_path):
+    logger.info("record_image_creation: 文件不存在，跳过记录 file=%s", abs_path)
+    return
+
+  try:
+    stat = os.stat(abs_path)
+    category_name = category or infer_category_from_filename(normalized)
+    is_cropped_face = "_face_" in normalized and normalized.count("_") >= 2
+    last_modified = datetime.fromtimestamp(stat.st_mtime)
+
+    nickname_value = nickname.strip() if isinstance(nickname,
+                                                    str) and nickname.strip() else None
+
+    await upsert_image_record(
+        file_path=normalized,
+        category=category_name,
+        nickname=nickname_value,
+        score=score,
+        is_cropped_face=is_cropped_face,
+        size_bytes=stat.st_size,
+        last_modified=last_modified,
+        bos_uploaded=bos_uploaded,
+        hostname=HOSTNAME,
+        extra_metadata=extra_metadata,
+    )
+  except Exception as exc:
+    logger.warning(f"写入图片记录失败: {exc}")

ddcolor_colorizer.py

@@ -0,0 +1,301 @@
+import os
+import tempfile
+import time
+
+import cv2
+import numpy as np
+
+from config import logger
+
+
+class DDColorColorizer:
+    def __init__(self):
+        start_time = time.perf_counter()
+        self.colorizer = None
+        # 检查是否启用DDColor功能
+        from config import ENABLE_DDCOLOR
+        if ENABLE_DDCOLOR:
+            self._initialize_model()
+        else:
+            logger.info("DDColor feature is disabled, skipping model initialization")
+        init_time = time.perf_counter() - start_time
+        if self.colorizer is not None:
+            logger.info(f"DDColorColorizer initialized successfully, time: {init_time:.3f}s")
+        else:
+            logger.info(f"DDColorColorizer initialization completed but not available, time: {init_time:.3f}s")
+
+    def _initialize_model(self):
+        """初始化DDColor模型（使用ModelScope）"""
+        try:
+            logger.info("Initializing DDColor model (using ModelScope)...")
+
+            # 添加torch类型兼容性补丁
+            import torch
+            if not hasattr(torch, 'uint64'):
+                logger.info("Adding torch.uint64 compatibility patch...")
+                torch.uint64 = torch.int64  # 使用int64作为uint64的替代
+            if not hasattr(torch, 'uint32'):
+                logger.info("Adding torch.uint32 compatibility patch...")
+                torch.uint32 = torch.int32  # 使用int32作为uint32的替代
+            if not hasattr(torch, 'uint16'):
+                logger.info("Adding torch.uint16 compatibility patch...")
+                torch.uint16 = torch.int16  # 使用int16作为uint16的替代
+
+            # 导入ModelScope相关模块
+            from modelscope.outputs import OutputKeys
+            from modelscope.pipelines import pipeline
+            from modelscope.utils.constant import Tasks
+
+            # 初始化DDColor pipeline
+            self.colorizer = pipeline(
+                Tasks.image_colorization,
+                model='damo/cv_ddcolor_image-colorization'
+            )
+            self.OutputKeys = OutputKeys
+
+            logger.info("DDColor model initialized successfully")
+
+        except ImportError as e:
+            logger.error(f"ModelScope module import failed: {e}")
+            self.colorizer = None
+        except Exception as e:
+            logger.error(f"DDColor model initialization failed: {e}")
+            self.colorizer = None
+
+    def is_available(self):
+        """检查DDColor是否可用"""
+        return self.colorizer is not None
+
+    def is_grayscale(self, image):
+        """检查图像是否为灰度图像"""
+        if len(image.shape) == 2:
+            return True
+        elif len(image.shape) == 3:
+            # 检查是否为伪彩色图像（RGB三个通道值相等）
+            b, g, r = cv2.split(image)
+
+            # 计算通道间的差异
+            diff_bg = np.abs(b.astype(float) - g.astype(float))
+            diff_gr = np.abs(g.astype(float) - r.astype(float))
+            diff_rb = np.abs(r.astype(float) - b.astype(float))
+
+            # 计算平均差异
+            avg_diff = (np.mean(diff_bg) + np.mean(diff_gr) + np.mean(diff_rb)) / 3.0
+
+            # 计算色彩饱和度
+            hsv = cv2.cvtColor(image, cv2.COLOR_BGR2HSV)
+            saturation = hsv[:, :, 1]  # S通道
+            avg_saturation = np.mean(saturation)
+
+            # 改进的灰度检测：同时考虑通道差异和饱和度
+            is_gray = (avg_diff < 5.0) or (avg_saturation < 20.0)
+
+            logger.info(f"Grayscale detection - Average channel difference: {avg_diff:.2f}, Average saturation: {avg_saturation:.2f}, Result: {is_gray}")
+            return is_gray
+        return False
+
+    def colorize_image(self, image):
+        """
+        使用DDColor对灰度图像进行上色
+        :param image: 输入图像 (numpy array, BGR格式)
+        :return: 上色后的图像 (numpy array, BGR格式)
+        """
+        if not self.is_available():
+            logger.error("DDColor model not initialized")
+            return image
+
+        # 检查是否为灰度图像
+        if not self.is_grayscale(image):
+            logger.info("Image is already colored, no need for colorization")
+            return image
+
+        return self.colorize_image_direct(image)
+
+    def colorize_image_direct(self, image):
+        """
+        直接对图像进行上色，不检查是否为灰度图
+        使用与test_ddcolor.py相同质量的文件路径方法
+        :param image: 输入图像 (numpy array, BGR格式)
+        :return: 上色后的图像 (numpy array, BGR格式)
+        """
+        if not self.is_available():
+            logger.error("DDColor model not initialized")
+            return image
+
+        # 直接使用文件路径方法，这是经过验证效果最好的方式
+        return self._colorize_image_via_file(image)
+
+    def _colorize_image_via_file(self, image):
+        """
+        通过临时文件进行上色，尽可能模拟test_ddcolor.py的处理方式
+        :param image: 输入图像 (numpy array, BGR格式)
+        :return: 上色后的图像 (numpy array, BGR格式)
+        """
+        try:
+            logger.info("Using high-quality file path method for colorization...")
+
+            # 使用最高质量设置保存临时图像，尽可能保持原始质量
+            with tempfile.NamedTemporaryFile(suffix='.webp', delete=False) as tmp_input:
+                # 使用WebP格式以获得更好的质量和更小的文件大小
+                cv2.imwrite(tmp_input.name, image, [cv2.IMWRITE_WEBP_QUALITY, 100])
+                tmp_input_path = tmp_input.name
+
+            try:
+                logger.info(f"Temporary file saved to: {tmp_input_path}")
+
+                # 使用ModelScope进行上色 - 与test_colorization完全相同的调用方式
+                result = self.colorizer(tmp_input_path)
+
+                # 获取上色后的图像 - 与test_colorization完全相同的处理
+                colorized_image = result[self.OutputKeys.OUTPUT_IMG]
+
+                logger.info(f"Colorization output: size={colorized_image.shape}, type={colorized_image.dtype}")
+
+                # ModelScope输出的图像已经是BGR格式，不需要转换
+                # （与test_colorization保存时直接使用cv2.imwrite一致）
+                logger.info("High-quality file path method colorization completed")
+                return colorized_image
+
+            finally:
+                # 清理临时文件
+                try:
+                    os.unlink(tmp_input_path)
+                except:
+                    pass
+
+        except Exception as e:
+            logger.error(f"High-quality file path method colorization failed: {e}")
+            logger.info("Returning original image")
+            return image
+
+    def restore_and_colorize(self, image, gfpgan_restorer=None):
+        """
+        先修复后上色的组合处理（旧版本，保持兼容性）
+        :param image: 输入图像
+        :param gfpgan_restorer: GFPGAN修复器实例
+        :return: 修复并上色后的图像
+        """
+        try:
+            # 先进行修复（如果有修复器）
+            if gfpgan_restorer and gfpgan_restorer.is_available():
+                logger.info("First performing image restoration...")
+                restored_image = gfpgan_restorer.restore_image(image)
+            else:
+                restored_image = image
+
+            # 再进行上色
+            if self.is_grayscale(restored_image):
+                logger.info("Grayscale image detected, performing colorization...")
+                colorized_image = self.colorize_image(restored_image)
+                return colorized_image
+            else:
+                logger.info("Image is already colored, only returning restoration result")
+                return restored_image
+
+        except Exception as e:
+            logger.error(f"Restoration and colorization combination processing failed: {e}")
+            return image
+
+    def colorize_and_restore(self, image, gfpgan_restorer=None):
+        """
+        先上色后修复的组合处理（新版本）
+        :param image: 输入图像
+        :param gfpgan_restorer: GFPGAN修复器实例
+        :return: 上色并修复后的图像
+        """
+        try:
+            # 先进行上色（如果是灰度图）
+            if self.is_grayscale(image):
+                logger.info("Grayscale image detected, performing colorization first...")
+                colorized_image = self.colorize_image_direct(image)
+            else:
+                logger.info("Image is already colored, skipping colorization step")
+                colorized_image = image
+
+            # 再进行修复（如果有修复器）
+            if gfpgan_restorer and gfpgan_restorer.is_available():
+                logger.info("Performing restoration on the colorized image...")
+                final_image = gfpgan_restorer.restore_image(colorized_image)
+                return final_image
+            else:
+                logger.info("No restorer available, returning colorization result")
+                return colorized_image
+
+        except Exception as e:
+            logger.error(f"Colorization and restoration combination processing failed: {e}")
+            return image
+
+    def save_debug_image(self, image, filename_prefix):
+        """保存调试用的图像"""
+        try:
+            debug_path = f"{filename_prefix}_debug.webp"
+            cv2.imwrite(debug_path, image, [cv2.IMWRITE_WEBP_QUALITY, 95])
+            logger.info(f"Debug image saved: {debug_path}")
+            return debug_path
+        except Exception as e:
+            logger.error(f"Failed to save debug image: {e}")
+            return None
+
+    def test_colorization(self, test_url=None):
+        """
+        测试上色功能
+        :param test_url: 测试图像URL，默认使用官方示例
+        :return: 测试结果
+        """
+        if not self.is_available():
+            return False, "DDColor模型未初始化"
+
+        try:
+            test_url = test_url or 'https://modelscope.oss-cn-beijing.aliyuncs.com/test/images/audrey_hepburn.jpg'
+            logger.info(f"Testing DDColor colorization feature, using image: {test_url}")
+
+            result = self.colorizer(test_url)
+            colorized_img = result[self.OutputKeys.OUTPUT_IMG]
+
+            # 保存测试结果
+            test_output_path = 'ddcolor_test_result.webp'
+            cv2.imwrite(test_output_path, colorized_img, [cv2.IMWRITE_WEBP_QUALITY, 95])
+
+            logger.info(f"DDColor test successful, result saved to: {test_output_path}")
+            return True, f"测试成功，结果保存到: {test_output_path}"
+
+        except Exception as e:
+            logger.error(f"DDColor test failed: {e}")
+            return False, f"测试失败: {e}"
+
+    def test_local_image(self, image_path):
+        """
+        测试本地图像上色，用于对比分析
+        :param image_path: 本地图像路径
+        :return: 测试结果
+        """
+        if not self.is_available():
+            return False, "DDColor模型未初始化"
+
+        try:
+            logger.info(f"Testing local image colorization: {image_path}")
+
+            # 读取本地图像
+            image = cv2.imread(image_path)
+            if image is None:
+                return False, f"无法读取图像: {image_path}"
+
+            # 检查是否为灰度
+            is_gray = self.is_grayscale(image)
+            logger.info(f"Local image grayscale detection result: {is_gray}")
+
+            # 保存原图用于对比
+            self.save_debug_image(image, "original")
+
+            # 直接上色
+            colorized_image = self.colorize_image_direct(image)
+
+            # 保存上色结果
+            result_path = self.save_debug_image(colorized_image, "local_colorized")
+
+            logger.info(f"Local image colorization successful, result saved to: {result_path}")
+            return True, f"本地图像上色成功，结果保存到: {result_path}"
+
+        except Exception as e:
+            logger.error(f"Local image colorization failed: {e}")
+            return False, f"本地图像上色失败: {e}"

debug_colorize.py

@@ -0,0 +1,238 @@
+#!/usr/bin/env python3
+"""
+调试上色效果差异的脚本
+"""
+
+import sys
+import os
+import cv2
+import numpy as np
+
+# 添加当前目录到路径
+sys.path.insert(0, os.path.dirname(__file__))
+
+from ddcolor_colorizer import DDColorColorizer
+from gfpgan_restorer import GFPGANRestorer
+import logging
+
+# 设置日志
+logging.basicConfig(level=logging.INFO, format='[%(levelname)s] %(message)s')
+
+def simulate_api_processing(image_path):
+    """
+    模拟API接口的完整处理流程
+    """
+    print("\n=== 模拟API接口处理流程 ===")
+    
+    # 初始化组件
+    print("初始化GFPGAN修复器...")
+    try:
+        gfpgan_restorer = GFPGANRestorer()
+        if not gfpgan_restorer.is_available():
+            print("❌ GFPGAN不可用")
+            return None
+        print("✅ GFPGAN初始化成功")
+    except Exception as e:
+        print(f"❌ GFPGAN初始化失败: {e}")
+        return None
+    
+    print("初始化DDColor上色器...")
+    try:
+        ddcolor_colorizer = DDColorColorizer()
+        if not ddcolor_colorizer.is_available():
+            print("❌ DDColor不可用")
+            return None
+        print("✅ DDColor初始化成功")
+    except Exception as e:
+        print(f"❌ DDColor初始化失败: {e}")
+        return None
+    
+    # 读取图像
+    print(f"读取图像: {image_path}")
+    image = cv2.imread(image_path)
+    if image is None:
+        print(f"❌ 无法读取图像: {image_path}")
+        return None
+    
+    print(f"原图尺寸: {image.shape}")
+    
+    # 保存原图
+    ddcolor_colorizer.save_debug_image(image, "api_original")
+    
+    # 检查原图灰度状态
+    original_is_grayscale = ddcolor_colorizer.is_grayscale(image)
+    print(f"原图灰度检测: {original_is_grayscale}")
+    
+    # 新的处理流程：先上色再修复
+    # 步骤1: 上色处理
+    print("\n步骤1: 上色处理...")
+    if original_is_grayscale:
+        print("策略: 对原图进行上色")
+        colorized_image = ddcolor_colorizer.colorize_image_direct(image)
+        ddcolor_colorizer.save_debug_image(colorized_image, "api_colorized")
+        strategy = "先上色"
+        current_image = colorized_image
+    else:
+        print("策略: 图像已经是彩色的，跳过上色")
+        strategy = "跳过上色"
+        current_image = image
+    
+    # 步骤2: GFPGAN修复
+    print("\n步骤2: GFPGAN修复...")
+    final_image = gfpgan_restorer.restore_image(current_image)
+    print(f"修复后图像尺寸: {final_image.shape}")
+    
+    # 保存最终结果
+    result_path = ddcolor_colorizer.save_debug_image(final_image, "api_final")
+    
+    strategy += " -> 再修复"
+    
+    print(f"\n✅ API模拟完成")
+    print(f"   - 处理策略: {strategy}")
+    print(f"   - 最终结果: {result_path}")
+    
+    return {
+        'original': image,
+        'colorized': colorized_image if original_is_grayscale else None,
+        'final': final_image,
+        'strategy': strategy
+    }
+
+def test_direct_colorization(image_path):
+    """
+    测试直接上色（类似test_ddcolor.py的方式）
+    """
+    print("\n=== 测试直接上色 ===")
+    
+    colorizer = DDColorColorizer()
+    if not colorizer.is_available():
+        print("❌ DDColor不可用")
+        return None
+    
+    # 直接使用URL进行上色（和test_ddcolor.py相同）
+    print("使用官方示例URL上色...")
+    success, message = colorizer.test_colorization()
+    
+    if success:
+        print(f"✅ URL上色成功: {message}")
+    else:
+        print(f"❌ URL上色失败: {message}")
+    
+    # 对本地图像进行直接上色
+    print(f"对本地图像直接上色: {image_path}")
+    success, message = colorizer.test_local_image(image_path)
+    
+    if success:
+        print(f"✅ 本地图像上色成功: {message}")
+    else:
+        print(f"❌ 本地图像上色失败: {message}")
+
+def compare_results():
+    """
+    对比分析结果
+    """
+    print("\n=== 结果对比分析 ===")
+    
+    # 列出生成的调试图像
+    debug_files = []
+    for f in os.listdir("."):
+        if f.endswith("_debug.webp"):
+            debug_files.append(f)
+    
+    if debug_files:
+        print("生成的调试文件:")
+        for f in sorted(debug_files):
+            print(f"  - {f}")
+        
+        print("\n对比建议:")
+        print("1. 比较 original_debug.webp 和 api_original_debug.webp")
+        print("2. 比较 local_colorized_debug.webp 和 api_final_debug.webp")
+        print("3. 检查 api_restored_debug.webp 的修复效果")
+        print("4. 观察 ddcolor_test_result.webp 的官方示例效果")
+    else:
+        print("未找到调试文件")
+
+def analyze_image_quality(image_path):
+    """
+    分析图像质量指标
+    """
+    print(f"\n=== 分析图像质量: {image_path} ===")
+    
+    if not os.path.exists(image_path):
+        print(f"文件不存在: {image_path}")
+        return
+    
+    image = cv2.imread(image_path)
+    if image is None:
+        print(f"无法读取图像: {image_path}")
+        return
+    
+    # 基本信息
+    h, w, c = image.shape
+    print(f"尺寸: {w}x{h}, 通道数: {c}")
+    
+    # 亮度分析
+    gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
+    mean_brightness = np.mean(gray)
+    print(f"平均亮度: {mean_brightness:.2f}")
+    
+    # 对比度分析
+    contrast = np.std(gray)
+    print(f"对比度(标准差): {contrast:.2f}")
+    
+    # 色彩分析
+    hsv = cv2.cvtColor(image, cv2.COLOR_BGR2HSV)
+    mean_saturation = np.mean(hsv[:, :, 1])
+    print(f"平均饱和度: {mean_saturation:.2f}")
+    
+    # 锐度分析（拉普拉斯算子）
+    laplacian = cv2.Laplacian(gray, cv2.CV_64F)
+    sharpness = np.var(laplacian)
+    print(f"锐度: {sharpness:.2f}")
+
+def main():
+    """主函数"""
+    print("DDColor 上色效果调试工具")
+    print("=" * 60)
+    
+    # 可以指定测试图像路径，或使用默认路径
+    test_image_path = "/path/to/your/test/image.jpg"  # 替换为实际路径
+    
+    if len(sys.argv) > 1:
+        test_image_path = sys.argv[1]
+    
+    print(f"测试图像路径: {test_image_path}")
+    
+    if not os.path.exists(test_image_path):
+        print("⚠️  测试图像不存在，将只运行URL测试")
+        
+        # 只测试直接上色
+        test_direct_colorization(None)
+        
+    else:
+        # 分析原图质量
+        analyze_image_quality(test_image_path)
+        
+        # 测试直接上色
+        test_direct_colorization(test_image_path)
+        
+        # 模拟API处理
+        api_result = simulate_api_processing(test_image_path)
+        
+        # 分析结果图像质量
+        if os.path.exists("api_final_debug.webp"):
+            print("\n--- API处理结果质量分析 ---")
+            analyze_image_quality("api_final_debug.webp")
+        
+        if os.path.exists("local_colorized_debug.webp"):
+            print("\n--- 直接上色结果质量分析 ---")
+            analyze_image_quality("local_colorized_debug.webp")
+    
+    # 对比分析
+    compare_results()
+    
+    print("\n调试完成！")
+    print("请检查生成的调试图像来识别问题所在。")
+
+if __name__ == "__main__":
+    main()

face_analyzer.py

@@ -0,0 +1,1101 @@
+import os
+import random
+import time
+from typing import List, Dict, Any
+
+import cv2
+import numpy as np
+
+import config
+from config import logger, MODELS_PATH, OUTPUT_DIR, DEEPFACE_AVAILABLE, \
+    YOLO_AVAILABLE
+from facial_analyzer import FacialFeatureAnalyzer
+from models import ModelType
+from utils import save_image_force_compress
+
+if DEEPFACE_AVAILABLE:
+    from deepface import DeepFace
+
+# 可选导入 YOLO
+if YOLO_AVAILABLE:
+    try:
+        from ultralytics import YOLO
+
+        YOLO_AVAILABLE = True
+    except ImportError:
+        YOLO_AVAILABLE = False
+        YOLO = None
+        print("Warning: ENABLE_YOLO=true but ultralytics not available")
+
+
+class EnhancedFaceAnalyzer:
+    """增强版人脸分析器 - 支持混合模型"""
+
+    def __init__(self, models_dir: str = MODELS_PATH):
+        """
+        初始化人脸分析器
+        :param models_dir: 模型文件目录
+        """
+        start_time = time.perf_counter()
+        self.models_dir = models_dir
+        self.MODEL_MEAN_VALUES = (104, 117, 123)
+        self.age_list = [
+            "(0-2)",
+            "(4-6)",
+            "(8-12)",
+            "(15-20)",
+            "(25-32)",
+            "(38-43)",
+            "(48-53)",
+            "(60-100)",
+        ]
+        self.gender_list = ["Male", "Female"]
+        # 性别对应的颜色 (BGR格式)
+        self.gender_colors = {
+            "Male": (255, 165, 0),  # 橙色 Orange
+            "Female": (255, 0, 255),  # 洋红 Magenta / Fuchsia
+        }
+
+        # 初始化五官分析器
+        self.facial_analyzer = FacialFeatureAnalyzer()
+        # 加载HowCuteAmI模型
+        self._load_howcuteami_models()
+        # 加载YOLOv人脸检测模型
+        self._load_yolo_model()
+
+        # 预热模型（可选，通过配置开关）
+        if getattr(config, "ENABLE_WARMUP", False):
+            self._warmup_models()
+
+        init_time = time.perf_counter() - start_time
+        logger.info(f"EnhancedFaceAnalyzer initialized successfully, time: {init_time:.3f}s")
+
+    def _cap_conf(self, value: float) -> float:
+        """将置信度限制在 [0, 0.9999] 并保留4位小数。"""
+        try:
+            v = float(value if value is not None else 0.0)
+        except Exception:
+            v = 0.0
+        if v >= 1.0:
+            v = 0.9999
+        if v < 0.0:
+            v = 0.0
+        return round(v, 4)
+
+    def _adjust_beauty_score(self, score: float) -> float:
+        try:
+            if not config.BEAUTY_ADJUST_ENABLED:
+                return score
+            # 读取提分区间与力度
+            low = float(getattr(config, "BEAUTY_ADJUST_MIN", 6.0))
+            high = float(getattr(config, "BEAUTY_ADJUST_MAX", getattr(config, "BEAUTY_ADJUST_THRESHOLD", 8.0)))
+            gamma = float(getattr(config, "BEAUTY_ADJUST_GAMMA", 0.3))
+            gamma = max(0.0001, min(1.0, gamma))
+
+            # 区间有效性保护
+            if not (0.0 <= low < high <= 10.0):
+                return score
+
+            # 低于下限不提分，区间内提向上限，高于上限不变
+            if score < low:
+                return score
+            if score < high:
+                # 向上限 high 进行温和靠拢：adjusted = high - gamma * (high - score)
+                adjusted = high - gamma * (high - score)
+                adjusted = round(min(10.0, max(0.0, adjusted)), 1)
+                try:
+                    logger.info(
+                        f"beauty_score adjusted: original={score:.1f} -> adjusted={adjusted:.1f} "
+                        f"(range=[{low:.1f},{high:.1f}], gamma={gamma:.3f})"
+                    )
+                except Exception:
+                    pass
+                return adjusted
+            return score
+        except Exception:
+            return score
+
+    def _load_yolo_model(self):
+        """加载YOLOv人脸检测模型"""
+        self.yolo_model = None
+        if config.YOLO_AVAILABLE:
+            try:
+                # 尝试加载本地YOLOv人脸模型
+                yolo_face_path = os.path.join(self.models_dir, config.YOLO_MODEL)
+
+                if os.path.exists(yolo_face_path):
+                    self.yolo_model = YOLO(yolo_face_path)
+                    logger.info(f"Local YOLO face model loaded successfully: {yolo_face_path}")
+                else:
+                    # 如果本地没有，尝试在线下载（第一次使用时）
+                    logger.info("Local YOLO face model does not exist, attempting to download...")
+                    try:
+                        # 检查是否是yolov8，使用相应的模型
+                        model_name = "yolov11n-face.pt"  # 默认使用yolov8n
+                        self.yolo_model = YOLO(model_name)
+                        logger.info(
+                            f"YOLOv8 general model loaded successfully (detecting 'person' class as face regions)"
+                        )
+                    except Exception as e:
+                        logger.warning(f"YOLOv model download failed: {e}")
+
+            except Exception as e:
+                logger.error(f"YOLOv model loading failed: {e}")
+        else:
+            logger.warning("ultralytics not installed, cannot use YOLOv")
+
+    def _load_howcuteami_models(self):
+        """加载HowCuteAmI深度学习模型"""
+        try:
+            # 人脸检测模型
+            face_proto = os.path.join(self.models_dir, "opencv_face_detector.pbtxt")
+            face_model = os.path.join(self.models_dir, "opencv_face_detector_uint8.pb")
+            self.face_net = cv2.dnn.readNet(face_model, face_proto)
+
+            # 年龄预测模型
+            age_proto = os.path.join(self.models_dir, "age_googlenet.prototxt")
+            age_model = os.path.join(self.models_dir, "age_googlenet.caffemodel")
+            self.age_net = cv2.dnn.readNet(age_model, age_proto)
+
+            # 性别预测模型
+            gender_proto = os.path.join(self.models_dir, "gender_googlenet.prototxt")
+            gender_model = os.path.join(self.models_dir, "gender_googlenet.caffemodel")
+            self.gender_net = cv2.dnn.readNet(gender_model, gender_proto)
+
+            # 颜值预测模型
+            beauty_proto = os.path.join(self.models_dir, "beauty_resnet.prototxt")
+            beauty_model = os.path.join(self.models_dir, "beauty_resnet.caffemodel")
+            self.beauty_net = cv2.dnn.readNet(beauty_model, beauty_proto)
+
+            logger.info("HowCuteAmI model loaded successfully!")
+
+        except Exception as e:
+            logger.error(f"HowCuteAmI model loading failed: {e}")
+            raise e
+
+    # 人脸检测方法
+    def _detect_faces(
+        self, frame: np.ndarray, conf_threshold: float = config.FACE_CONFIDENCE
+    ) -> List[List[int]]:
+        """
+        使用YOLO进行人脸检测，如果失败则回退到OpenCV DNN
+        """
+        # 优先使用YOLO
+        face_boxes = []
+        if self.yolo_model is not None:
+            try:
+                results = self.yolo_model(frame, conf=conf_threshold, verbose=False)
+                for result in results:
+                    boxes = result.boxes
+                    if boxes is not None:
+                        for box in boxes:
+                            # 检查类别ID (如果是专门的人脸模型，通常是0；如果是通用模型，person类别通常是0)
+                            class_id = int(box.cls[0])
+                            # 获取边界框坐标 (xyxy格式)
+                            x1, y1, x2, y2 = box.xyxy[0].cpu().numpy().astype(int)
+                            confidence = float(box.conf[0])
+                            logger.debug(
+                                f"detect class_id={class_id}, confidence={confidence}"
+                            )
+                            # 基本边界检查
+                            frame_height, frame_width = frame.shape[:2]
+                            x1 = max(0, int(x1))
+                            y1 = max(0, int(y1))
+                            x2 = min(frame_width, int(x2))
+                            y2 = min(frame_height, int(y2))
+
+                            # 过滤太小的检测框
+                            width, height = x2 - x1, y2 - y1
+                            if (
+                                width > 30 and height > 30
+                            ):  # YOLO通常检测精度更高，可以稍微提高最小尺寸
+                                # 如果使用通用模型检测person，需要进一步过滤头部区域
+                                if self._is_likely_face_region(x1, y1, x2, y2, frame):
+                                    face_boxes.append(self._scale_box([x1, y1, x2, y2]))
+                logger.info(
+                    f"YOLO detected {len(face_boxes)} faces, conf_threshold={conf_threshold}"
+                )
+                if face_boxes:  # 如果YOLO检测到了人脸，直接返回
+                    return face_boxes
+
+            except Exception as e:
+                logger.warning(f"YOLO detection failed, falling back to OpenCV DNN: {e}")
+                return self._detect_faces_opencv_fallback(frame, conf_threshold)
+
+        return face_boxes
+
+    def _is_likely_face_region(
+        self, x1: int, y1: int, x2: int, y2: int, frame: np.ndarray
+    ) -> bool:
+        """
+        判断检测区域是否可能是人脸区域（当使用通用YOLO模型时）
+        """
+        width, height = x2 - x1, y2 - y1
+
+        # 长宽比检查 - 人脸/头部通常接近正方形
+        aspect_ratio = width / height
+        if not (0.6 <= aspect_ratio <= 1.6):
+            return False
+
+        # 位置检查 - 人脸通常在图像上半部分（简单启发式）
+        frame_height = frame.shape[0]
+        center_y = (y1 + y2) / 2
+        if center_y > frame_height * 0.8:  # 如果中心点在图像下方80%以下，可能不是人脸
+            return False
+
+        # 尺寸检查 - 不应该占据整个图像
+        frame_width, frame_height = frame.shape[1], frame.shape[0]
+        if width > frame_width * 0.8 or height > frame_height * 0.8:
+            return False
+
+        return True
+
+    def _detect_faces_opencv_fallback(
+        self, frame: np.ndarray, conf_threshold: float = 0.5
+    ) -> List[List[int]]:
+        """
+        优化版人脸检测 - 支持多尺度检测和小人脸识别
+        """
+        frame_height, frame_width = frame.shape[:2]
+        all_boxes = []
+
+        # 多尺度检测配置 - 从小到大，更好地检测不同大小的人脸
+        detection_configs = [
+            {"size": (300, 300), "threshold": conf_threshold},
+            {
+                "size": (416, 416),
+                "threshold": max(0.3, conf_threshold - 0.2),
+            },  # 对大尺度降低阈值
+            {
+                "size": (512, 512),
+                "threshold": max(0.25, conf_threshold - 0.25),
+            },  # 进一步降低阈值检测小脸
+        ]
+        logger.info(f"Detecting faces using opencv, conf_threshold={conf_threshold}")
+        for config in detection_configs:
+            try:
+                # 图像预处理 - 增强对比度有助于小人脸检测
+                processed_frame = cv2.convertScaleAbs(frame, alpha=1.1, beta=10)
+
+                blob = cv2.dnn.blobFromImage(
+                    processed_frame, 1.0, config["size"], [104, 117, 123], True, False
+                )
+                self.face_net.setInput(blob)
+                detections = self.face_net.forward()
+
+                # 提取检测结果
+                for i in range(detections.shape[2]):
+                    confidence = detections[0, 0, i, 2]
+                    if confidence > config["threshold"]:
+                        x1 = int(detections[0, 0, i, 3] * frame_width)
+                        y1 = int(detections[0, 0, i, 4] * frame_height)
+                        x2 = int(detections[0, 0, i, 5] * frame_width)
+                        y2 = int(detections[0, 0, i, 6] * frame_height)
+
+                        # 基本边界检查
+                        x1, y1 = max(0, x1), max(0, y1)
+                        x2, y2 = min(frame_width, x2), min(frame_height, y2)
+
+                        # 过滤太小或不合理的检测框
+                        width, height = x2 - x1, y2 - y1
+                        if (
+                            width > 20
+                            and height > 20
+                            and width < frame_width * 0.8
+                            and height < frame_height * 0.8
+                        ):
+                            # 长宽比检查 - 人脸通常接近正方形
+                            aspect_ratio = width / height
+                            if 0.6 <= aspect_ratio <= 1.8:  # 允许一定的椭圆形变
+                                all_boxes.append(
+                                    {
+                                        "box": [x1, y1, x2, y2],
+                                        "confidence": confidence,
+                                        "area": width * height,
+                                    }
+                                )
+            except Exception as e:
+                logger.warning(f"Scale {config['size']} detection failed: {e}")
+                continue
+
+        # 如果没有检测到任何人脸，尝试更宽松的条件
+        if not all_boxes:
+            logger.info("No faces detected, trying more relaxed detection conditions...")
+            try:
+                # 最后一次尝试：最低阈值 + 图像增强
+                enhanced_frame = cv2.equalizeHist(
+                    cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
+                )
+                enhanced_frame = cv2.cvtColor(enhanced_frame, cv2.COLOR_GRAY2BGR)
+
+                blob = cv2.dnn.blobFromImage(
+                    enhanced_frame, 1.0, (300, 300), [104, 117, 123], True, False
+                )
+                self.face_net.setInput(blob)
+                detections = self.face_net.forward()
+
+                for i in range(detections.shape[2]):
+                    confidence = detections[0, 0, i, 2]
+                    if confidence > 0.15:  # 非常低的阈值
+                        x1 = int(detections[0, 0, i, 3] * frame_width)
+                        y1 = int(detections[0, 0, i, 4] * frame_height)
+                        x2 = int(detections[0, 0, i, 5] * frame_width)
+                        y2 = int(detections[0, 0, i, 6] * frame_height)
+
+                        x1, y1 = max(0, x1), max(0, y1)
+                        x2, y2 = min(frame_width, x2), min(frame_height, y2)
+
+                        width, height = x2 - x1, y2 - y1
+                        if width > 15 and height > 15:  # 更小的最小尺寸
+                            aspect_ratio = width / height
+                            if 0.5 <= aspect_ratio <= 2.0:  # 更宽松的长宽比
+                                all_boxes.append(
+                                    {
+                                        "box": [x1, y1, x2, y2],
+                                        "confidence": confidence,
+                                        "area": width * height,
+                                    }
+                                )
+            except Exception as e:
+                logger.warning(f"Relaxed condition detection also failed: {e}")
+
+        # NMS (非极大值抑制) 去除重复检测
+        if all_boxes:
+            final_boxes = self._apply_nms(all_boxes, overlap_threshold=0.4)
+            return [self._scale_box(box["box"]) for box in final_boxes]
+
+        return []
+
+    def _apply_nms(
+        self, detections: List[Dict], overlap_threshold: float = 0.4
+    ) -> List[Dict]:
+        """
+        非极大值抑制，去除重复的检测框
+        """
+        if not detections:
+            return []
+
+        # 按置信度排序
+        detections.sort(key=lambda x: x["confidence"], reverse=True)
+
+        keep = []
+        while detections:
+            # 保留置信度最高的
+            best = detections.pop(0)
+            keep.append(best)
+
+            # 移除与最佳检测重叠度高的其他检测
+            remaining = []
+            for det in detections:
+                if self._calculate_iou(best["box"], det["box"]) < overlap_threshold:
+                    remaining.append(det)
+            detections = remaining
+
+        return keep
+
+    def _calculate_iou(self, box1: List[int], box2: List[int]) -> float:
+        """
+        计算两个边界框的IoU (交并比)
+        """
+        x1_1, y1_1, x2_1, y2_1 = box1
+        x1_2, y1_2, x2_2, y2_2 = box2
+
+        # 计算交集
+        x1_i = max(x1_1, x1_2)
+        y1_i = max(y1_1, y1_2)
+        x2_i = min(x2_1, x2_2)
+        y2_i = min(y2_1, y2_2)
+
+        if x2_i <= x1_i or y2_i <= y1_i:
+            return 0.0
+
+        intersection = (x2_i - x1_i) * (y2_i - y1_i)
+
+        # 计算并集
+        area1 = (x2_1 - x1_1) * (y2_1 - y1_1)
+        area2 = (x2_2 - x1_2) * (y2_2 - y1_2)
+        union = area1 + area2 - intersection
+
+        return intersection / union if union > 0 else 0.0
+
+    def _scale_box(self, box: List[int]) -> List[int]:
+        """将矩形框缩放为正方形"""
+        width = box[2] - box[0]
+        height = box[3] - box[1]
+        maximum = max(width, height)
+        dx = int((maximum - width) / 2)
+        dy = int((maximum - height) / 2)
+
+        return [box[0] - dx, box[1] - dy, box[2] + dx, box[3] + dy]
+
+    def _crop_face(self, image: np.ndarray, box: List[int]) -> np.ndarray:
+        """裁剪人脸区域"""
+        x1, y1, x2, y2 = box
+        h, w = image.shape[:2]
+        x1 = max(0, x1)
+        y1 = max(0, y1)
+        x2 = min(w, x2)
+        y2 = min(h, y2)
+        return image[y1:y2, x1:x2]
+
+    def _predict_beauty_gender_with_howcuteami(
+        self, face: np.ndarray
+    ) -> Dict[str, Any]:
+        """使用HowCuteAmI模型预测颜值和性别"""
+        try:
+            blob = cv2.dnn.blobFromImage(
+                face, 1.0, (224, 224), self.MODEL_MEAN_VALUES, swapRB=False
+            )
+
+            # 性别预测
+            self.gender_net.setInput(blob)
+            gender_preds = self.gender_net.forward()
+            gender = self.gender_list[gender_preds[0].argmax()]
+            gender_confidence = float(np.max(gender_preds[0]))
+            gender_confidence = self._cap_conf(gender_confidence)
+            # 年龄预测
+            self.age_net.setInput(blob)
+            age_preds = self.age_net.forward()
+            age = self.age_list[age_preds[0].argmax()]
+            age_confidence = float(np.max(age_preds[0]))
+            # 颜值预测
+            blob_beauty = cv2.dnn.blobFromImage(
+                face, 1.0 / 255, (224, 224), self.MODEL_MEAN_VALUES, swapRB=False
+            )
+            self.beauty_net.setInput(blob_beauty)
+            beauty_preds = self.beauty_net.forward()
+            beauty_score = round(float(2.0 * np.sum(beauty_preds[0])), 1)
+            beauty_score = min(10.0, max(0.0, beauty_score))
+            beauty_score = self._adjust_beauty_score(beauty_score)
+            raw_score = float(np.sum(beauty_preds[0]))
+
+            return {
+                "age": age,
+                "age_confidence": round(age_confidence, 4),
+                "gender": gender,
+                "gender_confidence": gender_confidence,
+                "beauty_score": beauty_score,
+                "beauty_raw_score": round(raw_score, 4),
+                "age_model_used": "HowCuteAmI",
+                "gender_model_used": "HowCuteAmI",
+                "beauty_model_used": "HowCuteAmI",
+            }
+        except Exception as e:
+            logger.error(f"HowCuteAmI beauty gender prediction failed: {e}")
+            raise e
+
+    def _predict_age_emotion_with_deepface(
+        self, face_image: np.ndarray
+    ) -> Dict[str, Any]:
+        """使用DeepFace预测年龄、情绪（并返回可用的性别信息用于回退）"""
+        if not DEEPFACE_AVAILABLE:
+            # ���果DeepFace不可用，使用HowCuteAmI的年龄预测作为回退
+            return self._predict_age_with_howcuteami_fallback(face_image)
+
+        if face_image is None or face_image.size == 0:
+            raise ValueError("无效的人脸图像")
+
+        try:
+            # DeepFace分析 - 禁用进度条和详细输出
+            result = DeepFace.analyze(
+                img_path=face_image,
+                actions=["age", "emotion", "gender"],
+                enforce_detection=False,
+                detector_backend="skip",
+                silent=True  # 禁用进度条输出
+            )
+
+            # 处理结果 (DeepFace返回的结果格式可能是list或dict)
+            if isinstance(result, list):
+                result = result[0]
+
+            # 提取信息
+            age = result.get("age", 25)
+            emotion = result.get("dominant_emotion", "neutral")
+            emotion_scores = result.get("emotion", {})
+            # 性别信息（用于在HowCuteAmI置信度低时回退）
+            deep_gender = result.get("dominant_gender", "Woman")
+            deep_gender_conf = result.get("gender", {}).get(deep_gender, 50.0) / 100.0
+            deep_gender_conf = self._cap_conf(deep_gender_conf)
+            if str(deep_gender).lower() in ["woman", "female"]:
+                deep_gender = "Female"
+            else:
+                deep_gender = "Male"
+
+            age_conf = round(random.uniform(0.7613, 0.9599), 4)
+            return {
+                "age": str(int(age)),
+                "age_confidence": age_conf,
+                "emotion": emotion,
+                "emotion_analysis": emotion_scores,
+                "gender": deep_gender,
+                "gender_confidence": deep_gender_conf,
+            }
+        except Exception as e:
+            logger.error(f"DeepFace age emotion prediction failed, falling back to HowCuteAmI: {e}")
+            return self._predict_age_with_howcuteami_fallback(face_image)
+
+    def _predict_age_with_howcuteami_fallback(
+        self, face_image: np.ndarray
+    ) -> Dict[str, Any]:
+        """HowCuteAmI年龄预测回退方案"""
+        try:
+            if face_image is None or face_image.size == 0:
+                raise ValueError("无法读取人脸图像")
+
+            face_resized = cv2.resize(face_image, (224, 224))
+            blob = cv2.dnn.blobFromImage(
+                face_resized, 1.0, (224, 224), self.MODEL_MEAN_VALUES, swapRB=False
+            )
+
+            # 年龄预测
+            self.age_net.setInput(blob)
+            age_preds = self.age_net.forward()
+            age = self.age_list[age_preds[0].argmax()]
+            age_confidence = float(np.max(age_preds[0]))
+
+            return {
+                "age": age[1:-1],  # 去掉括号
+                "age_confidence": round(age_confidence, 4),
+                "emotion": "neutral",  # 默认情绪
+                "emotion_analysis": {"neutral": 100.0},  # 默认情绪分析
+            }
+        except Exception as e:
+            logger.error(f"HowCuteAmI age prediction fallback failed: {e}")
+            return {
+                "age": "25-32",
+                "age_confidence": 0.5,
+                "emotion": "neutral",
+                "emotion_analysis": {"neutral": 100.0},
+            }
+
+    def _predict_with_hybrid_model(
+        self, face: np.ndarray, face_image: np.ndarray
+    ) -> Dict[str, Any]:
+        """混合模型预测：HowCuteAmI（颜值+性别）+ DeepFace（年龄+情绪，年龄置信度低时优先使用）"""
+        # 使用HowCuteAmI预测颜值和性别
+        beauty_gender_result = self._predict_beauty_gender_with_howcuteami(face)
+
+        # 首先获取HowCuteAmI的年龄/性别预测置信度
+        howcuteami_age_confidence = beauty_gender_result.get("age_confidence", 0)
+        gender_confidence = beauty_gender_result.get("gender_confidence", 0)
+        if gender_confidence >= 1:
+            gender_confidence = 0.9999
+        age = beauty_gender_result["age"]
+        # 使用DeepFace获取年龄/情绪（以及可选的性别回退信息）
+        age_emotion_result = self._predict_age_emotion_with_deepface(
+            face_image
+        )
+
+        # 如果HowCuteAmI的年龄置信度低于阈值，则使用DeepFace的年龄
+        agec = config.AGE_CONFIDENCE
+        if howcuteami_age_confidence < agec:
+            deep_age = age_emotion_result["age"]
+            logger.info(
+                f"HowCuteAmI age confidence ({howcuteami_age_confidence}) below {agec}, value=({age}); using DeepFace for age prediction, value={deep_age}"
+            )
+            # 合并结果，使用DeepFace的年龄预测
+            result = {
+                "gender": beauty_gender_result["gender"],  # 先用HowCuteAmI，后面可能回退
+                "gender_confidence": self._cap_conf(gender_confidence),
+                "beauty_score": beauty_gender_result["beauty_score"],
+                "beauty_raw_score": beauty_gender_result["beauty_raw_score"],
+                "age": deep_age,
+                "age_confidence": age_emotion_result["age_confidence"],
+                "emotion": age_emotion_result["emotion"],
+                "emotion_analysis": age_emotion_result["emotion_analysis"],
+                "model_used": "hybrid_deepface_age",
+                "age_model_used": "DeepFace",
+                "gender_model_used": "HowCuteAmI",
+            }
+        else:
+            # HowCuteAmI年龄置信度足够高，使用原有逻辑
+            logger.info(
+                f"HowCuteAmI age confidence ({howcuteami_age_confidence}) is high enough, value={age}; using HowCuteAmI for age prediction"
+            )
+            # 合并结果，保留HowCuteAmI的年龄预测
+            result = {
+                "gender": beauty_gender_result["gender"],  # 先用HowCuteAmI，后面可能回退
+                "gender_confidence": self._cap_conf(gender_confidence),
+                "beauty_score": beauty_gender_result["beauty_score"],
+                "beauty_raw_score": beauty_gender_result["beauty_raw_score"],
+                "age": beauty_gender_result["age"],
+                "age_confidence": beauty_gender_result["age_confidence"],
+                "emotion": age_emotion_result["emotion"],
+                "emotion_analysis": age_emotion_result["emotion_analysis"],
+                "model_used": "hybrid",
+                "age_model_used": "HowCuteAmI",
+                "gender_model_used": "HowCuteAmI",
+            }
+
+        # 统一性别判定规则：任一模型判为Female则Female；两者都为Male才Male
+        try:
+            how_gender = beauty_gender_result.get("gender")
+            how_conf = float(beauty_gender_result.get("gender_confidence", 0) or 0)
+            deep_gender = age_emotion_result.get("gender")
+            deep_conf = float(age_emotion_result.get("gender_confidence", 0) or 0)
+
+            final_gender = result.get("gender")
+            final_conf = float(result.get("gender_confidence", 0) or 0)
+            # 规则判断
+            if (str(how_gender) == "Female") or (str(deep_gender) == "Female"):
+                final_gender = "Female"
+                final_conf = max(how_conf if how_gender == "Female" else 0,
+                                 deep_conf if deep_gender == "Female" else 0)
+                result["gender_model_used"] = "Combined(H+DF)"
+            elif (str(how_gender) == "Male") and (str(deep_gender) == "Male"):
+                final_gender = "Male"
+                final_conf = max(how_conf if how_gender == "Male" else 0,
+                                 deep_conf if deep_gender == "Male" else 0)
+                result["gender_model_used"] = "Combined(H+DF)"
+            # 否则保持原判定
+
+            result["gender"] = final_gender
+            result["gender_confidence"] = self._cap_conf(final_conf)
+        except Exception:
+            pass
+
+        return result
+
+    def _predict_with_howcuteami(self, face: np.ndarray) -> Dict[str, Any]:
+        """使用HowCuteAmI模型进行完整预测"""
+        try:
+            # 性别预测
+            blob = cv2.dnn.blobFromImage(
+                face, 1.0, (224, 224), self.MODEL_MEAN_VALUES, swapRB=False
+            )
+            self.gender_net.setInput(blob)
+            gender_preds = self.gender_net.forward()
+            gender = self.gender_list[gender_preds[0].argmax()]
+            gender_confidence = float(np.max(gender_preds[0]))
+            gender_confidence = self._cap_conf(gender_confidence)
+
+            # 年龄预测
+            self.age_net.setInput(blob)
+            age_preds = self.age_net.forward()
+            age = self.age_list[age_preds[0].argmax()]
+            age_confidence = float(np.max(age_preds[0]))
+
+            # 颜值预测
+            blob_beauty = cv2.dnn.blobFromImage(
+                face, 1.0 / 255, (224, 224), self.MODEL_MEAN_VALUES, swapRB=False
+            )
+            self.beauty_net.setInput(blob_beauty)
+            beauty_preds = self.beauty_net.forward()
+            beauty_score = round(float(2.0 * np.sum(beauty_preds[0])), 1)
+            beauty_score = min(10.0, max(0.0, beauty_score))
+            beauty_score = self._adjust_beauty_score(beauty_score)
+            raw_score = float(np.sum(beauty_preds[0]))
+
+            return {
+                "gender": gender,
+                "gender_confidence": gender_confidence,
+                "age": age[1:-1],  # 去掉括号
+                "age_confidence": round(age_confidence, 4),
+                "beauty_score": beauty_score,
+                "beauty_raw_score": round(raw_score, 4),
+                "model_used": "HowCuteAmI",
+                "emotion": "neutral",  # HowCuteAmI不支持情绪分析
+                "emotion_analysis": {"neutral": 100.0},
+                "age_model_used": "HowCuteAmI",
+                "gender_model_used": "HowCuteAmI",
+                "beauty_model_used": "HowCuteAmI",
+            }
+        except Exception as e:
+            logger.error(f"HowCuteAmI prediction failed: {e}")
+            raise e
+
+    def _predict_with_deepface(self, face_image: np.ndarray) -> Dict[str, Any]:
+        """使用DeepFace进行预测"""
+        if not DEEPFACE_AVAILABLE:
+            raise ValueError("DeepFace未安装")
+
+        if face_image is None or face_image.size == 0:
+            raise ValueError("无效的人脸图像")
+
+        try:
+            # DeepFace分析 - 禁用进度条和详细输出
+            result = DeepFace.analyze(
+                img_path=face_image,
+                actions=["age", "gender", "emotion"],
+                enforce_detection=False,
+                detector_backend="skip",
+                silent=True  # 禁用进度条输出
+            )
+
+            # 处理结果 (DeepFace返回的结果格式可能是list或dict)
+            if isinstance(result, list):
+                result = result[0]
+
+            # 提取信息
+            age = result.get("age", 25)
+            gender = result.get("dominant_gender", "Woman")
+            gender_confidence = result.get("gender", {}).get(gender, 0.5) / 100
+            gender_confidence = self._cap_conf(gender_confidence)
+
+            # 统一性别标签
+            if gender.lower() in ["woman", "female"]:
+                gender = "Female"
+            else:
+                gender = "Male"
+
+            # DeepFace没有内置颜值评分，这里使用简单的启发式方法
+            emotion = result.get("dominant_emotion", "neutral")
+            emotion_scores = result.get("emotion", {})
+
+            # 基于情绪和年龄的简单颜值估算
+            happiness_score = emotion_scores.get("happy", 0) / 100
+            neutral_score = emotion_scores.get("neutral", 0) / 100
+
+            # 简单的颜值算法 (可以改进)
+            base_beauty = 6.0  # 基础分
+            emotion_bonus = happiness_score * 2 + neutral_score * 1
+            age_factor = max(0.5, 1 - abs(age - 25) / 50)  # 25岁为最佳年龄
+
+            beauty_score = round(min(10.0, base_beauty + emotion_bonus + age_factor), 2)
+
+            age_conf = round(random.uniform(0.7613, 0.9599), 4)
+            return {
+                "gender": gender,
+                "gender_confidence": gender_confidence,
+                "age": str(int(age)),
+                "age_confidence": age_conf,  # DeepFace年龄置信度（随机范围）
+                "beauty_score": beauty_score,
+                "beauty_raw_score": round(beauty_score / 10, 4),
+                "model_used": "DeepFace",
+                "emotion": emotion,
+                "emotion_analysis": emotion_scores,
+                "age_model_used": "DeepFace",
+                "gender_model_used": "DeepFace",
+                "beauty_model_used": "Heuristic",
+            }
+        except Exception as e:
+            logger.error(f"DeepFace prediction failed: {e}")
+            raise e
+
+    def analyze_faces(
+        self,
+        image: np.ndarray,
+        original_image_hash: str,
+        model_type: ModelType = ModelType.HYBRID,
+    ) -> Dict[str, Any]:
+        """
+        分析图片中的人脸
+        :param image: 输入图像
+        :param original_image_hash: 原始图片的MD5哈希值
+        :param model_type: 使用的模型类型
+        :return: 分析结果
+        """
+        if image is None:
+            raise ValueError("无效的图像输入")
+
+        # 检测人脸
+        face_boxes = self._detect_faces(image)
+
+        if not face_boxes:
+            return {
+                "success": False,
+                "message": "请尝试上传清晰、无遮挡的正面照片",
+                "face_count": 0,
+                "faces": [],
+                "annotated_image": None,
+                "model_used": model_type.value,
+            }
+
+        results = {
+            "success": True,
+            "message": f"成功检测到 {len(face_boxes)} 张人脸",
+            "face_count": len(face_boxes),
+            "faces": [],
+            "model_used": model_type.value,
+        }
+
+        # 复制原图用于绘制
+        annotated_image = image.copy()
+        logger.debug(
+            f"Input annotated_image shape: {annotated_image.shape}, dtype: {annotated_image.dtype}, ndim: {annotated_image.ndim}"
+        )
+        # 分析每张人脸
+        for i, face_box in enumerate(face_boxes):
+            # 裁剪人脸
+            face_cropped = self._crop_face(image, face_box)
+            if face_cropped.size == 0:
+                logger.warning(f"Cropped face {i + 1} is empty, skipping.")
+                continue
+
+            face_resized = cv2.resize(face_cropped, (224, 224))
+            face_for_deepface = face_cropped.copy()
+
+            # 根据模型类型进行预测
+            try:
+                if model_type == ModelType.HYBRID:
+                    # 混合模式：颜值性别用HowCuteAmI，年龄情绪用DeepFace
+                    prediction_result = self._predict_with_hybrid_model(
+                        face_resized, face_for_deepface
+                    )
+                elif model_type == ModelType.HOWCUTEAMI:
+                    prediction_result = self._predict_with_howcuteami(face_resized)
+                    # 非混合模式也进行性别合并：引入DeepFace性别
+                    try:
+                        age_emotion_result = self._predict_age_emotion_with_deepface(
+                            face_for_deepface
+                        )
+                        how_gender = prediction_result.get("gender")
+                        how_conf = float(prediction_result.get("gender_confidence", 0) or 0)
+                        deep_gender = age_emotion_result.get("gender")
+                        deep_conf = float(age_emotion_result.get("gender_confidence", 0) or 0)
+                        final_gender = prediction_result.get("gender")
+                        final_conf = float(prediction_result.get("gender_confidence", 0) or 0)
+                        if (str(how_gender) == "Female") or (str(deep_gender) == "Female"):
+                            final_gender = "Female"
+                            final_conf = max(how_conf if how_gender == "Female" else 0,
+                                             deep_conf if deep_gender == "Female" else 0)
+                            prediction_result["gender_model_used"] = "Combined(H+DF)"
+                        elif (str(how_gender) == "Male") and (str(deep_gender) == "Male"):
+                            final_gender = "Male"
+                            final_conf = max(how_conf if how_gender == "Male" else 0,
+                                             deep_conf if deep_gender == "Male" else 0)
+                            prediction_result["gender_model_used"] = "Combined(H+DF)"
+                        prediction_result["gender"] = final_gender
+                        prediction_result["gender_confidence"] = round(float(final_conf), 4)
+                    except Exception:
+                        pass
+                elif model_type == ModelType.DEEPFACE and DEEPFACE_AVAILABLE:
+                    prediction_result = self._predict_with_deepface(face_for_deepface)
+                    # 非混合模式也进行性别合并：引入HowCuteAmI性别
+                    try:
+                        beauty_gender_result = self._predict_beauty_gender_with_howcuteami(
+                            face_resized
+                        )
+                        deep_gender = prediction_result.get("gender")
+                        deep_conf = float(prediction_result.get("gender_confidence", 0) or 0)
+                        how_gender = beauty_gender_result.get("gender")
+                        how_conf = float(beauty_gender_result.get("gender_confidence", 0) or 0)
+                        final_gender = prediction_result.get("gender")
+                        final_conf = float(prediction_result.get("gender_confidence", 0) or 0)
+                        if (str(how_gender) == "Female") or (str(deep_gender) == "Female"):
+                            final_gender = "Female"
+                            final_conf = max(how_conf if how_gender == "Female" else 0,
+                                             deep_conf if deep_gender == "Female" else 0)
+                            prediction_result["gender_model_used"] = "Combined(H+DF)"
+                        elif (str(how_gender) == "Male") and (str(deep_gender) == "Male"):
+                            final_gender = "Male"
+                            final_conf = max(how_conf if how_gender == "Male" else 0,
+                                             deep_conf if deep_gender == "Male" else 0)
+                            prediction_result["gender_model_used"] = "Combined(H+DF)"
+                        prediction_result["gender"] = final_gender
+                        prediction_result["gender_confidence"] = round(float(final_conf), 4)
+                    except Exception:
+                        pass
+                else:
+                    # 回退到混合模式
+                    prediction_result = self._predict_with_hybrid_model(
+                        face_resized, face_for_deepface
+                    )
+                    logger.warning(f"Model {model_type.value} is not available, using hybrid mode")
+
+            except Exception as e:
+                logger.error(f"Prediction failed, using default values: {e}")
+                prediction_result = {
+                    "gender": "Unknown",
+                    "gender_confidence": 0.5,
+                    "age": "25-32",
+                    "age_confidence": 0.5,
+                    "beauty_score": 5.0,
+                    "beauty_raw_score": 0.5,
+                    "emotion": "neutral",
+                    "emotion_analysis": {"neutral": 100.0},
+                    "model_used": "fallback",
+                }
+
+            # 五官分析
+            # facial_features = self.facial_analyzer.analyze_facial_features(
+            #     face_cropped, face_box
+            # )
+
+            # 颜色设置与年龄显示统一（应用女性年龄调整）
+            gender = prediction_result.get("gender", "Unknown")
+            color_bgr = self.gender_colors.get(gender, (128, 128, 128))
+            color_hex = f"#{color_bgr[2]:02x}{color_bgr[1]:02x}{color_bgr[0]:02x}"
+
+            # 年龄文本与调整
+            raw_age_str = prediction_result.get("age", "Unknown")
+            display_age_str = str(raw_age_str)
+            age_adjusted_flag = False
+            age_adjustment_value = int(getattr(config, "FEMALE_AGE_ADJUSTMENT", 0) or 0)
+            age_adjustment_threshold = int(getattr(config, "FEMALE_AGE_ADJUSTMENT_THRESHOLD", 999) or 999)
+
+            # 仅对女性且年龄达到阈值时进行调整
+            try:
+                # 支持 "25-32" 或 "25" 格式
+                if "-" in str(raw_age_str):
+                    age_num = int(str(raw_age_str).split("-")[0].strip("() "))
+                else:
+                    age_num = int(str(raw_age_str).strip())
+
+                if str(gender) == "Female" and age_num >= age_adjustment_threshold and age_adjustment_value > 0:
+                    adjusted_age = max(0, age_num - age_adjustment_value)
+                    display_age_str = str(adjusted_age)
+                    age_adjusted_flag = True
+                    try:
+                        logger.info(f"Adjusted age for female (draw+data): {age_num} -> {adjusted_age}")
+                    except Exception:
+                        pass
+            except Exception:
+                # 无法解析年龄时，保持原样
+                pass
+
+            # 保存裁剪的人脸
+            cropped_face_filename = f"{original_image_hash}_face_{i + 1}.webp"
+            cropped_face_path = os.path.join(OUTPUT_DIR, cropped_face_filename)
+            try:
+                save_image_force_compress(
+                    face_cropped, cropped_face_path, max_size_kb=100
+                )
+                logger.debug(f"cropped face: {cropped_face_path}")
+            except Exception as e:
+                logger.error(f"Failed to save cropped face {cropped_face_path}: {e}")
+                cropped_face_filename = None
+
+            # 在图片上绘制标注
+            if config.DRAW_SCORE:
+                cv2.rectangle(
+                    annotated_image,
+                    (face_box[0], face_box[1]),
+                    (face_box[2], face_box[3]),
+                    color_bgr,
+                    int(round(image.shape[0] / 400)),
+                    8,
+                )
+
+            # 标签文本
+            beauty_score = prediction_result.get("beauty_score", 0)
+            label = f"{gender}, {display_age_str}, {beauty_score}"
+
+            font_scale = max(
+                0.3, min(0.7, image.shape[0] / 800)
+            )  # 从500改为800，范围从0.5-1.0改为0.3-0.7
+            font_thickness = 2
+            font = cv2.FONT_HERSHEY_SIMPLEX
+            # 绘制文本
+            text_x = face_box[0]
+            text_y = face_box[1] - 10 if face_box[1] - 10 > 20 else face_box[1] + 30
+
+            # 计算文字大小（宽高）
+            (text_width, text_height), baseline = cv2.getTextSize(label, font, font_scale, font_thickness)
+
+            # 画黑色矩形背景，稍微比文字框大一点，增加边距
+            background_tl = (text_x, text_y - text_height - baseline)  # 矩形左上角
+            background_br = (text_x + text_width, text_y + baseline)  # 矩形右下角
+
+            if config.DRAW_SCORE:
+                cv2.rectangle(
+                    annotated_image,
+                    background_tl,
+                    background_br,
+                    color_bgr,  # 黑色背景
+                    thickness=-1  # 填充
+                )
+                cv2.putText(
+                    annotated_image,
+                    label,
+                    (text_x, text_y),
+                    font,
+                    font_scale,
+                    (255, 255, 255),
+                    font_thickness,
+                    cv2.LINE_AA,
+                )
+
+            # 构建人脸结果
+            face_result = {
+                "face_id": i + 1,
+                "gender": gender,
+                "gender_confidence": prediction_result.get("gender_confidence", 0),
+                "gender_model_used": prediction_result.get("gender_model_used", prediction_result.get("model_used", model_type.value)),
+                "age": display_age_str,
+                "age_confidence": prediction_result.get("age_confidence", 0),
+                "age_model_used": prediction_result.get("age_model_used", prediction_result.get("model_used", model_type.value)),
+                "beauty_score": prediction_result.get("beauty_score", 0),
+                "beauty_raw_score": prediction_result.get("beauty_raw_score", 0),
+                "emotion": prediction_result.get("emotion", "neutral"),
+                "emotion_analysis": prediction_result.get("emotion_analysis", {}),
+                # "facial_features": facial_features,  # 五官分析
+                "bounding_box": {
+                    "x1": int(face_box[0]),
+                    "y1": int(face_box[1]),
+                    "x2": int(face_box[2]),
+                    "y2": int(face_box[3]),
+                },
+                "color": {
+                    "bgr": [int(color_bgr[0]), int(color_bgr[1]), int(color_bgr[2])],
+                    "hex": color_hex,
+                },
+                "cropped_face_filename": cropped_face_filename,
+                "model_used": prediction_result.get("model_used", model_type.value),
+            }
+
+            if age_adjusted_flag:
+                face_result["age_adjusted"] = True
+                face_result["age_adjustment_value"] = int(age_adjustment_value)
+
+            results["faces"].append(face_result)
+
+        results["annotated_image"] = annotated_image
+        return results
+
+    def _warmup_models(self):
+        """预热模型，减少首次调用延迟"""
+        try:
+            logger.info("Starting to warm up models...")
+
+            # 创建一个小的测试图像 (64x64)
+            test_image = np.ones((64, 64, 3), dtype=np.uint8) * 128
+
+            # 预热DeepFace模型（如果可用）
+            if DEEPFACE_AVAILABLE:
+                try:
+                    import tempfile
+                    with tempfile.NamedTemporaryFile(suffix='.webp', delete=False) as tmp_file:
+                        cv2.imwrite(tmp_file.name, test_image, [cv2.IMWRITE_WEBP_QUALITY, 95])
+                        # 预热DeepFace - 使用最小的actions集合
+                        DeepFace.analyze(
+                            img_path=tmp_file.name,
+                            actions=["age", "emotion", "gender"],
+                            detector_backend="yolov8",
+                            enforce_detection=False,
+                            silent=True
+                        )
+                        os.unlink(tmp_file.name)
+                    logger.info("DeepFace model warm-up completed")
+                except Exception as e:
+                    logger.warning(f"DeepFace model warm-up failed: {e}")
+
+            # 预热OpenCV DNN模型
+            try:
+                # 预热人脸检测模型
+                blob = cv2.dnn.blobFromImage(test_image, 1.0, (300, 300), (104, 117, 123))
+                self.face_net.setInput(blob)
+                self.face_net.forward()
+
+                # 预热年龄预测模型
+                test_face = cv2.resize(test_image, (224, 224))
+                blob = cv2.dnn.blobFromImage(test_face, 1.0, (224, 224), self.MODEL_MEAN_VALUES, swapRB=False)
+                self.age_net.setInput(blob)
+                self.age_net.forward()
+
+                # 预热性别预测模型
+                self.gender_net.setInput(blob)
+                self.gender_net.forward()
+
+                # 预热颜值评分模型
+                self.beauty_net.setInput(blob)
+                self.beauty_net.forward()
+
+                logger.info("OpenCV DNN model warm-up completed")
+            except Exception as e:
+                logger.warning(f"OpenCV DNN model warm-up failed: {e}")
+
+            logger.info("Model warm-up completed")
+        except Exception as e:
+            logger.warning(f"Error occurred during model warm-up: {e}")

facial_analyzer.py

@@ -0,0 +1,912 @@
+import traceback
+from typing import List, Dict, Any
+
+import cv2
+import numpy as np
+
+import config
+from config import logger, DLIB_AVAILABLE
+
+if DLIB_AVAILABLE:
+    import mediapipe as mp
+
+
+class FacialFeatureAnalyzer:
+    """五官分析器"""
+
+    def __init__(self):
+        self.face_mesh = None
+        if DLIB_AVAILABLE:
+            try:
+                # 初始化MediaPipe Face Mesh
+                mp_face_mesh = mp.solutions.face_mesh
+                self.face_mesh = mp_face_mesh.FaceMesh(
+                    static_image_mode=True,
+                    max_num_faces=1,
+                    refine_landmarks=True,
+                    min_detection_confidence=0.5,
+                    min_tracking_confidence=0.5
+                )
+                logger.info("MediaPipe face landmark detector loaded successfully")
+            except Exception as e:
+                logger.error(f"Failed to load MediaPipe model: {e}")
+
+    def analyze_facial_features(
+        self, face_image: np.ndarray, face_box: List[int]
+    ) -> Dict[str, Any]:
+        """
+        分析五官特征
+        :param face_image: 人脸图像
+        :param face_box: 人脸边界框 [x1, y1, x2, y2]
+        :return: 五官分析结果
+        """
+        if not DLIB_AVAILABLE or self.face_mesh is None:
+            return self._basic_facial_analysis(face_image)
+
+        try:
+            # MediaPipe需要RGB图像
+            rgb_image = cv2.cvtColor(face_image, cv2.COLOR_BGR2RGB)
+
+            # 检测关键点
+            results = self.face_mesh.process(rgb_image)
+
+            if not results.multi_face_landmarks:
+                logger.warning("No facial landmarks detected")
+                return self._basic_facial_analysis(face_image)
+
+            # 获取第一个面部的关键点
+            face_landmarks = results.multi_face_landmarks[0]
+
+            # 将MediaPipe的468个关键点转换为类似dlib 68点的格式
+            points = self._convert_mediapipe_to_dlib_format(face_landmarks, face_image.shape)
+
+            return self._analyze_features_from_landmarks(points, face_image.shape)
+
+        except Exception as e:
+            logger.error(f"Facial feature analysis failed: {e}")
+            traceback.print_exc()  # ← 打印完整堆栈，包括确切行号
+            return self._basic_facial_analysis(face_image)
+
+    def _convert_mediapipe_to_dlib_format(self, face_landmarks, image_shape):
+        """
+        将MediaPipe的468个关键点转换为类似dlib 68点的格式
+        MediaPipe到dlib的关键点映射
+        """
+        h, w = image_shape[:2]
+
+        # MediaPipe关键点索引到dlib 68点的映射
+        # 这个映射基于MediaPipe Face Mesh的标准索引
+        mediapipe_to_dlib_map = {
+            # 面部轮廓 (0-16)
+            0: 234,   # 下巴最低点
+            1: 132,   # 右脸颊下
+            2: 172,   # 右脸颊
+            3: 136,   # 右脸颊上
+            4: 150,   # 右颧骨
+            5: 149,   # 右太阳穴
+            6: 176,   # 右额头边缘
+            7: 148,   # 右额头
+            8: 152,   # 额头中央
+            9: 377,   # 左额头
+            10: 400,  # 左额头边缘
+            11: 378,  # 左太阳穴
+            12: 379,  # 左颧骨
+            13: 365,  # 左脸颊上
+            14: 397,  # 左脸颊
+            15: 361,  # 左脸颊下
+            16: 454,  # 下巴左侧
+
+            # 右眉毛 (17-21)
+            17: 70,   # 右眉毛外端
+            18: 63,   # 右眉毛
+            19: 105,  # 右眉毛
+            20: 66,   # 右眉毛
+            21: 107,  # 右眉毛内端
+
+            # 左眉毛 (22-26)
+            22: 336,  # 左眉毛内端
+            23: 296,  # 左眉毛
+            24: 334,  # 左眉毛
+            25: 293,  # 左眉毛
+            26: 300,  # 左眉毛外端
+
+            # 鼻梁 (27-30)
+            27: 168,  # 鼻梁顶
+            28: 8,    # 鼻梁
+            29: 9,    # 鼻梁
+            30: 10,   # 鼻梁底
+
+            # 鼻翼 (31-35)
+            31: 151,  # 右鼻翼
+            32: 134,  # 右鼻孔
+            33: 2,    # 鼻尖
+            34: 363,  # 左鼻孔
+            35: 378,  # 左鼻翼
+
+            # 右眼 (36-41)
+            36: 33,   # 右眼外角
+            37: 7,    # 右眼上眼睑
+            38: 163,  # 右眼上眼睑
+            39: 144,  # 右眼内角
+            40: 145,  # 右眼下眼睑
+            41: 153,  # 右眼下眼睑
+
+            # 左眼 (42-47)
+            42: 362,  # 左眼内角
+            43: 382,  # 左眼上眼睑
+            44: 381,  # 左眼上眼睑
+            45: 380,  # 左眼外角
+            46: 374,  # 左眼下眼睑
+            47: 373,  # 左眼下眼睑
+
+            # 嘴部轮廓 (48-67)
+            48: 78,   # 右嘴角
+            49: 95,   # 右上唇
+            50: 88,   # 上唇右侧
+            51: 178,  # 上唇中央右
+            52: 87,   # 上唇中央
+            53: 14,   # 上唇中央左
+            54: 317,  # 上唇左侧
+            55: 318,  # 左上唇
+            56: 308,  # 左嘴角
+            57: 324,  # 左下唇
+            58: 318,  # 下唇左侧
+            59: 16,   # 下唇中央左
+            60: 17,   # 下唇中央
+            61: 18,   # 下唇中央右
+            62: 200,  # 下唇右侧
+            63: 199,  # 右下唇
+            64: 175,  # 右嘴角内
+            65: 84,   # 上唇内右
+            66: 17,   # 下唇内中央
+            67: 314,  # 上唇内左
+        }
+
+        # 转换关键点
+        points = []
+        for i in range(68):
+            if i in mediapipe_to_dlib_map:
+                mp_idx = mediapipe_to_dlib_map[i]
+                if mp_idx < len(face_landmarks.landmark):
+                    landmark = face_landmarks.landmark[mp_idx]
+                    x = int(landmark.x * w)
+                    y = int(landmark.y * h)
+                    points.append((x, y))
+                else:
+                    # 如果索引超出范围，使用默认位置
+                    points.append((w//2, h//2))
+            else:
+                # 如果没有映射，使用默认位置
+                points.append((w//2, h//2))
+
+        return points
+
+    def _analyze_features_from_landmarks(
+        self, landmarks: List[tuple], image_shape: tuple
+    ) -> Dict[str, Any]:
+        """基于68个关键点分析五官"""
+        try:
+            # 定义各部位的关键点索引
+            jawline = landmarks[0:17]  # 下颌线
+            left_eyebrow = landmarks[17:22]  # 左眉毛
+            right_eyebrow = landmarks[22:27]  # 右眉毛
+            nose = landmarks[27:36]  # 鼻子
+            left_eye = landmarks[36:42]  # 左眼
+            right_eye = landmarks[42:48]  # 右眼
+            mouth = landmarks[48:68]  # 嘴巴
+
+            # 计算各部位得分 (简化版，实际应用需要更复杂的算法)
+            scores = {
+                "eyes": self._score_eyes(left_eye, right_eye, image_shape),
+                "nose": self._score_nose(nose, image_shape),
+                "mouth": self._score_mouth(mouth, image_shape),
+                "eyebrows": self._score_eyebrows(
+                    left_eyebrow, right_eyebrow, image_shape
+                ),
+                "jawline": self._score_jawline(jawline, image_shape),
+            }
+
+            # 计算总体协调性
+            harmony_score = self._calculate_harmony_new(landmarks, image_shape)
+            # 温和上调整体协调性分数（与颜值类似的拉升策略）
+            harmony_score = self._adjust_harmony_score(harmony_score)
+
+            return {
+                "facial_features": scores,
+                "harmony_score": round(harmony_score, 2),
+                "overall_facial_score": round(sum(scores.values()) / len(scores), 2),
+                "analysis_method": "mediapipe_landmarks",
+            }
+
+        except Exception as e:
+            logger.error(f"Landmark analysis failed: {e}")
+            return self._basic_facial_analysis(None)
+
+    def _adjust_harmony_score(self, score: float) -> float:
+        """整体协调性分值温和拉升：当低于阈值时往阈值靠拢一点。"""
+        try:
+            if not getattr(config, "HARMONY_ADJUST_ENABLED", False):
+                return round(float(score), 2)
+            thr = float(getattr(config, "HARMONY_ADJUST_THRESHOLD", 8.0))
+            gamma = float(getattr(config, "HARMONY_ADJUST_GAMMA", 0.5))
+            gamma = max(0.0001, min(1.0, gamma))
+            s = float(score)
+            if s < thr:
+                s = thr - gamma * (thr - s)
+            return round(min(10.0, max(0.0, s)), 2)
+        except Exception:
+            try:
+                return round(float(score), 2)
+            except Exception:
+                return 6.21
+
+    def _score_eyes(
+        self, left_eye: List[tuple], right_eye: List[tuple], image_shape: tuple
+    ) -> float:
+        """眼部评分"""
+        try:
+            # 计算眼部对称性和大小
+            left_width = abs(left_eye[3][0] - left_eye[0][0])
+            right_width = abs(right_eye[3][0] - right_eye[0][0])
+
+            # 计算眼部高度
+            left_height = abs(left_eye[1][1] - left_eye[5][1])
+            right_height = abs(right_eye[1][1] - right_eye[5][1])
+
+            # 对称性评分 - 宽度对称性
+            width_symmetry = 1 - min(
+                abs(left_width - right_width) / max(left_width, right_width), 0.5
+            )
+
+            # 高度对称性
+            height_symmetry = 1 - min(
+                abs(left_height - right_height) / max(left_height, right_height), 0.5
+            )
+
+            # 大小适中性评分 (相对于脸部宽度) - 调整理想比例
+            avg_eye_width = (left_width + right_width) / 2
+            face_width = image_shape[1]
+            ideal_ratio = 0.08  # 调整理想比例，原来0.15太大
+            size_score = max(
+                0, 1 - abs(avg_eye_width / face_width - ideal_ratio) / ideal_ratio
+            )
+
+            # 眼部长宽比评分
+            avg_eye_height = (left_height + right_height) / 2
+            aspect_ratio = avg_eye_width / max(avg_eye_height, 1)  # 避免除零
+            ideal_aspect = 3.0  # 理想长宽比
+            aspect_score = max(0, 1 - abs(aspect_ratio - ideal_aspect) / ideal_aspect)
+
+            final_score = (
+                width_symmetry * 0.3
+                + height_symmetry * 0.3
+                + size_score * 0.25
+                + aspect_score * 0.15
+            ) * 10
+            return round(max(0, min(10, final_score)), 2)
+        except:
+            return 6.21
+
+    def _score_nose(self, nose: List[tuple], image_shape: tuple) -> float:
+        """鼻部评分"""
+        try:
+            # 鼻子关键点
+            nose_tip = nose[3]  # 鼻尖
+            nose_bridge_top = nose[0]  # 鼻梁顶部
+            left_nostril = nose[1]
+            right_nostril = nose[5]
+
+            # 计算鼻子的直线度 (鼻梁是否挺直)
+            straightness = 1 - min(
+                abs(nose_tip[0] - nose_bridge_top[0]) / (image_shape[1] * 0.1), 1.0
+            )
+
+            # 鼻宽评分 - 使用鼻翼宽度
+            nose_width = abs(right_nostril[0] - left_nostril[0])
+            face_width = image_shape[1]
+            ideal_nose_ratio = 0.06  # 调整理想比例
+            width_score = max(
+                0,
+                1 - abs(nose_width / face_width - ideal_nose_ratio) / ideal_nose_ratio,
+            )
+
+            # 鼻子长度评分
+            nose_length = abs(nose_tip[1] - nose_bridge_top[1])
+            face_height = image_shape[0]
+            ideal_length_ratio = 0.08
+            length_score = max(
+                0,
+                1
+                - abs(nose_length / face_height - ideal_length_ratio)
+                / ideal_length_ratio,
+            )
+
+            final_score = (
+                straightness * 0.4 + width_score * 0.35 + length_score * 0.25
+            ) * 10
+            return round(max(0, min(10, final_score)), 2)
+        except:
+            return 6.21
+
+    def _score_mouth(self, mouth: List[tuple], image_shape: tuple) -> float:
+        """嘴部评分 - 大幅优化，更宽松的评分标准"""
+        try:
+            # 嘴角点
+            left_corner = mouth[0]  # 左嘴角
+            right_corner = mouth[6]  # 右嘴角
+
+            # 上唇和下唇中心点
+            upper_lip_center = mouth[3]  # 上唇中心
+            lower_lip_center = mouth[9]  # 下唇中心
+
+            # 基础分数，避免过低
+            base_score = 6.0
+
+            # 1. 嘴宽评分 - 更宽松的标准
+            mouth_width = abs(right_corner[0] - left_corner[0])
+            face_width = image_shape[1]
+            mouth_ratio = mouth_width / face_width
+
+            # 设置更宽的合理范围 (0.04-0.15)
+            if 0.04 <= mouth_ratio <= 0.15:
+                width_score = 1.0  # 在合理范围内就给满分
+            elif mouth_ratio < 0.04:
+                width_score = max(0.3, mouth_ratio / 0.04)  # 太小时渐减
+            else:
+                width_score = max(0.3, 0.15 / mouth_ratio)  # 太大时渐减
+
+            # 2. 唇厚度评分 - 简化并放宽标准
+            lip_thickness = abs(lower_lip_center[1] - upper_lip_center[1])
+            # 只要厚度不是极端值就给高分
+            if lip_thickness > 3:  # 像素值，有一定厚度
+                thickness_score = min(1.0, lip_thickness / 25)  # 25像素为满分
+            else:
+                thickness_score = 0.5  # 太薄给中等分数
+
+            # 3. 嘴部对称性评分 - 更宽松
+            mouth_center_x = (left_corner[0] + right_corner[0]) / 2
+            face_center_x = image_shape[1] / 2
+            center_deviation = abs(mouth_center_x - face_center_x) / face_width
+
+            if center_deviation < 0.02:  # 偏差小于2%
+                symmetry_score = 1.0
+            elif center_deviation < 0.05:  # 偏差小于5%
+                symmetry_score = 0.8
+            else:
+                symmetry_score = max(0.5, 1 - center_deviation * 10)  # 最低0.5分
+
+            # 4. 嘴唇形状评分 - 简化
+            # 检查嘴角是否在合理位置
+            corner_height_diff = abs(left_corner[1] - right_corner[1])
+            if corner_height_diff < face_width * 0.02:  # 嘴角高度差异小
+                shape_score = 1.0
+            else:
+                shape_score = max(0.6, 1 - corner_height_diff / (face_width * 0.02))
+
+            # 5. 综合评分 - 调整权重，给基础分更大权重
+            feature_score = (
+                width_score * 0.3
+                + thickness_score * 0.25
+                + symmetry_score * 0.25
+                + shape_score * 0.2
+            )
+
+            # 最终分数 = 基础分 + 特征分奖励
+            final_score = base_score + feature_score * 4  # 最高10分
+
+            return round(max(4.0, min(10, final_score)), 2)  # 最低4分，最高10分
+        except Exception as e:
+            return 6.21
+
+    def _score_eyebrows(
+        self, left_brow: List[tuple], right_brow: List[tuple], image_shape: tuple
+    ) -> float:
+        """眉毛评分 - 改进算法"""
+        try:
+            # 计算眉毛长度
+            left_length = abs(left_brow[-1][0] - left_brow[0][0])
+            right_length = abs(right_brow[-1][0] - right_brow[0][0])
+
+            # 长度对称性
+            length_symmetry = 1 - min(
+                abs(left_length - right_length) / max(left_length, right_length), 0.5
+            )
+
+            # 计算眉毛拱形 - 改进方法
+            left_peak_y = min([p[1] for p in left_brow])  # 眉峰(y坐标最小)
+            left_ends_y = (left_brow[0][1] + left_brow[-1][1]) / 2  # 眉毛两端平均高度
+            left_arch = max(0, left_ends_y - left_peak_y)  # 拱形高度
+
+            right_peak_y = min([p[1] for p in right_brow])
+            right_ends_y = (right_brow[0][1] + right_brow[-1][1]) / 2
+            right_arch = max(0, right_ends_y - right_peak_y)
+
+            # 拱形对称性
+            arch_symmetry = 1 - min(
+                abs(left_arch - right_arch) / max(left_arch, right_arch, 1), 0.5
+            )
+
+            # 眉形适中性评分
+            avg_arch = (left_arch + right_arch) / 2
+            face_height = image_shape[0]
+            ideal_arch_ratio = 0.015  # 理想拱形比例
+            arch_ratio = avg_arch / face_height
+            arch_score = max(
+                0, 1 - abs(arch_ratio - ideal_arch_ratio) / ideal_arch_ratio
+            )
+
+            # 眉毛浓密度(通过点的密集程度估算)
+            density_score = min(1.0, (len(left_brow) + len(right_brow)) / 10)
+
+            final_score = (
+                length_symmetry * 0.3
+                + arch_symmetry * 0.3
+                + arch_score * 0.25
+                + density_score * 0.15
+            ) * 10
+            return round(max(0, min(10, final_score)), 2)
+        except:
+            return 6.21
+
+    def _score_jawline(self, jawline: List[tuple], image_shape: tuple) -> float:
+        """下颌线评分 - 改进算法"""
+        try:
+            jaw_points = [(p[0], p[1]) for p in jawline]
+
+            # 关键点
+            left_jaw = jaw_points[2]  # 左下颌角
+            jaw_tip = jaw_points[8]  # 下巴尖
+            right_jaw = jaw_points[14]  # 右下颌角
+
+            # 对称性评分 - 改进计算
+            left_dist = (
+                (left_jaw[0] - jaw_tip[0]) ** 2 + (left_jaw[1] - jaw_tip[1]) ** 2
+            ) ** 0.5
+            right_dist = (
+                (right_jaw[0] - jaw_tip[0]) ** 2 + (right_jaw[1] - jaw_tip[1]) ** 2
+            ) ** 0.5
+            symmetry = 1 - min(
+                abs(left_dist - right_dist) / max(left_dist, right_dist), 0.5
+            )
+
+            # 下颌角度评分
+            left_angle_y = abs(left_jaw[1] - jaw_tip[1])
+            right_angle_y = abs(right_jaw[1] - jaw_tip[1])
+            avg_angle = (left_angle_y + right_angle_y) / 2
+
+            # 理想的下颌角度
+            face_height = image_shape[0]
+            ideal_angle_ratio = 0.08
+            angle_ratio = avg_angle / face_height
+            angle_score = max(
+                0, 1 - abs(angle_ratio - ideal_angle_ratio) / ideal_angle_ratio
+            )
+
+            # 下颌线清晰度(通过点间距离变化评估)
+            smoothness_score = 0.8  # 简化处理，可以根据实际需要改进
+
+            final_score = (
+                symmetry * 0.4 + angle_score * 0.35 + smoothness_score * 0.25
+            ) * 10
+            return round(max(0, min(10, final_score)), 2)
+        except:
+            return 6.21
+
+    def _calculate_harmony(self, landmarks: List[tuple], image_shape: tuple) -> float:
+        """计算五官协调性"""
+        try:
+            # 黄金比例检测 (简化版)
+            face_height = max([p[1] for p in landmarks]) - min(
+                [p[1] for p in landmarks]
+            )
+            face_width = max([p[0] for p in landmarks]) - min([p[0] for p in landmarks])
+
+            # 理想比例约为1.618
+            ratio = face_height / face_width if face_width > 0 else 1
+            golden_ratio = 1.618
+            harmony = 1 - abs(ratio - golden_ratio) / golden_ratio
+
+            return max(0, min(10, harmony * 10))
+        except:
+            return 6.21
+
+    def _calculate_harmony_new(
+        self, landmarks: List[tuple], image_shape: tuple
+    ) -> float:
+        """
+        计算五官协调性 - 优化版本
+        基于多个美学比例和对称性指标
+        """
+        try:
+            logger.debug(f"face landmarks={len(landmarks)}")
+            if len(landmarks) < 68:  # 假设使用68点面部关键点
+                return 6.21
+
+            # 转换为numpy数组便于计算
+            points = np.array(landmarks)
+
+            # 1. 面部基础测量
+            face_measurements = self._get_face_measurements(points)
+
+            # 2. 计算多个协调性指标
+            scores = []
+
+            # 黄金比例评分 (权重: 20%)
+            golden_score = self._calculate_golden_ratios(face_measurements)
+            logger.debug(f"Golden ratio score={golden_score}")
+            scores.append(("golden_ratio", golden_score, 0.10))
+
+            # 对称性评分 (权重: 25%)
+            symmetry_score = self._calculate_facial_symmetry(face_measurements, points)
+            logger.debug(f"Symmetry score={symmetry_score}")
+            scores.append(("symmetry", symmetry_score, 0.40))
+
+            # 三庭五眼比例 (权重: 20%)
+            proportion_score = self._calculate_classical_proportions(face_measurements)
+            logger.debug(f"Three courts five eyes ratio={proportion_score}")
+            scores.append(("proportions", proportion_score, 0.05))
+
+            # 五官间距协调性 (权重: 15%)
+            spacing_score = self._calculate_feature_spacing(face_measurements)
+            logger.debug(f"Facial feature spacing harmony={spacing_score}")
+            scores.append(("spacing", spacing_score, 0))
+
+            # 面部轮廓协调性 (权重: 10%)
+            contour_score = self._calculate_contour_harmony(points)
+            logger.debug(f"Facial contour harmony={contour_score}")
+            scores.append(("contour", contour_score, 0.05))
+
+            # 眼鼻口比例协调性 (权重: 10%)
+            feature_score = self._calculate_feature_proportions(face_measurements)
+            logger.debug(f"Eye-nose-mouth proportion harmony={feature_score}")
+            scores.append(("features", feature_score, 0.40))
+
+            # 加权平均计算最终得分
+            final_score = sum(score * weight for _, score, weight in scores)
+            logger.debug(f"Weighted average final score={final_score}")
+            return max(0, min(10, final_score))
+
+        except Exception as e:
+            logger.error(f"Error calculating facial harmony: {e}")
+            traceback.print_exc()  # ← 打印完整堆栈，包括确切行号
+            return 6.21
+
+    def _get_face_measurements(self, points: np.ndarray) -> Dict[str, float]:
+        """提取面部关键测量数据"""
+        measurements = {}
+
+        # 面部轮廓点 (0-16)
+        face_contour = points[0:17]
+
+        # 眉毛点 (17-26)
+        left_eyebrow = points[17:22]
+        right_eyebrow = points[22:27]
+
+        # 眼睛点 (36-47)
+        left_eye = points[36:42]
+        right_eye = points[42:48]
+
+        # 鼻子点 (27-35)
+        nose = points[27:36]
+
+        # 嘴巴点 (48-67)
+        mouth = points[48:68]
+
+        # 基础测量
+        measurements["face_width"] = np.max(face_contour[:, 0]) - np.min(
+            face_contour[:, 0]
+        )
+        measurements["face_height"] = np.max(points[:, 1]) - np.min(points[:, 1])
+
+        # 眼部测量
+        measurements["left_eye_width"] = np.max(left_eye[:, 0]) - np.min(left_eye[:, 0])
+        measurements["right_eye_width"] = np.max(right_eye[:, 0]) - np.min(
+            right_eye[:, 0]
+        )
+        measurements["eye_distance"] = np.min(right_eye[:, 0]) - np.max(left_eye[:, 0])
+        measurements["left_eye_center"] = np.mean(left_eye, axis=0)
+        measurements["right_eye_center"] = np.mean(right_eye, axis=0)
+
+        # 鼻部测量
+        measurements["nose_width"] = np.max(nose[:, 0]) - np.min(nose[:, 0])
+        measurements["nose_height"] = np.max(nose[:, 1]) - np.min(nose[:, 1])
+        measurements["nose_tip"] = points[33]  # 鼻尖
+
+        # 嘴部测量
+        measurements["mouth_width"] = np.max(mouth[:, 0]) - np.min(mouth[:, 0])
+        measurements["mouth_height"] = np.max(mouth[:, 1]) - np.min(mouth[:, 1])
+
+        # 关键垂直距离
+        measurements["forehead_height"] = measurements["left_eye_center"][1] - np.min(
+            points[:, 1]
+        )
+        measurements["middle_face_height"] = (
+            measurements["nose_tip"][1] - measurements["left_eye_center"][1]
+        )
+        measurements["lower_face_height"] = (
+            np.max(points[:, 1]) - measurements["nose_tip"][1]
+        )
+
+        return measurements
+
+    def _calculate_golden_ratios(self, measurements: Dict[str, float]) -> float:
+        """计算黄金比例相关得分"""
+        golden_ratio = 1.618
+        scores = []
+
+        # 面部长宽比
+        if measurements["face_width"] > 0:
+            face_ratio = measurements["face_height"] / measurements["face_width"]
+            score = 1 - abs(face_ratio - golden_ratio) / golden_ratio
+            scores.append(max(0, score))
+
+        # 上中下三庭比例
+        total_height = (
+            measurements["forehead_height"]
+            + measurements["middle_face_height"]
+            + measurements["lower_face_height"]
+        )
+
+        if total_height > 0:
+            upper_ratio = measurements["forehead_height"] / total_height
+            middle_ratio = measurements["middle_face_height"] / total_height
+            lower_ratio = measurements["lower_face_height"] / total_height
+
+            # 理想比例约为 1:1:1
+            ideal_ratio = 1 / 3
+            upper_score = 1 - abs(upper_ratio - ideal_ratio) / ideal_ratio
+            middle_score = 1 - abs(middle_ratio - ideal_ratio) / ideal_ratio
+            lower_score = 1 - abs(lower_ratio - ideal_ratio) / ideal_ratio
+
+            scores.extend(
+                [max(0, upper_score), max(0, middle_score), max(0, lower_score)]
+            )
+
+        return np.mean(scores) * 10 if scores else 7.0
+
+    def _calculate_facial_symmetry(
+        self, measurements: Dict[str, float], points: np.ndarray
+    ) -> float:
+        """计算面部对称性"""
+        # 计算面部中线
+        face_center_x = np.mean(points[:, 0])
+
+        # 检查左右对称的关键点对
+        symmetry_pairs = [
+            (17, 26),  # 眉毛外端
+            (18, 25),  # 眉毛
+            (19, 24),  # 眉毛
+            (36, 45),  # 眼角
+            (39, 42),  # 眼角
+            (31, 35),  # 鼻翼
+            (48, 54),  # 嘴角
+            (4, 12),  # 面部轮廓
+            (5, 11),  # 面部轮廓
+            (6, 10),  # 面部轮廓
+        ]
+
+        symmetry_scores = []
+
+        for left_idx, right_idx in symmetry_pairs:
+            if left_idx < len(points) and right_idx < len(points):
+                left_point = points[left_idx]
+                right_point = points[right_idx]
+
+                # 计算到中线的距离差异
+                left_dist = abs(left_point[0] - face_center_x)
+                right_dist = abs(right_point[0] - face_center_x)
+
+                # 垂直位置差异
+                vertical_diff = abs(left_point[1] - right_point[1])
+
+                # 对称性得分
+                if left_dist + right_dist > 0:
+                    horizontal_symmetry = 1 - abs(left_dist - right_dist) / (
+                        left_dist + right_dist
+                    )
+                    vertical_symmetry = 1 - vertical_diff / measurements.get(
+                        "face_height", 100
+                    )
+
+                    symmetry_scores.append(
+                        (horizontal_symmetry + vertical_symmetry) / 2
+                    )
+
+        return np.mean(symmetry_scores) * 10 if symmetry_scores else 7.0
+
+    def _calculate_classical_proportions(self, measurements: Dict[str, float]) -> float:
+        """计算经典美学比例 (三庭五眼等)"""
+        scores = []
+
+        # 五眼比例检测
+        if measurements["face_width"] > 0:
+            eye_width_avg = (
+                measurements["left_eye_width"] + measurements["right_eye_width"]
+            ) / 2
+            ideal_eye_count = 5  # 理想情况下面宽应该等于5个眼宽
+            actual_eye_count = (
+                measurements["face_width"] / eye_width_avg if eye_width_avg > 0 else 5
+            )
+
+            eye_proportion_score = (
+                1 - abs(actual_eye_count - ideal_eye_count) / ideal_eye_count
+            )
+            scores.append(max(0, eye_proportion_score))
+
+        # 眼间距比例
+        if measurements.get("left_eye_width", 0) > 0:
+            eye_spacing_ratio = (
+                measurements["eye_distance"] / measurements["left_eye_width"]
+            )
+            ideal_spacing_ratio = 1.0  # 理想情况下眼间距约等于一个眼宽
+
+            spacing_score = (
+                1 - abs(eye_spacing_ratio - ideal_spacing_ratio) / ideal_spacing_ratio
+            )
+            scores.append(max(0, spacing_score))
+
+        # 鼻宽与眼宽比例
+        if (
+            measurements.get("left_eye_width", 0) > 0
+            and measurements.get("nose_width", 0) > 0
+        ):
+            nose_eye_ratio = measurements["nose_width"] / measurements["left_eye_width"]
+            ideal_nose_eye_ratio = 0.8  # 理想鼻宽约为眼宽的80%
+
+            nose_score = (
+                1 - abs(nose_eye_ratio - ideal_nose_eye_ratio) / ideal_nose_eye_ratio
+            )
+            scores.append(max(0, nose_score))
+
+        return np.mean(scores) * 10 if scores else 7.0
+
+    def _calculate_feature_spacing(self, measurements: Dict[str, float]) -> float:
+        """计算五官间距协调性"""
+        scores = []
+
+        # 眼鼻距离协调性
+        eye_nose_distance = abs(
+            measurements["left_eye_center"][1] - measurements["nose_tip"][1]
+        )
+        if measurements.get("face_height", 0) > 0:
+            eye_nose_ratio = eye_nose_distance / measurements["face_height"]
+            ideal_ratio = 0.15  # 理想比例
+            score = 1 - abs(eye_nose_ratio - ideal_ratio) / ideal_ratio
+            scores.append(max(0, score))
+
+        # 鼻嘴距离协调性
+        nose_mouth_distance = abs(
+            measurements["nose_tip"][1] - np.mean([measurements.get("mouth_height", 0)])
+        )
+        if measurements.get("face_height", 0) > 0:
+            nose_mouth_ratio = nose_mouth_distance / measurements["face_height"]
+            ideal_ratio = 0.12  # 理想比例
+            score = 1 - abs(nose_mouth_ratio - ideal_ratio) / ideal_ratio
+            scores.append(max(0, score))
+
+        return np.mean(scores) * 10 if scores else 7.0
+
+    def _calculate_contour_harmony(self, points: np.ndarray) -> float:
+        """计算面部轮廓协调性"""
+        try:
+            face_contour = points[0:17]  # 面部轮廓点
+
+            # 计算轮廓的平滑度
+            smoothness_scores = []
+
+            for i in range(1, len(face_contour) - 1):
+                # 计算相邻三点形成的角度
+                p1, p2, p3 = face_contour[i - 1], face_contour[i], face_contour[i + 1]
+
+                v1 = p1 - p2
+                v2 = p3 - p2
+
+                # 计算角度
+                cos_angle = np.dot(v1, v2) / (
+                    np.linalg.norm(v1) * np.linalg.norm(v2) + 1e-8
+                )
+                angle = np.arccos(np.clip(cos_angle, -1, 1))
+
+                # 角度越接近平滑曲线越好 (避免过于尖锐的角度)
+                smoothness = 1 - abs(angle - np.pi / 2) / (np.pi / 2)
+                smoothness_scores.append(max(0, smoothness))
+
+            return np.mean(smoothness_scores) * 10 if smoothness_scores else 7.0
+
+        except:
+            return 6.21
+
+    def _calculate_feature_proportions(self, measurements: Dict[str, float]) -> float:
+        """计算眼鼻口等五官内部比例协调性"""
+        scores = []
+
+        # 眼部比例 (长宽比)
+        left_eye_ratio = measurements.get("left_eye_width", 1) / max(
+            measurements.get("left_eye_width", 1) * 0.3, 1
+        )
+        right_eye_ratio = measurements.get("right_eye_width", 1) / max(
+            measurements.get("right_eye_width", 1) * 0.3, 1
+        )
+
+        # 理想眼部长宽比约为3:1
+        ideal_eye_ratio = 3.0
+        left_eye_score = 1 - abs(left_eye_ratio - ideal_eye_ratio) / ideal_eye_ratio
+        right_eye_score = 1 - abs(right_eye_ratio - ideal_eye_ratio) / ideal_eye_ratio
+
+        scores.extend([max(0, left_eye_score), max(0, right_eye_score)])
+
+        # 嘴部比例
+        if measurements.get("mouth_height", 0) > 0:
+            mouth_ratio = measurements["mouth_width"] / measurements["mouth_height"]
+            ideal_mouth_ratio = 3.5  # 理想嘴部长宽比
+            mouth_score = 1 - abs(mouth_ratio - ideal_mouth_ratio) / ideal_mouth_ratio
+            scores.append(max(0, mouth_score))
+
+        # 鼻部比例
+        if measurements.get("nose_height", 0) > 0:
+            nose_ratio = measurements["nose_height"] / measurements["nose_width"]
+            ideal_nose_ratio = 1.5  # 理想鼻部长宽比
+            nose_score = 1 - abs(nose_ratio - ideal_nose_ratio) / ideal_nose_ratio
+            scores.append(max(0, nose_score))
+
+        return np.mean(scores) * 10 if scores else 7.0
+
+    def _basic_facial_analysis(self, face_image) -> Dict[str, Any]:
+        """基础五官分析 (当dlib不可用时)"""
+        return {
+            "facial_features": {
+                "eyes": 7.0,
+                "nose": 7.0,
+                "mouth": 7.0,
+                "eyebrows": 7.0,
+                "jawline": 7.0,
+            },
+            "harmony_score": 7.0,
+            "overall_facial_score": 7.0,
+            "analysis_method": "basic_estimation",
+        }
+
+    def draw_facial_landmarks(self, face_image: np.ndarray) -> np.ndarray:
+        """
+        在人脸图像上绘制特征点
+        :param face_image: 人脸图像
+        :return: 带特征点标记的人脸图像
+        """
+        if not DLIB_AVAILABLE or self.face_mesh is None:
+            # 如果没有可用的面部网格检测器，直接返回原图
+            return face_image.copy()
+
+        try:
+            # 复制原图用于绘制
+            annotated_image = face_image.copy()
+            
+            # MediaPipe需要RGB图像
+            rgb_image = cv2.cvtColor(face_image, cv2.COLOR_BGR2RGB)
+
+            # 检测关键点
+            results = self.face_mesh.process(rgb_image)
+
+            if not results.multi_face_landmarks:
+                logger.warning("No facial landmarks detected for drawing")
+                return annotated_image
+
+            # 获取第一个面部的关键点
+            face_landmarks = results.multi_face_landmarks[0]
+
+            # 绘制所有关键点
+            h, w = face_image.shape[:2]
+            for landmark in face_landmarks.landmark:
+                x = int(landmark.x * w)
+                y = int(landmark.y * h)
+                # 绘制小圆点表示关键点
+                cv2.circle(annotated_image, (x, y), 1, (0, 255, 0), -1)
+                
+                # 绘制十字标记
+                cv2.line(annotated_image, (x-2, y), (x+2, y), (0, 255, 0), 1)
+                cv2.line(annotated_image, (x, y-2), (x, y+2), (0, 255, 0), 1)
+
+            return annotated_image
+
+        except Exception as e:
+            logger.error(f"Failed to draw facial landmarks: {e}")
+            return face_image.copy()

gfpgan_restorer.py

@@ -0,0 +1,96 @@
+import os
+import time
+
+from config import logger, MODELS_PATH
+from gfpgan import GFPGANer
+
+
+class GFPGANRestorer:
+    def __init__(self):
+        start_time = time.perf_counter()
+        self.restorer = None
+        self._initialize_model()
+        init_time = time.perf_counter() - start_time
+        if self.restorer is not None:
+            logger.info(f"GFPGANRestorer initialized successfully, time: {init_time:.3f}s")
+        else:
+            logger.info(f"GFPGANRestorer initialization completed but not available, time: {init_time:.3f}s")
+
+    def _initialize_model(self):
+        """初始化GFPGAN模型"""
+        try:
+            # 尝试多个可能的模型路径
+            possible_paths = [
+                f"{MODELS_PATH}/GFPGANv1.4.pth",
+                f"{MODELS_PATH}/gfpgan/GFPGANv1.4.pth",
+                os.path.expanduser("~/.cache/gfpgan/GFPGANv1.4.pth"),
+                "./models/GFPGANv1.4.pth"
+            ]
+
+            gfpgan_model_path = None
+            for path in possible_paths:
+                if os.path.exists(path):
+                    gfpgan_model_path = path
+                    break
+
+            if not gfpgan_model_path:
+                logger.warning(f"GFPGAN model file not found, tried paths: {possible_paths}")
+                logger.info("Will try to download GFPGAN model from the internet...")
+                # 使用默认路径，让GFPGAN自动下载
+                gfpgan_model_path = 'https://github.com/TencentARC/GFPGAN/releases/download/v1.3.0/GFPGANv1.4.pth'
+
+            logger.info(f"Using GFPGAN model: {gfpgan_model_path}")
+
+            # 初始化GFPGAN
+            self.restorer = GFPGANer(
+                model_path=gfpgan_model_path,
+                upscale=2,
+                arch='clean',
+                channel_multiplier=2,
+                bg_upsampler=None
+            )
+            logger.info("GFPGAN model initialized successfully")
+
+        except Exception as e:
+            logger.error(f"GFPGAN model initialization failed: {e}")
+            self.restorer = None
+
+
+    def is_available(self):
+        """检查GFPGAN是否可用"""
+        return self.restorer is not None
+
+    def restore_image(self, image):
+        """
+        使用GFPGAN修复老照片
+        :param image: 输入图像 (numpy array, BGR格式)
+        :return: 修复后的图像 (numpy array, BGR格式)
+        """
+        if not self.is_available():
+            raise Exception("GFPGAN模型未初始化")
+
+        try:
+            logger.info("Starting GFPGAN image restoration...")
+
+            # GFPGAN处理
+            # has_aligned=False: 输入图像没有对齐
+            # only_center_face=False: 处理所有检测到的人脸
+            # paste_back=True: 将修复的人脸贴回原图
+            cropped_faces, restored_faces, restored_img = self.restorer.enhance(
+                image,
+                has_aligned=False,
+                only_center_face=False,
+                paste_back=True
+            )
+
+            if restored_img is not None:
+                logger.info(f"GFPGAN restoration completed, detected {len(restored_faces)} faces")
+                return restored_img
+            else:
+                logger.warning("GFPGAN restoration returned empty image, using original image")
+                return image
+
+        except Exception as e:
+            logger.error(f"GFPGAN image restoration failed: {e}")
+            # 如果GFPGAN失败，返回原图而不是抛出异常
+            return image

models.py

@@ -0,0 +1,69 @@
+from enum import Enum
+from typing import List, Optional
+
+from pydantic import BaseModel
+
+
+class ModelType(str, Enum):
+    """模型类型枚举"""
+
+    HOWCUTEAMI = "howcuteami"
+    DEEPFACE = "deepface"
+    HYBRID = "hybrid"  # 混合模式：颜值性别用howcuteami，年龄情绪用deepface
+
+
+class ImageScoreItem(BaseModel):
+    file_path: str
+    score: float
+    is_cropped_face: bool = False
+    size_bytes: int
+    size_str: str
+    last_modified: str
+    nickname: Optional[str] = None
+
+
+class SearchRequest(BaseModel):
+    keyword: Optional[str] = ""
+    searchType: Optional[str] = "face"
+    top_k: Optional[int] = 5
+    score_threshold: float = 0.0
+    nickname: Optional[str] = None
+
+
+class ImageSearchRequest(BaseModel):
+    image: Optional[str] = None  # base64编码的图片
+    searchType: Optional[str] = "face"
+    top_k: Optional[int] = 5
+    score_threshold: float = 0.0
+    nickname: Optional[str] = None
+
+
+class ImageFileList(BaseModel):
+    results: List[ImageScoreItem]
+    count: int
+
+class PagedImageFileList(BaseModel):
+    results: List[ImageScoreItem]
+    count: int
+    page: int
+    page_size: int
+    total_pages: int
+
+class CelebrityMatchResponse(BaseModel):
+    filename: str
+    display_name: Optional[str] = None
+    distance: float
+    similarity: float
+    confidence: float
+    face_filename: Optional[str] = None
+
+
+class CategoryStatItem(BaseModel):
+  category: str
+  display_name: str
+  count: int
+
+
+class CategoryStatsResponse(BaseModel):
+  stats: List[CategoryStatItem]
+  total: int

realesrgan_upscaler.py

@@ -0,0 +1,235 @@
+import os
+import time
+
+import cv2
+import numpy as np
+
+from config import logger, MODELS_PATH, REALESRGAN_MODEL
+
+try:
+    from basicsr.archs.rrdbnet_arch import RRDBNet
+    from basicsr.utils.download_util import load_file_from_url
+    from realesrgan import RealESRGANer
+    from realesrgan.archs.srvgg_arch import SRVGGNetCompact
+    import torch
+
+    # 设置PyTorch CPU优化
+    torch.set_num_threads(min(torch.get_num_threads(), 8))  # 限制线程数
+    torch.set_num_interop_threads(min(4, torch.get_num_interop_threads()))  # 设置操作间线程数
+
+    REALESRGAN_AVAILABLE = True
+    logger.info("Real-ESRGAN imported successfully")
+except ImportError as e:
+    logger.error(f"Real-ESRGAN import failed: {e}")
+    REALESRGAN_AVAILABLE = False
+
+
+class RealESRGANUpscaler:
+    """Real-ESRGAN超清放大处理器"""
+
+    def __init__(self):
+        start_time = time.perf_counter()
+        self.upsampler = None
+        self.model_name = None
+        self.scale = 4
+        self.denoise_strength = 0.5
+        self._initialize()
+        init_time = time.perf_counter() - start_time
+        if self.upsampler is not None:
+            logger.info(f"RealESRGANUpscaler initialized successfully, time: {init_time:.3f}s")
+        else:
+            logger.info(f"RealESRGANUpscaler initialization completed but not available, time: {init_time:.3f}s")
+
+    def _initialize(self):
+        """初始化Real-ESRGAN模型"""
+        if not REALESRGAN_AVAILABLE:
+            logger.error("Real-ESRGAN is not available, cannot initialize super resolution processor")
+            return
+
+        try:
+            # 模型配置 - 从环境变量读取模型名称
+            model_name = REALESRGAN_MODEL
+            self.model_name = model_name
+
+            # 根据模型名称设置默认放大倍数
+            if 'x2' in model_name:
+                self.scale = 2
+            elif 'x4' in model_name:
+                self.scale = 4
+            else:
+                self.scale = 4  # 默认4倍
+
+            # 模型文件路径
+            model_path = None
+            if model_name == 'RealESRGAN_x4plus':
+                model = RRDBNet(num_in_ch=3, num_out_ch=3, num_feat=64, num_block=23, num_grow_ch=32, scale=4)
+                netscale = 4
+                file_url = 'https://github.com/xinntao/Real-ESRGAN/releases/download/v0.1.0/RealESRGAN_x4plus.pth'
+            elif model_name == 'RealESRNet_x4plus':
+                model = RRDBNet(num_in_ch=3, num_out_ch=3, num_feat=64, num_block=23, num_grow_ch=32, scale=4)
+                netscale = 4
+                file_url = 'https://github.com/xinntao/Real-ESRGAN/releases/download/v0.1.1/RealESRNet_x4plus.pth'
+            elif model_name == 'RealESRGAN_x4plus_anime_6B':
+                model = RRDBNet(num_in_ch=3, num_out_ch=3, num_feat=64, num_block=6, num_grow_ch=32, scale=4)
+                netscale = 4
+                file_url = 'https://github.com/xinntao/Real-ESRGAN/releases/download/v0.2.2.4/RealESRGAN_x4plus_anime_6B.pth'
+            elif model_name == 'RealESRGAN_x2plus':
+                model = RRDBNet(num_in_ch=3, num_out_ch=3, num_feat=64, num_block=23, num_grow_ch=32, scale=2)
+                netscale = 2
+                file_url = 'https://github.com/xinntao/Real-ESRGAN/releases/download/v0.2.1/RealESRGAN_x2plus.pth'
+            elif model_name == 'realesr-animevideov3':
+                model = SRVGGNetCompact(num_in_ch=3, num_out_ch=3, num_feat=64, num_conv=16, upscale=4, act_type='prelu')
+                netscale = 4
+                file_url = 'https://github.com/xinntao/Real-ESRGAN/releases/download/v0.2.5.0/realesr-animevideov3.pth'
+            elif model_name == 'realesr-general-x4v3':
+                # 最新的通用模型 v0.2.5.0
+                model = SRVGGNetCompact(num_in_ch=3, num_out_ch=3, num_feat=64, num_conv=32, upscale=4, act_type='prelu')
+                netscale = 4
+                file_url = 'https://github.com/xinntao/Real-ESRGAN/releases/download/v0.2.5.0/realesr-general-x4v3.pth'
+            elif model_name == 'realesr-general-wdn-x4v3':
+                # 最新的通用模型（带去噪）v0.2.5.0
+                model = SRVGGNetCompact(num_in_ch=3, num_out_ch=3, num_feat=64, num_conv=32, upscale=4, act_type='prelu')
+                netscale = 4
+                file_url = 'https://github.com/xinntao/Real-ESRGAN/releases/download/v0.2.5.0/realesr-general-wdn-x4v3.pth'
+
+            # 确保模型目录存在
+            model_dir = os.path.join(MODELS_PATH, 'realesrgan')
+            os.makedirs(model_dir, exist_ok=True)
+
+            # 检查本地是否已有模型文件
+            local_model_path = None
+            model_filename = f"{model_name}.pth"
+            local_pth = os.path.join(MODELS_PATH, model_filename)
+
+            if os.path.exists(local_pth):
+                local_model_path = local_pth
+                logger.info(f"Using local model file: {local_model_path}")
+
+            # 如果本地有模型文件，使用本地文件，��则下载
+            if local_model_path:
+                model_path = local_model_path
+            else:
+                # 下载模型
+                logger.info(f"Downloading model {model_name} from {file_url}")
+                model_path = load_file_from_url(
+                    url=file_url, model_dir=model_dir, progress=True, file_name=model_filename)
+
+            # 创建upsampler
+            self.upsampler = RealESRGANer(
+                scale=netscale,
+                model_path=model_path,
+                model=model,
+                tile=512,  # 启用分块处理，减少内存使用并提高CPU效率
+                tile_pad=10,
+                pre_pad=0,
+                half=False,  # 使用fp32精度
+                gpu_id=None  # 使用CPU
+            )
+
+            logger.info(f"Real-ESRGAN super resolution processor initialized successfully, model: {model_name}")
+
+        except Exception as e:
+            logger.error(f"Failed to initialize Real-ESRGAN: {e}")
+            self.upsampler = None
+
+    def is_available(self):
+        """检查处理器是否可用"""
+        return REALESRGAN_AVAILABLE and self.upsampler is not None
+
+    def _optimize_input_image(self, image):
+        """
+        优化输入图像以提高CPU处理速度
+        :param image: 输入图像
+        :return: 优化后的图像
+        """
+        # 确保图像数据类型为uint8（减少计算开销）
+        if image.dtype != np.uint8:
+            if image.dtype == np.float32 or image.dtype == np.float64:
+                image = (image * 255).astype(np.uint8)
+            else:
+                image = image.astype(np.uint8)
+
+        # 确保图像是3通道BGR格式
+        if len(image.shape) == 2:  # 灰度图
+            image = cv2.cvtColor(image, cv2.COLOR_GRAY2BGR)
+        elif image.shape[2] == 4:  # RGBA
+            image = cv2.cvtColor(image, cv2.COLOR_RGBA2BGR)
+        elif image.shape[2] == 3 and image.shape[2] != 3:  # RGB转BGR
+            image = cv2.cvtColor(image, cv2.COLOR_RGB2BGR)
+
+        return image
+
+    def upscale_image(self, image, scale=None, denoise_strength=None):
+        """
+        对图像进行超清放大
+        :param image: 输入图像 (numpy array)
+        :param scale: 放大倍数，默认使用模型的放大倍数
+        :param denoise_strength: 去噪强度 (0-1)，仅对realesr-general-x4v3模型有效
+        :return: 超清后的图像
+        """
+        if not self.is_available():
+            raise RuntimeError("Real-ESRGAN超清处理器不可用")
+
+        try:
+            start_time = time.perf_counter()
+
+            # 预处理优化图像
+            image = self._optimize_input_image(image)
+
+            # 设置去噪强度（仅对特定模型有效）
+            if denoise_strength is not None and self.model_name == 'realesr-general-x4v3':
+                self.denoise_strength = denoise_strength
+
+            # 根据图像大小动态调整tile大小以优化CPU性能
+            h, w = image.shape[:2]
+            pixel_count = h * w
+
+            # 根据图像大小调整tile大小
+            if pixel_count > 2000000:  # 大于2MP
+                tile_size = 256
+            elif pixel_count > 1000000:  # 大于1MP
+                tile_size = 384
+            else:
+                tile_size = 512
+
+            # 动态更新tile大小
+            if hasattr(self.upsampler, 'tile'):
+                self.upsampler.tile = tile_size
+                logger.info(f"Adjusting tile size to: {tile_size} based on image size ({w}x{h})")
+
+            # 执行超清处理
+            logger.info(f"Starting Real-ESRGAN super resolution processing, model: {self.model_name}")
+            output, _ = self.upsampler.enhance(image, outscale=scale or self.scale)
+
+            processing_time = time.perf_counter() - start_time
+            logger.info(f"Real-ESRGAN super resolution processing completed, time: {processing_time:.3f}s")
+
+            return output
+
+        except Exception as e:
+            logger.error(f"Real-ESRGAN super resolution processing failed: {e}")
+            raise RuntimeError(f"超清处理失败: {str(e)}")
+
+    def get_model_info(self):
+        """获取模型信息"""
+        return {
+            "model_name": self.model_name,
+            "scale": self.scale,
+            "available": self.is_available()
+        }
+
+
+def get_upscaler():
+    """获取Real-ESRGAN超清处理器实例"""
+    return RealESRGANUpscaler()
+
+
+# 全局实例（单例模式）
+_upscaler_instance = None
+
+def get_upscaler():
+    """获取全局超清处理器实例"""
+    global _upscaler_instance
+    if _upscaler_instance is None:
+        _upscaler_instance = RealESRGANUpscaler()
+    return _upscaler_instance

rembg_processor.py

@@ -0,0 +1,136 @@
+import time
+from typing import Optional, Tuple
+
+import cv2
+import numpy as np
+
+from config import logger, REMBG_AVAILABLE
+
+if REMBG_AVAILABLE:
+    import rembg
+    from rembg import new_session
+    from PIL import Image
+
+
+class RembgProcessor:
+    """rembg抠图处理器"""
+
+    def __init__(self):
+        start_time = time.perf_counter()
+        self.session = None
+        self.available = False
+        self.model_name = "u2net"  # 默认使用u2net模型，适合人像抠图
+
+        if REMBG_AVAILABLE:
+            try:
+                # 初始化rembg会话
+                self.session = new_session(self.model_name)
+                self.available = True
+                logger.info(f"rembg background removal processor initialized successfully, using model: {self.model_name}")
+            except Exception as e:
+                logger.error(f"rembg background removal processor initialization failed: {e}")
+                self.available = False
+        else:
+            logger.warning("rembg is not available, background removal function will be disabled")
+        init_time = time.perf_counter() - start_time
+        if self.available:
+            logger.info(f"RembgProcessor initialized successfully, time: {init_time:.3f}s")
+        else:
+            logger.info(f"RembgProcessor initialization completed but not available, time: {init_time:.3f}s")
+
+    def is_available(self) -> bool:
+        """检查抠图处理器是否可用"""
+        return self.available and self.session is not None
+
+    def remove_background(self, image: np.ndarray, background_color: Optional[Tuple[int, int, int]] = None) -> np.ndarray:
+        """
+        移除图片背景
+        :param image: 输入的OpenCV图像(BGR格式)
+        :param background_color: 替换的背景颜色(BGR格式)，如果为None则保持透明背景
+        :return: 处理后的图像
+        """
+        if not self.is_available():
+            raise Exception("rembg抠图处理器不可用")
+
+        try:
+            # 将OpenCV图像(BGR)转换为PIL图像(RGB)
+            image_rgb = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)
+            pil_image = Image.fromarray(image_rgb)
+
+            # 使用rembg移除背景
+            logger.info("Starting to remove background using rembg...")
+            output_image = rembg.remove(pil_image, session=self.session)
+
+            # 转换回OpenCV格式
+            if background_color is not None:
+                # 如果指定了背景颜色，创建纯色背景
+                background = Image.new('RGB', output_image.size, background_color[::-1])  # BGR转RGB
+                # 将透明图像粘贴到背景上
+                background.paste(output_image, mask=output_image)
+                result_array = np.array(background)
+                result_bgr = cv2.cvtColor(result_array, cv2.COLOR_RGB2BGR)
+            else:
+                # 保持透明背景，转换为BGRA格式
+                result_array = np.array(output_image)
+                if result_array.shape[2] == 4:  # RGBA格式
+                    # 转换RGBA到BGRA
+                    result_bgr = cv2.cvtColor(result_array, cv2.COLOR_RGBA2BGRA)
+                else:  # RGB格式
+                    result_bgr = cv2.cvtColor(result_array, cv2.COLOR_RGB2BGR)
+
+            logger.info("rembg background removal completed")
+            return result_bgr
+
+        except Exception as e:
+            logger.error(f"rembg background removal failed: {e}")
+            raise Exception(f"背景移除失败: {str(e)}")
+
+    def create_id_photo(self, image: np.ndarray, background_color: Tuple[int, int, int] = (255, 255, 255)) -> np.ndarray:
+        """
+        创建证件照（移除背景并添加纯色背景）
+        :param image: 输入的OpenCV图像
+        :param background_color: 背景颜色，默认白色(BGR格式)
+        :return: 处理后的证件照
+        """
+        logger.info(f"Starting to create ID photo, background color: {background_color}")
+
+        # 移除背景并添加指定颜色背景
+        id_photo = self.remove_background(image, background_color)
+
+        logger.info("ID photo creation completed")
+        return id_photo
+
+    def get_supported_models(self) -> list:
+        """获取支持的模型列表"""
+        if not REMBG_AVAILABLE:
+            return []
+
+        # rembg支持的模型列表
+        return [
+            "u2net",          # 通用模型，适合人像
+            "u2net_human_seg", # 专门针对人像的模型
+            "silueta",        # 适合物体抠图
+            "isnet-general-use" # 更精确的通用模型
+        ]
+
+    def switch_model(self, model_name: str) -> bool:
+        """
+        切换rembg模型
+        :param model_name: 模型名称
+        :return: 是否切换成功
+        """
+        if not REMBG_AVAILABLE:
+            return False
+
+        try:
+            if model_name in self.get_supported_models():
+                self.session = new_session(model_name)
+                self.model_name = model_name
+                logger.info(f"rembg model switched to: {model_name}")
+                return True
+            else:
+                logger.error(f"Unsupported model: {model_name}")
+                return False
+        except Exception as e:
+            logger.error(f"Failed to switch model: {e}")
+            return False

requirements.txt

@@ -0,0 +1,72 @@
+# 固定NumPy版本避免兼容性问题 - 必须最先安装
+numpy>=1.24.0,<2.0.0
+
+# 基础依赖
+fastapi>=0.104.0
+uvicorn[standard]>=0.24.0
+python-multipart>=0.0.6
+aiofiles>=23.2.1
+
+# 图像处理
+opencv-python>=4.8.0
+Pillow>=10.0.0
+
+# PyTorch 相关包 - 升级到2.x版本解决依赖冲突
+torch>=2.0.0,<2.9.0
+torchvision>=0.15.0
+
+# 机器学习和CV相关
+tf-keras
+aiohttp
+ultralytics
+deepface>=0.0.79
+mediapipe>=0.10.0
+# ModelScope相关包 - 让pip自动解决版本依赖
+modelscope==1.28.2
+datasets==2.21.0
+transformers==4.40.0
+# ModelScope DDColor的额外依赖
+timm==1.0.19
+sortedcontainers==2.4.0
+fsspec==2024.6.1
+multiprocess==0.70.16
+xxhash==3.5.0
+dill==0.3.8
+huggingface-hub==0.34.3
+# 修复pyarrow兼容性问题 - 使用稳定版本
+pyarrow==20.0.0
+
+# API相关
+pydantic>=2.4.0
+starlette>=0.27.0
+simplejson==3.20.1
+# 科学计算和工具
+scipy>=1.7.0,<1.13.0
+tqdm
+lmdb
+pyyaml
+
+# 定时任务
+apscheduler>=3.10.0
+
+# 数据库
+aiomysql>=0.2.0
+
+# 对象存储
+boto3>=1.34.0
+
+# GFPGAN 和相关包 - 修复依赖兼容性
+basicsr>=1.3.3
+facexlib>=0.2.5
+gfpgan>=1.3.0
+realesrgan>=0.3.0
+
+# CLIP 相关依赖
+cn_clip
+faiss-cpu
+onnxruntime
+diffusers
+accelerate
+# rembg 抠图处理
+rembg>=2.0.50
+easydict

rvm_processor.py

@@ -0,0 +1,132 @@
+import os
+import cv2
+import numpy as np
+import torch
+from torchvision import transforms
+
+import config
+from config import logger
+
+
+class RVMProcessor:
+    """RVM (Robust Video Matting) 抠图处理器"""
+
+    def __init__(self):
+        self.model = None
+        self.available = False
+        self.device = "cpu"  # 默认使用CPU，如果有GPU可以设置为"cuda"
+
+        try:
+            # 仅从本地加载，不使用网络
+            local_repo = getattr(config, 'RVM_LOCAL_REPO', '')
+            weights_path = getattr(config, 'RVM_WEIGHTS_PATH', '')
+
+            if not local_repo or not os.path.isdir(local_repo):
+                raise RuntimeError("RVM_LOCAL_REPO not set or invalid. Please set env RVM_LOCAL_REPO to local RobustVideoMatting repo path (with hubconf.py)")
+
+            if not weights_path or not os.path.isfile(weights_path):
+                raise RuntimeError("RVM_WEIGHTS_PATH not set or file not found. Please set env RVM_WEIGHTS_PATH to local RVM weights file path")
+
+            logger.info(f"Loading RVM model {config.RVM_MODEL} from local repo: {local_repo}")
+            # 使用本地仓库构建模型，禁用预训练以避免联网
+            self.model = torch.hub.load(local_repo, config.RVM_MODEL, source='local', pretrained=False)
+
+            # 加载本地权重
+            state = torch.load(weights_path, map_location=self.device)
+            if isinstance(state, dict) and 'state_dict' in state:
+                state = state['state_dict']
+            missing, unexpected = self.model.load_state_dict(state, strict=False)
+
+            # 迁移到设备并设置评估模式
+            self.model = self.model.to(self.device).eval()
+            self.available = True
+            logger.info("RVM background removal processor initialized successfully (local mode)")
+            if missing:
+                logger.warning(f"RVM weights missing keys: {list(missing)[:5]}... total={len(missing)}")
+            if unexpected:
+                logger.warning(f"RVM weights unexpected keys: {list(unexpected)[:5]}... total={len(unexpected)}")
+
+        except Exception as e:
+            logger.error(f"RVM background removal processor initialization failed: {e}")
+            self.available = False
+
+    def is_available(self) -> bool:
+        """检查RVM处理器是否可用"""
+        return self.available and self.model is not None
+
+    def remove_background(self, image: np.ndarray, background_color: tuple = None) -> np.ndarray:
+        """
+        使用RVM移除图片背景
+        :param image: 输入的OpenCV图像(BGR格式)
+        :param background_color: 替换的背景颜色(BGR格式)，如果为None则保持透明背景
+        :return: 处理后的图像
+        """
+        if not self.is_available():
+            raise Exception("RVM抠图处理器不可用")
+
+        try:
+            logger.info("Starting to remove background using RVM...")
+
+            # 保存原始图像尺寸
+            original_height, original_width = image.shape[:2]
+
+            # 将OpenCV图像(BGR)转换为RGB格式
+            image_rgb = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)
+
+            # 转换为tensor
+            src = transforms.ToTensor()(image_rgb).unsqueeze(0).to(self.device)
+
+            # 推理
+            rec = [None] * 4
+            with torch.no_grad():
+                fgr, pha, *rec = self.model(src, *rec, downsample_ratio=0.25)
+
+            # 转换为numpy数组
+            fgr = (fgr[0].permute(1, 2, 0).cpu().numpy() * 255).astype(np.uint8)  # (H,W,3)
+            pha = (pha[0, 0].cpu().numpy() * 255).astype(np.uint8)                # (H,W)
+
+            # 检查尺寸是否匹配，如果不匹配则调整
+            if fgr.shape[:2] != (original_height, original_width):
+                fgr = cv2.resize(fgr, (original_width, original_height))
+                pha = cv2.resize(pha, (original_width, original_height))
+
+            if background_color is not None:
+                # 如果指定了背景颜色，创建纯色背景
+                # 将前景图像转换为BGR格式
+                fgr_bgr = cv2.cvtColor(fgr, cv2.COLOR_RGB2BGR)
+
+                # 创建背景图像
+                background = np.full((original_height, original_width, 3), background_color, dtype=np.uint8)
+
+                # 使用alpha混合
+                alpha = pha.astype(np.float32) / 255.0
+                alpha = np.stack([alpha] * 3, axis=-1)
+
+                result = (fgr_bgr * alpha + background * (1 - alpha)).astype(np.uint8)
+            else:
+                # 保持透明背景，转换为BGRA格式
+                fgr_bgr = cv2.cvtColor(fgr, cv2.COLOR_RGB2BGR)
+                rgba = np.dstack((fgr_bgr, pha))  # (H,W,4)
+                result = rgba
+
+            logger.info("RVM background removal completed")
+            return result
+
+        except Exception as e:
+            logger.error(f"RVM background removal failed: {e}")
+            raise Exception(f"背景移除失败: {str(e)}")
+
+    def create_id_photo(self, image: np.ndarray, background_color: tuple = (255, 255, 255)) -> np.ndarray:
+        """
+        创建证件照（移除背景并添加纯色背景）
+        :param image: 输入的OpenCV图像
+        :param background_color: 背景颜色，默认白色(BGR格式)
+        :return: 处理后的证件照
+        """
+        logger.info(f"Starting to create ID photo, background color: {background_color}")
+
+        # 移除背景并添加指定颜色背景
+        id_photo = self.remove_background(image, background_color)
+
+        logger.info("ID photo creation completed")
+        return id_photo

test_tensorflow.py

@@ -0,0 +1,19 @@
+import deepface
+import sys
+import tensorflow as tf
+
+try:
+  import keras
+
+  keras_pkg = "keras (standalone)"
+  keras_ver = keras.__version__
+except Exception:
+  from tensorflow import keras
+
+  keras_pkg = "tf.keras"
+  keras_ver = keras.__version__
+
+print("py =", sys.version)
+print("deepface =", deepface.__version__)
+print("tensorflow =", tf.__version__)
+print("keras pkg =", keras_pkg, "keras =", keras_ver)

utils.py

@@ -0,0 +1,709 @@
+import base64
+import hashlib
+import os
+import re
+import shutil
+import threading
+
+import cv2
+import numpy as np
+from PIL import Image
+
+try:
+    import boto3
+    from botocore.exceptions import BotoCoreError, ClientError
+except ImportError:
+    boto3 = None
+    BotoCoreError = ClientError = Exception
+
+from config import (
+    IMAGES_DIR,
+    IMG_QUALITY,
+    logger,
+    SAVE_QUALITY,
+    BOS_ACCESS_KEY,
+    BOS_SECRET_KEY,
+    BOS_ENDPOINT,
+    BOS_BUCKET_NAME,
+    BOS_IMAGE_DIR,
+    BOS_UPLOAD_ENABLED,
+)
+
+_BOS_CLIENT = None
+_BOS_CLIENT_INITIALIZED = False
+_BOS_CLIENT_LOCK = threading.Lock()
+_IMAGES_DIR_ABS = os.path.abspath(os.path.expanduser(IMAGES_DIR))
+
+
+def _decode_bos_credential(raw_value: str) -> str:
+    """将Base64编码的凭证解码为明文，若解码失败则返回原值"""
+    if not raw_value:
+        return ""
+
+    value = raw_value.strip()
+    if not value:
+        return ""
+
+    try:
+        padding = len(value) % 4
+        if padding:
+            value += "=" * (4 - padding)
+        decoded = base64.b64decode(value).decode("utf-8").strip()
+        if decoded:
+            return decoded
+    except Exception:
+        pass
+    return value
+
+
+def _is_path_under_images_dir(file_path: str) -> bool:
+    try:
+        return os.path.commonpath(
+            [_IMAGES_DIR_ABS, os.path.abspath(file_path)]
+        ) == _IMAGES_DIR_ABS
+    except ValueError:
+        return False
+
+
+def _get_bos_client():
+    global _BOS_CLIENT, _BOS_CLIENT_INITIALIZED
+    if _BOS_CLIENT_INITIALIZED:
+        return _BOS_CLIENT
+
+    with _BOS_CLIENT_LOCK:
+        if _BOS_CLIENT_INITIALIZED:
+            return _BOS_CLIENT
+
+        if not BOS_UPLOAD_ENABLED:
+            _BOS_CLIENT_INITIALIZED = True
+            _BOS_CLIENT = None
+            return None
+        access_key = _decode_bos_credential(BOS_ACCESS_KEY)
+        secret_key = _decode_bos_credential(BOS_SECRET_KEY)
+        if not all([access_key, secret_key, BOS_ENDPOINT, BOS_BUCKET_NAME]):
+            logger.warning("BOS 上传未配置完整，跳过初始化")
+            _BOS_CLIENT_INITIALIZED = True
+            _BOS_CLIENT = None
+            return None
+
+        if boto3 is None:
+            logger.warning("未安装 boto3，BOS 上传功能不可用")
+            _BOS_CLIENT_INITIALIZED = True
+            _BOS_CLIENT = None
+            return None
+
+        try:
+            _BOS_CLIENT = boto3.client(
+                "s3",
+                aws_access_key_id=access_key,
+                aws_secret_access_key=secret_key,
+                endpoint_url=BOS_ENDPOINT,
+            )
+            logger.info("BOS 客户端初始化成功")
+        except Exception as e:
+            logger.warning(f"初始化 BOS 客户端失败，将跳过上传: {e}")
+            _BOS_CLIENT = None
+        finally:
+            _BOS_CLIENT_INITIALIZED = True
+
+    return _BOS_CLIENT
+
+
+def upload_file_to_bos(file_path: str, object_name: str | None = None) -> bool:
+    """
+    将指定文件上传到 BOS，失败不会抛出异常。
+    :param file_path: 本地文件路径
+    :param object_name: BOS 对象名称（可选）
+    :return: 是否成功上传
+    """
+    if not BOS_UPLOAD_ENABLED:
+        return False
+
+    expanded_path = os.path.abspath(os.path.expanduser(file_path))
+    if not os.path.isfile(expanded_path):
+        return False
+
+    if not _is_path_under_images_dir(expanded_path):
+        # 仅上传 IMAGES_DIR 内的文件，避免将临时文件同步至 BOS
+        return False
+
+    client = _get_bos_client()
+    if client is None:
+        return False
+
+    # 生成对象名称
+    if object_name:
+        object_key = object_name.strip("/ ")
+    else:
+        base_name = os.path.basename(expanded_path)
+        if BOS_IMAGE_DIR:
+            object_key = "/".join(
+                part.strip("/ ") for part in (BOS_IMAGE_DIR, base_name) if part
+            )
+        else:
+            object_key = base_name
+
+    try:
+        client.upload_file(expanded_path, BOS_BUCKET_NAME, object_key)
+        logger.info(f"文件已同步至 BOS: {object_key}")
+        return True
+    except (ClientError, BotoCoreError, Exception) as e:
+        logger.warning(f"上传到 BOS 失败（{object_key}）: {e}")
+        return False
+
+
+def delete_file_from_bos(file_path: str | None = None,
+    object_name: str | None = None) -> bool:
+    """
+    删除 BOS 中的指定对象，失败不会抛出异常。
+    :param file_path: 本地文件路径（可选，用于推导文件名）
+    :param object_name: BOS 对象名称（可选，优先使用）
+    :return: 是否成功删除
+    """
+    if not BOS_UPLOAD_ENABLED:
+        return False
+
+    client = _get_bos_client()
+    if client is None:
+        return False
+
+    key_candidate = object_name.strip("/ ") if object_name else ""
+
+    if not key_candidate and file_path:
+        base_name = os.path.basename(
+            os.path.abspath(os.path.expanduser(file_path)))
+        key_candidate = base_name.strip()
+
+    if not key_candidate:
+        return False
+
+    if BOS_IMAGE_DIR:
+        object_key = "/".join(
+            part.strip("/ ") for part in (BOS_IMAGE_DIR, key_candidate) if part
+        )
+    else:
+        object_key = key_candidate
+
+    try:
+        client.delete_object(Bucket=BOS_BUCKET_NAME, Key=object_key)
+        logger.info(f"已从 BOS 删除文件: {object_key}")
+        return True
+    except (ClientError, BotoCoreError, Exception) as e:
+        logger.warning(f"删除 BOS 文件失败（{object_key}）: {e}")
+        return False
+
+
+def image_to_base64(image: np.ndarray) -> str:
+    """将OpenCV图像转换为base64字符串"""
+    if image is None or image.size == 0:
+        return ""
+    _, buffer = cv2.imencode(".webp", image, [cv2.IMWRITE_WEBP_QUALITY, 90])
+    img_base64 = base64.b64encode(buffer).decode("utf-8")
+    return f"data:image/webp;base64,{img_base64}"
+
+
+def save_base64_to_unique_file(
+    base64_string: str, output_dir: str = "output_images"
+) -> str | None:
+    """
+    将带有MIME类型前缀的Base64字符串解码并保存到本地。
+    文件名格式为: {md5_hash}_{timestamp}.{extension}
+    """
+    os.makedirs(output_dir, exist_ok=True)
+
+    try:
+        match = re.match(r"data:(image/\w+);base64,(.+)", base64_string)
+        if match:
+            mime_type = match.group(1)
+            base64_data = match.group(2)
+        else:
+            mime_type = "image/jpeg"
+            base64_data = base64_string
+
+        extension_map = {
+            "image/jpeg": "jpg",
+            "image/png": "png",
+            "image/gif": "gif",
+            "image/webp": "webp",
+        }
+        file_extension = extension_map.get(mime_type, "webp")
+
+        decoded_data = base64.b64decode(base64_data)
+
+    except (ValueError, TypeError, base64.binascii.Error) as e:
+        logger.error(f"Base64 decoding failed: {e}")
+        return None
+
+    md5_hash = hashlib.md5(base64_data.encode("utf-8")).hexdigest()
+    filename = f"{md5_hash}.{file_extension}"
+    file_path = os.path.join(output_dir, filename)
+
+    try:
+        with open(file_path, "wb") as f:
+            f.write(decoded_data)
+        return file_path
+    except IOError as e:
+        logger.error(f"File writing failed: {e}")
+        return None
+
+
+def save_image_force_compress(
+    image: np.ndarray,
+    output_path: str,
+    max_size_kb: int = 100,
+    min_scale: float = 0.1,
+    scale_step: float = 0.9,
+    initial_quality: int = 95,
+    min_quality: int = 10,
+    quality_step: int = 5,
+) -> bool:
+    """
+    强制压缩图像到 max_size_kb 以下，即使原图已小于该大小。
+    先缩小尺寸再压缩质量，直到满足要求或失败。
+    """
+    max_bytes = max_size_kb * 1024
+    scale = IMG_QUALITY
+    height, width = image.shape[:2]
+    while scale >= min_scale:
+        resized_img = cv2.resize(
+            image,
+            (int(width * scale), int(height * scale)),
+            interpolation=cv2.INTER_AREA,
+        )
+        quality = initial_quality
+
+        while quality >= min_quality:
+            success, encoded_img = cv2.imencode(
+                ".webp", resized_img, [cv2.IMWRITE_WEBP_QUALITY, quality]
+            )
+            if not success:
+                return False
+
+            if len(encoded_img) <= max_bytes:
+                with open(output_path, "wb") as f:
+                    f.write(encoded_img)
+                logger.debug(
+                    f"压缩后图像大小: {len(encoded_img) / 1024:.2f} KB，scale={scale:.2f}, quality={quality}"
+                )
+                upload_file_to_bos(output_path)
+                return True
+
+            quality -= quality_step
+
+        scale *= scale_step
+
+    return False
+
+
+def human_readable_size(size_bytes):
+    """人性化文件大小展示"""
+    for unit in ["B", "KB", "MB", "GB"]:
+        if size_bytes < 1024:
+            return f"{size_bytes:.1f} {unit}"
+        size_bytes /= 1024
+    return f"{size_bytes:.1f} TB"
+
+
+def delete_file(file_path: str):
+    try:
+        os.remove(file_path)
+        logger.info(f"Deleted file: {file_path}")
+    except Exception as error:
+        logger.error(f"Failed to delete file {file_path}: {error}")
+
+
+def move_file_to_archive(file_path: str):
+    try:
+        if not os.path.exists(IMAGES_DIR):
+            os.makedirs(IMAGES_DIR)
+        filename = os.path.basename(file_path)
+        destination = os.path.join(IMAGES_DIR, filename)
+        shutil.move(file_path, destination)
+        logger.debug(f"Moved file to archive: {destination}")
+    except Exception as error:
+        logger.error(f"Failed to move file {file_path} to archive: {error}")
+
+
+def save_image_high_quality(image: np.ndarray, output_path: str, quality: int = SAVE_QUALITY) -> bool:
+    """
+    保存图像，保持高质量，不进行压缩
+    :param image: 图像数组
+    :param output_path: 输出路径
+    :param quality: WebP质量 (0-100)，默认95
+    :return: 保存���否成功
+    """
+    try:
+        success, encoded_img = cv2.imencode(
+            ".webp", image, [cv2.IMWRITE_WEBP_QUALITY, quality]
+        )
+        if not success:
+            logger.error(f"Image encoding failed: {output_path}")
+            return False
+
+        with open(output_path, "wb") as f:
+            f.write(encoded_img)
+
+        logger.info(f"High quality image saved successfully: {output_path}, quality: {quality}, size: {len(encoded_img) / 1024:.2f} KB")
+        upload_file_to_bos(output_path)
+        return True
+    except Exception as e:
+        logger.error(f"Failed to save image: {output_path}, error: {e}")
+        return False
+
+
+def convert_numpy_types(obj):
+    """转换所有 numpy 类型为原生 Python 类型"""
+    if isinstance(obj, (np.float32, np.float64)):
+        return float(obj)
+    elif isinstance(obj, (np.int32, np.int64)):
+        return int(obj)
+    elif isinstance(obj, dict):
+        return {k: convert_numpy_types(v) for k, v in obj.items()}
+    elif isinstance(obj, list):
+        return [convert_numpy_types(i) for i in obj]
+    else:
+        return obj
+
+
+def compress_image_by_quality(image: np.ndarray, quality: int, output_format: str = 'webp') -> tuple[bytes, dict]:
+    """
+    按质量压缩图像
+    :param image: 输入图像
+    :param quality: 压缩质量 (10-100)
+    :param output_format: 输出格式 ('jpg', 'png', 'webp')
+    :return: (压缩后的图像字节数据, 压缩信息)
+    """
+    try:
+        height, width = image.shape[:2]
+
+        if output_format.lower() == 'png':
+            # PNG使用压缩级别 (0-9)，质量参数转换为压缩级别
+            compression_level = max(0, min(9, int((100 - quality) / 10)))
+            success, encoded_img = cv2.imencode(
+                ".png", image, [cv2.IMWRITE_PNG_COMPRESSION, compression_level]
+            )
+        elif output_format.lower() == 'webp':
+            # WebP支持质量参数
+            success, encoded_img = cv2.imencode(
+                ".webp", image, [cv2.IMWRITE_WEBP_QUALITY, quality]
+            )
+        else:
+            # JPG格式
+            success, encoded_img = cv2.imencode(
+                ".jpg", image, [cv2.IMWRITE_JPEG_QUALITY, quality]
+            )
+
+        if not success:
+            raise Exception("图像编码失败")
+
+        compressed_bytes = encoded_img.tobytes()
+
+        info = {
+            'original_dimensions': f"{width} × {height}",
+            'compressed_dimensions': f"{width} × {height}",
+            'quality': quality,
+            'format': output_format.upper(),
+            'size': len(compressed_bytes)
+        }
+
+        return compressed_bytes, info
+
+    except Exception as e:
+        logger.error(f"Failed to compress image by quality: {e}")
+        raise
+
+
+def compress_image_by_dimensions(image: np.ndarray, target_width: int, target_height: int,
+                                quality: int = 100, output_format: str = 'jpg') -> tuple[bytes, dict]:
+    """
+    按尺寸压缩图像
+    :param image: 输入图像
+    :param target_width: 目标宽度
+    :param target_height: 目标高度
+    :param quality: 压缩质量
+    :param output_format: 输出格式
+    :return: (压缩后的图像字节数据, 压缩信息)
+    """
+    try:
+        original_height, original_width = image.shape[:2]
+
+        # 调整图像尺寸
+        resized_image = cv2.resize(
+            image, (target_width, target_height),
+            interpolation=cv2.INTER_AREA
+        )
+
+        # 按质量编码
+        if output_format.lower() == 'png':
+            compression_level = max(0, min(9, int((100 - quality) / 10)))
+            success, encoded_img = cv2.imencode(
+                ".png", resized_image, [cv2.IMWRITE_PNG_COMPRESSION, compression_level]
+            )
+        elif output_format.lower() == 'webp':
+            success, encoded_img = cv2.imencode(
+                ".webp", resized_image, [cv2.IMWRITE_WEBP_QUALITY, quality]
+            )
+        else:
+            success, encoded_img = cv2.imencode(
+                ".jpg", resized_image, [cv2.IMWRITE_JPEG_QUALITY, quality]
+            )
+
+        if not success:
+            raise Exception("图像编码失败")
+
+        compressed_bytes = encoded_img.tobytes()
+
+        info = {
+            'original_dimensions': f"{original_width} × {original_height}",
+            'compressed_dimensions': f"{target_width} × {target_height}",
+            'quality': quality,
+            'format': output_format.upper(),
+            'size': len(compressed_bytes)
+        }
+
+        return compressed_bytes, info
+
+    except Exception as e:
+        logger.error(f"Failed to compress image by dimensions: {e}")
+        raise
+
+
+def compress_image_by_file_size(image: np.ndarray, target_size_kb: float,
+                               output_format: str = 'jpg') -> tuple[bytes, dict]:
+    """
+    按文件大小压缩图像 - 使用多阶段二分法精确控制大小
+    :param image: 输入图像
+    :param target_size_kb: 目标文件大小（KB）
+    :param output_format: 输出格式
+    :return: (压缩后的图像字节数据, 压缩信息)
+    """
+    try:
+        original_height, original_width = image.shape[:2]
+        target_size_bytes = int(target_size_kb * 1024)
+
+        def encode_image(img, quality):
+            """编码图像并返回字节数据"""
+            if output_format.lower() == 'png':
+                compression_level = max(0, min(9, int((100 - quality) / 10)))
+                success, encoded_img = cv2.imencode(
+                    ".png", img, [cv2.IMWRITE_PNG_COMPRESSION, compression_level]
+                )
+            elif output_format.lower() == 'webp':
+                success, encoded_img = cv2.imencode(
+                    ".webp", img, [cv2.IMWRITE_WEBP_QUALITY, quality]
+                )
+            else:
+                success, encoded_img = cv2.imencode(
+                    ".jpg", img, [cv2.IMWRITE_JPEG_QUALITY, quality]
+                )
+
+            if success:
+                return encoded_img.tobytes()
+            return None
+
+        def find_best_scale_and_quality(target_bytes):
+            """寻找最佳的尺寸和质量组合"""
+            best_result = None
+            best_diff = float('inf')
+
+            # 尝试多个尺寸比例
+            test_scales = [1.0, 0.95, 0.9, 0.85, 0.8, 0.75, 0.7, 0.65, 0.6, 0.55, 0.5, 0.45, 0.4, 0.35, 0.3]
+
+            for scale in test_scales:
+                # 调整图像尺寸
+                if scale < 1.0:
+                    new_width = int(original_width * scale)
+                    new_height = int(original_height * scale)
+                    if new_width < 50 or new_height < 50:  # 避免尺寸太小
+                        continue
+                    working_image = cv2.resize(image, (new_width, new_height), interpolation=cv2.INTER_AREA)
+                else:
+                    working_image = image
+                    new_width, new_height = original_width, original_height
+
+                # 在这个尺寸下使用二分法寻找最佳质量
+                min_q, max_q = 10, 100
+                scale_best_result = None
+                scale_best_diff = float('inf')
+
+                for _ in range(20):  # 每个尺寸最多尝试20次质量调整
+                    current_quality = (min_q + max_q) // 2
+
+                    compressed_bytes = encode_image(working_image, current_quality)
+                    if not compressed_bytes:
+                        break
+
+                    current_size = len(compressed_bytes)
+                    size_diff = abs(current_size - target_bytes)
+                    size_ratio = current_size / target_bytes
+
+                    # 如果找到精确匹配，立即返回
+                    if 0.99 <= size_ratio <= 1.01:  # 1%误差以内
+                        return {
+                            'bytes': compressed_bytes,
+                            'scale': scale,
+                            'width': new_width,
+                            'height': new_height,
+                            'quality': current_quality,
+                            'size': current_size,
+                            'ratio': size_ratio
+                        }
+
+                    # 记录该尺寸下的最佳结果
+                    if size_diff < scale_best_diff:
+                        scale_best_diff = size_diff
+                        scale_best_result = {
+                            'bytes': compressed_bytes,
+                            'scale': scale,
+                            'width': new_width,
+                            'height': new_height,
+                            'quality': current_quality,
+                            'size': current_size,
+                            'ratio': size_ratio
+                        }
+
+                    # 二分法调整质量
+                    if current_size > target_bytes:
+                        max_q = current_quality - 1
+                    else:
+                        min_q = current_quality + 1
+
+                    if min_q >= max_q:
+                        break
+
+                # 更新全局最佳结果
+                if scale_best_result and scale_best_diff < best_diff:
+                    best_diff = scale_best_diff
+                    best_result = scale_best_result
+
+                # 如果已经找到很好的结果（5%以内），可以提前结束
+                if best_result and 0.95 <= best_result['ratio'] <= 1.05:
+                    break
+
+            return best_result
+
+        logger.info(f"Starting multi-stage compression, target size: {target_size_bytes} bytes ({target_size_kb}KB)")
+
+        # 寻找最佳组合
+        result = find_best_scale_and_quality(target_size_bytes)
+
+        if result:
+            error_percent = abs(result['ratio'] - 1) * 100
+            logger.info(f"Compression completed: scale ratio {result['scale']:.2f}, quality {result['quality']}%, "
+                       f"size {result['size']} bytes, error {error_percent:.2f}%")
+
+            # 不管误差多大都返回最接近的结果，只记录警告
+            if error_percent > 10:
+                if result['ratio'] < 0.5:  # 压缩过度
+                    suggested_size = result['size'] / 1024
+                    logger.warning(f"Target size {target_size_kb}KB is too small, actually compressed to {suggested_size:.1f}KB, error {error_percent:.1f}%")
+                elif result['ratio'] > 2.0:  # 无法达到目标
+                    suggested_size = result['size'] / 1024
+                    logger.warning(f"Target size {target_size_kb}KB is too large, minimum can be compressed to {suggested_size:.1f}KB, error {error_percent:.1f}%")
+                else:
+                    logger.warning(f"Cannot achieve target accuracy, error {error_percent:.1f}%, returning closest result")
+
+            info = {
+                'original_dimensions': f"{original_width} × {original_height}",
+                'compressed_dimensions': f"{result['width']} × {result['height']}",
+                'quality': result['quality'],
+                'format': output_format.upper(),
+                'size': result['size']
+            }
+
+            return result['bytes'], info
+        else:
+            raise Exception(f"无法将图片压缩到目标大小 {target_size_kb}KB")
+
+    except Exception as e:
+        logger.error(f"Failed to compress image by file size: {e}")
+        raise
+
+
+def convert_image_format(image: np.ndarray, target_format: str, quality: int = 100) -> tuple[bytes, dict]:
+    """
+    转换图像格式
+    :param image: 输入图像
+    :param target_format: 目标格式 ('jpg', 'png', 'webp')
+    :param quality: 质量参数
+    :return: (转换后的图像字节数据, 格式信息)
+    """
+    try:
+        height, width = image.shape[:2]
+
+        if target_format.lower() == 'png':
+            # PNG格式，使用压缩级别
+            compression_level = 6  # 默认压缩级别
+            success, encoded_img = cv2.imencode(
+                ".png", image, [cv2.IMWRITE_PNG_COMPRESSION, compression_level]
+            )
+        elif target_format.lower() == 'webp':
+            # WebP格式
+            success, encoded_img = cv2.imencode(
+                ".webp", image, [cv2.IMWRITE_WEBP_QUALITY, quality]
+            )
+        else:
+            # JPG格式
+            success, encoded_img = cv2.imencode(
+                ".jpg", image, [cv2.IMWRITE_JPEG_QUALITY, quality]
+            )
+
+        if not success:
+            raise Exception("图像格式转换失败")
+
+        converted_bytes = encoded_img.tobytes()
+
+        info = {
+            'original_dimensions': f"{width} × {height}",
+            'compressed_dimensions': f"{width} × {height}",
+            'quality': quality if target_format.lower() != 'png' else 100,
+            'format': target_format.upper(),
+            'size': len(converted_bytes)
+        }
+
+        return converted_bytes, info
+
+    except Exception as e:
+        logger.error(f"Image format conversion failed: {e}")
+        raise
+
+
+def save_image_with_transparency(image: np.ndarray, file_path: str) -> bool:
+    """
+    保存带透明通道的图像为PNG格式
+    :param image: OpenCV图像数组(BGRA格式，包含alpha通道)
+    :param file_path: 保存路径
+    :return: 保存是否成功
+    """
+    if image is None:
+        logger.error("Image is empty, cannot save")
+        return False
+
+    try:
+        # 确保目录存在
+        os.makedirs(os.path.dirname(file_path), exist_ok=True)
+
+        # 如果图像有4个通道(BGRA)，转换为RGBA然后保存
+        if len(image.shape) == 3 and image.shape[2] == 4:
+            # BGRA转换为RGBA
+            rgba_image = cv2.cvtColor(image, cv2.COLOR_BGRA2RGBA)
+        elif len(image.shape) == 3 and image.shape[2] == 3:
+            # 如果是BGR格式，先转换为RGB，但这种情况不应该有透明度
+            rgb_image = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)
+            rgba_image = np.dstack((rgb_image, np.full(rgb_image.shape[:2], 255, dtype=np.uint8)))
+        else:
+            logger.error("Image format does not support transparency saving")
+            return False
+
+        # 使用PIL保存PNG
+        pil_image = Image.fromarray(rgba_image, 'RGBA')
+        pil_image.save(file_path, 'PNG', optimize=True)
+
+        file_size = os.path.getsize(file_path)
+        logger.info(f"Transparent PNG image saved: {file_path}, size: {file_size/1024:.1f}KB")
+        upload_file_to_bos(file_path)
+        return True
+
+    except Exception as e:
+        logger.error(f"Failed to save transparent PNG image: {e}")
+        return False

vector_store.py

@@ -0,0 +1,119 @@
+# vector_store.py
+import logging
+import os
+import pickle
+
+import faiss
+import numpy as np
+import torch
+
+# 配置日志
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# 获取项目根目录
+PROJECT_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+# 拼接 FAISS 索引目录
+FAISS_INDEX_DIR = os.environ.get('FAISS_INDEX_DIR', os.path.join(PROJECT_ROOT, 'faiss', 'data'))
+os.makedirs(FAISS_INDEX_DIR, exist_ok=True)
+
+# 最终路径
+FAISS_INDEX_PATH = os.path.join(FAISS_INDEX_DIR, "index.faiss")
+ID_MAP_PATH = os.path.join(FAISS_INDEX_DIR, "id_map.pkl")
+
+# ViT-B/16 为 512，ViT-L/14 通常为 768 或 1024
+VECTOR_DIM = int(os.environ.get("VECTOR_DIM", 512))
+
+# 全局变量
+index = None
+id_map = None
+
+def init_vector_store():
+    """初始化向量存储"""
+    global index, id_map
+    try:
+        # 初始化或加载
+        if os.path.exists(FAISS_INDEX_PATH) and os.path.exists(ID_MAP_PATH):
+            index = faiss.read_index(FAISS_INDEX_PATH)
+            with open(ID_MAP_PATH, "rb") as f:
+                id_map = pickle.load(f)
+            logger.info(f"Vector store loaded successfully path={FAISS_INDEX_DIR}, contains {len(id_map)} vectors")
+        else:
+            index = faiss.IndexFlatIP(VECTOR_DIM)  # 归一化后可以用内积代替余弦相似度
+            id_map = []
+            logger.info("Initializing new vector store")
+        return True
+    except Exception as e:
+        logger.error(f"Vector store initialization failed: {e}")
+        return False
+
+def is_vector_store_available():
+    """检查向量存储是否可用"""
+    return index is not None and id_map is not None
+
+def check_image_exists(image_path: str) -> bool:
+    """
+    检查图像是否已经在向量库中存在
+    Args:
+        image_path: 图像路径/标识
+    Returns:
+        bool: 如果存在返回True，否则返回False
+    """
+    try:
+        if not is_vector_store_available():
+            return False
+        return image_path in id_map
+    except Exception as e:
+        logger.error(f"Failed to check if image exists: {str(e)}")
+        return False
+
+def add_image_vector(image_path: str, vector: torch.Tensor):
+    """添加图片向量到存储"""
+    if not is_vector_store_available():
+        raise RuntimeError("向量存储未初始化")
+
+    np_vector = vector.squeeze(0).numpy().astype('float32')
+    index.add(np_vector[np.newaxis, :])
+    id_map.append(image_path)
+    save_index()
+    logger.info(f"Image vector added: {image_path}")
+
+def search_text_vector(vector: torch.Tensor, top_k=5):
+    """搜索文本向量"""
+    if not is_vector_store_available():
+        raise RuntimeError("向量存储未初始化")
+
+    np_vector = vector.squeeze(0).numpy().astype('float32')
+    scores, indices = index.search(np_vector[np.newaxis, :], top_k)
+
+    if indices is None or len(indices[0]) == 0:
+        return []
+
+    results = [
+        (id_map[i], float(scores[0][j]))
+        for j, i in enumerate(indices[0])
+        if i < len(id_map) and i != -1
+    ]
+    return results
+
+def save_index():
+    """保存索引文件"""
+    try:
+        faiss.write_index(index, FAISS_INDEX_PATH)
+        with open(ID_MAP_PATH, "wb") as f:
+            pickle.dump(id_map, f)
+        logger.debug("Vector index saved")
+    except Exception as e:
+        logger.error(f"Failed to save vector index: {e}")
+
+def get_vector_store_info():
+    """获取向量存储信息"""
+    if not is_vector_store_available():
+        return {"status": "not_initialized", "count": 0}
+
+    return {
+        "status": "available",
+        "count": len(id_map),
+        "vector_dim": VECTOR_DIM,
+        "index_path": FAISS_INDEX_PATH
+    }

wx_access_token.py

@@ -0,0 +1,122 @@
+from typing import Optional
+
+import aiohttp
+
+from config import access_token_cache, WECHAT_APPID, WECHAT_SECRET, logger
+
+
+async def get_access_token() -> Optional[str]:
+    """获取微信 stable access_token (推荐方式)"""
+    import time
+
+    # 检查缓存是否有效
+    if access_token_cache["token"] and time.time() < access_token_cache["expires_at"]:
+        return access_token_cache["token"]
+    # 使用新的 getStableAccessToken 接口
+    url = "https://api.weixin.qq.com/cgi-bin/stable_token"
+    data = {
+        "grant_type": "client_credential",
+        "appid": WECHAT_APPID,
+        "secret": WECHAT_SECRET,
+        "force_refresh": False,  # 是否强制刷新
+    }
+
+    try:
+        async with aiohttp.ClientSession() as session:
+            async with session.post(url, json=data) as response:
+                if response.status == 200:
+                    result = await response.json()
+                    logger.debug(f"getStableAccessToken response: {result}")
+                    if "access_token" in result:
+                        access_token_cache["token"] = result["access_token"]
+                        access_token_cache["expires_at"] = (
+                            time.time() + result.get("expires_in", 7200) - 300
+                        )
+                        expires_time = access_token_cache["expires_at"]
+                        logger.debug(
+                            f"成功获取 stable access_token expires_time={expires_time}"
+                        )
+                        return result["access_token"]
+                    else:
+                        logger.error(f"Failed to get stable access_token: {result}")
+                else:
+                    logger.error(f"Failed to request stable access_token: {response.status}")
+    except Exception as e:
+        logger.error(f"Exception while getting stable access_token: {str(e)}")
+
+    return None
+
+
+async def get_access_token_old() -> Optional[str]:
+    """获取微信 access_token"""
+    import time
+
+    # 检查缓存是否有效
+    if access_token_cache["token"] and time.time() < access_token_cache["expires_at"]:
+        return access_token_cache["token"]
+    # 获取新的 access_token
+    url = "https://api.weixin.qq.com/cgi-bin/token"
+    params = {
+        "grant_type": "client_credential",
+        "appid": WECHAT_APPID,
+        "secret": WECHAT_SECRET,
+    }
+
+    try:
+        async with aiohttp.ClientSession() as session:
+            async with session.get(url, params=params) as response:
+                if response.status == 200:
+                    data = await response.json()
+                    if "access_token" in data:
+                        access_token_cache["token"] = data["access_token"]
+                        access_token_cache["expires_at"] = (
+                            time.time() + data.get("expires_in", 7200) - 300
+                        )  # 提前5分钟过期
+                        logger.info("Successfully obtained WeChat access_token...")
+                        return data["access_token"]
+                    else:
+                        logger.error(f"Failed to get access_token, returned content: {data}")
+                        return None
+                else:
+                    logger.error(f"Failed to get access_token, status={response.status}")
+                    return None
+    except Exception as e:
+        logger.error(f"Failed to get access_token: {str(e)}")
+
+    return None
+
+
+async def check_image_security(image_data: bytes) -> bool:
+    """
+    检测图片内容安全
+    :param image_data: 图片二进制数据
+    :return: True表示安全，False表示有风险
+    """
+    access_token = await get_access_token()
+    if not access_token:
+        logger.warning("Unable to get access_token, skipping security check")
+        return True  # 获取token失败时允许继续，避免影响正常用户
+    url = f"https://api.weixin.qq.com/wxa/img_sec_check?access_token={access_token}"
+    try:
+        async with aiohttp.ClientSession() as session:
+            # 微信API要求使用 multipart/form-data 格式
+            data = aiohttp.FormData()
+            data.add_field("media", image_data, content_type="image/jpeg")
+            async with session.post(url, data=data, timeout=10) as response:
+                if response.status == 200:
+                    result = await response.json()
+                    logger.info(f"Checking image content safety...result={result}")
+                    if result.get("errcode") == 0:
+                        return True  # 安全
+                    elif result.get("errcode") == 87014:
+                        logger.warning("Image content contains illegal content...")
+                        return False
+                    else:
+                        logger.warning(f"Image security check returned error: {result}")
+                        return True  # 其他错误时允许继续
+                else:
+                    logger.warning(f"Image security check request failed: {response.status}")
+                    return True
+    except Exception as e:
+        logger.error(f"Image security check exception: {str(e)}")
+        return True  # 异常时允许继续，避免影响正常用户