feat: use padding mode

Reviewed-on: #1

Dockerfile

@@ -2,7 +2,7 @@
 # Optimized for RTX 5080 GPU deployment
 
 # Use NVIDIA CUDA base image with Python 3.10
-FROM nvidia/cuda:12.8.0-runtime-ubuntu24.04
+FROM nvidia/cuda:12.9.0-runtime-ubuntu24.04
 
 # Set environment variables
 ENV PYTHONUNBUFFERED=1 \
@@ -15,7 +15,7 @@ ENV PYTHONUNBUFFERED=1 \
     # Application config (override defaults for container)
     # Use 127.0.0.1 for --network host mode, or override with -e for bridge mode
     PP_DOCLAYOUT_MODEL_DIR=/root/.cache/modelscope/hub/models/PaddlePaddle/PP-DocLayoutV2 \
-    PADDLEOCR_VL_URL=http://127.0.0.1:8000/v1
+    PADDLEOCR_VL_URL=http://127.0.0.1:8001/v1
 
 # Set working directory
 WORKDIR /app

PORT_CONFIGURATION.md

@@ -0,0 +1,148 @@
+# 端口配置检查总结
+
+## 搜索命令
+
+```bash
+# 搜索所有 8000 端口引用
+rg "(127\.0\.0\.1|localhost):8000"
+
+# 或使用 grep
+grep -r -n -E "(127\.0\.0\.1|localhost):8000" . \
+  --exclude-dir=.git \
+  --exclude-dir=__pycache__ \
+  --exclude-dir=.venv \
+  --exclude="*.pyc"
+```
+
+## 当前端口配置 ✅
+
+### PaddleOCR-VL 服务 (端口 8001)
+
+**代码文件** - 全部正确 ✅:
+- `app/core/config.py:25` → `http://127.0.0.1:8001/v1`
+- `app/services/ocr_service.py:492` → `http://localhost:8001/v1`
+- `app/core/dependencies.py:53` → `http://localhost:8001/v1` (fallback)
+- `Dockerfile:18` → `http://127.0.0.1:8001/v1`
+
+### Mineru API 服务 (端口 8000)
+
+**代码文件** - 全部正确 ✅:
+- `app/core/config.py:28` → `http://127.0.0.1:8000/file_parse`
+- `app/services/ocr_service.py:489` → `http://127.0.0.1:8000/file_parse`
+- `app/core/dependencies.py:52` → `http://127.0.0.1:8000/file_parse` (fallback)
+
+### 文档和示例文件
+
+以下文件包含示例命令，使用 `localhost:8000`，这些是文档用途，不影响实际运行：
+- `docs/*.md` - 各种 curl 示例
+- `README.md` - 配置示例 (使用 8080)
+- `docker-compose.yml` - 使用 8080
+- `openspec/changes/add-doc-processing-api/design.md` - 设计文档
+
+## 验证服务端口
+
+### 1. 检查 vLLM (PaddleOCR-VL)
+```bash
+# 应该在 8001
+lsof -i:8001
+
+# 验证模型
+curl http://127.0.0.1:8001/v1/models
+```
+
+### 2. 检查 Mineru API
+```bash
+# 应该在 8000
+lsof -i:8000
+
+# 验证健康状态
+curl http://127.0.0.1:8000/health
+```
+
+### 3. 检查你的 FastAPI 应用
+```bash
+# 应该在 8053
+lsof -i:8053
+
+# 验证健康状态
+curl http://127.0.0.1:8053/health
+```
+
+## 修复历史
+
+### 已修复的问题 ✅
+
+1. **app/services/ocr_service.py:492**
+   - 从: `paddleocr_vl_url: str = "http://localhost:8000/v1"`
+   - 到: `paddleocr_vl_url: str = "http://localhost:8001/v1"`
+
+2. **Dockerfile:18**
+   - 从: `PADDLEOCR_VL_URL=http://127.0.0.1:8000/v1`
+   - 到: `PADDLEOCR_VL_URL=http://127.0.0.1:8001/v1`
+
+3. **app/core/config.py:25**
+   - 已经是正确的 8001
+
+## 环境变量配置
+
+如果需要自定义端口，可以设置环境变量：
+
+```bash
+# PaddleOCR-VL (默认 8001)
+export PADDLEOCR_VL_URL=http://127.0.0.1:8001/v1
+
+# Mineru API (默认 8000)
+export MINER_OCR_API_URL=http://127.0.0.1:8000/file_parse
+```
+
+或在 `.env` 文件中：
+```env
+PADDLEOCR_VL_URL=http://127.0.0.1:8001/v1
+MINER_OCR_API_URL=http://127.0.0.1:8000/file_parse
+```
+
+## Docker 部署注意事项
+
+在 Docker 容器中，使用：
+- `--network host`: 使用 `127.0.0.1`
+- `--network bridge`: 使用 `host.docker.internal` 或容器名
+
+示例：
+```bash
+docker run \
+  --network host \
+  -e PADDLEOCR_VL_URL=http://127.0.0.1:8001/v1 \
+  -e MINER_OCR_API_URL=http://127.0.0.1:8000/file_parse \
+  doc-processer
+```
+
+## 快速验证脚本
+
+```bash
+#!/bin/bash
+echo "检查端口配置..."
+
+# 检查代码中的配置
+echo -e "\n=== PaddleOCR-VL URLs (应该是 8001) ==="
+rg "paddleocr_vl.*8\d{3}" app/
+
+echo -e "\n=== Mineru API URLs (应该是 8000) ==="
+rg "miner.*8\d{3}" app/
+
+# 检查服务状态
+echo -e "\n=== 检查运行中的服务 ==="
+echo "Port 8000 (Mineru):"
+lsof -i:8000 | grep LISTEN || echo "  未运行"
+
+echo "Port 8001 (PaddleOCR-VL):"
+lsof -i:8001 | grep LISTEN || echo "  未运行"
+
+echo "Port 8053 (FastAPI):"
+lsof -i:8053 | grep LISTEN || echo "  未运行"
+```
+
+保存为 `check_ports.sh`，然后运行：
+```bash
+chmod +x check_ports.sh
+./check_ports.sh
+```

app/api/v1/endpoints/image.py

@@ -1,23 +1,42 @@
 """Image OCR endpoint."""
 
-from fastapi import APIRouter, Depends, HTTPException
+import time
+import uuid
+import cv2
+from io import BytesIO
 
-from app.core.dependencies import get_image_processor, get_layout_detector, get_ocr_service, get_mineru_ocr_service
+from fastapi import APIRouter, Depends, HTTPException, Request, Response
+
+from app.core.dependencies import (
+    get_image_processor,
+    get_layout_detector,
+    get_ocr_service,
+    get_mineru_ocr_service,
+    get_glmocr_service,
+)
+from app.core.config import get_settings
+from app.core.logging_config import get_logger, RequestIDAdapter
 from app.schemas.image import ImageOCRRequest, ImageOCRResponse
 from app.services.image_processor import ImageProcessor
 from app.services.layout_detector import LayoutDetector
-from app.services.ocr_service import OCRService, MineruOCRService
+from app.services.ocr_service import OCRService, MineruOCRService, GLMOCRService
+
+settings = get_settings()
 
 router = APIRouter()
+logger = get_logger()
 
 
 @router.post("/ocr", response_model=ImageOCRResponse)
 async def process_image_ocr(
     request: ImageOCRRequest,
+    http_request: Request,
+    response: Response,
     image_processor: ImageProcessor = Depends(get_image_processor),
     layout_detector: LayoutDetector = Depends(get_layout_detector),
     mineru_service: MineruOCRService = Depends(get_mineru_ocr_service),
     paddle_service: OCRService = Depends(get_ocr_service),
+    glmocr_service: GLMOCRService = Depends(get_glmocr_service),
 ) -> ImageOCRResponse:
     """Process an image and extract content as LaTeX, Markdown, and MathML.
 
@@ -32,21 +51,89 @@ async def process_image_ocr(
     Note: OMML conversion is not included due to performance overhead.
     Use the /convert/latex-to-omml endpoint to convert LaTeX to OMML separately.
     """
+    # Get or generate request ID
+    request_id = http_request.headers.get("x-request-id", str(uuid.uuid4()))
+    response.headers["x-request-id"] = request_id
 
-    image = image_processor.preprocess(
+    # Create logger adapter with request_id
-        image_url=request.image_url,
+    log = RequestIDAdapter(logger, {"request_id": request_id})
-        image_base64=request.image_base64,
+    log.request_id = request_id
-    )
 
     try:
-        if request.model_name == "mineru":
+        log.info("Starting image OCR processing")
-            ocr_result = mineru_service.recognize(image)
+
-        elif request.model_name == "paddle":
+        # Preprocess image (load only, no padding yet)
-            ocr_result = paddle_service.recognize(image)
+        preprocess_start = time.time()
+        image = image_processor.preprocess(
+            image_url=request.image_url,
+            image_base64=request.image_base64,
+        )
+
+        # Apply padding only for layout detection
+        processed_image = image
+        if image_processor and settings.is_padding:
+            processed_image = image_processor.add_padding(image)
+
+        preprocess_time = time.time() - preprocess_start
+        log.debug(f"Image loading completed in {preprocess_time:.3f}s")
+
+        # Layout detection (using padded image if padding is enabled)
+        layout_start = time.time()
+        layout_info = layout_detector.detect(processed_image)
+        layout_time = time.time() - layout_start
+        log.info(f"Layout detection completed in {layout_time:.3f}s")
+
+        # OCR recognition (use original image without padding)
+        ocr_start = time.time()
+        if layout_info.MixedRecognition:
+            recognition_method = "MixedRecognition (MinerU)"
+            log.info(f"Using {recognition_method}")
+
+            # Convert original image (without padding) to bytes
+            success, encoded_image = cv2.imencode(".png", image)
+            if not success:
+                raise RuntimeError("Failed to encode image")
+
+            image_bytes = BytesIO(encoded_image.tobytes())
+            image_bytes.seek(0)  # Ensure position is at the beginning
+            ocr_result = mineru_service.recognize(image_bytes)
         else:
-            raise HTTPException(status_code=400, detail="Invalid model name")
+            recognition_method = "FormulaOnly (GLMOCR)"
+            log.info(f"Using {recognition_method}")
+
+            # Try GLM-OCR first, fallback to MinerU if token limit exceeded
+            try:
+                ocr_result = glmocr_service.recognize(image)
+            except Exception as e:
+                error_msg = str(e)
+                # Check if error is due to token limit (max_model_len exceeded)
+                if "max_model_len" in error_msg or "decoder prompt" in error_msg or "BadRequestError" in error_msg:
+                    log.warning(f"GLM-OCR failed due to token limit: {error_msg}")
+                    log.info("Falling back to MinerU for recognition")
+                    recognition_method = "FormulaOnly (MinerU fallback)"
+
+                    # Convert original image to bytes for MinerU
+                    success, encoded_image = cv2.imencode(".png", image)
+                    if not success:
+                        raise RuntimeError("Failed to encode image")
+
+                    image_bytes = BytesIO(encoded_image.tobytes())
+                    image_bytes.seek(0)
+                    ocr_result = mineru_service.recognize(image_bytes)
+                else:
+                    # Re-raise other errors
+                    raise
+        ocr_time = time.time() - ocr_start
+
+        total_time = time.time() - preprocess_start
+        log.info(f"OCR processing completed - Method: {recognition_method}, " f"Layout time: {layout_time:.3f}s, OCR time: {ocr_time:.3f}s, " f"Total time: {total_time:.3f}s")
+
     except RuntimeError as e:
+        log.error(f"OCR processing failed: {str(e)}", exc_info=True)
         raise HTTPException(status_code=503, detail=str(e))
