openbmbofficial/minicpm-ocr repository overview

⁠MiniCPM-OCR

Official GPU inference image for MiniCPM-OCR 1.0, a 1.3B vision-language model for Chinese and English OCR. Includes model weights, the MiniCPM-OCR SDK, an OpenAI-compatible vLLM server, and the upstream document parsing backend.

Choose the OCR model API or the end-to-end document parsing API below.

MiniCPM-OCR 1.0 官方 GPU 推理镜像，内置模型权重、OCR SDK、vLLM 和上游文档解析后端。支持中文、英文文本、表格、公式、印章等内容识别；结合 SDK 可将完整页面和 PDF 解析为 Markdown / JSON。

⁠Requirements

• Linux x86-64 with an NVIDIA GPU.
• An NVIDIA driver compatible with the image's CUDA 12.9 runtime.
• Docker with NVIDIA Container Toolkit configured.

Python, inference dependencies, and model weights are included in the image. The Quick start below was tested on November 4, 2026, on an RTX 5090 (32 GB) with NVIDIA driver 590.48.01.

⁠Quick start: OCR model API

This command starts the vLLM image recognition API only. The end-to-end document pipeline—orientation correction, PP-DocLayout analysis, region cropping, OCR, reading order, and document postprocessing—requires running the SDK separately. For an HTTP service that runs the complete pipeline, use End-to-end document parsing API below.

这里只启动 OCR 模型接口。旋转摆正、PP-DocLayout 版面分析、分区裁剪及文档后处理没有随此命令启动；完整页面和 PDF 解析需要另行运行 SDK pipeline。

docker run --rm --gpus all --ipc=host -p 8000:8000 \
  --health-cmd 'curl -fsS http://127.0.0.1:8000/health || exit 1' \
  openbmbofficial/minicpm-ocr:latest vllm serve /opt/models/ocr

The health command above replaces an inherited check for /ready with the vLLM /health endpoint.

The first launch performs CUDA graph capture and may take a few minutes. In a second terminal, wait until the API is ready and then list the served model:

curl -fsS --retry 120 --retry-all-errors --retry-delay 5 --max-time 5 \
  http://localhost:8000/health
curl -fsS http://localhost:8000/v1/models

These client commands require curl 7.71 or newer on the host. The model list should contain minicpm-ocr-1.0.

Use the following settings with an OpenAI-compatible client:

• Base URL: http://localhost:8000/v1
• Model: minicpm-ocr-1.0
• Image recognition endpoint: POST /v1/chat/completions

⁠OCR usage

Send an image followed by a task prompt in the request's user message:

• Text Recognition: — text recognition.
• Table Recognition: — table recognition.
• Formula Recognition: — formula recognition.
• Seal Recognition: — seal text recognition.
• Chart to Table: — chart-to-table conversion.

Save a PNG containing text as image.png in the current directory. Run the following in Bash on Linux after the readiness check above succeeds:

IMAGE_PATH=./image.png
IMAGE_B64=$(base64 -w 0 "$IMAGE_PATH")

cat > /tmp/minicpm-ocr-request.json <<EOF
{
  "model": "minicpm-ocr-1.0",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "image_url", "image_url": {"url": "data:image/png;base64,${IMAGE_B64}"}},
      {"type": "text", "text": "Text Recognition:"}
    ]
  }],
  "temperature": 0
}
EOF

curl -fsS http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  --data-binary @/tmp/minicpm-ocr-request.json

See the image recognition example⁠ for a complete request.

For full-page images and PDFs, use one of the complete pipeline recipes below.

⁠End-to-end document parsing API

Yes, this image includes the complete pipeline. It contains the SDK, the upstream Web Demo backend, and all models needed for:

PDF rendering / image input → orientation correction and deskew → PP-DocLayoutV3 → region cropping → MiniCPM-OCR → reading order and postprocessing → Markdown and structured page results.

这个镜像具备端到端能力。下面会同时启动 vLLM 和镜像内置的文档解析后端，上传整页图片或 PDF 即可完成摆正、版面分析、分区识别和文档后处理。

This recipe uses the GPU for OCR and CPU for layout and orientation models. It keeps the existing bundled model paths and needs no host Python installation. Use it as an alternative to the OCR-only Quick start: both examples publish host port 8000.

⁠1. Save the startup script

In a working directory on your Linux GPU host, create minicpm-ocr-pipeline.sh:

cat > minicpm-ocr-pipeline.sh <<'BASH'
#!/usr/bin/env bash
set -Eeuo pipefail

export OCR_LAYOUT_DEVICE=cpu OCR_UPRIGHT_DEVICE=cpu
export OCR_LAYOUT_WORKERS=1 OCR_UPRIGHT_WORKERS=1
export OCRWEB_DATA_DIR=/data/pipeline-data

children=()
cleanup() {
  for child in "${children[@]}"; do
    kill "$child" 2>/dev/null || true
  done
  for child in "${children[@]}"; do
    wait "$child" 2>/dev/null || true
  done
}
trap cleanup EXIT
trap 'exit 143' TERM
trap 'exit 130' INT

vllm serve /opt/models/ocr --port 18499 &
children+=("$!")

