{ "hf_id": "deepseek-ai/DeepSeek-OCR-2", "meta": { "title": "DeepSeek-OCR-2", "slug": "deepseek-ocr-2", "provider": "DeepSeek", "description": "Next-generation DeepSeek OCR model with improved document-to-markdown grounding and optical context compression.", "date_added": "2026-03-28", "date_updated": "2026-04-17", "tasks": [ "multimodal" ], "performance_headline": "Improved grounding and markdown conversion over DeepSeek-OCR", "related_recipes": [ "deepseek-ai/DeepSeek-OCR" ] }, "recommended_command": { "hardware": "h200", "strategy": "single_node_tp", "variant": "default", "node_count": 1, "deploy_type": "single_node", "env": {}, "docker_image": "vllm/vllm-openai:latest", "command": "vllm serve deepseek-ai/DeepSeek-OCR-2 \\\n --trust-remote-code \\\n --logits_processors vllm.model_executor.models.deepseek_ocr:NGramPerReqLogitsProcessor \\\n --no-enable-prefix-caching \\\n --mm-processor-cache-gb 0 \\\n --tensor-parallel-size 1", "argv": [ "vllm", "serve", "deepseek-ai/DeepSeek-OCR-2", "--trust-remote-code", "--logits_processors", "vllm.model_executor.models.deepseek_ocr:NGramPerReqLogitsProcessor", "--no-enable-prefix-caching", "--mm-processor-cache-gb", "0", "--tensor-parallel-size", "1" ], "docker_command": "docker run --gpus all \\\n --privileged --ipc=host -p 8000:8000 \\\n -v ~/.cache/huggingface:/root/.cache/huggingface \\\n vllm/vllm-openai:latest deepseek-ai/DeepSeek-OCR-2 \\\n --trust-remote-code \\\n --logits_processors vllm.model_executor.models.deepseek_ocr:NGramPerReqLogitsProcessor \\\n --no-enable-prefix-caching \\\n --mm-processor-cache-gb 0 \\\n --tensor-parallel-size 1", "docker_argv": [ "docker", "run", "--gpus", "all", "--privileged", "--ipc=host", "-p", "8000:8000", "-v", "~/.cache/huggingface:/root/.cache/huggingface", "vllm/vllm-openai:latest", "deepseek-ai/DeepSeek-OCR-2", "--trust-remote-code", "--logits_processors", "vllm.model_executor.models.deepseek_ocr:NGramPerReqLogitsProcessor", "--no-enable-prefix-caching", "--mm-processor-cache-gb", "0", "--tensor-parallel-size", "1" ], "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": "hopper", "compute_arch": "sm90", "display_name": "H200", "description": "NVIDIA H200 SXM 141 GB HBM3e ยท 8-GPU HGX node", "gpu_count": 8, "vram_gb": 1128, "multi_node": false }, "alternatives": { "multi_node_tp": "/deepseek-ai/DeepSeek-OCR-2/strategies/multi_node_tp.json", "kv_store_centralized_mooncake": "/deepseek-ai/DeepSeek-OCR-2/strategies/kv_store_centralized_mooncake.json", "kv_store_distributed_mooncake": "/deepseek-ai/DeepSeek-OCR-2/strategies/kv_store_distributed_mooncake.json" }, "by_hardware": { "h200": "/deepseek-ai/DeepSeek-OCR-2/hw/h200.json", "h100": "/deepseek-ai/DeepSeek-OCR-2/hw/h100.json", "b200": "/deepseek-ai/DeepSeek-OCR-2/hw/b200.json", "gb200": "/deepseek-ai/DeepSeek-OCR-2/hw/gb200.json", "b300": "/deepseek-ai/DeepSeek-OCR-2/hw/b300.json", "gb300": "/deepseek-ai/DeepSeek-OCR-2/hw/gb300.json", "mi300x": "/deepseek-ai/DeepSeek-OCR-2/hw/mi300x.json", "mi325x": "/deepseek-ai/DeepSeek-OCR-2/hw/mi325x.json", "mi350x": "/deepseek-ai/DeepSeek-OCR-2/hw/mi350x.json", "mi355x": "/deepseek-ai/DeepSeek-OCR-2/hw/mi355x.json" } }, "model": { "model_id": "deepseek-ai/DeepSeek-OCR-2", "min_vllm_version": "0.16.0", "architecture": "dense", "parameter_count": "3B", "active_parameters": "3B", "context_length": 8192, "base_args": [ "--trust-remote-code", "--logits_processors", "vllm.model_executor.models.deepseek_ocr:NGramPerReqLogitsProcessor", "--no-enable-prefix-caching", "--mm-processor-cache-gb", "0" ], "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:latest" } } }, "features": { "text_only": { "description": "Skip loading the vision encoder for text-only workloads โ€” frees VRAM for KV cache. Mutually exclusive with encoder_parallel.", "args": [ "--language-model-only" ] }, "encoder_parallel": { "description": "Run the vision encoder in data-parallel mode โ€” avoids TP comm overhead on the small encoder. Mutually exclusive with text_only.", "args": [ "--mm-encoder-tp-mode", "data" ] } }, "opt_in_features": [ "text_only", "encoder_parallel" ], "variants": { "default": { "precision": "bf16", "vram_minimum_gb": 7, "description": "Full precision BF16 (~3.4B params)" } }, "hardware_overrides": {}, "guide": "## Overview\n\nDeepSeek-OCR-2 is a frontier OCR model exploring optical context compression for LLMs.\nIt iterates on DeepSeek-OCR with better grounding and markdown conversion, and supports\nprompts like `\\n<|grounding|>Convert the document to markdown.` for richer\ndocument parsing.\n\n## Prerequisites\n\n- **Hardware**: Single GPU with >=8 GB VRAM is typically sufficient for BF16 inference.\n- **vLLM**: Current stable release (tested with `uv pip install -U vllm --torch-backend auto`).\n- **Python**: 3.10+\n\nInstall vLLM:\n```bash\nuv venv\nsource .venv/bin/activate\nuv pip install -U vllm --torch-backend auto\n```\n\n## Client Usage\n\n### Offline OCR (Python)\n\n```python\nfrom vllm import LLM, SamplingParams\nfrom vllm.model_executor.models.deepseek_ocr import NGramPerReqLogitsProcessor\nfrom PIL import Image\n\nllm = LLM(\n model=\"deepseek-ai/DeepSeek-OCR-2\",\n enable_prefix_caching=False,\n mm_processor_cache_gb=0,\n logits_processors=[NGramPerReqLogitsProcessor],\n)\n\nimage_1 = Image.open(\"path/to/your/image_1.png\").convert(\"RGB\")\nimage_2 = Image.open(\"path/to/your/image_2.png\").convert(\"RGB\")\n# prompt = \"\\nFree OCR. \"\nprompt = \"\\n<|grounding|>Convert the document to markdown. \"\n\nmodel_input = [\n {\"prompt\": prompt, \"multi_modal_data\": {\"image\": image_1}},\n {\"prompt\": prompt, \"multi_modal_data\": {\"image\": image_2}},\n]\n\nsampling_param = SamplingParams(\n temperature=0.0,\n max_tokens=8192,\n extra_args=dict(\n ngram_size=30,\n window_size=90,\n whitelist_token_ids={128821, 128822}, # , \n ),\n skip_special_tokens=False,\n)\n\nfor output in llm.generate(model_input, sampling_param):\n print(output.outputs[0].text)\n```\n\n### Online OCR serving\n\n```bash\nvllm serve deepseek-ai/DeepSeek-OCR-2 \\\n --logits_processors vllm.model_executor.models.deepseek_ocr:NGramPerReqLogitsProcessor \\\n --no-enable-prefix-caching \\\n --mm-processor-cache-gb 0\n```\n\n```python\nimport time\nfrom openai import OpenAI\n\nclient = OpenAI(api_key=\"EMPTY\", base_url=\"http://localhost:8000/v1\", timeout=3600)\n\nmessages = [\n {\n \"role\": \"user\",\n \"content\": [\n {\"type\": \"image_url\", \"image_url\": {\"url\": \"https://ofasys-multimodal-wlcb-3-toshanghai.oss-accelerate.aliyuncs.com/wpf272043/keepme/image/receipt.png\"}},\n {\"type\": \"text\", \"text\": \"Free OCR.\"},\n ],\n }\n]\n\nstart = time.time()\nresponse = client.chat.completions.create(\n model=\"deepseek-ai/DeepSeek-OCR-2\",\n messages=messages,\n max_tokens=2048,\n temperature=0.0,\n extra_body={\n \"skip_special_tokens\": False,\n \"vllm_xargs\": {\n \"ngram_size\": 30,\n \"window_size\": 90,\n \"whitelist_token_ids\": [128821, 128822],\n },\n },\n)\nprint(f\"Response costs: {time.time() - start:.2f}s\")\nprint(f\"Generated text: {response.choices[0].message.content}\")\n```\n\n## Troubleshooting / Configuration Tips\n\n- **Use the custom logits processor** along with the model for optimal OCR and markdown\n generation performance.\n- Unlike multi-turn chat, OCR tasks do not typically benefit from prefix caching or image\n reuse, so disable these features to avoid unnecessary hashing and caching overhead.\n- DeepSeek-OCR-2 works better with plain prompts than instruction formats. See the\n [official main prompts](https://huggingface.co/deepseek-ai/DeepSeek-OCR-2#main-prompts).\n- Depending on your hardware, adjust `max_num_batched_tokens` for better throughput.\n\n## References\n\n- [DeepSeek-OCR-2 on Hugging Face](https://huggingface.co/deepseek-ai/DeepSeek-OCR-2)\n- [vLLM multimodal inputs guide](https://docs.vllm.ai/en/latest/features/multimodal_inputs.html#offline-inference)\n", "source": { "source": "vllm", "repo": "vllm-project/vllm", "ref": "main", "sha": "389ffebe555705c85337025d5df108d0384d365e", "path": "recipes/models/deepseek-ai/DeepSeek-OCR-2.yaml", "edit_url": "https://github.com/vllm-project/vllm/edit/main/recipes/models/deepseek-ai/DeepSeek-OCR-2.yaml", "overlays": [] } }