Skip to content

A fast, helpful, and open-source document parser

9.6 KB
Raw Blame
import io
import logging
import os
import threading
from copy import deepcopy
from pathlib import Path
from typing import Any

import uvicorn
from fastapi import FastAPI, HTTPException
from fastapi.datastructures import UploadFile
from fastapi.param_functions import File, Form
from minicpmvocr import (
    DEFAULT_CONFIG,
    create_backend,
    create_layout_detector,
    get_element_cfg,
    load_prompt_map,
)
from minicpmvocr.layouts.download import ensure_layout_model
from PIL import Image
from pydantic import BaseModel
from starlette.concurrency import run_in_threadpool

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

DEFAULT_MODEL = "minicpm-ocr"
DEFAULT_BACKEND = "vllm"
DEFAULT_MAX_MODEL_LEN = 40960
DEFAULT_STARTUP_TIMEOUT = 60
DEFAULT_REQUEST_TIMEOUT = 300
DEFAULT_LAYOUT_DIR = "~/.cache/minicpm-ocr/layout"


class OcrResponse(BaseModel):
    results: list[Any]


class StatusResponse(BaseModel):
    status: str


def _env(name: str, default: str = "") -> str:
    return (os.getenv(name) or default).strip()


def _env_int(name: str, default: int) -> int:
    raw = _env(name, str(default))
    try:
        return int(raw)
    except ValueError:
        logger.warning("Invalid %s=%r; using %s", name, raw, default)
        return default


def _normalize_server_url(url: str) -> str:
    """The SDK expects the server root, without a trailing /v1."""
    url = (url or "").strip().rstrip("/")
    if url.endswith("/v1"):
        url = url[: -len("/v1")]
    return url


def _resize_to_min_side(image: Image.Image, target_min_side: int | None) -> Image.Image:
    if not target_min_side:
        return image
    width, height = image.size
    if min(width, height) >= target_min_side:
        return image
    scale = target_min_side / min(width, height)
    return image.resize((int(width * scale), int(height * scale)), Image.Resampling.LANCZOS)


def build_config(base_url: str) -> dict:
    cfg = deepcopy(DEFAULT_CONFIG)
    cfg["engine"].update(
        {
            "type": _env("MINICPM_OCR_BACKEND", DEFAULT_BACKEND),
            "model_name": _env("MINICPM_OCR_MODEL", DEFAULT_MODEL),
            "server_url": base_url,
            "api_key": _env("MINICPM_OCR_API_KEY"),
            "max_model_len": _env_int("MINICPM_OCR_MAX_MODEL_LEN", DEFAULT_MAX_MODEL_LEN),
            "startup_timeout_sec": _env_int("MINICPM_OCR_STARTUP_TIMEOUT", DEFAULT_STARTUP_TIMEOUT),
            "request_timeout_sec": _env_int("MINICPM_OCR_REQUEST_TIMEOUT", DEFAULT_REQUEST_TIMEOUT),
            # MiniCPM-OCR puts its output in content; leaving thinking enabled can
            # move the transcription into reasoning_content, which the SDK never reads.
            "extra_body": {"chat_template_kwargs": {"enable_thinking": False}},
        }
    )
    cfg["layout"].update(
        {
            "provider": "ppdoclayout3_paddlex",
            "model_dir": "",
            "device": _env("MINICPM_OCR_LAYOUT_DEVICE", "cpu"),
        }
    )
    return cfg


def _valid_bbox(bbox: Any) -> list[float] | None:
    if not isinstance(bbox, (list, tuple)) or len(bbox) != 4:
        return None
    try:
        x1, y1, x2, y2 = (float(value) for value in bbox)
    except (TypeError, ValueError):
        return None
    if x2 <= x1 or y2 <= y1:
        return None
    return [x1, y1, x2, y2]


def _block_to_result(block: dict, text: str) -> dict[str, Any]:
    bbox = _valid_bbox(block.get("bbox")) or [0, 0, 0, 0]
    result: dict[str, Any] = {
        "text": text,
        "bbox": [int(round(value)) for value in bbox],
        # MiniCPM-OCR returns no OCR confidence; the layout detection score is
        # not a recognition confidence, so report a neutral value.
        "confidence": 1.0,
    }
    polygon = block.get("polygon")
    if isinstance(polygon, list) and len(polygon) == 4:
        try:
            result["polygon"] = [[float(point[0]), float(point[1])] for point in polygon]
        except (TypeError, ValueError, IndexError):
            pass
    return result


