flowchart TB
    subgraph "上游调用方"
        AIOrch[AI Orchestrator]
        AgentEng[Agent Engine]
        RAGEng[RAG Engine]
        WebApp[Web应用]
    end

    subgraph "Multimodal Engine Service (Port 8005)"
        subgraph "HTTP 路由层"
            FastAPI[FastAPI App<br/>异步框架]
            OCRRouter[OCR Router<br/>/api/v1/ocr/*]
            VisionRouter[Vision Router<br/>/api/v1/vision/*]
            AnalysisRouter[Analysis Router<br/>/api/v1/analysis/*]
            HealthRouter[Health Router<br/>/health]
        end

        subgraph "中间件层"
            ErrorHandler[错误处理中间件]
            RequestContext[请求上下文中间件]
            CORS[CORS 中间件]
        end

        subgraph "服务层 (Service Layer)"
            OCRService[OCRService<br/>OCR识别服务]
            VisionService[VisionService<br/>图像理解服务]
            AnalysisService[AnalysisService<br/>综合分析服务]
        end

        subgraph "核心引擎层 (Core Engine Layer)"
            MMEngine[MultimodalEngine<br/>统筹引擎]
            OCREngine[OCREngine<br/>OCR引擎]
            VisionEngine[VisionEngine<br/>视觉引擎]
            VideoEngine[VideoEngine<br/>视频引擎]
        end

        subgraph "统计与监控"
            StatsTracker[StatsTracker<br/>统计追踪器]
        end

        subgraph "本地模型层"
            PaddleOCR[PaddleOCR<br/>PP-OCRv4 模型<br/>约200MB]
            EasyOCR[EasyOCR<br/>多语言模型<br/>可选]
        end
    end

    subgraph "下游依赖服务"
        ModelAdapter[Model Adapter<br/>Port 8006<br/>统一LLM路由]
        Storage[对象存储<br/>S3/MinIO<br/>图像/视频存储]

        subgraph "Vision LLM Providers"
            GPT4V[GPT-4 Vision<br/>OpenAI API]
            Claude3V[Claude-3 Vision<br/>Anthropic API]
            GeminiV[Gemini Pro Vision<br/>Google API]
        end
    end

    subgraph "可观测性基础设施"
        Prometheus[Prometheus<br/>指标采集]
        Jaeger[Jaeger<br/>分布式追踪]
        Loki[Loki<br/>日志聚合]
    end

    AIOrch -->|HTTP| FastAPI
    AgentEng -->|HTTP| FastAPI
    RAGEng -->|HTTP| FastAPI
    WebApp -->|HTTP| FastAPI

    FastAPI --> ErrorHandler
    ErrorHandler --> RequestContext
    RequestContext --> CORS

    CORS --> OCRRouter
    CORS --> VisionRouter
    CORS --> AnalysisRouter
    CORS --> HealthRouter

    OCRRouter --> OCRService
    VisionRouter --> VisionService
    AnalysisRouter --> AnalysisService

    OCRService --> OCREngine
    VisionService --> VisionEngine
    AnalysisService --> OCRService
    AnalysisService --> VisionService

    OCREngine --> MMEngine
    VisionEngine --> MMEngine
    VideoEngine --> MMEngine

    MMEngine --> StatsTracker

    OCRService --> PaddleOCR
    OCRService --> EasyOCR

    VisionService -->|HTTP POST<br/>/api/v1/chat/completions| ModelAdapter
    ModelAdapter --> GPT4V
    ModelAdapter --> Claude3V
    ModelAdapter --> GeminiV

    OCRService -.->|下载图像| Storage
    VisionService -.->|下载图像| Storage

    FastAPI -->|/metrics| Prometheus
    FastAPI -->|Trace Context| Jaeger
    FastAPI -->|结构化日志| Loki

sequenceDiagram
    autonumber
    participant Client as 上游调用方<br/>(AI Orchestrator/Agent/RAG)
    participant Router as FastAPI Router<br/>(OCR/Vision/Analysis)
    participant Middleware as 中间件层<br/>(Error/Context/CORS)
    participant Service as 服务层<br/>(OCRService/VisionService)
    participant Engine as 核心引擎层<br/>(OCREngine/VisionEngine)
    participant Model as 本地模型<br/>(PaddleOCR/EasyOCR)
    participant Adapter as Model Adapter<br/>(LLM路由服务)
    participant LLM as Vision LLM<br/>(GPT-4V/Claude-3V)
    participant Stats as StatsTracker<br/>(统计追踪)

    Note over Client,Stats: 场景 1：OCR 文字识别（本地推理）

    Client->>Router: POST /api/v1/ocr/recognize<br/>{image_base64, languages, threshold}
    Router->>Middleware: 路由分发
    Middleware->>Middleware: 错误处理+上下文注入+CORS
    Middleware->>Service: OCRService.recognize()
    Service->>Service: Base64 解码为字节流
    Service->>Service: PIL 加载图像 + RGB 转换
    Service->>Model: PaddleOCR.ocr(image, cls=True)

    Note over Model: PP-OCRv4 文本检测+识别<br/>耗时约 200-500ms

    Model-->>Service: [[bbox, (text, confidence)], ...]
    Service->>Service: 置信度过滤（threshold=0.5）<br/>文本拼接 + 语言检测
    Service->>Engine: OCREngine.recognize()
    Engine->>Stats: 记录成功计数 + 延迟
    Engine-->>Router: OCRResponse<br/>{text_blocks, full_text, language}
    Router-->>Client: 200 OK + JSON

    Note over Client,Stats: 场景 2：图像理解（Vision LLM）

    Client->>Router: POST /api/v1/vision/understand<br/>{image_base64, prompt, model}
    Router->>Middleware: 路由分发
    Middleware->>Service: VisionService.understand()
    Service->>Service: 保持 Base64 编码（无需解码）
    Service->>Adapter: POST /api/v1/chat/completions<br/>{model, messages, max_tokens}

    Note over Adapter: Model Adapter 路由选择<br/>GPT-4V / Claude-3V / Gemini

    Adapter->>LLM: POST /v1/chat/completions<br/>(Vision API 格式)

    Note over LLM: Vision LLM 推理<br/>耗时约 2-5s

    LLM-->>Adapter: {choices, usage}
    Adapter-->>Service: {content, tokens_used}
    Service->>Engine: VisionEngine.understand()
    Engine->>Stats: 记录成功计数 + 延迟
    Engine-->>Router: VisionResponse<br/>{answer, model, tokens_used}
    Router-->>Client: 200 OK + JSON

    Note over Client,Stats: 场景 3：图像综合分析（多任务编排）

    Client->>Router: POST /api/v1/analysis/image<br/>{image_base64, tasks:[description,colors,text]}
    Router->>Middleware: 路由分发
    Middleware->>Service: AnalysisService.analyze()

    par 并行执行多任务
        Service->>Service: _get_description()<br/>→ VisionService
        Service->>Service: _extract_colors()<br/>→ Pillow 颜色提取
        Service->>Service: _extract_text()<br/>→ OCRService
    end

    Service->>Service: 汇总结果 + 元数据提取
    Service-->>Router: ImageAnalysisResponse<br/>{description, colors, text, metadata}
    Router-->>Client: 200 OK + JSON

# app/routers/ocr.py
@router.post("/recognize", response_model=OCRResponse)
async def recognize_text(request: OCRRequest):
    # ...

{
    "image_url": "https://example.com/image.jpg",  # 图像 URL（二选一）
    "image_base64": "iVBORw0KGgoAAAA...",          # Base64 编码（二选一）
    "languages": ["ch", "en"],                     # 语言列表（可选）
    "detect_orientation": true,                    # 是否检测方向（可选）
    "confidence_threshold": 0.5                    # 置信度阈值（可选）
}

# app/routers/ocr.py
@router.post("/recognize/upload", response_model=OCRResponse)
async def recognize_upload(
    file: UploadFile = File(...),
    languages: str = None,
    detect_orientation: bool = True,
    confidence_threshold: float = None,
):
    # ...

# app/models/multimodal.py - OCRResponse
{
    "text_blocks": [
        {
            "text": "您好，世界",
            "confidence": 0.95,
            "bbox": [[10, 20], [100, 20], [100, 50], [10, 50]]
        },
        {
            "text": "Hello, World",
            "confidence": 0.92,
            "bbox": [[10, 60], [120, 60], [120, 90], [10, 90]]
        }
    ],
    "full_text": "您好，世界\nHello, World",
    "language": "zh",
    "processing_time_ms": 250.5
}

{
    "text_blocks": [
        {
            "text": "发票",
            "confidence": 0.98,
            "bbox": [[120, 50], [200, 50], [200, 90], [120, 90]]
        },
        {
            "text": "金额：¥1,234.56",
            "confidence": 0.95,
            "bbox": [[100, 150], [300, 150], [300, 190], [100, 190]]
        }
    ],
    "full_text": "发票\n金额：¥1,234.56",
    "language": "zh",
    "processing_time_ms": 312.8
}

{
    "detail": "OCR recognition failed: PaddleOCR not loaded"
}

HTTP Request (POST /api/v1/ocr/recognize)
    ↓
OCRRouter.recognize_text() [app/routers/ocr.py:18]
    ↓
OCRService.recognize() [app/services/ocr_service.py:80]
    ↓
OCRService._recognize_with_paddleocr() [app/services/ocr_service.py:145]
    ↓
PaddleOCR.ocr() [paddleocr库]

# app/routers/ocr.py:18 - HTTP 路由入口
@router.post("/recognize", response_model=OCRResponse)
async def recognize_text(request: OCRRequest):
    """
    OCR 文字识别

    - **image_url**: 图像 URL
    - **image_base64**: 图像 Base64 编码
    - **languages**: 语言列表
    - **detect_orientation**: 是否检测文字方向
    - **confidence_threshold**: 置信度阈值
    """
    try:
        logger.info(f"OCR request: languages={request.languages}")

        # 调用服务层
        response = await ocr_service.recognize(request)

        logger.info(f"OCR completed: found {len(response.text_blocks)} text blocks")
        return response

    except Exception as e:
        logger.error(f"OCR recognition failed: {e}", exc_info=True)
        raise HTTPException(status_code=500, detail=f"OCR recognition failed: {str(e)}")

# app/services/ocr_service.py:80 - 服务层逻辑
async def recognize(self, request: OCRRequest) -> OCRResponse:
    """OCR 识别"""
    # 1) 获取图像数据（URL下载 或 Base64解码）
    if request.image_base64:
        image_data = base64.b64decode(request.image_base64)
    elif request.image_url:
        image_data = await self._download_image(request.image_url)
    else:
        raise ValueError("Either image_url or image_base64 must be provided")

    # 2) 调用底层识别方法
    response = await self.recognize_from_bytes(
        image_data=image_data,
        languages=request.languages,
        detect_orientation=request.detect_orientation,
        confidence_threshold=request.confidence_threshold,
    )

    return response

async def recognize_from_bytes(
    self,
    image_data: bytes,
    languages: Optional[List[str]] = None,
    detect_orientation: bool = True,
    confidence_threshold: Optional[float] = None,
) -> OCRResponse:
    """从图像字节识别"""
    start_time = time.time()

    # 根据 Provider 选择识别方法
    if self.provider == "paddleocr":
        result = await self._recognize_with_paddleocr(image_data, confidence_threshold)
    elif self.provider == "easyocr":
        result = await self._recognize_with_easyocr(image_data, languages, confidence_threshold)
    else:
        raise ValueError(f"Unsupported OCR provider: {self.provider}")

    processing_time_ms = (time.time() - start_time) * 1000

    return OCRResponse(
        text_blocks=result["text_blocks"],
        full_text=result["full_text"],
        language=result["language"],
        processing_time_ms=processing_time_ms,
    )

# app/services/ocr_service.py:145 - PaddleOCR 推理
async def _recognize_with_paddleocr(
    self, image_data: bytes, confidence_threshold: Optional[float]
) -> dict:
    """使用 PaddleOCR 识别"""
    if not self.ocr_engine:
        raise RuntimeError("PaddleOCR not loaded")

    try:
        # 1) 加载图像（PIL）
        image = Image.open(io.BytesIO(image_data))

        # 2) 转换为 RGB（PaddleOCR 要求）
        if image.mode != "RGB":
            image = image.convert("RGB")

        # 3) 执行 OCR（PaddleOCR 同步调用）
        #    cls=True 启用方向分类器
        result = self.ocr_engine.ocr(image, cls=True)

        # 4) 解析结果并过滤低置信度
        text_blocks = []
        full_text_parts = []
        threshold = confidence_threshold or settings.OCR_CONFIDENCE_THRESHOLD  # 默认 0.5

        if result and result[0]:
            for line in result[0]:
                bbox = line[0]  # 边界框：[[x1,y1], [x2,y2], [x3,y3], [x4,y4]]
                text_info = line[1]  # (文本, 置信度)
                text = text_info[0]
                confidence = text_info[1]

                # 5) 置信度过滤（关键优化点）
                if confidence < threshold:
                    continue

                # 6) 转换边界框格式
                bbox_int = [[int(x), int(y)] for x, y in bbox]

                text_blocks.append(
                    OCRTextBlock(
                        text=text,
                        confidence=float(confidence),
                        bbox=bbox_int,
                    )
                )

                full_text_parts.append(text)

        # 7) 拼接完整文本
        full_text = "\n".join(full_text_parts)

        # 8) 检测主要语言（简单实现）
        language = "zh" if any("\u4e00" <= c <= "\u9fff" for c in full_text) else "en"

        return {
            "text_blocks": text_blocks,
            "full_text": full_text,
            "language": language,
        }

    except Exception as e:
        logger.error(f"PaddleOCR recognition failed: {e}", exc_info=True)
        raise

# app/services/ocr_service.py:34 - 模型预加载（关键优化点）
def _load_paddleocr(self):
    """加载 PaddleOCR 模型"""
    try:
        logger.info(f"Loading PaddleOCR: languages={settings.OCR_LANGUAGES}, use_gpu={settings.OCR_USE_GPU}")

        # 初始化 PaddleOCR（模型自动下载到 ~/.paddleocr/）
        self.ocr_engine = PaddleOCR(
            use_angle_cls=True,  # 启用方向分类（支持旋转文本）
            lang="ch",           # 支持中英文
            use_gpu=settings.OCR_USE_GPU,  # GPU 加速（可选）
            show_log=False,      # 不显示详细日志
        )

        logger.info("PaddleOCR loaded successfully")

    except Exception as e:
        logger.error(f"Failed to load PaddleOCR: {e}")
        # 不抛出异常，允许服务启动（降级模式）

sequenceDiagram
    autonumber
    participant Client as 上游调用方<br/>(AI Orchestrator/RAG)
    participant Router as OCRRouter<br/>/api/v1/ocr/recognize
    participant Service as OCRService<br/>recognize()
    participant Model as PaddleOCR<br/>PP-OCRv4模型

    Client->>Router: POST /api/v1/ocr/recognize<br/>{image_base64, languages, threshold}

    Router->>Router: 参数校验（Pydantic）
    Router->>Service: recognize(request: OCRRequest)

    Service->>Service: Base64 解码为字节流
    Service->>Service: PIL.Image.open(BytesIO(image_data))
    Service->>Service: 转换 RGB 格式

    Service->>Model: PaddleOCR.ocr(image, cls=True)

    Note over Model: PP-OCRv4 推理流程<br/>1. 文本检测（DBNet）<br/>2. 方向分类（ResNet-18）<br/>3. 文本识别（CRNN）<br/>耗时：200-500ms（CPU）

    Model-->>Service: [[bbox, (text, confidence)], ...]

    Service->>Service: 置信度过滤<br/>（丢弃 < 0.5 的文本块）
    Service->>Service: 边界框格式转换<br/>（4点坐标）
    Service->>Service: 文本拼接（\n 分隔）
    Service->>Service: 语言检测<br/>（中文字符范围检测）

    Service-->>Router: OCRResponse<br/>{text_blocks, full_text, language, processing_time_ms}

    Router-->>Client: 200 OK + JSON

    Note over Client,Router: 关键性能指标<br/>P50: 250ms, P95: 500ms, P99: 800ms

@app.post("/vision/understand")
async def vision_understand(
    file: UploadFile = File(...),
    prompt: str = "Describe this image in detail.",
    tenant_id: str = None,
    user_id: str = None,
)

{
    "description": "详细描述",
    "tags": ["tag1", "tag2"],
    "confidence": 0.92,
    "duration_ms": 2000
}

# main.py - HTTP 入口
@app.post("/vision/understand")
async def vision_understand(
    file: UploadFile = File(...),
    prompt: str = "Describe this image in detail.",
    tenant_id: str = None,
    user_id: str = None,
):
    # 1) 前置校验
    if not multimodal_engine:
        raise HTTPException(status_code=503, detail="Multimodal Engine not initialized")

    REQUEST_COUNT.labels(endpoint="/vision/understand", type="vision").inc()

    # 2) 读取文件内容
    image_data = await file.read()

    # 3) 调用 MultimodalEngine
    with REQUEST_LATENCY.labels(endpoint="/vision/understand", type="vision").time():
        result = await multimodal_engine.vision_understand(
            image_data=image_data,
            prompt=prompt,
            tenant_id=tenant_id,
            user_id=user_id,
        )

    return result

# multimodal_engine.py - 业务层
async def vision_understand(
    self,
    image_data: bytes,
    prompt: str = "Describe this image in detail.",
    tenant_id: Optional[str] = None,
    user_id: Optional[str] = None,
) -> Dict[str, Any]:
    start_time = time.time()
    self.stats["total_requests"] += 1
    self.stats["vision_requests"] += 1

    try:
        # 1) 调用 VisionEngine 执行理解
        result = await self.vision_engine.understand(
            image_data=image_data,
            prompt=prompt,
            tenant_id=tenant_id,
            user_id=user_id,
        )

        # 2) 更新统计
        self.stats["successful_requests"] += 1
        latency = (time.time() - start_time) * 1000
        self._latencies.append(latency)
        self._update_avg_latency()

        # 3) 附加耗时信息
        result["duration_ms"] = latency
        return result

    except Exception as e:
        self.stats["failed_requests"] += 1
        logger.error(f"Error in vision understanding: {e}", exc_info=True)
        raise

# vision_engine.py - 引擎层
async def understand(
    self,
    image_data: bytes,
    prompt: str = "Describe this image in detail.",
    tenant_id: Optional[str] = None,
    user_id: Optional[str] = None,
) -> Dict[str, Any]:
    self.stats["total_vision_requests"] += 1

    try:
        # 1) 根据 Provider 选择方法
        if self.provider == "openai":
            result = await self._understand_openai(image_data, prompt)
        elif self.provider == "azure":
            result = await self._understand_azure(image_data, prompt)
        elif self.provider == "anthropic":
            result = await self._understand_anthropic(image_data, prompt)
        else:
            raise ValueError(f"Unsupported vision provider: {self.provider}")

        # 2) 更新成功计数
        self.stats["successful_vision_requests"] += 1
        return result

    except Exception as e:
        self.stats["failed_vision_requests"] += 1
        logger.error(f"Vision understanding failed: {e}", exc_info=True)
        raise

# vision_engine.py - OpenAI Vision 实现
async def _understand_openai(
    self, image_data: bytes, prompt: str
) -> Dict[str, Any]:
    # 1) 图像 Base64 编码
    image_base64 = base64.b64encode(image_data).decode("utf-8")

    # 2) 优先使用统一LLM客户端（UnifiedLLMClient）
    if self.unified_client:
        try:
            result = await self.unified_client.chat(
                messages=[
                    {
                        "role": "user",
                        "content": [
                            {"type": "text", "text": prompt},
                            {
                                "type": "image_url",
                                "image_url": {
                                    "url": f"data:image/jpeg;base64,{image_base64}"
                                },
                            },
                        ],
                    }
                ],
                model=self.model,
                max_tokens=500,
            )
            description = result["content"]
        except Exception as e:
            logger.warning(f"UnifiedLLMClient failed, falling back to direct call: {e}")
            # 3) 降级：直接调用 OpenAI API
            description = await self._openai_direct_call(image_base64, prompt)
    else:
        # 4) 直接调用 OpenAI API
        description = await self._openai_direct_call(image_base64, prompt)

    # 5) 提取标签（简单实现：匹配常见对象名词）
    tags = self._extract_tags(description)

    return {
        "description": description,
        "tags": tags,
        "confidence": 0.92,
        "provider": "openai",
        "model": self.model,
    }

# vision_engine.py - 直接 API 调用（降级方案）
async def _openai_direct_call(self, image_base64: str, prompt: str) -> str:
    headers = {
        "Authorization": f"Bearer {self.api_key}",
        "Content-Type": "application/json",
    }

    payload = {
        "model": self.model,
        "messages": [
            {
                "role": "user",
                "content": [
                    {"type": "text", "text": prompt},
                    {
                        "type": "image_url",
                        "image_url": {
                            "url": f"data:image/jpeg;base64,{image_base64}"
                        },
                    },
                ],
            }
        ],
        "max_tokens": 500,
    }

    # 1) 调用 OpenAI API
    response = await self.client.post(
        f"{self.endpoint}/chat/completions", headers=headers, json=payload
    )
    response.raise_for_status()

    # 2) 解析响应
    data = response.json()
    return data["choices"][0]["message"]["content"]

sequenceDiagram
    autonumber
    participant Client as 上游调用方
    participant FastAPI as FastAPI<br/>/vision/understand
    participant MMEngine as MultimodalEngine
    participant VisionEngine as VisionEngine
    participant UnifiedClient as UnifiedLLMClient
    participant ModelAdapter as Model Adapter
    participant VisionLLM as Vision LLM<br/>(GPT-4V)

    Client->>FastAPI: POST /vision/understand<br/>(file, prompt)
    FastAPI->>FastAPI: 读取文件内容
    FastAPI->>MMEngine: vision_understand(image_data, prompt)

    MMEngine->>MMEngine: 统计计数
    MMEngine->>VisionEngine: understand(image_data, prompt)

    VisionEngine->>VisionEngine: 选择 Provider（openai）
    VisionEngine->>VisionEngine: Base64 编码图像

    alt 使用 UnifiedLLMClient（推荐路径）
        VisionEngine->>UnifiedClient: chat(messages, model)
        UnifiedClient->>ModelAdapter: POST /api/v1/chat/completions

        ModelAdapter->>ModelAdapter: 路由选择（GPT-4V）
        ModelAdapter->>VisionLLM: POST /v1/chat/completions<br/>(messages, model, max_tokens)

        Note over VisionLLM: Vision LLM 推理<br/>耗时约 2-5s

        VisionLLM-->>ModelAdapter: {choices: [{message: {content}}], usage}
        ModelAdapter-->>UnifiedClient: {content, model, usage}
        UnifiedClient-->>VisionEngine: {content: "描述文本"}
    else UnifiedClient 失败（降级路径）
        VisionEngine->>VisionEngine: _openai_direct_call()
        VisionEngine->>VisionLLM: POST /v1/chat/completions<br/>（直接调用，绕过 Model Adapter）
        VisionLLM-->>VisionEngine: {choices: [{message: {content}}]}
    end

    VisionEngine->>VisionEngine: _extract_tags(description)<br/>提取标签（关键词）
    VisionEngine-->>MMEngine: {description, tags, confidence, provider, model}

    MMEngine->>MMEngine: 更新统计<br/>计算耗时
    MMEngine-->>FastAPI: {description, tags, confidence, duration_ms}

    FastAPI-->>Client: 200 OK

@app.post("/vision/detect")
async def vision_detect(
    file: UploadFile = File(...),
    detect_type: str = "objects",  # objects, faces, scenes, text
    tenant_id: str = None,
    user_id: str = None,
)

{
    "detections": [
        {"label": "person", "confidence": 0.95, "bbox": [x, y, w, h]},
        {"label": "car", "confidence": 0.88, "bbox": [x, y, w, h]}
    ],
    "raw_description": "原始描述文本",
    "duration_ms": 2500
}

# main.py - HTTP 入口
@app.post("/vision/detect")
async def vision_detect(
    file: UploadFile = File(...),
    detect_type: str = "objects",
    tenant_id: str = None,
    user_id: str = None,
):
    # 1) 前置校验
    if not multimodal_engine:
        raise HTTPException(status_code=503, detail="Multimodal Engine not initialized")

    REQUEST_COUNT.labels(endpoint="/vision/detect", type="detection").inc()

    # 2) 读取文件内容
    image_data = await file.read()

    # 3) 调用 MultimodalEngine
    with REQUEST_LATENCY.labels(endpoint="/vision/detect", type="detection").time():
        result = await multimodal_engine.vision_detect(
            image_data=image_data,
            detect_type=detect_type,
            tenant_id=tenant_id,
            user_id=user_id,
        )

    return result

# multimodal_engine.py - 业务层
async def vision_detect(
    self,
    image_data: bytes,
    detect_type: str = "objects",
    tenant_id: Optional[str] = None,
    user_id: Optional[str] = None,
) -> Dict[str, Any]:
    start_time = time.time()
    self.stats["total_requests"] += 1
    self.stats["vision_requests"] += 1

    try:
        # 1) 调用 VisionEngine 执行检测
        result = await self.vision_engine.detect(
            image_data=image_data,
            detect_type=detect_type,
            tenant_id=tenant_id,
            user_id=user_id,
        )

        # 2) 更新统计
        self.stats["successful_requests"] += 1
        latency = (time.time() - start_time) * 1000
        self._latencies.append(latency)
        self._update_avg_latency()

        # 3) 附加耗时信息
        result["duration_ms"] = latency
        return result

    except Exception as e:
        self.stats["failed_requests"] += 1
        logger.error(f"Error in vision detection: {e}", exc_info=True)
        raise

# vision_engine.py - 引擎层
async def detect(
    self,
    image_data: bytes,
    detect_type: str = "objects",
    tenant_id: Optional[str] = None,
    user_id: Optional[str] = None,
) -> Dict[str, Any]:
    self.stats["total_vision_requests"] += 1

    try:
        # 1) 根据检测类型构造提示词（Prompt Engineering）
        if detect_type == "objects":
            prompt = "List all objects in this image with their locations."
        elif detect_type == "faces":
            prompt = "Detect all faces in this image and describe them."
        elif detect_type == "scenes":
            prompt = "Describe the scene and setting of this image."
        elif detect_type == "text":
            prompt = "Extract all visible text from this image."
        else:
            prompt = f"Detect {detect_type} in this image."

        # 2) 复用理解接口进行检测
        result = await self.understand(image_data, prompt, tenant_id, user_id)

        # 3) 转换为检测格式（解析 LLM 输出）
        detection_result = {
            "detections": self._parse_detections(result["description"], detect_type),
            "raw_description": result["description"],
        }

        self.stats["successful_vision_requests"] += 1
        return detection_result

    except Exception as e:
        self.stats["failed_vision_requests"] += 1
        logger.error(f"Vision detection failed: {e}", exc_info=True)
        raise

# vision_engine.py - 检测结果解析（简单实现）
def _parse_detections(
    self, description: str, detect_type: str
) -> List[Dict[str, Any]]:
    # 这里应该使用更复杂的 NLP 技术解析
    # 简单实现：返回模拟数据（演示用）
    if detect_type == "objects":
        return [
            {"label": "person", "confidence": 0.95, "bbox": [100, 100, 50, 100]},
            {"label": "car", "confidence": 0.88, "bbox": [300, 200, 80, 60]},
        ]
    elif detect_type == "faces":
        return [
            {"label": "face", "confidence": 0.97, "bbox": [120, 110, 40, 50]},
        ]
    else:
        return []

sequenceDiagram
    autonumber
    participant Client as 上游调用方
    participant FastAPI as FastAPI<br/>/vision/detect
    participant MMEngine as MultimodalEngine
    participant VisionEngine as VisionEngine
    participant UnifiedClient as UnifiedLLMClient
    participant ModelAdapter as Model Adapter
    participant VisionLLM as Vision LLM

    Client->>FastAPI: POST /vision/detect<br/>(file, detect_type="objects")
    FastAPI->>FastAPI: 读取文件内容
    FastAPI->>MMEngine: vision_detect(image_data, detect_type)

    MMEngine->>MMEngine: 统计计数
    MMEngine->>VisionEngine: detect(image_data, detect_type)

    VisionEngine->>VisionEngine: 构造检测提示词<br/>（Prompt Engineering）
    Note over VisionEngine: detect_type="objects"<br/>→ prompt="List all objects..."

    VisionEngine->>VisionEngine: 复用 understand() 接口
    VisionEngine->>VisionEngine: Base64 编码图像

    VisionEngine->>UnifiedClient: chat(messages, model)
    UnifiedClient->>ModelAdapter: POST /api/v1/chat/completions
    ModelAdapter->>VisionLLM: POST /v1/chat/completions

    Note over VisionLLM: Vision LLM 推理<br/>耗时约 2-5s

    VisionLLM-->>ModelAdapter: {choices: [{message: {content: "In this image..."}}]}
    ModelAdapter-->>UnifiedClient: {content: "In this image..."}
    UnifiedClient-->>VisionEngine: {description: "In this image..."}

    VisionEngine->>VisionEngine: _parse_detections()<br/>解析检测结果
    Note over VisionEngine: 从 LLM 描述中提取<br/>对象标签 + 位置信息

    VisionEngine-->>MMEngine: {detections: [...], raw_description: "..."}

    MMEngine->>MMEngine: 更新统计<br/>计算耗时
    MMEngine-->>FastAPI: {detections, raw_description, duration_ms}

    FastAPI-->>Client: 200 OK

@app.post("/video/analyze")
async def video_analyze(
    file: UploadFile = File(...),
    analysis_type: str = "summary",  # summary, keyframes, objects, speech
    tenant_id: str = None,
    user_id: str = None,
)

{
    "summary": "视频摘要文本",
    "duration_seconds": 120.5,
    "fps": 30,
    "resolution": "1920x1080",
    "scenes": [
        {"start": 0.0, "end": 30.0, "description": "开场场景"},
        {"start": 30.0, "end": 60.0, "description": "中间场景"}
    ],
    "provider": "opencv",
    "duration_ms": 5000
}

{
    "keyframes": [
        {
            "timestamp": 0.0,
            "frame_number": 0,
            "thumbnail_url": "https://storage/keyframe_0.jpg",
            "description": "开场画面"
        }
    ],
    "total_keyframes": 3,
    "provider": "opencv",
    "duration_ms": 3000
}

{
    "objects": [
        {
            "label": "person",
            "confidence": 0.95,
            "appearances": [
                {"start": 0.0, "end": 120.5, "bbox": [100, 100, 50, 100]}
            ]
        }
    ],
    "total_objects": 3,
    "provider": "opencv",
    "duration_ms": 8000
}

{
    "speech": [
        {
            "start": 5.0,
            "end": 10.0,
            "text": "欢迎观看",
            "confidence": 0.94,
            "speaker": "Speaker 1"
        }
    ],
    "total_segments": 2,
    "language": "zh",
    "provider": "opencv",
    "duration_ms": 12000
}

# main.py - HTTP 入口
@app.post("/video/analyze")
async def video_analyze(
    file: UploadFile = File(...),
    analysis_type: str = "summary",
    tenant_id: str = None,
    user_id: str = None,
):
    # 1) 前置校验
    if not multimodal_engine:
        raise HTTPException(status_code=503, detail="Multimodal Engine not initialized")

    REQUEST_COUNT.labels(endpoint="/video/analyze", type="video").inc()

    # 2) 读取文件内容
    video_data = await file.read()

    # 3) 调用 MultimodalEngine
    with REQUEST_LATENCY.labels(endpoint="/video/analyze", type="video").time():
        result = await multimodal_engine.video_analyze(
            video_data=video_data,
            analysis_type=analysis_type,
            tenant_id=tenant_id,
            user_id=user_id,
        )

    return result

# multimodal_engine.py - 业务层
async def video_analyze(
    self,
    video_data: bytes,
    analysis_type: str = "summary",
    tenant_id: Optional[str] = None,
    user_id: Optional[str] = None,
) -> Dict[str, Any]:
    start_time = time.time()
    self.stats["total_requests"] += 1
    self.stats["video_requests"] += 1

    try:
        # 1) 调用 VideoEngine 执行分析
        result = await self.video_engine.analyze(
            video_data=video_data,
            analysis_type=analysis_type,
            tenant_id=tenant_id,
            user_id=user_id,
        )

        # 2) 更新统计
        self.stats["successful_requests"] += 1
        latency = (time.time() - start_time) * 1000
        self._latencies.append(latency)
        self._update_avg_latency()

        # 3) 附加耗时信息
        result["duration_ms"] = latency
        return result

    except Exception as e:
        self.stats["failed_requests"] += 1
        logger.error(f"Error in video analysis: {e}", exc_info=True)
        raise

# video_engine.py - 引擎层
async def analyze(
    self,
    video_data: bytes,
    analysis_type: str = "summary",
    tenant_id: Optional[str] = None,
    user_id: Optional[str] = None,
) -> Dict[str, Any]:
    self.stats["total_video_requests"] += 1

    try:
        # 1) 根据分析类型分发到不同方法
        if analysis_type == "summary":
            result = await self._analyze_summary(video_data)
        elif analysis_type == "keyframes":
            result = await self._extract_keyframes(video_data)
        elif analysis_type == "objects":
            result = await self._detect_objects(video_data)
        elif analysis_type == "speech":
            result = await self._extract_speech(video_data)
        else:
            raise ValueError(f"Unsupported analysis type: {analysis_type}")

        self.stats["successful_video_requests"] += 1
        return result

    except Exception as e:
        self.stats["failed_video_requests"] += 1
        logger.error(f"Video analysis failed: {e}", exc_info=True)
        raise

# video_engine.py - 摘要分析（模拟实现）
async def _analyze_summary(self, video_data: bytes) -> Dict[str, Any]:
    # 这里应该使用视频分析模型生成摘要
    # 简单实现：返回模拟数据
    return {
        "summary": "This video shows a person walking in a park during sunset. "
                  "The scene is peaceful with trees and a lake in the background.",
        "duration_seconds": 120.5,
        "fps": 30,
        "resolution": "1920x1080",
        "scenes": [
            {"start": 0.0, "end": 30.0, "description": "Person enters park"},
            {"start": 30.0, "end": 60.0, "description": "Walking by the lake"},
            {"start": 60.0, "end": 120.5, "description": "Sunset view"},
        ],
        "provider": self.provider,
    }

# video_engine.py - 关键帧提取（模拟实现）
async def _extract_keyframes(self, video_data: bytes) -> Dict[str, Any]:
    # 这里应该使用 OpenCV 或其他工具提取关键帧
    # 简单实现：返回模拟数据
    return {
        "keyframes": [
            {
                "timestamp": 0.0,
                "frame_number": 0,
                "thumbnail_url": "https://storage/keyframe_0.jpg",
                "description": "Opening scene",
            },
            {
                "timestamp": 30.0,
                "frame_number": 900,
                "thumbnail_url": "https://storage/keyframe_30.jpg",
                "description": "Mid scene",
            },
            {
                "timestamp": 120.0,
                "frame_number": 3600,
                "thumbnail_url": "https://storage/keyframe_120.jpg",
                "description": "Closing scene",
            },
        ],
        "total_keyframes": 3,
        "provider": self.provider,
    }

sequenceDiagram
    autonumber
    participant Client as 上游调用方
    participant FastAPI as FastAPI<br/>/video/analyze
    participant MMEngine as MultimodalEngine
    participant VideoEngine as VideoEngine
    participant OpenCV as OpenCV/FFmpeg<br/>（待实现）
    participant VisionLLM as Vision LLM<br/>（可选）

    Client->>FastAPI: POST /video/analyze<br/>(file, analysis_type="summary")
    FastAPI->>FastAPI: 读取文件内容
    FastAPI->>MMEngine: video_analyze(video_data, analysis_type)

    MMEngine->>MMEngine: 统计计数
    MMEngine->>VideoEngine: analyze(video_data, analysis_type)

    VideoEngine->>VideoEngine: 根据 analysis_type 分发

    alt analysis_type="summary"
        VideoEngine->>VideoEngine: _analyze_summary()
        Note over VideoEngine: 当前为模拟实现<br/>返回固定摘要数据
        VideoEngine-->>MMEngine: {summary, scenes, duration}
    else analysis_type="keyframes"
        VideoEngine->>VideoEngine: _extract_keyframes()
        Note over VideoEngine: 待实现：使用 OpenCV<br/>提取关键帧（场景切换点）
        VideoEngine-->>MMEngine: {keyframes, total_keyframes}
    else analysis_type="objects"
        VideoEngine->>VideoEngine: _detect_objects()
        Note over VideoEngine: 待实现：逐帧对象检测<br/>+ 时序追踪
        VideoEngine-->>MMEngine: {objects, total_objects}
    else analysis_type="speech"
        VideoEngine->>VideoEngine: _extract_speech()
        Note over VideoEngine: 待实现：提取音频<br/>+ ASR 转录
        VideoEngine-->>MMEngine: {speech, total_segments, language}
    end

    MMEngine->>MMEngine: 更新统计<br/>计算耗时
    MMEngine-->>FastAPI: VideoAnalysisResponse + duration_ms

    FastAPI-->>Client: 200 OK

# app/services/ocr_service.py:34
def _load_paddleocr(self):
    """加载 PaddleOCR 模型（启动时预加载）"""
    try:
        logger.info(f"Loading PaddleOCR: languages={settings.OCR_LANGUAGES}, use_gpu={settings.OCR_USE_GPU}")

        # 初始化 PaddleOCR（模型自动下载到 ~/.paddleocr/）
        self.ocr_engine = PaddleOCR(
            use_angle_cls=True,  # 启用方向分类（支持旋转文本）
            lang="ch",           # 支持中英文混合
            use_gpu=settings.OCR_USE_GPU,  # GPU 加速（可选）
            show_log=False,      # 不显示详细日志
        )

        logger.info("PaddleOCR loaded successfully")

    except Exception as e:
        logger.error(f"Failed to load PaddleOCR: {e}")
        # 不抛出异常，允许服务启动（降级模式）

# app/services/ocr_service.py:176
threshold = confidence_threshold or settings.OCR_CONFIDENCE_THRESHOLD  # 默认 0.5

for line in result[0]:
    bbox = line[0]
    text_info = line[1]
    text = text_info[0]
    confidence = text_info[1]

    # 置信度过滤（关键优化点）
    if confidence < threshold:
        continue  # 丢弃低置信度文本块

    text_blocks.append(OCRTextBlock(text=text, confidence=confidence, bbox=bbox))

# app/core/vision_engine.py:172
# 优先使用统一LLM客户端（推荐路径）
if self.unified_client:
    try:
        result = await self.unified_client.chat(
            messages=[
                {
                    "role": "user",
                    "content": [
                        {"type": "text", "text": prompt},
                        {
                            "type": "image_url",
                            "image_url": {
                                "url": f"data:image/jpeg;base64,{image_base64}"
                            },
                        },
                    ],
                }
            ],
            model=self.model,
            max_tokens=500,
        )
        description = result["content"]

    except Exception as e:
        logger.warning(f"UnifiedLLMClient failed, falling back to direct call: {e}")
        # 降级：直接调用 OpenAI API（绕过 Model Adapter）
        description = await self._openai_direct_call(image_base64, prompt)
else:
    # 直接调用 OpenAI API（未配置 UnifiedLLMClient）
    description = await self._openai_direct_call(image_base64, prompt)

# app/routers/vision.py - 异步路由
@router.post("/understand", response_model=VisionResponse)
async def understand_image(request: VisionRequest):
    # 异步调用服务层
    response = await vision_service.understand(request)
    return response

# app/services/vision_service.py - 异步 HTTP 调用
async def _understand_with_vision_llm(...):
    # 使用 httpx.AsyncClient 异步调用 Model Adapter
    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{self.model_adapter_endpoint}/api/v1/chat/completions",
            json={...},
            timeout=60.0,
        )
    return response

# vision_engine.py
if detect_type == "objects":
    prompt = "List all objects in this image with their locations."
elif detect_type == "faces":
    prompt = "Detect all faces in this image and describe them."
elif detect_type == "scenes":
    prompt = "Describe the scene and setting of this image."
elif detect_type == "text":
    prompt = "Extract all visible text from this image."