{
  "hf_id": "openbmb/MiniCPM-OCR-1.0",
  "meta": {
    "title": "MiniCPM-OCR 1.0",
    "slug": "minicpm-ocr-1-0",
    "provider": "MiniCPM (OpenBMB)",
    "description": "MiniCPM-OCR 1.0 (1.3B) — OCR-specific document-parsing VLM that turns page images and region crops into Markdown text, tables, formulas, charts, and seals",
    "date_added": "2026-11-17",
    "date_updated": "2026-11-17",
    "tasks": [
      "multimodal"
    ],
    "performance_headline": "93.68 on Real5-OmniDocBench — OCR-specific 1.3B model with DSpark speculative decoding",
    "related_recipes": [
      "openbmb/MiniCPM-V-4.6"
    ],
    "default_hardware": "rtx_4090",
    "hardware": {
      "rtx_4090": "verified"
    }
  },
  "recommended_command": {
    "hardware": "rtx_4090",
    "strategy": "single_node_tp",
    "variant": "default",
    "node_count": 1,
    "deploy_type": "single_node",
    "env": {},
    "docker_image": "vllm/vllm-openai:v0.34.0",
    "command": "vllm serve openbmb/MiniCPM-OCR-1.0 \\\n  --trust-request-mm-kwargs \\\n  --limit-mm-per-prompt '{\"image\":36,\"video\":0}' \\\n  --max-model-len 40960 \\\n  --max-num-batched-tokens 40960 \\\n  --tensor-parallel-size 1 \\\n  --speculative-config '{\"method\":\"dspark\",\"model\":\"openbmb/MiniCPM-OCR-1.0-DSpark\",\"num_speculative_tokens\":15,\"enable_adaptive_verification\":false}'",
    "argv": [
      "vllm",
      "serve",
      "openbmb/MiniCPM-OCR-1.0",
      "--trust-request-mm-kwargs",
      "--limit-mm-per-prompt",
      "{\"image\":36,\"video\":0}",
      "--max-model-len",
      "40960",
      "--max-num-batched-tokens",
      "40960",
      "--tensor-parallel-size",
      "1",
      "--speculative-config",
      "{\"method\":\"dspark\",\"model\":\"openbmb/MiniCPM-OCR-1.0-DSpark\",\"num_speculative_tokens\":15,\"enable_adaptive_verification\":false}"
    ],
    "docker_command": "docker run --gpus all \\\n  --privileged --ipc=host -p 8000:8000 \\\n  -v ~/.cache/huggingface:/root/.cache/huggingface \\\n  vllm/vllm-openai:v0.34.0 openbmb/MiniCPM-OCR-1.0 \\\n  --trust-request-mm-kwargs \\\n  --limit-mm-per-prompt '{\"image\":36,\"video\":0}' \\\n  --max-model-len 40960 \\\n  --max-num-batched-tokens 40960 \\\n  --tensor-parallel-size 1 \\\n  --speculative-config '{\"method\":\"dspark\",\"model\":\"openbmb/MiniCPM-OCR-1.0-DSpark\",\"num_speculative_tokens\":15,\"enable_adaptive_verification\":false}'",
    "docker_argv": [
      "docker",
      "run",
      "--gpus",
      "all",
      "--privileged",
      "--ipc=host",
      "-p",
      "8000:8000",
      "-v",
      "~/.cache/huggingface:/root/.cache/huggingface",
      "vllm/vllm-openai:v0.34.0",
      "openbmb/MiniCPM-OCR-1.0",
      "--trust-request-mm-kwargs",
      "--limit-mm-per-prompt",
      "{\"image\":36,\"video\":0}",
      "--max-model-len",
      "40960",
      "--max-num-batched-tokens",
      "40960",
      "--tensor-parallel-size",
      "1",
      "--speculative-config",
      "{\"method\":\"dspark\",\"model\":\"openbmb/MiniCPM-OCR-1.0-DSpark\",\"num_speculative_tokens\":15,\"enable_adaptive_verification\":false}"
    ],
    "strategy_spec": {
      "name": "single_node_tp",
      "deploy_type": "single_node",
      "display_name": "Tensor Parallel",
      "short_label": "TP",
      "orientation": "latency",
      "description": "Single-node tensor parallel. Splits the model across all local GPUs. TP size is set to the GPU count at deploy time. The simplest multi-GPU strategy — works for all model architectures.\n",
      "hardware_match": {
        "min_gpus": 1,
        "max_gpus": 8,
        "multi_node": false
      },
      "vllm_args": [],
      "parallel_flag": "--tensor-parallel-size"
    },
    "hardware_profile": {
      "brand": "NVIDIA",
      "generation": "ada",
      "compute_arch": "sm89",
      "display_name": "RTX 4090",
      "description": "NVIDIA RTX 4090 · 1× RTX 4090 GPU · 24 GB VRAM",
      "gpu_count": 1,
      "vram_gb": 24,
      "multi_node": false,
      "scalable": false,
      "restricted": true
    },
    "by_hardware": {
      "rtx_4090": "/openbmb/MiniCPM-OCR-1.0/hw/rtx_4090.json",
      "h100": "/openbmb/MiniCPM-OCR-1.0/hw/h100.json",
      "h200": "/openbmb/MiniCPM-OCR-1.0/hw/h200.json",
      "b200": "/openbmb/MiniCPM-OCR-1.0/hw/b200.json",
      "gb200": "/openbmb/MiniCPM-OCR-1.0/hw/gb200.json",
      "b300": "/openbmb/MiniCPM-OCR-1.0/hw/b300.json",
      "gb300": "/openbmb/MiniCPM-OCR-1.0/hw/gb300.json",
      "mi300x": "/openbmb/MiniCPM-OCR-1.0/hw/mi300x.json",
      "mi325x": "/openbmb/MiniCPM-OCR-1.0/hw/mi325x.json",
      "mi350x": "/openbmb/MiniCPM-OCR-1.0/hw/mi350x.json",
      "mi355x": "/openbmb/MiniCPM-OCR-1.0/hw/mi355x.json"
    }
  },
  "model": {
    "model_id": "openbmb/MiniCPM-OCR-1.0",
    "min_vllm_version": "0.34.0",
    "docker_image": "vllm/vllm-openai:v0.34.0",
    "architecture": "dense",
    "parameter_count": "1.3B",
    "active_parameters": "1.3B",
    "context_length": 262144,
    "base_args": [
      "--trust-request-mm-kwargs",
      "--limit-mm-per-prompt",
      "{\"image\":36,\"video\":0}",
      "--max-model-len",
      "40960",
      "--max-num-batched-tokens",
      "40960"
    ],
    "base_env": {},
    "install": {
      "pip": {
        "command": "uv venv\nsource .venv/bin/activate\nuv pip install -U vllm --torch-backend auto"
      },
      "docker": {
        "command": "docker pull vllm/vllm-openai:v0.34.0"
      },
      "extras": [
        {
          "note": "The minicpm_ocr processors ship in transformers >= 5.21; vLLM 0.34.0 accepts < 5.23",
          "command": "uv pip install -U \"transformers>=5.21.0,<5.23.0\""
        }
      ]
    }
  },
  "features": {
    "spec_decoding": {
      "description": "DSpark speculative decoding with the matching 0.3B draft model (15 tokens per step) — the model card reports ~55% faster end-to-end parsing",
      "args": [
        "--speculative-config",
        "{\"method\":\"dspark\",\"model\":\"openbmb/MiniCPM-OCR-1.0-DSpark\",\"num_speculative_tokens\":15,\"enable_adaptive_verification\":false}"
      ]
    }
  },
  "opt_in_features": [],
  "variants": {
    "default": {
      "precision": "bf16",
      "vram_minimum_gb": 4,
      "description": "BF16 weights (~2.6 GB) — fits on a single 24 GB consumer GPU"
    },
    "awq": {
      "model_id": "openbmb/MiniCPM-OCR-1.0-AWQ",
      "label": "AWQ",
      "precision": "int4",
      "vram_minimum_gb": 3,
      "description": "Official 4-bit AWQ checkpoint — smaller footprint, same serving path",
      "json": "/openbmb/MiniCPM-OCR-1.0-AWQ.json"
    },
    "gptq": {
      "model_id": "openbmb/MiniCPM-OCR-1.0-GPTQ",
      "label": "GPTQ",
      "precision": "int4",
      "vram_minimum_gb": 3,
      "description": "Official 4-bit GPTQ checkpoint — smaller footprint, same serving path",
      "json": "/openbmb/MiniCPM-OCR-1.0-GPTQ.json"
    }
  },
  "troubleshooting": [
    {
      "title": "ValueError: The checkpoint you are trying to load has model type `minicpm_ocr` but Transformers does not recognize this architecture",
      "body": "transformers < 5.21 predates the `minicpm_ocr` config and processors.\nInstall transformers 5.21–5.22 (`uv pip install -U \"transformers>=5.21.0,<5.23.0\"`);\nthe recipe's dependency step does this.\n"
    }
  ],
  "guide": "## Overview\n\n**MiniCPM-OCR 1.0** is a 1.3B OCR-specific model in the MiniCPM-V family. It\npairs a SigLIP-style vision encoder with the **Qwen3.5-0.8B** hybrid\nlinear/full-attention backbone from MiniCPM-V 4.6, and is trained for\ntext-centric document parsing: text blocks, tables, formulas, charts, seals,\nand key-information extraction. It scores **93.68 on Real5-OmniDocBench** and\n**54.7 on OCRBench v2**.\n\nThe checkpoint is the recognition stage. Send a page image or a cropped\nregion together with a region prompt; for PDFs, the companion `minicpm-ocr`\nSDK detects layout with PP-DocLayoutV3, crops regions, calls this service,\nand assembles the results into Markdown/JSON.\n\nThis recipe was run end to end on **one RTX 4090 (24 GB)** with vLLM 0.34.0\nand transformers 5.22, on the BF16 checkpoint and both official 4-bit\ncheckpoints, with and without the DSpark draft model. With DSpark on the\n4090, test requests accepted ~60% of drafted tokens (348/570), and\nmulti-token requests completed 20–45% faster than plain decoding.\n\n## Prerequisites\n\n- **vLLM ≥ 0.34.0** — v0.33.0 registered `MiniCPMOcrForConditionalGeneration`\n  but pins transformers < 5.21, before the `minicpm_ocr` processors shipped.\n  0.34.0 includes the follow-up downsample fix ([PR #64105](https://github.com/vllm-project/vllm/pull/64105)).\n- **transformers ≥ 5.21, < 5.23** — the range the model's processors need\n  within vLLM 0.34.0's pin.\n- One GPU is enough: BF16 weights are ~2.6 GB, and the DSpark draft model\n  adds ~0.6 GB. Use `temperature=0` for OCR.\n- **Context** — the default command keeps the model guide's 40,960-token\n  window, sized for page crops; the checkpoint supports up to 262,144 tokens.\n\n## Client usage\n\nThe prompt selects what to read in the image: `Text Recognition:` for text\nblocks and pages, `Table Recognition:` for tables, `Formula Recognition:` for\nformulas, `Seal Recognition:` for seals, and `Chart to Table:` for charts.\nKey-information extraction takes a field list instead. Tables and charts come\nback as OTSL; the SDK converts them to HTML.\n\n```python\nfrom openai import OpenAI\n\nclient = OpenAI(api_key=\"EMPTY\", base_url=\"http://localhost:8000/v1\", timeout=600)\n\nresponse = client.chat.completions.create(\n    model=\"openbmb/MiniCPM-OCR-1.0\",\n    messages=[{\n        \"role\": \"user\",\n        \"content\": [\n            {\"type\": \"image_url\", \"image_url\": {\"url\": \"https://.../page.png\"}},\n            {\"type\": \"text\", \"text\": \"Text Recognition:\"},\n        ],\n    }],\n    temperature=0.0,\n    max_tokens=2048,\n)\nprint(response.choices[0].message.content)\n```\n\n### Full documents with the SDK\n\nThe official SDK handles layout detection, region cropping, and result\nassembly around this service. Install it in a separate environment\n(`pip install \"minicpm-ocr[all]\"`) and point it at the server. Pass the\nserved model name (`--model`) to match the server; the SDK defaults to\n`minicpm-ocr`.\n\nThe server keeps `--trust-request-mm-kwargs` so the SDK can set\nper-request image-processing options such as `downsample_mode`. Keep it only\nfor trusted clients: without it, vLLM rejects per-request image options.\n\n## References\n\n- [Model card](https://huggingface.co/openbmb/MiniCPM-OCR-1.0)\n- [DSpark draft model](https://huggingface.co/openbmb/MiniCPM-OCR-1.0-DSpark)\n- [GitHub: OpenBMB/MiniCPM-OCR](https://github.com/OpenBMB/MiniCPM-OCR)\n- [Deployment guide](https://github.com/OpenBMB/MiniCPM-OCR/blob/main/docs/minicpm_ocr_tutorial_en.md)\n- [vLLM support PR #63095](https://github.com/vllm-project/vllm/pull/63095)\n",
  "source": {
    "source": "vllm",
    "repo": "vllm-project/vllm",
    "ref": "main",
    "sha": "592699add6b92023d7dcbce8ce788fd0dd8ba483",
    "path": "recipes/models/openbmb/MiniCPM-OCR-1.0.yaml",
    "edit_url": "https://github.com/vllm-project/vllm/edit/main/recipes/models/openbmb/MiniCPM-OCR-1.0.yaml",
    "overlays": []
  }
}