Skip to content

A fast, helpful, and open-source document parser

3.8 KB
Raw Blame

MiniCPM-OCR Service

A FastAPI server wrapping MiniCPM-OCR 1.0 to conform to the LiteParse OCR API specification (see ../../OCR_API_SPEC.md).

MiniCPM-OCR is a 1.3B document-parsing model for Chinese and English. It is block-level: this server runs the model's bundled PP-DocLayout layout detector in-process, crops each detected block, and asks a MiniCPM-OCR inference server to recognize the crop with the recipe for that block type (Text Recognition:, Table Recognition:, Formula Recognition:, ...).

Inference backend (required)

The adapter does not bundle the 1.3B VLM weights. Run MiniCPM-OCR with one of its supported serving engines and point MINICPM_OCR_BASE_URL at the server root. The MiniCPM-OCR deployment guide covers vLLM, SGLang, llama.cpp, and Ollama.

# vLLM example
vllm serve openbmb/MiniCPM-OCR-1.0 \
  --served-model-name minicpm-ocr --host 127.0.0.1 --port 18499

Environment

Variable Default Meaning
MINICPM_OCR_BASE_URL required Inference server root, without /v1 (a trailing /v1 is stripped)
MINICPM_OCR_MODEL minicpm-ocr Served model name
MINICPM_OCR_BACKEND vllm vllm, sglang, openai, llamacpp, or ollama
MINICPM_OCR_API_KEY empty Optional bearer token for the inference server
MINICPM_OCR_MAX_MODEL_LEN 40960 Context length reported to the SDK; keep it equal to the server's
MINICPM_OCR_STARTUP_TIMEOUT 60 Seconds to wait for the inference server on the first request
MINICPM_OCR_REQUEST_TIMEOUT 300 Per-request timeout in seconds
MINICPM_OCR_LAYOUT_DEVICE cpu Paddle device for layout detection (cpu or cuda:0)
MINICPM_OCR_LAYOUT_DIR ~/.cache/minicpm-ocr/layout Cache for the PP-DocLayoutV3 model

Build and Run

# install and run
uv run server.py

The first POST /ocr downloads the PP-DocLayoutV3 layout model into MINICPM_OCR_LAYOUT_DIR and connects to the inference server; GET /health answers before either happens.

curl -X POST http://localhost:8832/ocr \
  -F "[email protected]" \
  -F "language=en"
lit parse document.pdf --ocr-server-url http://localhost:8832/ocr

Docker

The image contains the API and the layout model only; the inference server runs separately and is reached through MINICPM_OCR_BASE_URL.

docker build -t minicpm-ocr-liteparse .
docker run --rm -p 8832:8832 \
  -e MINICPM_OCR_BASE_URL=http://host.docker.internal:18499 \
  -v minicpm-ocr-layout:/models/layout \
  minicpm-ocr-liteparse

Mount /models/layout to keep the PP-DocLayoutV3 download across container runs. For air-gapped deployments, pre-populate that volume before starting the container.

Notes

  • language is accepted for API compatibility but unused: one MiniCPM-OCR model handles Chinese and English.
  • confidence is reported as 1.0. MiniCPM-OCR does not return a recognition confidence, and the layout score is not a substitute for one.
  • A block whose completion ends with an explicit non-stop finish_reason (for example length) is skipped with a warning instead of returning a truncated prefix.