ready=false
for ((attempt = 0; attempt < 180; attempt++)); do
  if curl -fsS --max-time 5 http://127.0.0.1:18499/health >/dev/null 2>&1; then
    ready=true
    break
  fi
  if ! kill -0 "${children[0]}" 2>/dev/null; then
    echo "The OCR model server exited before becoming ready." >&2
    exit 1
  fi
  sleep 5
done
if [[ "$ready" != true ]]; then
  echo "The OCR model server did not become ready within the startup timeout." >&2
  exit 1
fi

cd /opt/app/webdemo/backend
PORT=8000 /opt/venv/bin/python -s server.py &
children+=("$!")
wait -n "${children[@]}"
BASH

The script keeps vLLM on internal port 18499 and serves the document API on port 8000. CPU layout and orientation avoid competing with vLLM for GPU memory.

⁠2. Start the complete service

Run this from the directory containing the script:

docker run --rm --name minicpm-ocr-pipeline --gpus all --ipc=host \
  -p 8000:8000 -v "$PWD:/data" \
  --health-cmd 'curl -fsS http://127.0.0.1:8000/health || exit 1' \
  openbmbofficial/minicpm-ocr:latest bash /data/minicpm-ocr-pipeline.sh

Leave that terminal running. In a second terminal, wait for startup:

curl -fsS --retry 180 --retry-all-errors --retry-delay 5 --max-time 5 \
  http://localhost:8000/health

This returns {"status":"ok"} after the OCR model server and document API have started. Layout and orientation models load on the first document request.

⁠3. Upload a PDF or page image

Save your input as document.pdf in the working directory, then submit it:

curl -fsS http://localhost:8000/api/document-parse/jobs \
  -F '[email protected]'

For a page image, replace document.pdf with your PNG or JPEG filename. The response includes a job id and starts with status: "Running". Orientation correction is enabled by default.

Copy the returned id, then query the job:

JOB_ID=PASTE_THE_RETURNED_JOB_ID
curl -fsS "http://localhost:8000/api/document-parse/jobs/$JOB_ID" \
  -o result.json

Repeat the query until status becomes "Success" or "Failed". On success, result.json contains:

• pages_done and pages_total: document progress.
• pages[].choices[0].message.content: each page's Markdown.
• pages[].minicpm_ocr.blocks: ordered regions with labels, coordinates, recognized content and per-region status.
• pages[].minicpm_ocr.rotation: orientation and deskew decisions, including whether a correction was applied.

Check region statuses as well as the job status when processing your own documents. Runtime data is retained in pipeline-data/ under the mounted working directory; query jobs while this API process is running, because the job registry is held in memory.

⁠SDK: export directly to Markdown and JSON

With the complete service above still running and document.pdf in the mounted working directory:

docker exec -w /data minicpm-ocr-pipeline \
  /opt/venv/bin/minicpmvocr parse /data/document.pdf \
  --server-url http://127.0.0.1:18499 --model minicpm-ocr-1.0 \
  --device cpu --set upright.device=cpu \
  -o /data/document.md --json /data/document.json

This runs the same full SDK pipeline and writes document.md, document.json and runs/ into the host working directory. Replace the input path with /data/image.png to parse a page image. The SDK JSON uses pages[].ocr for blocks and rotation metadata; the HTTP backend uses pages[].minicpm_ocr.

Use the absolute SDK executable path shown above: the image's default PATH does not include /opt/venv/bin.

⁠Verification

The published image was tested on gjsl5090 on November 4, 2026, using an RTX 5090 (32 GB), NVIDIA driver 590.48.01, and image digest sha256:7c397ed0301736f7c9c29a3f9ec5c698a36592c73b2cb1dfd78fe2ad5e7ab773.

Both SDK parsing and the document HTTP API successfully parsed a two-page PDF containing an upright page, a page rotated 90° clockwise, and a table. The rotated page was corrected by 90° counterclockwise and confirmed by the orientation vote. All 30 regions completed with zero OCR failures; the table was exported as HTML within Markdown. A rotated PNG was also parsed with the SDK, and the HTTP API corrected a PNG tilted by 2.4° with a recorded deskew angle of -2.4°. Host ports and GPU selection were adjusted to isolate the test from other running services.

These checks establish that the included components work together. They are functional smoke tests, not an OCR accuracy benchmark. Cross-page table merging is disabled by default; the examples do not enable it.

⁠Included components

• MiniCPM-OCR 1.0 weights: /opt/models/ocr
• Layout model: /opt/models/layout
• Orientation model: /opt/models/paddle_upright
• MiniCPM-OCR SDK 1.0.4 and Python 3.12: /opt/venv
• Project source: /opt/app
• Document HTTP backend: /opt/app/webdemo/backend/server.py
• vLLM inference server with OpenAI-compatible endpoints.

⁠Model updates

The server startup script checks Hugging Face for OCR weight updates. If the check or download fails, it continues with the existing weights.

模型权重已内置；联网检查或下载失败时继续使用现有权重。

⁠Development

Open an interactive shell:

docker run --rm -it --gpus all openbmbofficial/minicpm-ocr:latest bash

The image's default command is bash; use the explicit vllm serve command in Quick start to start the API. The bundled wrapper loads /opt/models/ocr; it does not forward arbitrary vLLM arguments.

⁠Links

• GitHub⁠
• Model weights⁠
• Issues⁠

MiniCPM-OCR code and model weights are released under the Apache License 2.0. Third-party components retain their respective licenses.