CLIP-GmP-ViT-L-14 日志分级输出与错误码标准化设计

4.2 五级日志系统

Python logging 模块默认提供 5 个日志级别：

• DEBUG：最详细的调试信息。
• INFO：确认事情按预期运行。
• WARNING：意外情况，但程序可继续运行。
• ERROR：严重错误，部分功能不可用。
• CRITICAL：非常严重的错误，程序可能无法运行。

4.3 实战：在 CLIP 项目中应用

将日志系统集成到主程序 app.py 中：

import gradio as gr
import torch
from PIL import Image
import time
import traceback
from logger_config import logger

class CLIPGMPProcessor:
    def __init__(self):
        self.model = None
        self.processor = None
        self.device = "cuda" if torch.cuda.is_available() else "cpu"
        logger.info(f"初始化处理器，使用设备：{self.device}")

    def load_models(self):
        try:
            logger.info("开始加载 CLIP-GmP-ViT-L-14 模型和相关组件")
            from transformers import CLIPProcessor, CLIPModel
            start_time = time.time()
            logger.debug("加载 CLIP 模型...")
            self.model = CLIPModel.from_pretrained("path/to/clip-gmp-vit-l-14")
            self.model.to(self.device)
            self.model.eval()
            logger.debug("加载 CLIP 处理器...")
            self.processor = CLIPProcessor.from_pretrained("path/to/clip-gmp-vit-l-14")
            load_time = time.time() - start_time
            logger.info(f"模型加载完成，总耗时：{load_time:.2f}秒")
            return True
        except Exception as e:
            logger.error(f"模型加载失败：{str(e)}")
            logger.debug(f"错误详情：{traceback.format_exc()}")
            return False

    def calculate_similarity(self, image, text):
        try:
            logger.info(f"计算相似度 - 文本：{text[:30]}...")
            if self.model is None or self.processor is None:
                logger.error("模型未加载，无法计算相似度")
                return 0.0
            inputs = self.processor(text=[text], images=image, return_tensors="pt", padding=True)
            inputs = {k: v.to(self.device) for k, v in inputs.items()}
            with torch.no_grad():
                outputs = self.model(**inputs)
            similarity = outputs.logits_per_image.item()
            logger.info(f"相似度计算完成：{similarity:.4f}")
            return similarity
        except Exception as e:
            logger.error(f"相似度计算失败：{str(e)}")
            logger.debug(f"错误堆栈：{traceback.format_exc()}")
            return 0.0

processor = CLIPGMPProcessor()

def single_image_text_similarity(image, text):
    logger.info("=== 开始单图单文相似度计算 ===")
    if image is None:
        logger.warning("用户未上传图片")
        return "请上传图片"
    if not text or text.strip() == "":
        logger.warning("用户未输入文本")
        return "请输入文本描述"
    try:
        if isinstance(image, str):
            pil_image = Image.open(image)
        else:
            pil_image = Image.fromarray(image)
        similarity = processor.calculate_similarity(pil_image, text)
        logger.info(f"单图单文计算完成，结果：{similarity:.4f}")
        return f"相似度：{similarity:.4f}"
    except Exception as e:
        logger.error(f"单图单文计算异常：{str(e)}")
        return f"计算失败：{str(e)}"

def batch_retrieval(image, texts):
    logger.info("=== 开始批量检索 ===")
    if image is None:
        logger.warning("批量检索：用户未上传图片")
        return "请上传图片"
    if not texts:
        logger.warning("批量检索：用户未输入文本")
        return "请输入文本列表"
    try:
        if isinstance(image, str):
            pil_image = Image.open(image)
        else:
            pil_image = Image.fromarray(image)
        results = []
        text_list = [t.strip() for t in texts.split('\n') if t.strip()]
        logger.info(f"批量检索：图片已接收，文本数量：{len(text_list)}")
        for i, text in enumerate(text_list):
            logger.debug(f"处理第 {i+1} 个文本：{text[:30]}...")
            similarity = processor.calculate_similarity(pil_image, text)
            results.append((text, similarity))
        results.sort(key=lambda x: x[1], reverse=True)
        output_lines = []
        for i, (text, sim) in enumerate(results):
            output_lines.append(f"{i+1}. {text[:50]}... - 相似度：{sim:.4f}")
        output = "\n".join(output_lines)
        logger.info(f"批量检索完成，共处理 {len(results)} 个文本")
        return output
    except Exception as e:
        logger.error(f"批量检索异常：{str(e)}")
        return f"批量检索失败：{str(e)}"