class MiniCPMOCRServer:
    """LiteParse OCR server backed by MiniCPM-OCR 1.0.

    Layout detection runs in this process with the model's bundled PP-DocLayout
    provider; text recognition is delegated to a MiniCPM-OCR inference server
    (vLLM, SGLang, llama.cpp or Ollama) because the 1.3B VLM is expected to run
    on its own serving engine, as with the Surya adapter.

    The request ``language`` field is accepted for API compatibility but unused:
    MiniCPM-OCR 1.0 handles Chinese and English with one model.
    """

    def __init__(self) -> None:
        base_url = _normalize_server_url(_env("MINICPM_OCR_BASE_URL"))
        if not base_url:
            raise ValueError(
                "MINICPM_OCR_BASE_URL is required and must point at a MiniCPM-OCR "
                "server root, for example http://localhost:8000 (without /v1)."
            )

        self.cfg = build_config(base_url)
        self.prompt_map = load_prompt_map(self.cfg)
        self.layout_detector = None
        self.engine = None
        self._init_lock = threading.Lock()
        # Paddle's predictor and the SDK client are kept single-threaded; the
        # endpoint offloads this work to a thread so /health stays responsive.
        self._infer_lock = threading.Lock()

    def _ensure_models(self) -> None:
        if self.layout_detector is not None and self.engine is not None:
            return
        with self._init_lock:
            if self.layout_detector is None:
                layout_dir = Path(_env("MINICPM_OCR_LAYOUT_DIR", DEFAULT_LAYOUT_DIR)).expanduser()
                self.cfg["layout"]["model_dir"] = str(ensure_layout_model(layout_dir))
                self.layout_detector = create_layout_detector(self.cfg["layout"])
            if self.engine is None:
                engine = create_backend(self.cfg)
                engine.start()
                # Only publish the engine after it is ready: a failed start must
                # leave the attribute unset so the next request retries.
                self.engine = engine

    def _ocr(self, image: Image.Image) -> list[dict[str, Any]]:
        self._ensure_models()

        with self._infer_lock:
            detections = self.layout_detector.detect([image])[0]
            blocks = self.layout_detector.crop(image, detections)

            results: list[dict[str, Any]] = []
            pixel_array = None
            for block in blocks:
                label = block.get("label", "")
                elem_cfg = get_element_cfg(self.prompt_map, label)
                if elem_cfg is None or block.get("skip_vlm", False):
                    continue

                bbox = _valid_bbox(block.get("bbox"))
                if bbox is None:
                    logger.warning("Skipping %s block with invalid bbox: %r", label, block.get("bbox"))
                    continue
                x1, y1, x2, y2 = (int(round(value)) for value in bbox)

                crop = block.get("image")
                if crop is None:
                    # Some providers return only boxes; fall back to a page crop.
                    if x2 <= x1 or y2 <= y1:
                        continue
                    if pixel_array is None:
                        import numpy as np

                        pixel_array = np.asarray(image.convert("RGB"))
                    crop = pixel_array[y1:y2, x1:x2]
                if crop is None or getattr(crop, "size", 0) == 0:
                    continue

                crop_image = Image.fromarray(crop).convert("RGB")
                model_image = _resize_to_min_side(crop_image, elem_cfg.get("resize_min_side"))
                prediction = self.engine.recognize(
                    model_image,
                    prompt=elem_cfg["prompt"],
                    max_new_tokens=elem_cfg["max_new_tokens"],
                    slice_nums=elem_cfg["slice_nums"],
                )

                finish_reason = prediction.get("finish_reason")
                if finish_reason not in (None, "", "stop"):
                    logger.warning(
                        "Skipping truncated %s block: finish_reason=%s", label, finish_reason
                    )
                    continue

                text = (prediction.get("text") or "").strip()
                if not text:
                    continue
                results.append(_block_to_result(block, text))

        return results

    def _create_ocr_server(self) -> FastAPI:
        app = FastAPI()

        @app.post("/ocr")
        async def ocr_endpoint(
            file: UploadFile = File(...), language: str = Form(default="en")
        ) -> OcrResponse:
            try:
                image_data = await file.read()
                image = Image.open(io.BytesIO(image_data))
                if image.mode != "RGB":
                    image = image.convert("RGB")
            except Exception as e:
                raise HTTPException(status_code=400, detail=f"Invalid image: {e}")

            try:
                # Layout detection and recognition are blocking; keep the event
                # loop free so /health and other requests stay responsive.
                results = await run_in_threadpool(self._ocr, image)
            except Exception as e:
                logger.exception("MiniCPM-OCR failed")
                raise HTTPException(status_code=500, detail=str(e))

            return OcrResponse(results=results)

        @app.get("/health")
        def health() -> StatusResponse:
            return StatusResponse(status="healthy")

        return app

    def serve(self) -> None:
        app = self._create_ocr_server()
        uvicorn.run(app, host="0.0.0.0", port=8832)


if __name__ == "__main__":
    logging.info("Starting server on port 8832")
    MiniCPMOCRServer().serve()