A fast, helpful, and open-source document parser
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
languageis accepted for API compatibility but unused: one MiniCPM-OCR model handles Chinese and English.confidenceis reported as1.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-
stopfinish_reason(for examplelength) is skipped with a warning instead of returning a truncated prefix.