def main():
    logger.info("启动 CLIP-GmP-ViT-L-14 Gradio 服务")
    if not processor.load_models():
        logger.critical("模型加载失败，服务无法启动")
        return
    with gr.Blocks(title="CLIP-GmP-ViT-L-14 图文相似度计算") as demo:
        gr.Markdown("# CLIP-GmP-ViT-L-14 图文相似度计算")
        gr.Markdown("上传图片并输入文本，计算它们之间的相似度")
        with gr.Tab("单图单文相似度"):
            with gr.Row():
                with gr.Column():
                    image_input = gr.Image(label="上传图片", type="filepath")
                    text_input = gr.Textbox(label="输入文本", placeholder="描述图片的内容...")
                    single_btn = gr.Button("计算相似度")
                with gr.Column():
                    single_output = gr.Textbox(label="计算结果", interactive=False)
                    single_btn.click(single_image_text_similarity, inputs=[image_input, text_input], outputs=single_output)
        with gr.Tab("批量检索"):
            with gr.Row():
                with gr.Column():
                    batch_image_input = gr.Image(label="上传图片", type="filepath")
                    batch_text_input = gr.Textbox(label="输入文本列表（每行一个）", placeholder="描述 1\n描述 2\n描述 3...", lines=10)
                    batch_btn = gr.Button("批量计算")
                with gr.Column():
                    batch_output = gr.Textbox(label="检索结果", interactive=False, lines=15)
                    batch_btn.click(batch_retrieval, inputs=[batch_image_input, batch_text_input], outputs=batch_output)
        logger.info("Gradio 界面创建完成，启动服务...")
        demo.launch(server_name="0.0.0.0", server_port=7860)

if __name__ == "__main__":
    main()

4.4 日志查看与分析

实时查看控制台输出：

2024-01-15 10:30:25 - clip_gmp_logger - INFO - app.py:45 - 启动 CLIP-GmP-ViT-L-14 Gradio 服务

查看日志文件：

tail -f /root/CLIP-GmP-ViT-L-14/logs/app.log
grep "ERROR" /root/CLIP-GmP-ViT-L-14/logs/app.log

日志轮转配置：

from logging.handlers import RotatingFileHandler
file_handler = RotatingFileHandler(
    log_file, maxBytes=10*1024*1024,
    backupCount=5, encoding='utf-8'
)

5. 错误码标准化设计

5.1 错误码设计原则

1. 唯一性：每个错误码对应具体场景。
2. 可读性：从代码看出错误类型。
3. 分类清晰：按模块分层组织。
4. 易于扩展：方便添加新错误码。

5.2 错误码分类方案

格式：ERR_[模块]_[错误类型]_[具体错误]

• 模块前缀：SYS_ (系统), MODEL_ (模型), DATA_ (数据), API_ (接口), AUTH_ (认证)
• 错误类型：LOAD_, INIT_, PARAM_, FORMAT_, NOT_FOUND_, TIMEOUT_

5.3 实现错误码系统

创建 error_codes.py：

from enum import Enum
from typing import Dict, Any, Optional

class ErrorCode(Enum):
    SYS_INIT_FAILED = ("SYS_001", "系统初始化失败")
    MODEL_LOAD_FAILED = ("MODEL_001", "模型加载失败")
    DATA_FILE_NOT_FOUND = ("DATA_001", "文件不存在")
    API_PARAM_MISSING = ("API_001", "缺少必要参数")