+    except Exception as e:
+        log.error(f"Unexpected error during OCR processing: {str(e)}", exc_info=True)
+        raise HTTPException(status_code=500, detail="Internal server error")
 
     return ImageOCRResponse(
         latex=ocr_result.get("latex", ""),

app/core/config.py

@@ -21,18 +21,39 @@ class Settings(BaseSettings):
     api_prefix: str = "/doc_process/v1"
     debug: bool = False
 
+    # Base Host Settings (can be overridden via .env file)
+    # Default: 127.0.0.1 (production)
+    # Dev: Set BASE_HOST=100.115.184.74 in .env file
+    base_host: str = "127.0.0.1"
+
     # PaddleOCR-VL Settings
-    paddleocr_vl_url: str = "http://127.0.0.1:8000/v1"
+    @property
+    def paddleocr_vl_url(self) -> str:
+        """Get PaddleOCR-VL URL based on base_host."""
+        return f"http://{self.base_host}:8001/v1"
 
     # MinerOCR Settings
-    miner_ocr_api_url: str = "http://127.0.0.1:8000/file_parse"
+    @property
+    def miner_ocr_api_url(self) -> str:
+        """Get MinerOCR API URL based on base_host."""
+        return f"http://{self.base_host}:8000/file_parse"
+
+    # GLM OCR Settings
+    @property
+    def glm_ocr_url(self) -> str:
+        """Get GLM OCR URL based on base_host."""
+        return f"http://{self.base_host}:8002/v1"
+
+    # padding ratio
+    is_padding: bool = True
+    padding_ratio: float = 0.1
 
     # Model Paths
-    pp_doclayout_model_dir: Optional[str] = "/home/yoge/.cache/modelscope/hub/models/PaddlePaddle/PP-DocLayoutV2"
+    pp_doclayout_model_dir: Optional[str] = "/home/yoge/.cache/modelscope/hub/models/PaddlePaddle/PP-DocLayoutV3"
 
     # Image Processing
     max_image_size_mb: int = 10
-    image_padding_ratio: float = 0.15  # 15% on each side = 30% total expansion
+    image_padding_ratio: float = 0.1  # 10% on each side = 20% total expansion
 
     device: torch.device = torch.device("cuda:0" if torch.cuda.is_available() else "cpu")  # cuda:0 or cpu
 
@@ -40,6 +61,10 @@ class Settings(BaseSettings):
     host: str = "0.0.0.0"
     port: int = 8053
 
+    # Logging Settings
+    log_dir: Optional[str] = None  # Defaults to /app/logs in container or ./logs locally
+    log_level: str = "INFO"  # DEBUG, INFO, WARNING, ERROR, CRITICAL
+
     @property
     def pp_doclayout_dir(self) -> Path:
         """Get the PP-DocLayout model directory path."""

app/core/dependencies.py

@@ -2,7 +2,7 @@
 
 from app.services.image_processor import ImageProcessor
 from app.services.layout_detector import LayoutDetector
-from app.services.ocr_service import OCRService, MineruOCRService
+from app.services.ocr_service import OCRService, MineruOCRService, GLMOCRService
 from app.services.converter import Converter
 from app.core.config import get_settings
 
@@ -49,10 +49,22 @@ def get_converter() -> Converter:
 def get_mineru_ocr_service() -> MineruOCRService:
     """Get a MinerOCR service instance."""
     settings = get_settings()
-    api_url = getattr(settings, 'miner_ocr_api_url', 'http://127.0.0.1:8000/file_parse')
+    api_url = getattr(settings, "miner_ocr_api_url", "http://127.0.0.1:8000/file_parse")
+    glm_ocr_url = getattr(settings, "glm_ocr_url", "http://localhost:8002/v1")
     return MineruOCRService(
         api_url=api_url,
         converter=get_converter(),
         image_processor=get_image_processor(),
+        glm_ocr_url=glm_ocr_url,
     )
 
+
+def get_glmocr_service() -> GLMOCRService:
+    """Get a GLM OCR service instance."""
+    settings = get_settings()
+    glm_ocr_url = getattr(settings, "glm_ocr_url", "http://127.0.0.1:8002/v1")
+    return GLMOCRService(
+        vl_server_url=glm_ocr_url,
+        image_processor=get_image_processor(),
+        converter=get_converter(),
+    )

app/core/logging_config.py

@@ -0,0 +1,157 @@
+"""Logging configuration with rotation by day and size."""
+
+import logging
+import logging.handlers
+from pathlib import Path
+from typing import Any, Optional
+
+from app.core.config import get_settings
+
+
+class TimedRotatingAndSizeFileHandler(logging.handlers.TimedRotatingFileHandler):
+    """File handler that rotates by both time (daily) and size (100MB)."""
+
+    def __init__(
+        self,
+        filename: str,
+        when: str = "midnight",
+        interval: int = 1,
+        backupCount: int = 30,
+        maxBytes: int = 100 * 1024 * 1024,  # 100MB
+        encoding: Optional[str] = None,
+        delay: bool = False,
+        utc: bool = False,
+        atTime: Optional[Any] = None,
+    ):
+        """Initialize handler with both time and size rotation.
+
+        Args:
+            filename: Log file path
+            when: When to rotate (e.g., 'midnight', 'H', 'M')
+            interval: Rotation interval
+            backupCount: Number of backup files to keep
+            maxBytes: Maximum file size before rotation (in bytes)
+            encoding: File encoding
+            delay: Delay file opening until first emit
+            utc: Use UTC time
+            atTime: Time to rotate (for 'midnight' rotation)
+        """
+        super().__init__(
+            filename=filename,
+            when=when,
+            interval=interval,
+            backupCount=backupCount,
+            encoding=encoding,
+            delay=delay,
+            utc=utc,
+            atTime=atTime,
+        )
+        self.maxBytes = maxBytes
+
+    def shouldRollover(self, record):
+        """Check if rollover should occur based on time or size."""
+        # Check time-based rotation first
+        if super().shouldRollover(record):
+            return True
+
+        # Check size-based rotation
+        if self.stream is None:
+            self.stream = self._open()
+        if self.maxBytes > 0:
+            msg = "%s\n" % self.format(record)
+            self.stream.seek(0, 2)  # Seek to end
+            if self.stream.tell() + len(msg) >= self.maxBytes:
+                return True
+        return False
+
+
+def setup_logging(log_dir: Optional[str] = None) -> logging.Logger:
+    """Setup application logging with rotation by day and size.
+
+    Args:
+        log_dir: Directory for log files. Defaults to /app/logs in container or ./logs locally.
+
+    Returns:
+        Configured logger instance.
+    """
+    settings = get_settings()
+
+    # Determine log directory
+    if log_dir is None:
+        log_dir = Path("/app/logs") if Path("/app/logs").exists() else Path("./logs")
+    else:
+        log_dir = Path(log_dir)
+
+    # Create log directory if it doesn't exist
+    log_dir.mkdir(parents=True, exist_ok=True)
+
+    # Create logger
+    logger = logging.getLogger("doc_processer")
+    logger.setLevel(logging.DEBUG if settings.debug else logging.INFO)
+
+    # Remove existing handlers to avoid duplicates
+    logger.handlers.clear()
+
+    # Create custom formatter that handles missing request_id
+    class RequestIDFormatter(logging.Formatter):
+        """Formatter that handles request_id in log records."""
+
+        def format(self, record):
+            # Add request_id if not present
+            if not hasattr(record, "request_id"):
+                record.request_id = getattr(record, "request_id", "unknown")
+            return super().format(record)
+
+    formatter = RequestIDFormatter(
+        fmt="%(asctime)s - %(name)s - %(levelname)s - [%(request_id)s] - %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+
+    # File handler with rotation by day and size
+    # Rotates daily at midnight OR when file exceeds 100MB, keeps 30 days
+    log_file = log_dir / "doc_processer.log"
+    file_handler = TimedRotatingAndSizeFileHandler(
+        filename=str(log_file),
+        when="midnight",
+        interval=1,
+        backupCount=30,
+        maxBytes=100 * 1024 * 1024,  # 100MB
+        encoding="utf-8",
+    )
+    file_handler.setLevel(logging.DEBUG if settings.debug else logging.INFO)
+    file_handler.setFormatter(formatter)
+
+    # Console handler
+    console_handler = logging.StreamHandler()
+    console_handler.setLevel(logging.INFO)
+    console_handler.setFormatter(formatter)
+
+    # Add handlers
+    logger.addHandler(file_handler)
+    logger.addHandler(console_handler)
+
+    return logger
+
+
+# Global logger instance
+_logger: Optional[logging.Logger] = None
+
+
+def get_logger() -> logging.Logger:
+    """Get the global logger instance."""
+    global _logger
+    if _logger is None:
+        _logger = setup_logging()
+    return _logger
+
+
+class RequestIDAdapter(logging.LoggerAdapter):
+    """Logger adapter that adds request_id to log records."""
+
+    def process(self, msg, kwargs):
+        """Add request_id to extra if not present."""
+        if "extra" not in kwargs:
+            kwargs["extra"] = {}
+        if "request_id" not in kwargs["extra"]:
+            kwargs["extra"]["request_id"] = getattr(self, "request_id", "unknown")
+        return msg, kwargs

app/main.py

@@ -7,9 +7,13 @@ from fastapi import FastAPI
 from app.api.v1.router import api_router
 from app.core.config import get_settings
 from app.core.dependencies import init_layout_detector
+from app.core.logging_config import setup_logging
 
 settings = get_settings()
 
+# Initialize logging
+setup_logging()
+
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):

app/services/converter.py

@@ -136,6 +136,7 @@ class Converter:
         """Get cached XSLT transform for MathML to mml: conversion."""
         if cls._mml_xslt_transform is None:
             from lxml import etree
+
             xslt_doc = etree.fromstring(MML_XSLT.encode("utf-8"))
             cls._mml_xslt_transform = etree.XSLT(xslt_doc)
         return cls._mml_xslt_transform
@@ -197,14 +198,17 @@ class Converter:
             return ConvertResult(latex="", mathml="", mml="")
 
         try:
+            # Detect if formula is display (block) or inline
+            is_display = self._is_display_formula(md_text)
+
             # Extract the LaTeX formula content (remove delimiters)
             latex_formula = self._extract_latex_formula(md_text)
 
             # Preprocess formula for better conversion (fix array specifiers, etc.)
             preprocessed_formula = self._preprocess_formula_for_conversion(latex_formula)
 
-            # Convert to MathML
+            # Convert to MathML (pass display flag to use correct delimiters)
-            mathml = self._latex_to_mathml(preprocessed_formula)
+            mathml = self._latex_to_mathml(preprocessed_formula, is_display=is_display)
 
             # Convert MathML to mml:math format (with namespace prefix)
             mml = self._mathml_to_mml(mathml)
@@ -238,18 +242,18 @@ class Converter:
 
         # Preprocess formula using the same preprocessing as export
         preprocessed = self._preprocess_formula_for_conversion(latex_formula.strip())
-        
+
         return self._latex_to_omml(preprocessed)
 
     def _preprocess_formula_for_conversion(self, latex_formula: str) -> str:
         """Preprocess LaTeX formula for any conversion (MathML, OMML, etc.).
 
         Applies the same preprocessing steps as preprocess_for_export to ensure
-        consistency across all conversion paths. This fixes common issues that 
+        consistency across all conversion paths. This fixes common issues that
         cause Pandoc conversion to fail.
 
-        Note: OCR number errors are fixed earlier in the pipeline (in ocr_service.py),
+        Note: OCR errors (number errors, command spacing) are fixed earlier in the
-        so we don't need to handle them here.
+        pipeline (in ocr_service.py), so we don't need to handle them here.
 
         Args:
             latex_formula: Pure LaTeX formula.
@@ -259,18 +263,38 @@ class Converter:
         """
         # 1. Convert matrix environments
         latex_formula = self._convert_matrix_environments(latex_formula)
-        
+
         # 2. Fix array column specifiers (remove spaces)
         latex_formula = self._fix_array_column_specifiers(latex_formula)
-        
+
         # 3. Fix brace spacing
         latex_formula = self._fix_brace_spacing(latex_formula)
-        
+
         # 4. Convert special environments (cases, aligned)
         latex_formula = self._convert_special_environments(latex_formula)
-        
+
         return latex_formula
 
+    def _is_display_formula(self, text: str) -> bool:
+        """Check if the formula is a display (block) formula.
+
+        Args:
+            text: Text containing LaTeX formula with delimiters.
+
+        Returns:
+            True if display formula ($$...$$ or \\[...\\]), False if inline.
+        """
+        text = text.strip()
+
+        # Display math delimiters: $$...$$ or \[...\]
+        if text.startswith("$$") and text.endswith("$$"):
+            return True
+        if text.startswith("\\[") and text.endswith("\\]"):
+            return True
+
+        # Inline math delimiters: $...$ or \(...\)
+        return False
+
     def _extract_latex_formula(self, text: str) -> str:
         """Extract LaTeX formula from text by removing delimiters.
 
@@ -299,18 +323,30 @@ class Converter:
 
     @staticmethod
     @lru_cache(maxsize=256)
-    def _latex_to_mathml_cached(latex_formula: str) -> str:
+    def _latex_to_mathml_cached(latex_formula: str, is_display: bool = False) -> str:
         """Cached conversion of LaTeX formula to MathML.
 
         Uses Pandoc for conversion to ensure Word compatibility.
         Pandoc generates standard MathML that Word can properly import.
 
-        Uses LRU cache to avoid recomputing for repeated formulas.
+        Args:
+            latex_formula: Pure LaTeX formula (without delimiters).
+            is_display: True if display (block) formula, False if inline.
+
+        Returns:
+            Standard MathML representation.
         """
+        # Use appropriate delimiters based on formula type
+        # Display formulas use $$...$$, inline formulas use $...$
+        if is_display:
+            pandoc_input = f"$${latex_formula}$$"
+        else:
+            pandoc_input = f"${latex_formula}$"
+
         try:
             # Use Pandoc for Word-compatible MathML (primary method)
             mathml_html = pypandoc.convert_text(
-                f"${latex_formula}$",
+                pandoc_input,
                 "html",
                 format="markdown+tex_math_dollars",
                 extra_args=["--mathml"],
@@ -321,24 +357,23 @@ class Converter:
                 mathml = match.group(0)
                 # Post-process for Word compatibility
                 return Converter._postprocess_mathml_for_word(mathml)
-            
+
-            # If no match, return as-is
+            # If Pandoc didn't generate MathML (returned HTML instead), use fallback
-            return mathml_html.rstrip("\n")
+            # This happens when Pandoc's mathml output format is not available or fails
-            
+            raise ValueError("Pandoc did not generate MathML, got HTML instead")
+
         except Exception as pandoc_error:
             # Fallback: try latex2mathml (less Word-compatible)
             try:
                 mathml = latex_to_mathml(latex_formula)
                 return Converter._postprocess_mathml_for_word(mathml)
             except Exception as e:
-                raise RuntimeError(
+                raise RuntimeError(f"MathML conversion failed: {pandoc_error}. latex2mathml fallback also failed: {e}") from e
-                    f"MathML conversion failed: {pandoc_error}. latex2mathml fallback also failed: {e}"
+
-                ) from e
-    
     @staticmethod
     def _postprocess_mathml_for_word(mathml: str) -> str:
         """Post-process MathML to improve Word compatibility.
-        
+
         Applies transformations to make MathML more compatible and concise:
         - Remove <semantics> and <annotation> wrappers (Word doesn't need them)
         - Remove unnecessary attributes (form, stretchy, fence, columnalign, etc.)
@@ -346,32 +381,32 @@ class Converter:
         - Change display="inline" to display="block" for better rendering
         - Decode Unicode entities to actual characters (Word prefers this)
         - Ensure proper namespace
-        
+
         Args:
             mathml: MathML string.
-            
+
         Returns:
             Simplified, Word-compatible MathML string.
         """
         import re
-        
+
         # Step 1: Remove <semantics> and <annotation> wrappers
         # These often cause Word import issues
-        if '<semantics>' in mathml:
+        if "<semantics>" in mathml:
             # Extract content between <semantics> and <annotation>
-            match = re.search(r'<semantics>(.*?)<annotation', mathml, re.DOTALL)
+            match = re.search(r"<semantics>(.*?)<annotation", mathml, re.DOTALL)
             if match:
                 content = match.group(1).strip()
-                
+
                 # Get the math element attributes
                 math_attrs = ""
-                math_match = re.search(r'<math([^>]*)>', mathml)
+                math_match = re.search(r"<math([^>]*)>", mathml)
                 if math_match:
                     math_attrs = math_match.group(1)
-                
+
                 # Rebuild without semantics
-                mathml = f'<math{math_attrs}>{content}</math>'
+                mathml = f"<math{math_attrs}>{content}</math>"
-        
+
         # Step 2: Remove unnecessary attributes that don't affect rendering
         # These are verbose and Word doesn't need them
         unnecessary_attrs = [
@@ -390,234 +425,231 @@ class Converter:
             r'\s+class="[^"]*"',
             r'\s+style="[^"]*"',
         ]
-        
+
         for attr_pattern in unnecessary_attrs:
-            mathml = re.sub(attr_pattern, '', mathml)
+            mathml = re.sub(attr_pattern, "", mathml)
-        
+
         # Step 3: Remove redundant single <mrow> wrapper at the top level
         # Pattern: <math ...><mrow>content</mrow></math>
         # Simplify to: <math ...>content</math>
-        mrow_pattern = r'(<math[^>]*>)\s*<mrow>(.*?)</mrow>\s*(</math>)'
+        mrow_pattern = r"(<math[^>]*>)\s*<mrow>(.*?)</mrow>\s*(</math>)"
         match = re.search(mrow_pattern, mathml, re.DOTALL)
         if match:
             # Check if there's only one mrow at the top level
             content = match.group(2)
             # Only remove if the content doesn't have other top-level elements
-            if not re.search(r'</[^>]+>\s*<[^/]', content):
+            if not re.search(r"</[^>]+>\s*<[^/]", content):
-                mathml = f'{match.group(1)}{content}{match.group(3)}'
+                mathml = f"{match.group(1)}{content}{match.group(3)}"
-        
+
         # Step 4: Change display to block for better Word rendering
         mathml = mathml.replace('display="inline"', 'display="block"')
-        
+
         # Step 5: If no display attribute, add it
-        if 'display=' not in mathml and '<math' in mathml:
+        if "display=" not in mathml and "<math" in mathml:
-            mathml = mathml.replace('<math', '<math display="block"', 1)
+            mathml = mathml.replace("<math", '<math display="block"', 1)
-        
+
         # Step 6: Ensure xmlns is present
-        if 'xmlns=' not in mathml and '<math' in mathml:
+        if "xmlns=" not in mathml and "<math" in mathml:
-            mathml = mathml.replace('<math', '<math xmlns="http://www.w3.org/1998/Math/MathML"', 1)
+            mathml = mathml.replace("<math", '<math xmlns="http://www.w3.org/1998/Math/MathML"', 1)
-        
+
         # Step 7: Decode common Unicode entities to actual characters (Word prefers this)
         unicode_map = {
             # Basic operators
-            '&#x0002B;': '+',
+            "&#x0002B;": "+",
-            '&#x0002D;': '-',
+            "&#x0002D;": "-",
-            '&#x0002A;': '*',
+            "&#x0002A;": "*",
-            '&#x0002F;': '/',
+            "&#x0002F;": "/",
-            '&#x0003D;': '=',
+            "&#x0003D;": "=",
-            '&#x0003C;': '<',
+            "&#x0003C;": "<",
-            '&#x0003E;': '>',
+            "&#x0003E;": ">",
-            '&#x00028;': '(',
+            "&#x00028;": "(",
-            '&#x00029;': ')',
+            "&#x00029;": ")",
-            '&#x0002C;': ',',
+            "&#x0002C;": ",",
-            '&#x0002E;': '.',
+            "&#x0002E;": ".",
-            '&#x0007C;': '|',
+            "&#x0007C;": "|",
-            '&#x00B0;': '°',
+            "&#x00B0;": "°",
-            '&#x00D7;': '×',  # times
+            "&#x00D7;": "×",  # times
-            '&#x00F7;': '÷',  # div
+            "&#x00F7;": "÷",  # div
-            '&#x00B1;': '±',  # pm
+            "&#x00B1;": "±",  # pm
-            '&#x2213;': '∓',  # mp
+            "&#x2213;": "∓",  # mp
-            
             # Ellipsis symbols
-            '&#x02026;': '…',  # ldots (horizontal)
+            "&#x02026;": "…",  # ldots (horizontal)
-            '&#x022EE;': '⋮',  # vdots (vertical)
+            "&#x022EE;": "⋮",  # vdots (vertical)
-            '&#x022EF;': '⋯',  # cdots (centered)
+            "&#x022EF;": "⋯",  # cdots (centered)
-            '&#x022F0;': '⋰',  # iddots (diagonal up)
+            "&#x022F0;": "⋰",  # iddots (diagonal up)
-            '&#x022F1;': '⋱',  # ddots (diagonal down)
+            "&#x022F1;": "⋱",  # ddots (diagonal down)
-            
             # Greek letters (lowercase)
-            '&#x03B1;': 'α',  # alpha
+            "&#x03B1;": "α",  # alpha
-            '&#x03B2;': 'β',  # beta
+            "&#x03B2;": "β",  # beta
-            '&#x03B3;': 'γ',  # gamma
+            "&#x03B3;": "γ",  # gamma
-            '&#x03B4;': 'δ',  # delta
+            "&#x03B4;": "δ",  # delta
-            '&#x03B5;': 'ε',  # epsilon
+            "&#x03B5;": "ε",  # epsilon
-            '&#x03B6;': 'ζ',  # zeta
+            "&#x03B6;": "ζ",  # zeta
-            '&#x03B7;': 'η',  # eta
+            "&#x03B7;": "η",  # eta
-            '&#x03B8;': 'θ',  # theta
+            "&#x03B8;": "θ",  # theta
-            '&#x03B9;': 'ι',  # iota
+            "&#x03B9;": "ι",  # iota
-            '&#x03BA;': 'κ',  # kappa
+            "&#x03BA;": "κ",  # kappa
-            '&#x03BB;': 'λ',  # lambda
+            "&#x03BB;": "λ",  # lambda
-            '&#x03BC;': 'μ',  # mu
+            "&#x03BC;": "μ",  # mu
-            '&#x03BD;': 'ν',  # nu
+            "&#x03BD;": "ν",  # nu
-            '&#x03BE;': 'ξ',  # xi
+            "&#x03BE;": "ξ",  # xi
-            '&#x03BF;': 'ο',  # omicron
+            "&#x03BF;": "ο",  # omicron
-            '&#x03C0;': 'π',  # pi
+            "&#x03C0;": "π",  # pi
-            '&#x03C1;': 'ρ',  # rho
+            "&#x03C1;": "ρ",  # rho
-            '&#x03C2;': 'ς',  # final sigma
+            "&#x03C2;": "ς",  # final sigma
-            '&#x03C3;': 'σ',  # sigma
+            "&#x03C3;": "σ",  # sigma
-            '&#x03C4;': 'τ',  # tau
+            "&#x03C4;": "τ",  # tau
-            '&#x03C5;': 'υ',  # upsilon
+            "&#x03C5;": "υ",  # upsilon
-            '&#x03C6;': 'φ',  # phi
+            "&#x03C6;": "φ",  # phi
-            '&#x03C7;': 'χ',  # chi
+            "&#x03C7;": "χ",  # chi
-            '&#x03C8;': 'ψ',  # psi
+            "&#x03C8;": "ψ",  # psi
-            '&#x03C9;': 'ω',  # omega
+            "&#x03C9;": "ω",  # omega
-            '&#x03D5;': 'ϕ',  # phi variant
+            "&#x03D5;": "ϕ",  # phi variant
-            
             # Greek letters (uppercase)
-            '&#x0391;': 'Α',  # Alpha
+            "&#x0391;": "Α",  # Alpha
-            '&#x0392;': 'Β',  # Beta
+            "&#x0392;": "Β",  # Beta
-            '&#x0393;': 'Γ',  # Gamma
+            "&#x0393;": "Γ",  # Gamma
-            '&#x0394;': 'Δ',  # Delta
+            "&#x0394;": "Δ",  # Delta
-            '&#x0395;': 'Ε',  # Epsilon
+            "&#x0395;": "Ε",  # Epsilon
-            '&#x0396;': 'Ζ',  # Zeta
+            "&#x0396;": "Ζ",  # Zeta
-            '&#x0397;': 'Η',  # Eta
+            "&#x0397;": "Η",  # Eta
-            '&#x0398;': 'Θ',  # Theta
+            "&#x0398;": "Θ",  # Theta
-            '&#x0399;': 'Ι',  # Iota
+            "&#x0399;": "Ι",  # Iota
-            '&#x039A;': 'Κ',  # Kappa
+            "&#x039A;": "Κ",  # Kappa
-            '&#x039B;': 'Λ',  # Lambda
+            "&#x039B;": "Λ",  # Lambda
-            '&#x039C;': 'Μ',  # Mu
+            "&#x039C;": "Μ",  # Mu
-            '&#x039D;': 'Ν',  # Nu
+            "&#x039D;": "Ν",  # Nu
-            '&#x039E;': 'Ξ',  # Xi
+            "&#x039E;": "Ξ",  # Xi
-            '&#x039F;': 'Ο',  # Omicron
+            "&#x039F;": "Ο",  # Omicron
-            '&#x03A0;': 'Π',  # Pi
+            "&#x03A0;": "Π",  # Pi
-            '&#x03A1;': 'Ρ',  # Rho
+            "&#x03A1;": "Ρ",  # Rho
-            '&#x03A3;': 'Σ',  # Sigma
+            "&#x03A3;": "Σ",  # Sigma
-            '&#x03A4;': 'Τ',  # Tau
+            "&#x03A4;": "Τ",  # Tau
-            '&#x03A5;': 'Υ',  # Upsilon
+            "&#x03A5;": "Υ",  # Upsilon
-            '&#x03A6;': 'Φ',  # Phi
+            "&#x03A6;": "Φ",  # Phi
-            '&#x03A7;': 'Χ',  # Chi
+            "&#x03A7;": "Χ",  # Chi
-            '&#x03A8;': 'Ψ',  # Psi
+            "&#x03A8;": "Ψ",  # Psi
-            '&#x03A9;': 'Ω',  # Omega
+            "&#x03A9;": "Ω",  # Omega
-            
             # Math symbols
-            '&#x2205;': '∅',  # emptyset
+            "&#x2205;": "∅",  # emptyset
-            '&#x2208;': '∈',  # in
+            "&#x2208;": "∈",  # in
-            '&#x2209;': '∉',  # notin
+            "&#x2209;": "∉",  # notin
-            '&#x220B;': '∋',  # ni
+            "&#x220B;": "∋",  # ni
-            '&#x220C;': '∌',  # nni
+            "&#x220C;": "∌",  # nni
-            '&#x2211;': '∑',  # sum
+            "&#x2211;": "∑",  # sum
-            '&#x220F;': '∏',  # prod
+            "&#x220F;": "∏",  # prod
-            '&#x221A;': '√',  # sqrt
+            "&#x221A;": "√",  # sqrt
-            '&#x221B;': '∛',  # cbrt
+            "&#x221B;": "∛",  # cbrt
-            '&#x221C;': '∜',  # fourthroot
+            "&#x221C;": "∜",  # fourthroot
-            '&#x221E;': '∞',  # infty
+            "&#x221E;": "∞",  # infty
-            '&#x2229;': '∩',  # cap
+            "&#x2229;": "∩",  # cap
-            '&#x222A;': '∪',  # cup
+            "&#x222A;": "∪",  # cup
-            '&#x222B;': '∫',  # int
+            "&#x222B;": "∫",  # int
-            '&#x222C;': '∬',  # iint
+            "&#x222C;": "∬",  # iint
-            '&#x222D;': '∭',  # iiint
+            "&#x222D;": "∭",  # iiint
-            '&#x222E;': '∮',  # oint
+            "&#x222E;": "∮",  # oint
-            '&#x2282;': '⊂',  # subset
+            "&#x2282;": "⊂",  # subset
-            '&#x2283;': '⊃',  # supset
+            "&#x2283;": "⊃",  # supset
-            '&#x2284;': '⊄',  # nsubset
+            "&#x2284;": "⊄",  # nsubset
-            '&#x2285;': '⊅',  # nsupset
+            "&#x2285;": "⊅",  # nsupset
-            '&#x2286;': '⊆',  # subseteq
+            "&#x2286;": "⊆",  # subseteq
-            '&#x2287;': '⊇',  # supseteq
+            "&#x2287;": "⊇",  # supseteq
-            '&#x2288;': '⊈',  # nsubseteq
+            "&#x2288;": "⊈",  # nsubseteq
-            '&#x2289;': '⊉',  # nsupseteq
+            "&#x2289;": "⊉",  # nsupseteq
-            '&#x2264;': '≤',  # leq
+            "&#x2264;": "≤",  # leq
-            '&#x2265;': '≥',  # geq
+            "&#x2265;": "≥",  # geq
-            '&#x2260;': '≠',  # neq
+            "&#x2260;": "≠",  # neq
-            '&#x2261;': '≡',  # equiv
+            "&#x2261;": "≡",  # equiv
-            '&#x2248;': '≈',  # approx
+            "&#x2248;": "≈",  # approx
-            '&#x2243;': '≃',  # simeq
+            "&#x2243;": "≃",  # simeq
-            '&#x2245;': '≅',  # cong
+            "&#x2245;": "≅",  # cong
-            '&#x2202;': '∂',  # partial
+            "&#x2202;": "∂",  # partial
-            '&#x2207;': '∇',  # nabla
+            "&#x2207;": "∇",  # nabla
-            '&#x2200;': '∀',  # forall
+            "&#x2200;": "∀",  # forall
-            '&#x2203;': '∃',  # exists
+            "&#x2203;": "∃",  # exists
-            '&#x2204;': '∄',  # nexists
+            "&#x2204;": "∄",  # nexists
-            '&#x00AC;': '¬',  # neg/lnot
+            "&#x00AC;": "¬",  # neg/lnot
-            '&#x2227;': '∧',  # wedge/land
+            "&#x2227;": "∧",  # wedge/land
-            '&#x2228;': '∨',  # vee/lor
+            "&#x2228;": "∨",  # vee/lor
-            '&#x2192;': '→',  # to/rightarrow
+            "&#x2192;": "→",  # to/rightarrow
-            '&#x2190;': '←',  # leftarrow
+            "&#x2190;": "←",  # leftarrow
-            '&#x2194;': '↔',  # leftrightarrow
+            "&#x2194;": "↔",  # leftrightarrow
-            '&#x21D2;': '⇒',  # Rightarrow
+            "&#x21D2;": "⇒",  # Rightarrow
-            '&#x21D0;': '⇐',  # Leftarrow
+            "&#x21D0;": "⇐",  # Leftarrow
-            '&#x21D4;': '⇔',  # Leftrightarrow
+            "&#x21D4;": "⇔",  # Leftrightarrow
-            '&#x2191;': '↑',  # uparrow
+            "&#x2191;": "↑",  # uparrow
-            '&#x2193;': '↓',  # downarrow
+            "&#x2193;": "↓",  # downarrow
-            '&#x21D1;': '⇑',  # Uparrow
+            "&#x21D1;": "⇑",  # Uparrow
-            '&#x21D3;': '⇓',  # Downarrow
+            "&#x21D3;": "⇓",  # Downarrow
-            '&#x2195;': '↕',  # updownarrow
+            "&#x2195;": "↕",  # updownarrow
-            '&#x21D5;': '⇕',  # Updownarrow
+            "&#x21D5;": "⇕",  # Updownarrow
-            '&#x2260;': '≠',  # ne
+            "&#x2260;": "≠",  # ne
-            '&#x226A;': '≪',  # ll
+            "&#x226A;": "≪",  # ll
-            '&#x226B;': '≫',  # gg
+            "&#x226B;": "≫",  # gg
-            '&#x2A7D;': '⩽',  # leqslant
+            "&#x2A7D;": "⩽",  # leqslant
-            '&#x2A7E;': '⩾',  # geqslant
+            "&#x2A7E;": "⩾",  # geqslant
-            '&#x22A5;': '⊥',  # perp
+            "&#x22A5;": "⊥",  # perp
-            '&#x2225;': '∥',  # parallel
+            "&#x2225;": "∥",  # parallel
-            '&#x2220;': '∠',  # angle
+            "&#x2220;": "∠",  # angle
-            '&#x25B3;': '△',  # triangle
+            "&#x25B3;": "△",  # triangle
-            '&#x25A1;': '□',  # square
+            "&#x25A1;": "□",  # square
-            '&#x25CA;': '◊',  # diamond
+            "&#x25CA;": "◊",  # diamond
-            '&#x2660;': '♠',  # spadesuit
+            "&#x2660;": "♠",  # spadesuit
-            '&#x2661;': '♡',  # heartsuit
+            "&#x2661;": "♡",  # heartsuit
-            '&#x2662;': '♢',  # diamondsuit
+            "&#x2662;": "♢",  # diamondsuit
-            '&#x2663;': '♣',  # clubsuit
+            "&#x2663;": "♣",  # clubsuit
-            '&#x2113;': 'ℓ',  # ell
+            "&#x2113;": "ℓ",  # ell
-            '&#x2118;': '℘',  # wp (Weierstrass p)
+            "&#x2118;": "℘",  # wp (Weierstrass p)
-            '&#x211C;': 'ℜ',  # Re (real part)
+            "&#x211C;": "ℜ",  # Re (real part)
-            '&#x2111;': 'ℑ',  # Im (imaginary part)
+            "&#x2111;": "ℑ",  # Im (imaginary part)
-            '&#x2135;': 'ℵ',  # aleph
+            "&#x2135;": "ℵ",  # aleph
-            '&#x2136;': 'ℶ',  # beth
+            "&#x2136;": "ℶ",  # beth
         }
-        
+
         for entity, char in unicode_map.items():
             mathml = mathml.replace(entity, char)
-        
+
         # Also handle decimal entity format (&#NNNN;) for common characters
         # Convert decimal to hex-based lookup
         decimal_patterns = [
-            (r'&#955;', 'λ'),    # lambda (decimal 955 = hex 03BB)
+            (r"&#955;", "λ"),  # lambda (decimal 955 = hex 03BB)
-            (r'&#8942;', '⋮'),   # vdots (decimal 8942 = hex 22EE)
+            (r"&#8942;", "⋮"),  # vdots (decimal 8942 = hex 22EE)
-            (r'&#8943;', '⋯'),   # cdots (decimal 8943 = hex 22EF)
+            (r"&#8943;", "⋯"),  # cdots (decimal 8943 = hex 22EF)
-            (r'&#8230;', '…'),   # ldots (decimal 8230 = hex 2026)
+            (r"&#8230;", "…"),  # ldots (decimal 8230 = hex 2026)
-            (r'&#8734;', '∞'),   # infty (decimal 8734 = hex 221E)
+            (r"&#8734;", "∞"),  # infty (decimal 8734 = hex 221E)
-            (r'&#8721;', '∑'),   # sum (decimal 8721 = hex 2211)
+            (r"&#8721;", "∑"),  # sum (decimal 8721 = hex 2211)
-            (r'&#8719;', '∏'),   # prod (decimal 8719 = hex 220F)
+            (r"&#8719;", "∏"),  # prod (decimal 8719 = hex 220F)
-            (r'&#8730;', '√'),   # sqrt (decimal 8730 = hex 221A)
+            (r"&#8730;", "√"),  # sqrt (decimal 8730 = hex 221A)
-            (r'&#8712;', '∈'),   # in (decimal 8712 = hex 2208)
+            (r"&#8712;", "∈"),  # in (decimal 8712 = hex 2208)
-            (r'&#8713;', '∉'),   # notin (decimal 8713 = hex 2209)
+            (r"&#8713;", "∉"),  # notin (decimal 8713 = hex 2209)
-            (r'&#8745;', '∩'),   # cap (decimal 8745 = hex 2229)
+            (r"&#8745;", "∩"),  # cap (decimal 8745 = hex 2229)
-            (r'&#8746;', '∪'),   # cup (decimal 8746 = hex 222A)
+            (r"&#8746;", "∪"),  # cup (decimal 8746 = hex 222A)
-            (r'&#8804;', '≤'),   # leq (decimal 8804 = hex 2264)
+            (r"&#8804;", "≤"),  # leq (decimal 8804 = hex 2264)
-            (r'&#8805;', '≥'),   # geq (decimal 8805 = hex 2265)
+            (r"&#8805;", "≥"),  # geq (decimal 8805 = hex 2265)
-            (r'&#8800;', '≠'),   # neq (decimal 8800 = hex 2260)
+            (r"&#8800;", "≠"),  # neq (decimal 8800 = hex 2260)
-            (r'&#8776;', '≈'),   # approx (decimal 8776 = hex 2248)
+            (r"&#8776;", "≈"),  # approx (decimal 8776 = hex 2248)
-            (r'&#8801;', '≡'),   # equiv (decimal 8801 = hex 2261)
+            (r"&#8801;", "≡"),  # equiv (decimal 8801 = hex 2261)
         ]
-        
+
         for pattern, char in decimal_patterns:
             mathml = mathml.replace(pattern, char)
-        
+
         # Step 8: Clean up extra whitespace
-        mathml = re.sub(r'>\s+<', '><', mathml)
+        mathml = re.sub(r">\s+<", "><", mathml)
-        
+
         return mathml
 
-    def _latex_to_mathml(self, latex_formula: str) -> str:
+    def _latex_to_mathml(self, latex_formula: str, is_display: bool = False) -> str:
         """Convert LaTeX formula to standard MathML.
 
         Args:
             latex_formula: Pure LaTeX formula (without delimiters).
+            is_display: True if display (block) formula, False if inline.
 
         Returns:
             Standard MathML representation.
         """
-        return self._latex_to_mathml_cached(latex_formula)
+        return self._latex_to_mathml_cached(latex_formula, is_display=is_display)
 
     def _mathml_to_mml(self, mathml: str) -> str:
         """Convert standard MathML to mml:math format with namespace prefix.

app/services/layout_detector.py

@@ -87,11 +87,11 @@ class LayoutDetector:
     def _get_layout_detector(self):
         """Get or create LayoutDetection instance."""
         if LayoutDetector._layout_detector is None:
-            LayoutDetector._layout_detector = LayoutDetection(model_name="PP-DocLayoutV2")
+            LayoutDetector._layout_detector = LayoutDetection(model_name="PP-DocLayoutV3")
         return LayoutDetector._layout_detector
 
     def detect(self, image: np.ndarray) -> LayoutInfo:
-        """Detect layout of the image using PP-DocLayoutV2.
+        """Detect layout of the image using PP-DocLayoutV3.
 
         Args:
             image: Input image as numpy array.
@@ -125,15 +125,16 @@ class LayoutDetector:
             # Normalize label to region type
             region_type = self.LABEL_TO_TYPE.get(label, "text")
 
-            regions.append(LayoutRegion(
+            regions.append(
-                type=region_type,
+                LayoutRegion(
-                bbox=coordinate,
+                    type=region_type,
-                confidence=score,
+                    bbox=coordinate,
-                score=score,
+                    confidence=score,
-            ))
+                    score=score,
+                )
+            )
 
-
+        mixed_recognition = any(region.type == "text" and region.score > 0.3 for region in regions)
-        mixed_recognition = any(region.type == "text" and region.score > 0.85 for region in regions)
 
         return LayoutInfo(regions=regions, MixedRecognition=mixed_recognition)
 
@@ -144,14 +145,14 @@ if __name__ == "__main__":
     from app.services.image_processor import ImageProcessor
     from app.services.converter import Converter
     from app.services.ocr_service import OCRService
-    
+
     settings = get_settings()
-    
+
     # Initialize dependencies
     layout_detector = LayoutDetector()
     image_processor = ImageProcessor(padding_ratio=settings.image_padding_ratio)
     converter = Converter()
-    
+
     # Initialize OCR service
     ocr_service = OCRService(
         vl_server_url=settings.paddleocr_vl_url,
@@ -159,20 +160,20 @@ if __name__ == "__main__":
         image_processor=image_processor,
         converter=converter,
     )
-    
+
     # Load test image
-    image_path = "test/complex_formula.png"
+    image_path = "test/timeout.jpg"
     image = cv2.imread(image_path)
-    
+
     if image is None:
         print(f"Failed to load image: {image_path}")
     else:
         print(f"Image loaded: {image.shape}")
-        
+
         # Run OCR recognition
         result = ocr_service.recognize(image)
-        
+
         print("\n=== OCR Result ===")
         print(f"Markdown:\n{result['markdown']}")
         print(f"\nLaTeX:\n{result['latex']}")
-        print(f"\nMathML:\n{result['mathml']}")
+        print(f"\nMathML:\n{result['mathml']}")

app/services/ocr_service.py

@@ -5,6 +5,7 @@ import numpy as np
 import cv2
 import requests
 from io import BytesIO
+import base64
 from app.core.config import get_settings
 from paddleocr import PaddleOCRVL
 from typing import Optional
@@ -12,6 +13,7 @@ from app.services.layout_detector import LayoutDetector
 from app.services.image_processor import ImageProcessor
 from app.services.converter import Converter
 from abc import ABC, abstractmethod
+from openai import OpenAI
 
 settings = get_settings()
 
@@ -39,12 +41,23 @@ _COMMANDS_NEED_SPACE = {
     "log",
     "ln",
     "exp",
+    # set relations (often glued by OCR)
+    "in",
+    "notin",
+    "subset",
+    "supset",
+    "subseteq",
+    "supseteq",
+    "cap",
+    "cup",
     # misc
     "partial",
     "nabla",
 }
 
 _MATH_SEGMENT_PATTERN = re.compile(r"\$\$.*?\$\$|\$.*?\$", re.DOTALL)
+# Match LaTeX commands: \command (greedy match all letters)
+# The splitting logic in _split_glued_command_token will handle \inX -> \in X
 _COMMAND_TOKEN_PATTERN = re.compile(r"\\[a-zA-Z]+")
 
 # stage2: differentials inside math segments
@@ -63,6 +76,7 @@ def _split_glued_command_token(token: str) -> str:
     Examples:
     - \\cdotdS -> \\cdot dS
     - \\intdx  -> \\int dx
+    - \\inX    -> \\in X (stop at uppercase letter)
     """
     if not token.startswith("\\"):
         return token
@@ -72,8 +86,8 @@ def _split_glued_command_token(token: str) -> str:
         return token
 
     best = None
-    # longest prefix that is in whitelist
+    # Find longest prefix that is in whitelist
-    for i in range(1, len(body)):
+    for i in range(1, len(body) + 1):
         prefix = body[:i]
         if prefix in _COMMANDS_NEED_SPACE:
             best = prefix
@@ -90,42 +104,52 @@ def _split_glued_command_token(token: str) -> str:
 
 def _clean_latex_syntax_spaces(expr: str) -> str:
     """Clean unwanted spaces in LaTeX syntax (common OCR errors).
-    
+
     OCR often adds spaces in LaTeX syntax structures where they shouldn't be:
     - Subscripts: a _ {i 1} -> a_{i1}
     - Superscripts: x ^ {2 3} -> x^{23}
     - Fractions: \\frac { a } { b } -> \\frac{a}{b}
     - Commands: \\ alpha -> \\alpha
     - Braces: { a b } -> {ab} (within subscripts/superscripts)
-    
+
     This is safe because these spaces are always OCR errors - LaTeX doesn't
     need or want spaces in these positions.
-    
+
     Args:
         expr: LaTeX math expression.
-        
+
     Returns:
         Expression with LaTeX syntax spaces cleaned.
     """
     # Pattern 1: Spaces around _ and ^ (subscript/superscript operators)
     # a _ {i} -> a_{i}, x ^ {2} -> x^{2}
-    expr = re.sub(r'\s*_\s*', '_', expr)
+    expr = re.sub(r"\s*_\s*", "_", expr)
-    expr = re.sub(r'\s*\^\s*', '^', expr)
+    expr = re.sub(r"\s*\^\s*", "^", expr)
-    
+
     # Pattern 2: Spaces inside braces that follow _ or ^
     # _{i 1} -> _{i1}, ^{2 3} -> ^{23}
     # This is safe because spaces inside subscript/superscript braces are usually OCR errors
+    # BUT: if content contains LaTeX commands (\in, \alpha, etc.), spaces after them
+    # must be preserved as they serve as command terminators (\in X != \inX)
     def clean_subscript_superscript_braces(match):
         operator = match.group(1)  # _ or ^
-        content = match.group(2)   # content inside braces
+        content = match.group(2)  # content inside braces
-        # Remove spaces but preserve LaTeX commands (e.g., \alpha, \beta)
+        if "\\" not in content:
-        # Only remove spaces between non-backslash characters
+            # No LaTeX commands: safe to remove all spaces
-        cleaned = re.sub(r'(?<!\\)\s+(?!\\)', '', content)
+            cleaned = re.sub(r"\s+", "", content)
+        else:
+            # Contains LaTeX commands: remove spaces carefully
+            # Keep spaces that follow a LaTeX command (e.g., \in X must keep the space)
+            # Remove spaces everywhere else (e.g., x \in -> x\in is fine)
+            # Strategy: remove spaces before \ and between non-command chars,
+            # but preserve the space after \command when followed by a non-\ char
+            cleaned = re.sub(r"\s+(?=\\)", "", content)  # remove space before \cmd
+            cleaned = re.sub(r"(?<!\\)(?<![a-zA-Z])\s+", "", cleaned)  # remove space after non-letter non-\
         return f"{operator}{{{cleaned}}}"
-    
+
     # Match _{ ... } or ^{ ... }
-    expr = re.sub(r'([_^])\{([^}]+)\}', clean_subscript_superscript_braces, expr)
+    expr = re.sub(r"([_^])\{([^}]+)\}", clean_subscript_superscript_braces, expr)
-    
+
     # Pattern 3: Spaces inside \frac arguments
     # \frac { a } { b } -> \frac{a}{b}
     # \frac{ a + b }{ c } -> \frac{a+b}{c}
@@ -133,47 +157,46 @@ def _clean_latex_syntax_spaces(expr: str) -> str:
         numerator = match.group(1).strip()
         denominator = match.group(2).strip()
         return f"\\frac{{{numerator}}}{{{denominator}}}"
-    
+
-    expr = re.sub(r'\\frac\s*\{\s*([^}]+?)\s*\}\s*\{\s*([^}]+?)\s*\}', 
+    expr = re.sub(r"\\frac\s*\{\s*([^}]+?)\s*\}\s*\{\s*([^}]+?)\s*\}", clean_frac_braces, expr)
-                  clean_frac_braces, expr)
+
-    
     # Pattern 4: Spaces after backslash in LaTeX commands
     # \ alpha -> \alpha, \ beta -> \beta
-    expr = re.sub(r'\\\s+([a-zA-Z]+)', r'\\\1', expr)
+    expr = re.sub(r"\\\s+([a-zA-Z]+)", r"\\\1", expr)
-    
+
     # Pattern 5: Spaces before/after braces in general contexts (conservative)
     # Only remove if the space is clearly wrong (e.g., after operators)
     # { x } in standalone context is kept as-is to avoid breaking valid spacing
     # But after operators like \sqrt{ x } -> \sqrt{x}
-    expr = re.sub(r'(\\[a-zA-Z]+)\s*\{\s*', r'\1{', expr)  # \sqrt { -> \sqrt{
+    expr = re.sub(r"(\\[a-zA-Z]+)\s*\{\s*", r"\1{", expr)  # \sqrt { -> \sqrt{
-    
+
     return expr
 
 
 def _postprocess_math(expr: str) -> str:
     """Postprocess a *math* expression (already inside $...$ or $$...$$).
-    
+
     Processing stages:
     0. Fix OCR number errors (spaces in numbers)
-    1. Split glued LaTeX commands (e.g., \\cdotdS -> \\cdot dS)
+    1. Split glued LaTeX commands (e.g., \\cdotdS -> \\cdot dS, \\inX -> \\in X)
     2. Clean LaTeX syntax spaces (e.g., a _ {i 1} -> a_{i1})
     3. Normalize differentials (DISABLED by default to avoid breaking variables)
-    
+
     Args:
         expr: LaTeX math expression without delimiters.
-        
+
     Returns:
         Processed LaTeX expression.
     """
     # stage0: fix OCR number errors (digits with spaces)
     expr = _fix_ocr_number_errors(expr)
-    
+
-    # stage1: split glued command tokens (e.g. \cdotdS)
+    # stage1: split glued command tokens (e.g. \cdotdS, \inX)
     expr = _COMMAND_TOKEN_PATTERN.sub(lambda m: _split_glued_command_token(m.group(0)), expr)
-    
+
     # stage2: clean LaTeX syntax spaces (OCR often adds unwanted spaces)
     expr = _clean_latex_syntax_spaces(expr)
-    
+
     # stage3: normalize differentials - DISABLED
     # This feature is disabled because it's too aggressive and can break:
     # - LaTeX commands containing 'd': \vdots, \lambda (via subscripts), \delta, etc.
@@ -186,40 +209,36 @@ def _postprocess_math(expr: str) -> str:
     #
     # If differential normalization is needed, implement a context-aware version:
     # expr = _normalize_differentials_contextaware(expr)
-    
+
     return expr
 
 
 def _normalize_differentials_contextaware(expr: str) -> str:
     """Context-aware differential normalization (optional, not used by default).
-    
+
     Only normalizes differentials in specific mathematical contexts:
     1. After integral symbols: \\int dx, \\iint dA, \\oint dr
     2. In fraction denominators: \\frac{dy}{dx}
     3. In explicit differential notation: f(x)dx (function followed by differential)
-    
+
     This avoids false positives like variable names, subscripts, or LaTeX commands.
-    
+
     Args:
         expr: LaTeX math expression.
-        
+
     Returns:
         Expression with differentials normalized in safe contexts only.
     """
     # Pattern 1: After integral commands
     # \int dx -> \int d x
-    integral_pattern = re.compile(
+    integral_pattern = re.compile(r"(\\i+nt|\\oint)\s*([^\\]*?)\s*d([a-zA-Z])(?![a-zA-Z])")
-        r'(\\i+nt|\\oint)\s*([^\\]*?)\s*d([a-zA-Z])(?![a-zA-Z])'
+    expr = integral_pattern.sub(r"\1 \2 d \3", expr)
-    )
+
-    expr = integral_pattern.sub(r'\1 \2 d \3', expr)
-    
     # Pattern 2: In fraction denominators
     # \frac{...}{dx} -> \frac{...}{d x}
-    frac_pattern = re.compile(
+    frac_pattern = re.compile(r"(\\frac\{[^}]*\}\{[^}]*?)d([a-zA-Z])(?![a-zA-Z])([^}]*\})")
-        r'(\\frac\{[^}]*\}\{[^}]*?)d([a-zA-Z])(?![a-zA-Z])([^}]*\})'
+    expr = frac_pattern.sub(r"\1d \2\3", expr)
-    )
+
-    expr = frac_pattern.sub(r'\1d \2\3', expr)
-    
     return expr
 
 
@@ -241,21 +260,21 @@ def _fix_ocr_number_errors(expr: str) -> str:
     """
     # Fix pattern 1: "digit space digit(s). digit(s)" → "digit digit(s).digit(s)"
     # Example: "2 2. 2" → "22.2"
-    expr = re.sub(r'(\d)\s+(\d+)\.\s*(\d+)', r'\1\2.\3', expr)
+    expr = re.sub(r"(\d)\s+(\d+)\.\s*(\d+)", r"\1\2.\3", expr)
-    
+
     # Fix pattern 2: "digit(s). space digit(s)" → "digit(s).digit(s)"
     # Example: "22. 2" → "22.2"
-    expr = re.sub(r'(\d+)\.\s+(\d+)', r'\1.\2', expr)
+    expr = re.sub(r"(\d+)\.\s+(\d+)", r"\1.\2", expr)
-    
+
     # Fix pattern 3: "digit space digit" (no decimal point, within same number context)
     # Be careful: only merge if followed by decimal point or comma/end
     # Example: "1 5 0" → "150" when followed by comma or end
-    expr = re.sub(r'(\d)\s+(\d)(?=\s*[,\)]|$)', r'\1\2', expr)
+    expr = re.sub(r"(\d)\s+(\d)(?=\s*[,\)]|$)", r"\1\2", expr)
-    
+
     # Fix pattern 4: Multiple spaces in decimal numbers
     # Example: "2  2  .  2" → "22.2"
-    expr = re.sub(r'(\d)\s+(\d)(?=\s*\.)', r'\1\2', expr)
+    expr = re.sub(r"(\d)\s+(\d)(?=\s*\.)", r"\1\2", expr)
-    
+
     return expr
 
 
@@ -272,7 +291,87 @@ def _postprocess_markdown(markdown_content: str) -> str:
             return f"${_postprocess_math(seg[1:-1])}$"
         return seg
 
-    return _MATH_SEGMENT_PATTERN.sub(_fix_segment, markdown_content)
+    markdown_content = _MATH_SEGMENT_PATTERN.sub(_fix_segment, markdown_content)
+
+    # Apply markdown-level postprocessing (after LaTeX processing)
+    markdown_content = _remove_false_heading_from_single_formula(markdown_content)
+
+    return markdown_content
+
+
+def _remove_false_heading_from_single_formula(markdown_content: str) -> str:
+    """Remove false heading markers from single-formula content.
+
+    OCR sometimes incorrectly identifies a single formula as a heading by adding '#' prefix.
+    This function detects and removes the heading marker when:
+    1. The content contains only one formula (display or inline)
+    2. The formula line starts with '#' (heading marker)
+    3. No other non-formula text content exists
+
+    Examples:
+        Input:  "# $$E = mc^2$$"
+        Output: "$$E = mc^2$$"
+
+        Input:  "# $x = y$"
+        Output: "$x = y$"
+
+        Input:  "# Introduction\n$$E = mc^2$$"  (has text, keep heading)
+        Output: "# Introduction\n$$E = mc^2$$"
+
+    Args:
+        markdown_content: Markdown text with potential false headings.
+
+    Returns:
+        Markdown text with false heading markers removed.
+    """
+    if not markdown_content or not markdown_content.strip():
+        return markdown_content
+
+    lines = markdown_content.split("\n")
+
+    # Count formulas and heading lines
+    formula_count = 0
+    heading_lines = []
+    has_non_formula_text = False
+
+    for i, line in enumerate(lines):
+        line_stripped = line.strip()
+
+        if not line_stripped:
+            continue
+
+        # Check if line starts with heading marker
+        heading_match = re.match(r"^(#{1,6})\s+(.+)$", line_stripped)
+
+        if heading_match:
+            heading_level = heading_match.group(1)
+            content = heading_match.group(2)
+
+            # Check if the heading content is a formula
+            if re.fullmatch(r"\$\$?.+\$\$?", content):
+                # This is a heading with a formula
+                heading_lines.append((i, heading_level, content))
+                formula_count += 1
+            else:
+                # This is a real heading with text
+                has_non_formula_text = True
+        elif re.fullmatch(r"\$\$?.+\$\$?", line_stripped):
+            # Standalone formula line (not in a heading)
+            formula_count += 1
+        elif line_stripped and not re.match(r"^#+\s*$", line_stripped):
+            # Non-empty, non-heading, non-formula line
+            has_non_formula_text = True
+
+    # Only remove heading markers if:
+    # 1. There's exactly one formula
+    # 2. That formula is in a heading line
+    # 3. There's no other text content
+    if formula_count == 1 and len(heading_lines) == 1 and not has_non_formula_text:
+        # Remove the heading marker from the formula
+        line_idx, heading_level, formula_content = heading_lines[0]
+        lines[line_idx] = formula_content
+
+    return "\n".join(lines)
 
 
 class OCRServiceBase(ABC):
@@ -404,6 +503,93 @@ class OCRService(OCRServiceBase):
             return self._recognize_formula(image)
 
 
+class GLMOCRService(OCRServiceBase):
+    """Service for OCR using GLM-4V model via vLLM."""
+
+    def __init__(
+        self,
+        vl_server_url: str,
+        image_processor: ImageProcessor,
+        converter: Converter,
+    ):
+        """Initialize GLM OCR service.
+
+        Args:
+            vl_server_url: URL of the vLLM server for GLM-4V (default: http://127.0.0.1:8002/v1).
+            image_processor: Image processor instance.
+            converter: Converter instance for format conversion.
+        """
+        self.vl_server_url = vl_server_url or settings.glm_ocr_url
+        self.image_processor = image_processor
+        self.converter = converter
+        self.openai_client = OpenAI(api_key="EMPTY", base_url=self.vl_server_url, timeout=3600)
+
+    def _recognize_formula(self, image: np.ndarray) -> dict:
+        """Recognize formula/math content using GLM-4V.
+
+        Args:
+            image: Input image as numpy array in BGR format.
+
+        Returns:
+            Dict with 'latex', 'markdown', 'mathml', 'mml' keys.
+
+        Raises:
+            RuntimeError: If recognition fails (preserves original exception for fallback handling).
+        """
+        # Add padding to image
+        padded_image = self.image_processor.add_padding(image)
+
+        # Encode image to base64
+        success, encoded_image = cv2.imencode(".png", padded_image)
+        if not success:
+            raise RuntimeError("Failed to encode image")
+
+        image_base64 = base64.b64encode(encoded_image.tobytes()).decode("utf-8")
+        image_url = f"data:image/png;base64,{image_base64}"
+
+        # Call OpenAI-compatible API with formula recognition prompt
+        prompt = "Formula Recognition:"
+        messages = [{"role": "user", "content": [{"type": "image_url", "image_url": {"url": image_url}}, {"type": "text", "text": prompt}]}]
+
+        # Don't catch exceptions here - let them propagate for fallback handling
+        response = self.openai_client.chat.completions.create(
+            model="glm-ocr",
+            messages=messages,
+            temperature=0.0,
+        )
+
+        markdown_content = response.choices[0].message.content
+
+        # Process LaTeX delimiters
+        if markdown_content.startswith(r"\[") or markdown_content.startswith(r"\("):
+            markdown_content = markdown_content.replace(r"\[", "$$").replace(r"\(", "$$")
+            markdown_content = markdown_content.replace(r"\]", "$$").replace(r"\)", "$$")
+        elif not markdown_content.startswith("$$") and not markdown_content.startswith("$"):
+            markdown_content = f"$${markdown_content}$$"
+
+        # Apply postprocessing
+        markdown_content = _postprocess_markdown(markdown_content)
+        convert_result = self.converter.convert_to_formats(markdown_content)
+
+        return {
+            "latex": convert_result.latex,
+            "mathml": convert_result.mathml,
+            "mml": convert_result.mml,
+            "markdown": markdown_content,
+        }
+
+    def recognize(self, image: np.ndarray) -> dict:
+        """Recognize content using GLM-4V.
+
+        Args:
+            image: Input image as numpy array in BGR format.
+
+        Returns:
+            Dict with 'latex', 'markdown', 'mathml', 'mml' keys.
+        """
+        return self._recognize_formula(image)
+
+
 class MineruOCRService(OCRServiceBase):
     """Service for OCR using local file_parse API."""
 
@@ -412,36 +598,98 @@ class MineruOCRService(OCRServiceBase):
         api_url: str = "http://127.0.0.1:8000/file_parse",
         image_processor: Optional[ImageProcessor] = None,
         converter: Optional[Converter] = None,
+        glm_ocr_url: str = "http://localhost:8002/v1",
+        layout_detector: Optional[LayoutDetector] = None,
     ):
         """Initialize Local API service.
 
         Args:
             api_url: URL of the local file_parse API endpoint.
             converter: Optional converter instance for format conversion.
+            glm_ocr_url: URL of the GLM-OCR vLLM server.
         """
         self.api_url = api_url
         self.image_processor = image_processor
         self.converter = converter
+        self.glm_ocr_url = glm_ocr_url
+        self.openai_client = OpenAI(api_key="EMPTY", base_url=glm_ocr_url, timeout=3600)
 
-    def recognize(self, image: np.ndarray) -> dict:
+    def _recognize_formula_with_paddleocr_vl(self, image: np.ndarray, prompt: str = "Formula Recognition:") -> str:
-        """Recognize content using local file_parse API.
+        """Recognize formula using PaddleOCR-VL API.
 
         Args:
             image: Input image as numpy array in BGR format.
+            prompt: Recognition prompt (default: "Formula Recognition:")
+
+        Returns:
+            Recognized formula text (LaTeX format).
+        """
+        try:
+            # Encode image to base64
+            success, encoded_image = cv2.imencode(".png", image)
+            if not success:
+                raise RuntimeError("Failed to encode image")
+
+            image_base64 = base64.b64encode(encoded_image.tobytes()).decode("utf-8")
+            image_url = f"data:image/png;base64,{image_base64}"
+
+            # Call OpenAI-compatible API
+            messages = [{"role": "user", "content": [{"type": "image_url", "image_url": {"url": image_url}}, {"type": "text", "text": prompt}]}]
+
+            response = self.openai_client.chat.completions.create(
+                model="glm-ocr",
+                messages=messages,
+                temperature=0.0,
+            )
+
+            return response.choices[0].message.content
+
+        except Exception as e:
+            raise RuntimeError(f"PaddleOCR-VL formula recognition failed: {e}") from e
+
+    def _extract_and_recognize_formulas(self, markdown_content: str, original_image: np.ndarray) -> str:
+        """Extract image references from markdown and recognize formulas.
+
+        Args:
+            markdown_content: Markdown content with potential image references.
+            original_image: Original input image.
+
+        Returns:
+            Markdown content with formulas recognized by PaddleOCR-VL.
+        """
+        # Pattern to match image references: ![](images/xxx.png) or ![](images/xxx.jpg)
+        image_pattern = re.compile(r"!\[\]\(images/[^)]+\)")
+
+        if not image_pattern.search(markdown_content):
+            return markdown_content
+
+        formula_text = self._recognize_formula_with_paddleocr_vl(original_image)
+
+        if formula_text.startswith(r"\[") or formula_text.startswith(r"\("):
+            formula_text = formula_text.replace(r"\[", "$$").replace(r"\(", "$$")
+            formula_text = formula_text.replace(r"\]", "$$").replace(r"\)", "$$")
+        elif not formula_text.startswith("$$") and not formula_text.startswith("$"):
+            formula_text = f"$${formula_text}$$"
+
+        return formula_text
+
+    def recognize(self, image_bytes: BytesIO) -> dict:
+        """Recognize content using local file_parse API.
+
+        Args:
+            image_bytes: Input image as BytesIO object (already encoded as PNG).
 
         Returns:
             Dict with 'markdown', 'latex', 'mathml' keys.
         """
         try:
-            if self.image_processor:
+            # Decode image_bytes to numpy array for potential formula recognition
-                image = self.image_processor.add_padding(image)
+            image_bytes.seek(0)
+            image_data = np.frombuffer(image_bytes.read(), dtype=np.uint8)
+            original_image = cv2.imdecode(image_data, cv2.IMREAD_COLOR)
 
-            # Convert numpy array to image bytes
+            # Reset image_bytes for API request
-            success, encoded_image = cv2.imencode(".png", image)
+            image_bytes.seek(0)
-            if not success:
-                raise RuntimeError("Failed to encode image")
-
-            image_bytes = BytesIO(encoded_image.tobytes())
 
             # Prepare multipart form data
             files = {"files": ("image.png", image_bytes, "image/png")}
@@ -474,6 +722,9 @@ class MineruOCRService(OCRServiceBase):
             if "results" in result and "image" in result["results"]:
                 markdown_content = result["results"]["image"].get("md_content", "")
 
+            if "![](images/" in markdown_content:
+                markdown_content = self._extract_and_recognize_formulas(markdown_content, original_image)
+
             # Apply postprocessing to fix OCR errors
             markdown_content = _postprocess_markdown(markdown_content)
 
@@ -502,7 +753,13 @@ class MineruOCRService(OCRServiceBase):
 
 if __name__ == "__main__":
     mineru_service = MineruOCRService()
-    image = cv2.imread("test/complex_formula.png")
+    image = cv2.imread("test/formula2.jpg")
     image_numpy = np.array(image)
-    ocr_result = mineru_service.recognize(image_numpy)
+    # Encode image to bytes (as done in API layer)
+    success, encoded_image = cv2.imencode(".png", image_numpy)
+    if not success:
+        raise RuntimeError("Failed to encode image")
+    image_bytes = BytesIO(encoded_image.tobytes())
+    image_bytes.seek(0)
+    ocr_result = mineru_service.recognize(image_bytes)
     print(ocr_result)

docker-compose.yml

@@ -17,6 +17,8 @@ services:
       # Mount pre-downloaded models (adjust paths as needed)
       - ./models/DocLayout:/app/models/DocLayout:ro
       - ./models/PP-DocLayout:/app/models/PP-DocLayout:ro
+      # Mount logs directory to persist logs across container restarts
+      - ./logs:/app/logs
     deploy:
       resources:
         reservations:
@@ -47,6 +49,8 @@ services:
     volumes:
       - ./models/DocLayout:/app/models/DocLayout:ro
       - ./models/PP-DocLayout:/app/models/PP-DocLayout:ro
+      # Mount logs directory to persist logs across container restarts
+      - ./logs:/app/logs
     profiles:
       - cpu
     restart: unless-stopped

docs/LATEX_POSTPROCESSING_COMPLETE.md

@@ -0,0 +1,380 @@
+# LaTeX 后处理完整方案总结
+
+## 功能概述
+
+实现了一个安全、智能的 LaTeX 后处理管道，修复 OCR 识别的常见错误。
+
+## 处理管道
+
+```
+输入: a _ {i 1} + \ vdots
+
+↓ Stage 0: 数字错误修复
+  修复: 2 2. 2 → 22.2
+  结果: a _ {i 1} + \ vdots
+
+↓ Stage 1: 拆分粘连命令
+  修复: \intdx → \int dx
+  结果: a _ {i 1} + \vdots
+
+↓ Stage 2: 清理 LaTeX 语法空格 ← 新增
+  修复: a _ {i 1} → a_{i1}
+  修复: \ vdots → \vdots
+  结果: a_{i1}+\vdots
+
+↓ Stage 3: 微分规范化 (已禁用)
+  跳过
+  结果: a_{i1}+\vdots
+
+输出: a_{i1}+\vdots ✅
+```
+
+## Stage 详解
+
+### Stage 0: 数字错误修复 ✅
+
+**目的**: 修复 OCR 数字识别错误
+
+**示例**:
+- `2 2. 2` → `22.2`
+- `1 5 0` → `150`
+- `3 0. 4` → `30.4`
+
+**安全性**: ✅ 高（只处理数字和小数点）
+
+---
+
+### Stage 1: 拆分粘连命令 ✅
+
+**目的**: 修复 OCR 命令粘连错误
+
+**示例**:
+- `\intdx` → `\int dx`
+- `\cdotdS` → `\cdot dS`
+- `\sumdx` → `\sum dx`
+
+**方法**: 基于白名单的智能拆分
+
+**白名单**:
+```python
+_COMMANDS_NEED_SPACE = {
+    "cdot", "times", "div", "pm", "mp",
+    "int", "iint", "iiint", "oint", "sum", "prod", "lim",
+    "sin", "cos", "tan", "cot", "sec", "csc",
+    "log", "ln", "exp",
+    "partial", "nabla",
+}
+```
+
+**安全性**: ✅ 高（白名单机制）
+
+---
+
+### Stage 2: 清理 LaTeX 语法空格 ✅ 新增
+
+**目的**: 清理 OCR 在 LaTeX 语法中插入的不必要空格
+
+**清理规则**:
+
+#### 1. 下标/上标操作符空格
+```latex
+a _ {i 1}  →  a_{i1}
+x ^ {2 3}  →  x^{23}
+```
+
+#### 2. 大括号内部空格（智能）
+```latex
+a_{i 1}     →  a_{i1}       (移除空格)
+y_{\alpha}  →  y_{\alpha}   (保留命令)
+```
+
+#### 3. 分式空格
+```latex
+\frac { a } { b }  →  \frac{a}{b}
+```
+
+#### 4. 命令反斜杠后空格
+```latex
+\ alpha  →  \alpha
+\ beta   →  \beta
+```
+
+#### 5. 命令后大括号前空格
+```latex
+\sqrt { x }  →  \sqrt{x}
+\sin { x }   →  \sin{x}
+```
+
+**安全性**: ✅ 高（只清理明确的语法位置）
+
+---
+
+### Stage 3: 微分规范化 ❌ 已禁用
+
+**原计划**: 规范化微分符号 `dx → d x`
+
+**为什么禁用**:
+- ❌ 无法区分微分和变量名
+- ❌ 会破坏 LaTeX 命令（`\vdots` → `\vd ots`）
+- ❌ 误判率太高
+- ✅ 收益小（`dx` 本身就是有效的 LaTeX）
+
+**状态**: 禁用，提供可选的上下文感知版本
+
+---
+
+## 解决的问题
+
+### 问题 1: LaTeX 命令被拆分 ✅ 已解决
+
+**原问题**:
+```latex
+\vdots     →  \vd ots      ❌
+\lambda_1  →  \lambd a_1   ❌
+```
+
+**解决方案**: 禁用 Stage 3 微分规范化
+
+**结果**:
+```latex
+\vdots     →  \vdots       ✅
+\lambda_1  →  \lambda_1    ✅
+```
+
+### 问题 2: 语法空格错误 ✅ 已解决
+
+**原问题**:
+```latex
+a _ {i 1}  (OCR 识别结果)
+```
+
+**解决方案**: 新增 Stage 2 空格清理
+
+**结果**:
+```latex
+a _ {i 1}  →  a_{i1}  ✅
+```
+
+### 问题 3: Unicode 实体未转换 ✅ 已解决（之前）
+
+**原问题**:
+```
+MathML 中 λ 未转换为 λ
+```
+
+**解决方案**: 扩展 Unicode 实体映射表
+
+**结果**:
+```
+λ → λ  ✅
+⋮ → ⋮  ✅
+```
+
+---
+
+## 完整测试用例
+
+### 测试 1: 下标空格（用户需求）
+```latex
+输入:  a _ {i 1}
+输出:  a_{i1}  ✅
+```
+
+### 测试 2: 上标空格
+```latex
+输入:  x ^ {2 3}
+输出:  x^{23}  ✅
+```
+
+### 测试 3: 分式空格
+```latex
+输入:  \frac { a } { b }
+输出:  \frac{a}{b}  ✅
+```
+
+### 测试 4: 命令空格
+```latex
+输入:  \ alpha + \ beta
+输出:  \alpha+\beta  ✅
+```
+
+### 测试 5: LaTeX 命令保护
+```latex
+输入:  \vdots
+输出:  \vdots  ✅ (不被破坏)
+
+输入:  \lambda_{1}
+输出:  \lambda_{1}  ✅ (不被破坏)
+```
+
+### 测试 6: 复杂组合
+```latex
+输入:  \frac { a _ {i 1} } { \ sqrt { x ^ {2} } }
+输出:  \frac{a_{i1}}{\sqrt{x^{2}}}  ✅
+```
+
+---
+
+## 安全性保证
+
+### ✅ 保护机制
+
+1. **白名单机制** (Stage 1)
+   - 只拆分已知命令
+   - 不处理未知命令
+
+2. **语法位置检查** (Stage 2)
+   - 只清理明确的语法位置
+   - 不处理模糊的空格
+
+3. **命令保护** (Stage 2)
+   - 保留反斜杠后的内容
+   - 使用 `(?<!\\)` 负向后查找
+
+4. **禁用危险功能** (Stage 3)
+   - 微分规范化已禁用
+   - 避免误判
+
+### ⚠️ 潜在边界情况
+
+#### 1. 运算符空格被移除
+
+```latex
+输入:  a + b
+输出:  a+b  (空格被移除)
+```
+
+**评估**: 可接受（LaTeX 渲染效果相同）
+
+#### 2. 命令间空格被移除
+
+```latex
+输入:  \alpha \beta
+输出:  \alpha\beta  (空格被移除)
+```
+
+**评估**: 可能需要调整（如果这是问题）
+
+**解决方案**（可选）:
+```python
+# 保留命令后的空格
+expr = re.sub(r'(\\[a-zA-Z]+)\s+(\\[a-zA-Z]+)', r'\1 \2', expr)
+```
+
+---
+
+## 性能分析
+
+| Stage | 操作数 | 时间估算 |
+|-------|-------|---------|
+| 0 | 4 个正则表达式 | < 0.5ms |
+| 1 | 1 个正则表达式 + 白名单查找 | < 1ms |
+| 2 | 5 个正则表达式 | < 1ms |
+| 3 | 已禁用 | 0ms |
+| **总计** | | **< 3ms** |
+
+**结论**: ✅ 性能影响可忽略
+
+---
+
+## 文档和工具
+
+### 📄 文档
+1. `docs/LATEX_SPACE_CLEANING.md` - 空格清理详解
+2. `docs/LATEX_PROTECTION_FINAL_FIX.md` - 命令保护方案
+3. `docs/DISABLE_DIFFERENTIAL_NORMALIZATION.md` - 微分规范化禁用说明
+4. `docs/DIFFERENTIAL_PATTERN_BUG_FIX.md` - 初始 Bug 修复
+5. `docs/LATEX_RENDERING_FIX_REPORT.md` - Unicode 实体映射修复
+
+### 🧪 测试工具
+1. `test_latex_space_cleaning.py` - 空格清理测试
+2. `test_disabled_differential_norm.py` - 微分规范化禁用测试
+3. `test_differential_bug_fix.py` - Bug 修复验证
+4. `diagnose_latex_rendering.py` - 渲染问题诊断
+
+---
+
+## 部署检查清单
+
+- [x] Stage 0: 数字错误修复 - 保留 ✅
+- [x] Stage 1: 拆分粘连命令 - 保留 ✅
+- [x] Stage 2: 清理语法空格 - **新增** ✅
+- [x] Stage 3: 微分规范化 - 禁用 ✅
+- [x] Unicode 实体映射 - 已扩展 ✅
+- [x] 代码无语法错误 - 已验证 ✅
+- [ ] 服务重启 - **待完成**
+- [ ] 功能测试 - **待完成**
+
+---
+
+## 部署步骤
+
+1. **✅ 代码已完成**
+   - `app/services/ocr_service.py` 已更新
+   - `app/services/converter.py` 已更新
+
+2. **✅ 测试准备**
+   - 测试脚本已创建
+   - 文档已完善
+
+3. **🔄 重启服务**
+   ```bash
+   # 重启 FastAPI 服务
+   ```
+
+4. **🧪 功能验证**
+   ```bash
+   # 运行测试
+   python test_latex_space_cleaning.py
+   
+   # 测试 API
+   curl -X POST "http://localhost:8000/api/v1/image/ocr" \
+     -H "Content-Type: application/json" \
+     -d '{"image_base64": "...", "model_name": "paddle"}'
+   ```
+
+5. **✅ 验证结果**
+   - 检查 `a _ {i 1}` → `a_{i1}`
+   - 检查 `\vdots` 不被破坏
+   - 检查 `\lambda_{1}` 不被破坏
+
+---
+
+## 总结
+
+| 功能 | 状态 | 优先级 |
+|-----|------|--------|
+| 数字错误修复 | ✅ 保留 | 必需 |
+| 粘连命令拆分 | ✅ 保留 | 必需 |
+| **语法空格清理** | ✅ **新增** | **重要** |
+| 微分规范化 | ❌ 禁用 | 可选 |
+| LaTeX 命令保护 | ✅ 完成 | 必需 |
+| Unicode 实体映射 | ✅ 完成 | 必需 |
+
+### 三大改进
+
+1. **禁用微分规范化** → 保护所有 LaTeX 命令
+2. **新增空格清理** → 修复 OCR 语法错误  
+3. **扩展 Unicode 映射** → 支持所有数学符号
+
+### 设计原则
+
+✅ **Do No Harm** - 不确定的不要改  
+✅ **Fix Clear Errors** - 只修复明确的错误  
+✅ **Whitelist Over Blacklist** - 基于白名单处理  
+
+---
+
+## 下一步
+
+**立即行动**:
+1. 重启服务
+2. 测试用户示例: `a _ {i 1}` → `a_{i1}`
+3. 验证 LaTeX 命令不被破坏
+
+**后续优化**（如需要）:
+1. 根据实际使用调整空格清理规则
+2. 收集更多 OCR 错误模式
+3. 添加配置选项（细粒度控制）
+
+🎉 **完成！现在的后处理管道既安全又智能！**

docs/REMOVE_FALSE_HEADING.md

@@ -0,0 +1,366 @@
+# 移除单公式假标题功能
+
+## 功能概述
+
+OCR 识别时，有时会错误地将单个公式识别为标题格式（在公式前添加 `#`）。
+
+新增功能：自动检测并移除单公式内容的假标题标记。
+
+## 问题背景
+
+### OCR 错误示例
+
+当图片中只有一个数学公式时，OCR 可能错误识别为：
+
+```markdown
+# $$E = mc^2$$
+```
+
+但实际应该是：
+
+```markdown
+$$E = mc^2$$
+```
+
+### 产生原因
+
+1. **视觉误判**: OCR 将公式的位置或样式误判为标题
+2. **布局分析错误**: 检测到公式居中或突出显示，误认为是标题
+3. **字体大小**: 大号公式被识别为标题级别的文本
+
+## 解决方案
+
+### 处理逻辑
+
+**移除标题标记的条件**（必须**同时满足**）:
+
+1. ✅ 内容中只有**一个公式**（display 或 inline）
+2. ✅ 该公式在以 `#` 开头的行（标题行）
+3. ✅ 没有其他文本内容（除了空行）
+
+**保留标题标记的情况**:
+
+1. ❌ 有真实的文本内容（如 `# Introduction`）
+2. ❌ 有多个公式
+3. ❌ 公式不在标题行
+
+### 实现位置
+
+**文件**: `app/services/ocr_service.py`
+
+**函数**: `_remove_false_heading_from_single_formula()`
+
+**集成点**: 在 `_postprocess_markdown()` 的最后阶段
+
+### 处理流程
+
+```
+输入 Markdown
+    ↓
+LaTeX 语法后处理
+    ↓
+移除单公式假标题 ← 新增
+    ↓
+输出 Markdown
+```
+
+## 使用示例
+
+### 示例 1: 移除假标题 ✅
+
+```markdown
+输入:  # $$E = mc^2$$
+输出:  $$E = mc^2$$
+说明:  只有一个公式且在标题中，移除 #
+```
+
+### 示例 2: 保留真标题 ❌
+
+```markdown
+输入:  # Introduction
+       $$E = mc^2$$
+
+输出:  # Introduction
+       $$E = mc^2$$
+
+说明:  有文本内容，保留标题
+```
+
+### 示例 3: 多个公式 ❌
+
+```markdown
+输入:  # $$x = y$$
+       $$a = b$$
+
+输出:  # $$x = y$$
+       $$a = b$$
+
+说明:  有多个公式，保留标题
+```
+
+### 示例 4: 无标题公式 →
+
+```markdown
+输入:  $$E = mc^2$$
+输出:  $$E = mc^2$$
+说明:  本身就没有标题，无需修改
+```
+
+## 详细测试用例
+
+### 类别 1: 应该移除标题 ✅
+
+| 输入 | 输出 | 说明 |
+|-----|------|------|
+| `# $$E = mc^2$$` | `$$E = mc^2$$` | 单个 display 公式 |
+| `# $x = y$` | `$x = y$` | 单个 inline 公式 |
+| `## $$\frac{a}{b}$$` | `$$\frac{a}{b}$$` | 二级标题 |
+| `### $$\lambda_{1}$$` | `$$\lambda_{1}$$` | 三级标题 |
+
+### 类别 2: 应该保留标题（有文本） ❌
+
+| 输入 | 输出 | 说明 |
+|-----|------|------|
+| `# Introduction\n$$E = mc^2$$` | 不变 | 标题有文本 |
+| `# Title\nText\n$$x=y$$` | 不变 | 有段落文本 |
+| `$$E = mc^2$$\n# Summary` | 不变 | 后面有文本标题 |
+
+### 类别 3: 应该保留标题（多个公式） ❌
+
+| 输入 | 输出 | 说明 |
+|-----|------|------|
+| `# $$x = y$$\n$$a = b$$` | 不变 | 两个公式 |
+| `$$x = y$$\n# $$a = b$$` | 不变 | 两个公式 |
+
+### 类别 4: 无需修改 →
+
+| 输入 | 输出 | 说明 |
+|-----|------|------|
+| `$$E = mc^2$$` | 不变 | 无标题标记 |
+| `$x = y$` | 不变 | 无标题标记 |
+| 空字符串 | 不变 | 空内容 |
+
+## 算法实现
+
+### 步骤 1: 分析内容
+
+```python
+for each line:
+    if line starts with '#':
+        if line content is a formula:
+            count as heading_formula
+        else:
+            mark as has_text_content
+    elif line is a formula:
+        count as standalone_formula
+    elif line has text:
+        mark as has_text_content
+```
+
+### 步骤 2: 决策
+
+```python
+if (total_formulas == 1 AND 
+    heading_formulas == 1 AND 
+    NOT has_text_content):
+    remove heading marker
+else:
+    keep as-is
+```
+
+### 步骤 3: 执行
+
+```python
+if should_remove:
+    replace "# $$formula$$" with "$$formula$$"
+```
+
+## 正则表达式说明
+
+### 检测标题行
+
+```python
+heading_match = re.match(r'^(#{1,6})\s+(.+)$', line_stripped)
+```
+
+- `^(#{1,6})` - 1-6 个 `#` 符号（Markdown 标题级别）
+- `\s+` - 至少一个空格
+- `(.+)$` - 标题内容
+
+### 检测公式
+
+```python
+re.fullmatch(r'\$\$?.+\$\$?', content)
+```
+
+- `\$\$?` - `$` 或 `$$`（inline 或 display）
+- `.+` - 公式内容
+- `\$\$?` - 结束的 `$` 或 `$$`
+
+## 边界情况处理
+
+### 1. 空行
+
+```markdown
+输入:  # $$E = mc^2$$
+       
+       
+
+输出:  $$E = mc^2$$
+       
+       
+
+说明:  空行不影响判断
+```
+
+### 2. 前后空行
+
+```markdown
+输入:  
+       
+       # $$E = mc^2$$
+       
+       
+
+输出:  
+       
+       $$E = mc^2$$
+       
+       
+
+说明:  保留空行结构
+```
+
+### 3. 复杂公式
+
+```markdown
+输入:  # $$\int_{0}^{\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2}$$
+
+输出:  $$\int_{0}^{\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2}$$
+
+说明:  复杂公式也能正确处理
+```
+
+## 安全性分析
+
+### ✅ 安全保证
+
+1. **保守策略**: 只在明确的情况下移除标题
+2. **多重条件**: 必须同时满足 3 个条件
+3. **保留真标题**: 有文本内容的标题不会被移除
+4. **保留结构**: 多公式场景保持原样
+
+### ⚠️ 已考虑的风险
+
+#### 风险 1: 误删有意义的标题
+
+**场景**: 用户真的想要 `# $$formula$$` 格式
+
+**缓解**: 
+- 仅在单公式场景下触发
+- 如果有任何文本，保留标题
+- 这种真实需求极少（通常标题会有文字说明）
+
+#### 风险 2: 多级标题判断
+
+**场景**: `##`, `###` 等不同级别
+
+**处理**: 支持所有级别（`#{1,6}`）
+
+#### 风险 3: 公式类型混合
+
+**场景**: Display (`$$`) 和 inline (`$`) 混合
+
+**处理**: 两种类型都能正确识别和计数
+
+## 性能影响
+
+| 操作 | 复杂度 | 时间 |
+|-----|-------|------|
+| 分行 | O(n) | < 0.1ms |
+| 遍历行 | O(n) | < 0.5ms |
+| 正则匹配 | O(m) | < 0.5ms |
+| 替换 | O(1) | < 0.1ms |
+| **总计** | **O(n)** | **< 1ms** |
+
+**评估**: ✅ 性能影响可忽略
+
+## 与其他功能的关系
+
+### 处理顺序
+
+```
+1. OCR 识别 → Markdown 输出
+2. LaTeX 数学公式后处理
+   - 数字错误修复
+   - 命令拆分
+   - 语法空格清理
+3. Markdown 级别后处理
+   - 移除单公式假标题 ← 本功能
+```
+
+### 为什么放在最后
+
+- 需要看到完整的 Markdown 结构
+- 需要 LaTeX 公式已经被清理干净
+- 避免影响前面的处理步骤
+
+## 配置选项（未来扩展）
+
+如果需要更细粒度的控制：
+
+```python
+def _remove_false_heading_from_single_formula(
+    markdown_content: str,
+    enabled: bool = True,
+    max_heading_level: int = 6,
+    preserve_if_has_text: bool = True,
+) -> str:
+    """Configurable heading removal."""
+    # ...
+```
+
+## 测试验证
+
+```bash
+python test_remove_false_heading.py
+```
+
+**关键测试**:
+- ✅ `# $$E = mc^2$$` → `$$E = mc^2$$`
+- ✅ `# Introduction\n$$E = mc^2$$` → 不变
+- ✅ `# $$x = y$$\n$$a = b$$` → 不变
+
+## 部署检查
+
+- [x] 函数实现完成
+- [x] 集成到处理管道
+- [x] 无语法错误
+- [x] 测试用例覆盖
+- [x] 文档完善
+- [ ] 服务重启
+- [ ] 功能验证
+
+## 向后兼容性
+
+**影响**: ✅ 正向改进
+
+- **之前**: 单公式可能带有错误的 `#` 标记
+- **之后**: 自动移除假标题，Markdown 更干净
+- **兼容性**: 不影响有真实文本的标题
+
+## 总结
+
+| 方面 | 状态 |
+|-----|------|
+| 用户需求 | ✅ 实现 |
+| 单公式假标题 | ✅ 移除 |
+| 真标题保护 | ✅ 保留 |
+| 多公式场景 | ✅ 保留 |
+| 安全性 | ✅ 高（保守策略） |
+| 性能 | ✅ < 1ms |
+| 测试覆盖 | ✅ 完整 |
+
+**状态**: ✅ **实现完成，等待测试验证**
+
+**下一步**: 重启服务，测试只包含单个公式的图片！

docs/REMOVE_FALSE_HEADING_SUMMARY.md

@@ -0,0 +1,132 @@
+# 移除单公式假标题 - 快速指南
+
+## 问题
+
+OCR 识别单个公式时，可能错误添加标题标记：
+
+```markdown
+❌ 错误识别:  # $$E = mc^2$$
+✅ 应该是:    $$E = mc^2$$
+```
+
+## 解决方案
+
+**自动移除假标题标记**
+
+### 移除条件（必须同时满足）
+
+1. ✅ 只有**一个**公式
+2. ✅ 该公式在标题行（以 `#` 开头）
+3. ✅ 没有其他文本内容
+
+### 保留标题的情况
+
+1. ❌ 有文本内容：`# Introduction\n$$E = mc^2$$`
+2. ❌ 多个公式：`# $$x = y$$\n$$a = b$$`
+3. ❌ 公式不在标题中：`$$E = mc^2$$`
+
+## 示例
+
+### ✅ 移除假标题
+
+```markdown
+输入:  # $$E = mc^2$$
+输出:  $$E = mc^2$$
+```
+
+```markdown
+输入:  ## $$\frac{a}{b}$$
+输出:  $$\frac{a}{b}$$
+```
+
+### ❌ 保留真标题
+
+```markdown
+输入:  # Introduction
+       $$E = mc^2$$
+
+输出:  # Introduction
+       $$E = mc^2$$
+```
+
+### ❌ 保留多公式场景
+
+```markdown
+输入:  # $$x = y$$
+       $$a = b$$
+
+输出:  # $$x = y$$
+       $$a = b$$
+```
+
+## 实现
+
+**文件**: `app/services/ocr_service.py`
+
+**函数**: `_remove_false_heading_from_single_formula()`
+
+**位置**: Markdown 后处理的最后阶段
+
+## 处理流程
+
+```
+OCR 识别
+    ↓
+LaTeX 公式后处理
+    ↓
+移除单公式假标题 ← 新增
+    ↓
+输出 Markdown
+```
+
+## 安全性
+
+### ✅ 保护机制
+
+- **保守策略**: 只在明确的单公式场景下移除
+- **多重条件**: 必须同时满足 3 个条件
+- **保留真标题**: 有文本的标题不会被移除
+
+### 不会误删
+
+- ✅ 带文字的标题：`# Introduction`
+- ✅ 多公式场景：`# $$x=y$$\n$$a=b$$`
+- ✅ 标题 + 公式：`# Title\n$$x=y$$`
+
+## 测试
+
+```bash
+python test_remove_false_heading.py
+```
+
+**关键测试**:
+- ✅ `# $$E = mc^2$$` → `$$E = mc^2$$`
+- ✅ `# Intro\n$$E=mc^2$$` → 不变（保留标题）
+- ✅ `# $$x=y$$\n$$a=b$$` → 不变（多公式）
+
+## 性能
+
+- **时间复杂度**: O(n)，n 为行数
+- **处理时间**: < 1ms
+- **影响**: ✅ 可忽略
+
+## 部署
+
+1. ✅ 代码已完成
+2. ✅ 测试已覆盖
+3. 🔄 重启服务
+4. 🧪 测试验证
+
+## 总结
+
+| 方面 | 状态 |
+|-----|------|
+| 移除假标题 | ✅ 实现 |
+| 保护真标题 | ✅ 保证 |
+| 保护多公式 | ✅ 保证 |
+| 安全性 | ✅ 高 |
+| 性能 | ✅ 优 |
+
+**状态**: ✅ **完成**
+
+**下一步**: 重启服务，测试单公式图片识别！

pyproject.toml

@@ -19,7 +19,7 @@ dependencies = [
     "numpy==2.2.6",
     "pillow==12.0.0",
     "python-docx==1.2.0",
-    "paddleocr==3.3.2",
+    "paddleocr==3.4.0",
     "doclayout-yolo==0.0.4",
     "latex2mathml==3.78.1",
     "paddle==1.2.0",
@@ -27,11 +27,12 @@ dependencies = [
     "paddlepaddle",
     "paddleocr[doc-parser]",
     "safetensors",
-    "lxml>=5.0.0"
+    "lxml>=5.0.0",
+    "openai",
 ]
 
-[tool.uv.sources]
+# [tool.uv.sources]
-paddlepaddle = { path = "wheels/paddlepaddle-3.4.0.dev20251224-cp310-cp310-linux_x86_64.whl" }
+# paddlepaddle = { path = "wheels/paddlepaddle-3.4.0.dev20251224-cp310-cp310-linux_x86_64.whl" }
 
 [project.optional-dependencies]
 dev = [

test_latex_space_cleaning.py

@@ -1,154 +0,0 @@
-"""Test LaTeX syntax space cleaning functionality.
-
-Tests the _clean_latex_syntax_spaces() function which removes
-unwanted spaces in LaTeX syntax that are common OCR errors.
-"""
-
-import re
-
-
-def _clean_latex_syntax_spaces(expr: str) -> str:
-    """Clean unwanted spaces in LaTeX syntax (common OCR errors)."""
-    # Pattern 1: Spaces around _ and ^
-    expr = re.sub(r'\s*_\s*', '_', expr)
-    expr = re.sub(r'\s*\^\s*', '^', expr)
-    
-    # Pattern 2: Spaces inside braces that follow _ or ^
-    def clean_subscript_superscript_braces(match):
-        operator = match.group(1)
-        content = match.group(2)
-        # Remove spaces but preserve LaTeX commands
-        cleaned = re.sub(r'(?<!\\)\s+(?!\\)', '', content)
-        return f"{operator}{{{cleaned}}}"
-    
-    expr = re.sub(r'([_^])\{([^}]+)\}', clean_subscript_superscript_braces, expr)
-    
-    # Pattern 3: Spaces inside \frac arguments
-    def clean_frac_braces(match):
-        numerator = match.group(1).strip()
-        denominator = match.group(2).strip()
-        return f"\\frac{{{numerator}}}{{{denominator}}}"
-    
-    expr = re.sub(r'\\frac\s*\{\s*([^}]+?)\s*\}\s*\{\s*([^}]+?)\s*\}', 
-                  clean_frac_braces, expr)
-    
-    # Pattern 4: Spaces after backslash
-    expr = re.sub(r'\\\s+([a-zA-Z]+)', r'\\\1', expr)
-    
-    # Pattern 5: Spaces after LaTeX commands before braces
-    expr = re.sub(r'(\\[a-zA-Z]+)\s*\{\s*', r'\1{', expr)
-    
-    return expr
-
-
-# Test cases
-test_cases = [
-    # Subscripts with spaces
-    (r"a _ {i 1}", r"a_{i1}", "subscript with spaces"),
-    (r"x _ { n }", r"x_{n}", "subscript with spaces around"),
-    (r"a_{i 1}", r"a_{i1}", "subscript braces with spaces"),
-    (r"y _ { i j k }", r"y_{ijk}", "subscript multiple spaces"),
-    
-    # Superscripts with spaces
-    (r"x ^ {2 3}", r"x^{23}", "superscript with spaces"),
-    (r"a ^ { n }", r"a^{n}", "superscript with spaces around"),
-    (r"e^{ 2 x }", r"e^{2x}", "superscript expression with spaces"),
-    
-    # Fractions with spaces
-    (r"\frac { a } { b }", r"\frac{a}{b}", "fraction with spaces"),
-    (r"\frac{ x + y }{ z }", r"\frac{x+y}{z}", "fraction expression with spaces"),
-    (r"\frac { 1 } { 2 }", r"\frac{1}{2}", "fraction numbers with spaces"),
-    
-    # LaTeX commands with spaces
-    (r"\ alpha", r"\alpha", "command with space after backslash"),
-    (r"\ beta + \ gamma", r"\beta+\gamma", "multiple commands with spaces"),
-    (r"\sqrt { x }", r"\sqrt{x}", "sqrt with space before brace"),
-    (r"\sin { x }", r"\sin{x}", "sin with space"),
-    
-    # Combined cases
-    (r"a _ {i 1} + b ^ {2 3}", r"a_{i1}+b^{23}", "subscript and superscript"),
-    (r"\frac { a _ {i} } { b ^ {2} }", r"\frac{a_{i}}{b^{2}}", "fraction with sub/superscripts"),
-    (r"x _ { \alpha }", r"x_{\alpha}", "subscript with LaTeX command"),
-    (r"y ^ { \beta + 1 }", r"y^{\beta+1}", "superscript with expression"),
-    
-    # Edge cases - should preserve necessary spaces
-    (r"a + b", r"a+b", "arithmetic operators (space removed)"),
-    (r"\int x dx", r"\intxdx", "integral (spaces removed - might be too aggressive)"),
-    (r"f(x) = x^2", r"f(x)=x^2", "function definition (spaces removed)"),
-    
-    # LaTeX commands should be preserved
-    (r"\lambda_{1}", r"\lambda_{1}", "lambda with subscript (already clean)"),
-    (r"\vdots", r"\vdots", "vdots (should not be affected)"),
-    (r"\alpha \beta \gamma", r"\alpha\beta\gamma", "Greek letters (spaces removed between commands)"),
-]
-
-print("=" * 80)
-print("LaTeX Syntax Space Cleaning Test")
-print("=" * 80)
-
-passed = 0
-failed = 0
-warnings = 0
-
-for original, expected, description in test_cases:
-    result = _clean_latex_syntax_spaces(original)
-    
-    if result == expected:
-        status = "✅ PASS"
-        passed += 1
-    else:
-        status = "❌ FAIL"
-        failed += 1
-        # Check if it's close but not exact
-        if result.replace(" ", "") == expected.replace(" ", ""):
-            status = "⚠️  CLOSE"
-            warnings += 1
-    
-    print(f"{status} {description:40s}")
-    print(f"     Input:    {original}")
-    print(f"     Expected: {expected}")
-    print(f"     Got:      {result}")
-    if result != expected:
-        print(f"     >>> Mismatch!")
-    print()
-
-print("=" * 80)
-print("USER'S SPECIFIC EXAMPLE")
-print("=" * 80)
-
-user_example = r"a _ {i 1}"
-expected_output = r"a_{i1}"
-result = _clean_latex_syntax_spaces(user_example)
-
-print(f"Input:    {user_example}")
-print(f"Expected: {expected_output}")
-print(f"Got:      {result}")
-print(f"Status:   {'✅ CORRECT' if result == expected_output else '❌ INCORRECT'}")
-
-print("\n" + "=" * 80)
-print("SUMMARY")
-print("=" * 80)
-print(f"Total tests: {len(test_cases)}")
-print(f"✅ Passed: {passed}")
-print(f"❌ Failed: {failed}")
-print(f"⚠️  Close: {warnings}")
-
-if failed == 0:
-    print("\n✅ All tests passed!")
-else:
-    print(f"\n⚠️  {failed} test(s) failed")
-
-print("\n" + "=" * 80)
-print("IMPORTANT NOTES")
-print("=" * 80)
-print("""
-1. ✅ Subscript/superscript spaces: a _ {i 1} -> a_{i1}
-2. ✅ Fraction spaces: \\frac { a } { b } -> \\frac{a}{b}
-3. ✅ Command spaces: \\ alpha -> \\alpha
-4. ⚠️  This might remove some intentional spaces in expressions
-5. ⚠️  LaTeX commands inside braces are preserved (e.g., _{\\alpha})
-
-If any edge cases are broken, the patterns can be adjusted to be more conservative.
-""")
-
-print("=" * 80)