class ServiceError(Exception):
    def __init__(self, error_code: ErrorCode, message: Optional[str] = None, details: Optional[Dict[str, Any]] = None, cause: Optional[Exception] = None):
        self.error_code = error_code
        self.code, self.default_message = error_code.value
        self.message = message if message is not None else self.default_message
        self.details = details or {}
        self.cause = cause
        full_message = f"[{self.code}] {self.message}"
        if self.details:
            details_str = ", ".join(f"{k}={v}" for k, v in self.details.items())
            full_message += f" ({details_str})"
        super().__init__(full_message)

    def to_dict(self) -> Dict[str, Any]:
        return {
            "code": self.code,
            "message": self.message,
            "details": self.details,
            "type": self.error_code.name
        }

5.4 在 CLIP 项目中使用错误码

在 app.py 中集成错误处理：

from error_codes import ServiceError, ModelLoadError, ParameterError, ErrorCode

def validate_input(self, image, text: str = None, is_batch: bool = False):
    errors = []
    if image is None:
        errors.append(ParameterError("image", "不能为空"))
    elif isinstance(image, str) and not os.path.exists(image):
        errors.append(DataFormatError("image", "有效的文件路径", image))
    return errors

def single_image_text_similarity(image, text):
    try:
        if image is None:
            raise ParameterError("image", "不能为空")
        if not text or text.strip() == "":
            raise ParameterError("text", "不能为空")
        similarity = processor.calculate_similarity(image, text)
        return {"success": True, "similarity": similarity, "message": f"相似度：{similarity:.4f}"}
    except ServiceError as e:
        logger.error(f"服务异常：{e.code} - {e.message}")
        return {"success": False, "error_code": e.code, "message": e.message, "details": e.details}
    except Exception as e:
        logger.error(f"未处理的异常：{str(e)}")
        return {"success": False, "error_code": "UNKNOWN_ERROR", "message": "系统内部错误"}

6. 完整项目集成

6.1 项目结构优化

/root/CLIP-GmP-ViT-L-14/
├── app.py
├── logger_config.py
├── error_codes.py
├── config.py
├── requirements.txt
├── start.sh
├── stop.sh
├── tests/
└── logs/

6.2 配置文件

创建 config.py 统一管理配置：

import os
from pathlib import Path

BASE_DIR = Path(__file__).parent.absolute()

MODEL_CONFIG = {
    "name": "CLIP-GmP-ViT-L-14",
    "path": os.path.join(BASE_DIR, "models/clip-gmp-vit-l-14"),
    "default_device": "cuda",
    "fallback_device": "cpu"
}

LOG_CONFIG = {
    "level": "INFO",
    "file": os.path.join(BASE_DIR, "logs/app.log"),
    "max_bytes": 10 * 1024 * 1024,
    "backup_count": 5
}

6.3 启动脚本优化

更新 start.sh：

#!/bin/bash
set -e
cd "$(dirname "$0")"
log_info() { echo -e "[INFO] $(date '+%Y-%m-%d %H:%M:%S') - $1"; }
check_python() { command -v python3 &> /dev/null || exit 1; }
check_dependencies() { pip install -r requirements.txt; }
start_service() { nohup python3 app.py > logs/startup.log 2>&1 &; }
main() {
    check_python
    check_dependencies
    start_service
}
main

7. 总结

该方案为 AI 项目提供了标准化的日志与错误处理框架。通过 Python logging 构建五级日志系统，支持控制台与文件双通道输出及轮转机制。建立 ERR_ 前缀错误码规范，涵盖系统、模型、数据等模块，通过 ServiceError 基类统一异常处理。配合 Gradio 服务集成及 Shell 监控脚本，实现从部署到运维的全链路标准化，提升系统健壮性与团队协作效率。